Attribution: project + user tags and per-project budgets (burn vs budget)

[vivekchand]

Priority: P0 for team use — "what did this project spend on tokens, against its budget?"

Problem

• "By team" usage (routes/usage.py:3713) groups by a per-runtime team_mapping and falls back to the runtime name (local_store.py:12306). It isn't per project or per user.
• Per-user/org fields exist only for OTLP (local_store.py:1887).
• There is a single global budget (routes/alerts.py:818).

Proposal (v1)

• A project tag on every session, resolved in order: CLAWMETRY_PROJECT env → git remote → cwd root. User = OS user (or OTLP user.email).
• Budgets per project: an amount and period, with alerts at 50/80/100% and a daily burn chart.
• CSV export per project and per user (extend /api/usage/export, routes/usage.py:3112).

Done when

• Two repos on one machine show as two projects with separate spend
• A budget alert fires in a test at 80%
• Works for Claude Code, Codex and Copilot sessions

Enterprise planning refinement, 13 September 2026

The specific requirements below refine the original scope and supersede conflicting implementation assumptions. Existing findings and discussion remain available.

Identity and budget refinement

Inspect the shipped principal/owner model and open PR #5204 before changing metadata. That PR extends derived principal inheritance; do not create a competing user/team identity schema or restamp history on every label edit.

Separate organization boundary, human/service principal, project/client engagement and execution/session. OS usernames and OTel email tags are hints, not authoritative tenant membership. Environment/git/cwd-derived project suggestions need source/confidence and a visible unassigned fallback; avoid publishing raw local paths or emails in shared metrics.

• Authorized mapping supports historical periods and corrections with provenance. Two repos sharing a remote/path naming convention do not silently collapse into one client project.
• Each budget declares period/timezone/currency and financial basis. Alerts are distinct from routed enforcement; observing spend cannot retroactively prevent a charge.
• Exports and downstream reports include assigned/unassigned/unpriced amounts and completeness; runtime/gateway overlap follows LiteLLM integration: proxy callback / OTel ingestion + spend-log import #5940 rather than double counting.
• Test two projects, two users on one host, a service principal, a forged tenant/project claim, a membership change, late events and a period boundary.
• Cross-team report aggregation/authorization is implemented in the cloud membership/report surfaces; the OSS endpoint continues to persist/query DuckDB facts and gated contracts.

Related #5936/#5937/#5940 and VDI #5942. Run-level token/line totals must not be presented as an individual productivity score.

[vivekchand]

PR: #5965 (CI green, mergeable, not merged)

What it delivers

• LiteLLM's OpenTelemetry export is recognised. Each proxied request becomes one gateway usage record.
  • Team, user and key come only from the key LiteLLM authenticated. A team_id in the request body is ignored.
  • Cost is LiteLLM's own figure, labelled as gateway-reported, in USD. Missing cost shows as not reported, never $0.
  • Models, tokens, streaming, status, and trace / parent / response ids are kept.
• Redelivery is idempotent. A cache replay is counted but not charged, in either arrival order. Failures are counted per team.
• Gateway records are kept apart from agent costs:
  • they create no sessions and carry no span cost
  • they are excluded from the app and org rollups and from the Agents tab graph
  • overlap with agents is reported as correlated / uncorrelated requests
• /api/usage/by-team gains a gateway block (no new route). The Usage tab's Cost by Team card shows it with every label escaped.
• A real LiteLLM 1.83.7 proxy (Postgres, two teams, two keys) runs in CI. Per-team spend matched LiteLLM's /spend/logs with residual 0, and was unchanged after a dashboard restart.
• Requirement: https://factory.8090.ai/project/b415065f-ab2f-4f53-8864-0c009fd098cb/requirements/9511c826-af04-4dcf-978b-90803f27fb04 (AC-OBS-GWY-001.1 to .10, each cited by tests).

What remains

• No importer for LiteLLM's database or /spend/logs. The export already carries cost and identity, and /spend/logs is used only as the CI reconciliation source.
• The per-team residual against LiteLLM's records is printed in CI, not shown in the dashboard.
• Scoping which gateway may claim which tenant depends on scoped ingest keys (feat(ingest): let a scoped ingest key authenticate /v1/* and /api/v1/*, so an agent off-box can be observed #5679 / feat(ingest): open the front door — ingest key, generated contract, setup prompt, live status #5684).
• Cache-read / cache-write token categories are parsed but not verified against a real provider.
• Agent correlation uses shared trace context only; there is no fallback by provider request id.
• Retries inside LiteLLM appear as one request with its final outcome.
• The Prisma engine binaries in the CI job are not hash-pinned.
• No recorded video walkthrough.
• Handled elsewhere: price books (Pricing: custom price book for negotiated rates + Azure OpenAI deployment aliases #5936), cost labels on other surfaces (Cost figures: label vendor-reported vs contract vs estimated everywhere; split actual spend from API-equivalent #5937), per-project budgets (Attribution: project + user tags and per-project budgets (burn vs budget) #5941), durable acknowledgements (OTLP intake: durable acknowledgements, recovery and unsampled usage accounting #5949), the hosted dashboard.

[vivekchand]

Status 2026-09-14: the PR for this issue is #5968 (project attribution and per-project budgets). It is open and conflicts with main, so it needs a rebase. The earlier comment here describes #5965, which is the LiteLLM PR for #5940.