[PR #410] [MERGED] Extract usage tracking helpers and refactor UsageTrackingService #713

New issue

Closed

opened 2026-03-13 21:05:20 +03:00 by kerem · 0 comments

kerem commented

2026-03-13 21:05:20 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/AJaySi/ALwrity/pull/410
Author: @AJaySi
Created: 3/12/2026
Status: ✅ Merged
Merged: 3/12/2026
Merged by: @AJaySi

Base: main ← Head: codex/refactor-usage-tracking-service-for-better-error-handling-90ieb9

📝 Commits (1)

ad1756a Extract usage trends and reset logic into usage_tracking_helpers

📊 Changes

5 files changed (+573 additions, -469 deletions)

View changed files

➕ backend/services/subscription/usage_tracking_helpers/__init__.py (+29 -0)
➕ backend/services/subscription/usage_tracking_helpers/usage_reset_helpers.py (+73 -0)
➕ backend/services/subscription/usage_tracking_helpers/usage_stats_helpers.py (+250 -0)
➕ backend/services/subscription/usage_tracking_helpers/usage_trends_helpers.py (+171 -0)
📝 backend/services/subscription/usage_tracking_service.py (+50 -469)

📄 Description

Motivation

Move complex, repeated logic out of UsageTrackingService into focused helper modules to improve readability and maintainability.
Centralize cost reconciliation, provider breakdown, trends building, and reset logic so behavior is easier to test and reuse.
Preserve existing backfill/self-heal behavior when usage summaries are incomplete while reducing duplication in the main service.

Description

Added a new helper package backend/services/subscription/usage_tracking_helpers with __init__.py exporting the helper API.
Implemented usage_reset_helpers.reset_usage_summary_counters to encapsulate summary reset behavior and replaced inline reset logic in UsageTrackingService.reset_current_billing_period with a call to reset_usage_summary_counters.
Implemented usage_stats_helpers providing build_default_usage_percentages, build_empty_usage_response, build_provider_breakdown, calculate_final_total_cost, and maybe_persist_reconciled_costs to handle provider cost resolution, percentage calculations, and optional DB persistence of reconciled costs, and replaced the verbose inlined code in get_user_usage_stats with calls to these helpers.
Implemented usage_trends_helpers providing build_billing_periods, query_usage_summaries, self_heal_summaries_from_logs, and build_usage_trends_response, and refactored get_usage_trends to use these helpers for period construction, summary queries, self-healing from logs, and response assembly.
Added a defensive ValueError check in get_user_usage_stats when user_id is missing and adjusted imports in usage_tracking_service.py to use the new helper functions.

Testing

No automated tests were executed as part of this rollout.

Codex Task

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/AJaySi/ALwrity/pull/410 **Author:** [@AJaySi](https://github.com/AJaySi) **Created:** 3/12/2026 **Status:** ✅ Merged **Merged:** 3/12/2026 **Merged by:** [@AJaySi](https://github.com/AJaySi) **Base:** `main` ← **Head:** `codex/refactor-usage-tracking-service-for-better-error-handling-90ieb9` --- ### 📝 Commits (1) - [`ad1756a`](https://github.com/AJaySi/ALwrity/commit/ad1756aaa2c93e1387387b502a01062fa1565f4d) Extract usage trends and reset logic into usage_tracking_helpers ### 📊 Changes **5 files changed** (+573 additions, -469 deletions) <details> <summary>View changed files</summary> ➕ `backend/services/subscription/usage_tracking_helpers/__init__.py` (+29 -0) ➕ `backend/services/subscription/usage_tracking_helpers/usage_reset_helpers.py` (+73 -0) ➕ `backend/services/subscription/usage_tracking_helpers/usage_stats_helpers.py` (+250 -0) ➕ `backend/services/subscription/usage_tracking_helpers/usage_trends_helpers.py` (+171 -0) 📝 `backend/services/subscription/usage_tracking_service.py` (+50 -469) </details> ### 📄 Description ### Motivation - Move complex, repeated logic out of `UsageTrackingService` into focused helper modules to improve readability and maintainability. - Centralize cost reconciliation, provider breakdown, trends building, and reset logic so behavior is easier to test and reuse. - Preserve existing backfill/self-heal behavior when usage summaries are incomplete while reducing duplication in the main service. ### Description - Added a new helper package `backend/services/subscription/usage_tracking_helpers` with `__init__.py` exporting the helper API. - Implemented `usage_reset_helpers.reset_usage_summary_counters` to encapsulate summary reset behavior and replaced inline reset logic in `UsageTrackingService.reset_current_billing_period` with a call to `reset_usage_summary_counters`. - Implemented `usage_stats_helpers` providing `build_default_usage_percentages`, `build_empty_usage_response`, `build_provider_breakdown`, `calculate_final_total_cost`, and `maybe_persist_reconciled_costs` to handle provider cost resolution, percentage calculations, and optional DB persistence of reconciled costs, and replaced the verbose inlined code in `get_user_usage_stats` with calls to these helpers. - Implemented `usage_trends_helpers` providing `build_billing_periods`, `query_usage_summaries`, `self_heal_summaries_from_logs`, and `build_usage_trends_response`, and refactored `get_usage_trends` to use these helpers for period construction, summary queries, self-healing from logs, and response assembly. - Added a defensive `ValueError` check in `get_user_usage_stats` when `user_id` is missing and adjusted imports in `usage_tracking_service.py` to use the new helper functions. ### Testing - No automated tests were executed as part of this rollout. ------ [Codex Task](https://chatgpt.com/codex/tasks/task_e_69b173dae06c83289f203cebf2319092) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

kerem

2026-03-13 21:05:20 +03:00

closed this issue
added the
pull-request
label

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/ALwrity#713

No description provided.

Rows
Columns