Usage Tracking

# From app/modules/usage/updater.py:55-93
async def refresh_accounts(
    self,
    accounts: list[Account],
    latest_usage: Mapping[str, UsageHistory],
) -> bool:
    """Refresh usage for all accounts. Returns True if usage rows were written."""
    settings = get_settings()
    if not settings.usage_refresh_enabled:
        return False

    refreshed = False
    now = utcnow()
    interval = settings.usage_refresh_interval_seconds
    for account in accounts:
        if account.status == AccountStatus.DEACTIVATED:
            continue
        latest = latest_usage.get(account.id)
        if latest and (now - latest.recorded_at).total_seconds() < interval:
            continue
        # Refresh this account's usage

# From app/modules/usage/updater.py:134-169
if primary and primary.used_percent is not None:
    entry = await self._usage_repo.add_entry(
        account_id=account.id,
        used_percent=float(primary.used_percent),
        window="primary",
        reset_at=_reset_at(primary.reset_at, primary.reset_after_seconds, now_epoch),
        window_minutes=_window_minutes(primary.limit_window_seconds),
    )

if secondary and secondary.used_percent is not None:
    entry = await self._usage_repo.add_entry(
        account_id=account.id,
        used_percent=float(secondary.used_percent),
        window="secondary",
        reset_at=_reset_at(secondary.reset_at, secondary.reset_after_seconds, now_epoch),
        window_minutes=_window_minutes(secondary.limit_window_seconds),
    )

CREATE TABLE usage_history (
    id INTEGER PRIMARY KEY,
    account_id TEXT NOT NULL,
    recorded_at TIMESTAMP NOT NULL,
    window TEXT,  -- 'primary' or 'secondary'
    used_percent REAL NOT NULL,
    input_tokens INTEGER,
    output_tokens INTEGER,
    reset_at INTEGER,  -- Unix timestamp
    window_minutes INTEGER,  -- Window duration in minutes
    credits_has BOOLEAN,
    credits_unlimited BOOLEAN,
    credits_balance REAL
);

# From app/modules/proxy/load_balancer.py:76-81
latest_primary = await repos.usage.latest_by_account()
updater = UsageUpdater(repos.usage, repos.accounts)
refreshed = await updater.refresh_accounts(accounts, latest_primary)
if refreshed:
    latest_primary = await repos.usage.latest_by_account()
latest_secondary = await repos.usage.latest_by_account(window="secondary")

# From app/core/balancer/logic.py:110-114
def _usage_sort_key(state: AccountState) -> tuple[float, float, float, str]:
    primary_used = state.used_percent if state.used_percent is not None else 0.0
    secondary_used = state.secondary_used_percent if state.secondary_used_percent is not None else primary_used
    last_selected = state.last_selected_at or 0.0
    return secondary_used, primary_used, last_selected, state.account_id

# From app/core/usage/quota.py:9-57
def apply_usage_quota(
    *,
    status: AccountStatus,
    primary_used: float | None,
    primary_reset: int | None,
    primary_window_minutes: int | None,
    runtime_reset: float | None,
    secondary_used: float | None,
    secondary_reset: int | None,
) -> tuple[AccountStatus, float | None, float | None]:
    # Secondary (quota) takes precedence
    if secondary_used is not None:
        if secondary_used >= 100.0:
            status = AccountStatus.QUOTA_EXCEEDED
            used_percent = 100.0
            if secondary_reset is not None:
                reset_at = secondary_reset
            return status, used_percent, reset_at
    
    # Then primary (rate limit)
    if primary_used is not None:
        if primary_used >= 100.0:
            status = AccountStatus.RATE_LIMITED
            used_percent = 100.0
            if primary_reset is not None:
                reset_at = primary_reset
            return status, used_percent, reset_at
    
    return status, used_percent, reset_at

# From app/modules/usage/updater.py:209-216
def _credits_snapshot(payload: UsagePayload) -> tuple[bool | None, bool | None, float | None]:
    credits = payload.credits
    if credits is None:
        return None, None, None
    credits_has = credits.has_credits
    credits_unlimited = credits.unlimited
    balance_value = credits.balance
    return credits_has, credits_unlimited, _parse_credits_balance(balance_value)

GET /api/usage

{
  "accounts": [
    {
      "account_id": "user-abc123",
      "email": "[email protected]",
      "plan_type": "plus",
      "status": "active",
      "used_percent_avg": 45.2,
      "reset_at": 1735689600,
      "window_minutes": 10080,  // 7 days
      "samples": 144,  // Data points in 28 days
      "last_recorded_at": "2024-12-31T23:55:00Z"
    }
  ],
  "since": "2024-12-04T00:00:00Z"
}

GET /api/usage/trends?account_id=user-abc123

{
  "buckets": [
    {
      "bucket_epoch": 1735660800,  // 6-hour bucket
      "account_id": "user-abc123",
      "window": "primary",
      "avg_used_percent": 32.5,
      "samples": 72
    },
    {
      "bucket_epoch": 1735682400,
      "account_id": "user-abc123",
      "window": "primary",
      "avg_used_percent": 48.1,
      "samples": 68
    }
  ],
  "bucket_seconds": 21600,  // 6 hours
  "since": "2024-12-04T00:00:00Z"
}

async def trends_by_bucket(
    self,
    since: datetime,
    bucket_seconds: int = 21600,  # 6 hours
    window: str | None = None,
    account_id: str | None = None,
) -> list[UsageTrendBucket]:
    # Floor timestamp to bucket boundary
    if dialect == "postgresql":
        bucket_expr = func.floor(func.extract("epoch", UsageHistory.recorded_at) / bucket_seconds) * bucket_seconds
    else:
        epoch_col = cast(func.strftime("%s", UsageHistory.recorded_at), Integer)
        bucket_expr = cast(epoch_col / bucket_seconds, Integer) * bucket_seconds
    
    # Aggregate within buckets
    stmt = (
        select(
            bucket_col,
            UsageHistory.account_id,
            window_expr.label("window"),
            func.avg(UsageHistory.used_percent).label("avg_used_percent"),
            func.count(UsageHistory.id).label("samples"),
        )
        .where(*conditions)
        .group_by(bucket_col, UsageHistory.account_id, window_expr)
        .order_by(bucket_col)
    )

# Enable/disable usage refresh (default: true)
USAGE_REFRESH_ENABLED=true

# Refresh interval in seconds (default: 300)
USAGE_REFRESH_INTERVAL_SECONDS=300

# Historical retention period (default: 28 days)
USAGE_RETENTION_DAYS=28

USAGE_REFRESH_ENABLED=false

CREATE INDEX idx_usage_recorded_at ON usage_history(recorded_at);
CREATE INDEX idx_usage_account_time ON usage_history(account_id, recorded_at);