codexLB-up 1.25.0b10__py3-none-any.whl

app/modules/conversation_archive/service.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import gzip
+import json
+import zlib
+from collections.abc import Iterator
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from app.core.config.settings import get_settings
+
+_JSONL_SUFFIX = ".jsonl"
+_GZIP_JSONL_SUFFIX = ".jsonl.gz"
+
+
+@dataclass(frozen=True)
+class ConversationArchivePage:
+    records: list[dict[str, Any]]
+    total: int
+    has_more: bool
+
+
+class ConversationArchiveNotFoundError(ValueError):
+    pass
+
+
+class ConversationArchiveInvalidFileError(ValueError):
+    pass
+
+
+def read_archive_records(
+    *,
+    filename: str | None,
+    limit: int,
+    offset: int,
+    direction: str | None = None,
+    kind: str | None = None,
+    transport: str | None = None,
+    request_id: str | None = None,
+    requested_at: datetime | None = None,
+) -> ConversationArchivePage:
+    paths = _archive_paths_for_lookup(filename=filename, requested_at=requested_at, request_id=request_id)
+    records: list[dict[str, Any]] = []
+    total = 0
+    end = offset + limit
+
+    for path in sorted(paths, key=lambda item: item.name):
+        for record in _iter_records(path):
+            if not _record_matches(
+                record,
+                direction=direction,
+                kind=kind,
+                transport=transport,
+                request_id=request_id,
+            ):
+                continue
+            if offset <= total < end:
+                records.append({**record, "_archive_file": path.name})
+            total += 1
+
+    return ConversationArchivePage(
+        records=records,
+        total=total,
+        has_more=end < total,
+    )
+
+
+def _archive_paths_for_lookup(
+    *,
+    filename: str | None,
+    requested_at: datetime | None,
+    request_id: str | None,
+) -> list[Path]:
+    if filename:
+        return [_resolve_archive_file(filename)]
+    directory = _archive_dir()
+    if requested_at is None:
+        return list(_iter_archive_paths(directory))
+
+    if request_id is not None:
+        return sorted(path for path in _iter_archive_paths(directory) if path.exists() and path.is_file())
+
+    requested_at_utc = requested_at.astimezone(UTC)
+    hourly_stems = [(requested_at_utc + timedelta(hours=delta)).strftime("%Y-%m-%dT%H") for delta in (-1, 0, 1)]
+    daily_stems = {
+        requested_at_utc.strftime("%Y-%m-%d"),
+        (requested_at_utc.date() - timedelta(days=1)).strftime("%Y-%m-%d"),
+        (requested_at_utc.date() + timedelta(days=1)).strftime("%Y-%m-%d"),
+    }
+    candidates: list[Path] = []
+    for stem in hourly_stems:
+        candidates.extend(
+            (
+                directory / f"{stem}{_GZIP_JSONL_SUFFIX}",
+                directory / f"{stem}{_JSONL_SUFFIX}",
+            )
+        )
+    for stem in daily_stems:
+        candidates.extend(
+            (
+                directory / f"{stem}{_GZIP_JSONL_SUFFIX}",
+                directory / f"{stem}{_JSONL_SUFFIX}",
+            )
+        )
+    return [path for path in candidates if path.exists() and path.is_file()]
+
+
+def _archive_dir() -> Path:
+    return Path(getattr(get_settings(), "conversation_archive_dir")).expanduser()
+
+
+def _iter_archive_paths(directory: Path) -> Iterator[Path]:
+    yield from directory.glob(f"*{_JSONL_SUFFIX}")
+    yield from directory.glob(f"*{_GZIP_JSONL_SUFFIX}")
+
+
+def _resolve_archive_file(filename: str) -> Path:
+    if Path(filename).name != filename or not (
+        filename.endswith(_JSONL_SUFFIX) or filename.endswith(_GZIP_JSONL_SUFFIX)
+    ):
+        raise ConversationArchiveInvalidFileError("Invalid conversation archive file name")
+
+    path = _archive_dir() / filename
+    if not path.exists() or not path.is_file():
+        raise ConversationArchiveNotFoundError("Conversation archive file not found")
+    return path
+
+
+def _iter_records(path: Path) -> Iterator[dict[str, Any]]:
+    opener = gzip.open if path.name.endswith(_GZIP_JSONL_SUFFIX) else Path.open
+    try:
+        with opener(path, "rt", encoding="utf-8") as fh:
+            for line in fh:
+                stripped = line.strip()
+                if not stripped:
+                    continue
+                try:
+                    parsed = json.loads(stripped)
+                except json.JSONDecodeError:
+                    continue
+                if isinstance(parsed, dict):
+                    yield parsed
+    except (EOFError, gzip.BadGzipFile, zlib.error):
+        return
+
+
+def _record_matches(
+    record: dict[str, Any],
+    *,
+    direction: str | None,
+    kind: str | None,
+    transport: str | None,
+    request_id: str | None,
+) -> bool:
+    if direction and record.get("direction") != direction:
+        return False
+    if kind and record.get("kind") != kind:
+        return False
+    if transport and record.get("transport") != transport:
+        return False
+    if request_id and str(record.get("request_id") or "") != request_id:
+        return False
+    return True

app/modules/dashboard/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

app/modules/dashboard/api.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query
+
+from app.core.auth.dashboard_access import DashboardPrincipal, Permission
+from app.core.auth.dependencies import (
+    require_dashboard_permission,
+    set_dashboard_error_format,
+    validate_dashboard_session,
+)
+from app.core.openai.model_registry import get_model_registry, is_public_model
+from app.db.session import detach_session_objects, get_background_session
+from app.dependencies import DashboardContext, get_dashboard_context
+from app.modules.dashboard.schemas import (
+    DashboardOverviewResponse,
+    DashboardOverviewTimeframeKey,
+    DashboardProjectionsResponse,
+)
+from app.modules.model_sources.catalog import source_models_to_upstream_models
+from app.modules.model_sources.repository import ModelSourcesRepository
+
+router = APIRouter(
+    prefix="/api",
+    tags=["dashboard"],
+    dependencies=[Depends(validate_dashboard_session), Depends(set_dashboard_error_format)],
+)
+
+
+@router.get(
+    "/dashboard/overview",
+    response_model=DashboardOverviewResponse,
+    dependencies=[Depends(require_dashboard_permission(Permission.ACCOUNTS_READ))],
+)
+async def get_overview(
+    timeframe: DashboardOverviewTimeframeKey = Query("7d"),
+    principal: DashboardPrincipal = Depends(validate_dashboard_session),
+    context: DashboardContext = Depends(get_dashboard_context),
+) -> DashboardOverviewResponse:
+    return await context.service.get_overview(
+        timeframe,
+        redact_identity=not principal.has(Permission.ACCOUNTS_WRITE),
+    )
+
+
+@router.get(
+    "/dashboard/projections",
+    response_model=DashboardProjectionsResponse,
+    dependencies=[Depends(require_dashboard_permission(Permission.ACCOUNTS_READ))],
+)
+async def get_projections(
+    context: DashboardContext = Depends(get_dashboard_context),
+) -> DashboardProjectionsResponse:
+    return await context.service.get_projections()
+
+
+@router.get("/models", dependencies=[Depends(require_dashboard_permission(Permission.DASHBOARD_READ))])
+async def list_models() -> dict:
+    registry = get_model_registry()
+    models_by_slug = registry.get_models_with_fallback()
+    if not models_by_slug:
+        return {"models": []}
+    allowed_efforts = {"minimal", "low", "medium", "high", "xhigh", "max", "ultra"}
+
+    def _normalize_effort(value: str | None) -> str | None:
+        if not isinstance(value, str):
+            return None
+        normalized = value.strip().lower()
+        if normalized in allowed_efforts:
+            return normalized
+        return None
+
+    models = [
+        {
+            "id": slug,
+            "name": model.display_name or slug,
+            "sourceOnly": False,
+            "supportedReasoningEfforts": list(
+                dict.fromkeys(
+                    effort
+                    for effort in (_normalize_effort(level.effort) for level in model.supported_reasoning_levels)
+                    if effort is not None
+                )
+            ),
+            "defaultReasoningEffort": _normalize_effort(model.default_reasoning_level),
+        }
+        for slug, model in models_by_slug.items()
+        if is_public_model(model, None)
+    ]
+    # The API-key "allowed models" picker must offer OpenAI-compatible source
+    # models too, or source-scoped allowlists cannot be configured in the UI.
+    seen_slugs = set(models_by_slug)
+    async with get_background_session() as session:
+        sources = await ModelSourcesRepository(session).list_enabled_sources()
+        detach_session_objects(session)
+    for source_model in source_models_to_upstream_models(sources):
+        if source_model.slug in seen_slugs:
+            continue
+        seen_slugs.add(source_model.slug)
+        models.append(
+            {
+                "id": source_model.slug,
+                "name": source_model.display_name or source_model.slug,
+                "sourceOnly": True,
+            }
+        )
+    return {"models": models}

app/modules/dashboard/builders.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from app.core import usage as usage_core
+from app.core.usage.types import UsageWindowRow
+from app.db.models import Account
+from app.modules.dashboard.schemas import (
+    DashboardMetricsComparison,
+    DashboardOverviewSummary,
+    DashboardOverviewTimeframe,
+    DashboardOverviewTimeframeKey,
+    DashboardUsageCost,
+    DashboardUsageMetrics,
+)
+from app.modules.usage.builders import (
+    ActivityCostSummary,
+    ActivityMetricsSummary,
+    build_usage_window_summary_model,
+)
+
+
+@dataclass(frozen=True)
+class DashboardOverviewTimeframeConfig:
+    key: DashboardOverviewTimeframeKey
+    window_minutes: int
+    bucket_seconds: int
+    bucket_count: int
+
+
+_OVERVIEW_TIMEFRAME_CONFIGS: dict[DashboardOverviewTimeframeKey, DashboardOverviewTimeframeConfig] = {
+    "1d": DashboardOverviewTimeframeConfig(
+        key="1d",
+        window_minutes=1440,
+        bucket_seconds=3600,
+        bucket_count=24,
+    ),
+    "7d": DashboardOverviewTimeframeConfig(
+        key="7d",
+        window_minutes=10080,
+        bucket_seconds=21600,
+        bucket_count=28,
+    ),
+    "30d": DashboardOverviewTimeframeConfig(
+        key="30d",
+        window_minutes=43200,
+        bucket_seconds=86400,
+        bucket_count=30,
+    ),
+}
+
+
+def resolve_overview_timeframe(
+    key: DashboardOverviewTimeframeKey,
+) -> DashboardOverviewTimeframeConfig:
+    return _OVERVIEW_TIMEFRAME_CONFIGS[key]
+
+
+def build_overview_timeframe(
+    config: DashboardOverviewTimeframeConfig,
+) -> DashboardOverviewTimeframe:
+    return DashboardOverviewTimeframe(
+        key=config.key,
+        windowMinutes=config.window_minutes,
+        bucketSeconds=config.bucket_seconds,
+        bucketCount=config.bucket_count,
+    )
+
+
+def build_dashboard_overview_summary(
+    *,
+    accounts: list[Account],
+    primary_rows: list[UsageWindowRow],
+    secondary_rows: list[UsageWindowRow],
+    activity_cost: ActivityCostSummary,
+    activity_metrics: ActivityMetricsSummary,
+    comparison: DashboardMetricsComparison | None = None,
+) -> DashboardOverviewSummary:
+    account_map = {account.id: account for account in accounts}
+    primary_summary = usage_core.summarize_usage_window(primary_rows, account_map, "primary")
+    secondary_summary = usage_core.summarize_usage_window(secondary_rows, account_map, "secondary")
+
+    primary_window = build_usage_window_summary_model(usage_core.normalize_usage_window(primary_summary))
+    secondary_window = build_usage_window_summary_model(usage_core.normalize_usage_window(secondary_summary))
+
+    return DashboardOverviewSummary(
+        primary_window=primary_window,
+        secondary_window=secondary_window,
+        cost=DashboardUsageCost(
+            currency=activity_cost.currency,
+            totalUsd=activity_cost.total_usd,
+        ),
+        metrics=DashboardUsageMetrics.model_validate(
+            {
+                "requests": activity_metrics.requests,
+                "tokens": activity_metrics.tokens,
+                "cached_input_tokens": activity_metrics.cached_input_tokens,
+                "error_rate": activity_metrics.error_rate,
+                "error_count": activity_metrics.error_count,
+                "cancelled_count": activity_metrics.cancelled_count,
+                "top_error": activity_metrics.top_error,
+                "conversations": activity_metrics.conversation_count,
+                "conversation_requests": activity_metrics.conversation_request_count,
+            }
+        ),
+        comparison=comparison,
+    )

app/modules/dashboard/repository.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime
+
+from sqlalchemy import case, func, select, union_all
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.usage.types import BucketConversationAggregate, BucketModelAggregate, RequestActivityAggregate
+from app.db.models import (
+    Account,
+    AccountLimitWarmup,
+    ApiKey,
+    DashboardSettings,
+    RequestLog,
+    UsageHistory,
+)
+from app.modules.accounts.repository import AccountsRepository
+from app.modules.limit_warmup.repository import LimitWarmupRepository
+from app.modules.request_logs.repository import RequestLogsRepository
+from app.modules.settings.repository import SettingsRepository
+from app.modules.usage.repository import (
+    AdditionalUsageRepository,
+    NormalizedUsageWindow,
+    UsageHistorySnapshot,
+    UsageRepository,
+)
+
+# The weekly credit pace's trailing-demand aggregate (a LAG window over seven
+# days of usage_history per account) is re-run by every /dashboard/overview
+# and /dashboard/projections poll although the displayed pace tolerates short
+# staleness. Cache it per account->window signature for a small fixed TTL,
+# mirroring the request-log COUNT cache (app/modules/request_logs/repository.py);
+# the test suite patches the TTL to 0 so pace figures stay exact within a test.
+_TRAILING_DEMAND_TTL_SECONDS = 60.0
+_TRAILING_DEMAND_MAX_ENTRIES = 16
+# (window span in whole seconds, sorted account -> window pairs)
+_TrailingDemandKey = tuple[int, tuple[tuple[str, NormalizedUsageWindow], ...]]
+_trailing_demand_cache: dict[_TrailingDemandKey, tuple[dict[str, float], float]] = {}
+
+
+def _clear_trailing_demand_cache() -> None:
+    _trailing_demand_cache.clear()
+
+
+def _cached_trailing_demand(key: _TrailingDemandKey) -> dict[str, float] | None:
+    entry = _trailing_demand_cache.get(key)
+    if entry is None:
+        return None
+    deltas, expires_at = entry
+    if time.monotonic() >= expires_at:
+        _trailing_demand_cache.pop(key, None)
+        return None
+    return deltas
+
+
+def _store_trailing_demand(key: _TrailingDemandKey, deltas: dict[str, float], ttl_seconds: float) -> None:
+    if len(_trailing_demand_cache) >= _TRAILING_DEMAND_MAX_ENTRIES:
+        oldest = min(_trailing_demand_cache, key=lambda existing: _trailing_demand_cache[existing][1])
+        _trailing_demand_cache.pop(oldest, None)
+    _trailing_demand_cache[key] = (deltas, time.monotonic() + ttl_seconds)
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyAttributionRow:
+    api_key_id: str | None
+    name: str
+    requests: int
+    billable_tokens: int
+    cached_tokens: int
+    dominant_model: str
+
+
+class DashboardRepository:
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+        self._accounts_repo = AccountsRepository(session)
+        self._usage_repo = UsageRepository(session)
+        self._logs_repo = RequestLogsRepository(session)
+        self._additional_usage_repo = AdditionalUsageRepository(session)
+        self._limit_warmup_repo = LimitWarmupRepository(session)
+        self._settings_repo = SettingsRepository(session)
+
+    async def list_accounts(self) -> list[Account]:
+        return await self._accounts_repo.list_accounts()
+
+    async def latest_usage_by_account(self, window: str) -> dict[str, UsageHistory]:
+        return await self._usage_repo.latest_by_account(window=window)
+
+    async def bulk_usage_history_since(
+        self,
+        account_ids: list[str],
+        window: str,
+        since: datetime,
+        *,
+        cutoffs: dict[str, datetime] | None = None,
+        per_account_row_cap: int | None = None,
+        uncapped_recent_floor: datetime | None = None,
+    ) -> dict[str, list[UsageHistorySnapshot]]:
+        return await self._usage_repo.bulk_history_since(
+            account_ids,
+            window,
+            since,
+            cutoffs=cutoffs,
+            per_account_row_cap=per_account_row_cap,
+            uncapped_recent_floor=uncapped_recent_floor,
+        )
+
+    async def latest_window_minutes(self, window: str) -> int | None:
+        return await self._usage_repo.latest_window_minutes(window)
+
+    async def positive_used_percent_deltas_by_account(
+        self,
+        account_windows: Mapping[str, NormalizedUsageWindow],
+        *,
+        since: datetime,
+        until: datetime,
+    ) -> dict[str, float]:
+        """Trailing positive used-percent deltas, memoized per window span and account->window signature.
+
+        The key carries the span ``until - since`` but not the bounds themselves:
+        both dashboard callers pass a trailing window anchored at ``now``, so
+        within the TTL the window drifts by at most the TTL and the figure is
+        display-only. A different span, account set or window mapping is its
+        own key.
+        """
+        ttl_seconds = _TRAILING_DEMAND_TTL_SECONDS
+        cache_key: _TrailingDemandKey = (
+            round((until - since).total_seconds()),
+            tuple(sorted(account_windows.items())),
+        )
+        if ttl_seconds > 0:
+            cached = _cached_trailing_demand(cache_key)
+            if cached is not None:
+                return dict(cached)
+        deltas = await self._usage_repo.positive_used_percent_deltas_by_account(
+            account_windows,
+            since=since,
+            until=until,
+        )
+        if ttl_seconds > 0:
+            _store_trailing_demand(cache_key, deltas, ttl_seconds)
+        return dict(deltas)
+
+    async def aggregate_logs_by_bucket(
+        self,
+        since: datetime,
+        bucket_seconds: int = 21600,
+    ) -> list[BucketModelAggregate]:
+        return await self._logs_repo.aggregate_by_bucket(since, bucket_seconds)
+
+    async def aggregate_conversations_by_bucket(
+        self,
+        since: datetime,
+        bucket_seconds: int = 21600,
+    ) -> list[BucketConversationAggregate]:
+        return await self._logs_repo.aggregate_conversations_by_bucket(since, bucket_seconds)
+
+    async def aggregate_activity_since(self, since: datetime) -> RequestActivityAggregate:
+        return await self._logs_repo.aggregate_activity_since(since)
+
+    async def aggregate_activity_between(
+        self,
+        since: datetime,
+        until: datetime,
+    ) -> RequestActivityAggregate:
+        return await self._logs_repo.aggregate_activity_between(since, until)
+
+    async def top_error_since(self, since: datetime) -> str | None:
+        return await self._logs_repo.top_error_since(since)
+
+    async def top_error_between(self, since: datetime, until: datetime) -> str | None:
+        return await self._logs_repo.top_error_between(since, until)
+
+    async def earliest_activity_at(self) -> datetime | None:
+        return await self._logs_repo.earliest_activity_at()
+
+    async def top_api_key_attribution_since(
+        self,
+        since: datetime,
+        *,
+        now: datetime,
+        per_metric_limit: int = 3,
+    ) -> list[ApiKeyAttributionRow]:
+        key_name = func.coalesce(func.nullif(ApiKey.name, ""), "(unnamed)")
+        billable_tokens = func.coalesce(RequestLog.input_tokens, 0) + func.coalesce(
+            RequestLog.output_tokens, RequestLog.reasoning_tokens, 0
+        )
+        grouped_models = (
+            select(
+                RequestLog.api_key_id.label("api_key_id"),
+                key_name.label("name"),
+                RequestLog.model.label("model"),
+                func.count(RequestLog.id).label("requests"),
+                func.coalesce(func.sum(billable_tokens), 0).label("billable_tokens"),
+                func.coalesce(func.sum(RequestLog.cached_input_tokens), 0).label("cached_tokens"),
+            )
+            .select_from(RequestLog)
+            .outerjoin(ApiKey, ApiKey.id == RequestLog.api_key_id)
+            .where(
+                RequestLog.requested_at >= since,
+                RequestLog.requested_at <= now,
+                RequestLog.deleted_at.is_(None),
+                # Warmup probes are internal traffic and must not surface as
+                # top consumers, matching the request-log usage queries.
+                RequestLogsRepository._exclude_warmup_clause(),
+            )
+            .group_by(RequestLog.api_key_id, key_name, RequestLog.model)
+            .cte("weekly_pace_key_models")
+        )
+        ranked_models = select(
+            grouped_models,
+            func.row_number()
+            .over(
+                partition_by=grouped_models.c.api_key_id,
+                order_by=(
+                    grouped_models.c.requests.desc(),
+                    grouped_models.c.billable_tokens.desc(),
+                    grouped_models.c.model.asc(),
+                ),
+            )
+            .label("model_rank"),
+        ).cte("weekly_pace_ranked_models")
+        key_totals = (
+            select(
+                ranked_models.c.api_key_id,
+                func.max(ranked_models.c.name).label("name"),
+                func.sum(ranked_models.c.requests).label("requests"),
+                func.sum(ranked_models.c.billable_tokens).label("billable_tokens"),
+                func.sum(ranked_models.c.cached_tokens).label("cached_tokens"),
+                func.max(
+                    case(
+                        (ranked_models.c.model_rank == 1, ranked_models.c.model),
+                        else_=None,
+                    )
+                ).label("dominant_model"),
+            )
+            .group_by(ranked_models.c.api_key_id)
+            .cte("weekly_pace_key_totals")
+        )
+        top_by_requests = (
+            select(key_totals)
+            .order_by(
+                key_totals.c.requests.desc(),
+                key_totals.c.billable_tokens.desc(),
+                key_totals.c.api_key_id.asc(),
+            )
+            .limit(per_metric_limit)
+            .subquery("weekly_pace_top_requests")
+        )
+        top_by_billable = (
+            select(key_totals)
+            .order_by(
+                key_totals.c.billable_tokens.desc(),
+                key_totals.c.requests.desc(),
+                key_totals.c.api_key_id.asc(),
+            )
+            .limit(per_metric_limit)
+            .subquery("weekly_pace_top_billable")
+        )
+        candidates = union_all(
+            select(top_by_requests),
+            select(top_by_billable),
+        ).cte("weekly_pace_key_candidates")
+        statement = (
+            select(
+                candidates.c.api_key_id,
+                func.max(candidates.c.name).label("name"),
+                func.max(candidates.c.requests).label("requests"),
+                func.max(candidates.c.billable_tokens).label("billable_tokens"),
+                func.max(candidates.c.cached_tokens).label("cached_tokens"),
+                func.max(candidates.c.dominant_model).label("dominant_model"),
+            )
+            .group_by(candidates.c.api_key_id)
+            .order_by(
+                func.max(candidates.c.requests).desc(),
+                func.max(candidates.c.billable_tokens).desc(),
+                candidates.c.api_key_id.asc(),
+            )
+            .limit(per_metric_limit * 2)
+        )
+        rows = (await self._session.execute(statement)).all()
+        return [
+            ApiKeyAttributionRow(
+                api_key_id=str(row.api_key_id) if row.api_key_id is not None else None,
+                name=str(row.name),
+                requests=int(row.requests),
+                billable_tokens=int(row.billable_tokens),
+                cached_tokens=int(row.cached_tokens),
+                dominant_model=str(row.dominant_model),
+            )
+            for row in rows
+        ]
+
+    async def latest_additional_recorded_at(self) -> datetime | None:
+        return await self._additional_usage_repo.latest_recorded_at()
+
+    async def latest_limit_warmups_by_account(self, account_ids: list[str]) -> dict[str, AccountLimitWarmup]:
+        return await self._limit_warmup_repo.latest_by_account(account_ids)
+
+    async def get_settings(self) -> DashboardSettings:
+        return await self._settings_repo.get_or_create()