Skip to content

feat(admin): LLM token-usage analytics aggregation endpoints #525

@Ar1anit

Description

@Ar1anit

Summary

Follow-up to #522 (anonymous per-feature token-usage tracking). Once LlmUsageEvent rows exist, build read-only admin analytics aggregation endpoints so we can see how users interact with AI features in terms of tokens and cost.

Depends on #522 being merged (the data source).

Motivation

Scope

  • Aggregation queries over LlmUsageEvent (group by feature, tier, language, day) — sums of promptTokens/completionTokens/totalTokens/estimatedCostUsd, plus call counts and success rate.
  • New admin-only endpoints under /api/v1/admin/llm-usage/*, gated by the existing ADMIN_EMAILS allow-list (same pattern as the other /admin/* routes).
  • Time-range + group-by query params.
  • No per-user drill-down that could de-anonymize (only aggregates, or grouped by actorHash at most for cohort sequences — never resolvable back to a User).
  • Docs sync (ARCHITECTURE.md, README.md, .github/copilot-instructions.md).

Out of scope

  • Frontend dashboard UI (can be a further follow-up).
  • ML model (tracked separately).

Acceptance criteria

  • Aggregation endpoints return correct sums/counts over LlmUsageEvent.
  • Endpoints are admin-gated and return 403 for non-admins.
  • No endpoint can map an actorHash back to a real user.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions