feat(api): SP-2 PR-B · dashboard aggregation endpoints + candidates surface (AIN-263/264/265/266)

[hizrianraz]

Summary

Lands the four read-only endpoints the /dashboard Glance page reads — until this router landed, all three GETs 404'd and the front door crashed (digest 3541235483). The candidates surface on /v1/inferences/{id}/decision is additive (byte-reproducible candidates[] unchanged; dashboard_candidates[] is the new collapsed shape SP-3 renders).

Stacks on SP-1 (#70). Base is chore/sp1-inference-rename; merges AFTER that PR.

Endpoints (all tenant-scoped, §D3 honest-empty 200s)

• GET /v1/usage/daily?days=30 (AIN-263) — daily inference rollup. Empty tenant → days:[] zeros 200.
• GET /v1/caps/rollup (AIN-264) — caps utilization snapshot. budget.set sums spend_policy.daily_cap_usd; latency_p50_ms from routing_outcomes (24h).
• GET /v1/agents/{id}/metrics (AIN-265) — 24h window. 404s cross-tenant (same masking as /v1/inferences/{id}/decision).
• /v1/inferences/{id}/decision (AIN-266) — adds dashboard_candidates: list[DashboardCandidate] parallel to candidates[]; each row carries chosen: bool + excluded: str | null.

Tests

• tests/unit/test_dashboard_candidates.py — 8 pure tests against candidate_dashboard_summary().
• tests/integration/test_dashboard.py — honest-empty 200s × 3; cross-tenant 404; tenant scoping; real-spend caps; candidates shape; no-mutation invariant on routing_outcomes.
• tests/smoke/test_openapi_contract.py — EXPECTED_OPERATIONS extended with the 3 new GETs.

Pre-commit ran ruff + ruff-format + mypy --strict + pytest (unit + smoke) — all green.

Test plan

• CI green
• Branch preview: curl /v1/usage/daily with fresh ai_infera_* key → 200 + days:[] (honest empty)
• After a real inference: /v1/usage/daily shows one entry, /v1/inferences/{id}/decision carries dashboard_candidates[]
• Cross-tenant GET /v1/agents/{otherA}/metrics with tenant B's key → 404
• /v1/caps/rollup with no §16 traffic returns latency_p50_ms: null (not 0, not error)

🤖 Generated with Claude Code

---

Note

Low Risk
Read-only SELECT aggregations with existing tenant auth and 404 masking; no schema or routing-brain write paths changed beyond an additive decision field.

Overview
Adds read-only, tenant-scoped dashboard APIs so the Glance page can load without 404s: GET /v1/usage/daily (daily calls/cost/status rollup, up to 90 days, empty tenants get days:[] and zero totals), GET /v1/caps/rollup (agent count, budget caps vs today’s spend, 24h p50 latency, quality/reliability breach counts), and GET /v1/agents/{agent_id}/metrics (24h calls, cost, p50, last active, top models; 404 for other tenants’ agents).

Extends GET /v1/inferences/{id}/decision with additive dashboard_candidates (collapsed model/score/cost/chosen/excluded) alongside the existing candidates receipt, via candidate_dashboard_summary in the new dashboard router. Registers the router in main.py; OpenAPI smoke tests list the three new GETs. Integration/unit tests cover honest-empty 200s, tenant isolation, caps with real traffic, decision shape, and no writes to routing_outcomes.

Note: per-day by_status.fallback is always 0 in v0 (audit-based fallback counting deferred).

^{Reviewed by Cursor Bugbot for commit a7f63ca. Bugbot is set up for automated code reviews on this repo. Configure here.}

[linear-code]

AIN-263 [parity-spine B-A · backend] GET /v1/usage/daily — per-day spend series

Spawned from AIN-217 Phase 3–4 parity spine (Bucket 2 — backend, missing endpoint).

What

GET /v1/usage/daily — per-day spend series. Currently 404.

Unblocks

• /dashboard daily-spend chart (currently honest "ACCRUING" empty-state)
• /billing 30-bar spend chart

Scope

• FastAPI endpoint on api.ainfera.ai, derived from real inference cost data (inferences.cost_usd / routing_outcomes).
• Real aggregation only — no fabricated series (§D3). FE empty-states stay honest until live.
• Alembic if any schema needed; RLS on; authed per tenant.

Done

• curl-200 with real per-day series · FE charts populate · holds on prod

Review in Linear

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is ON, but it could not run because the branch was deleted or merged before autofix could start.}

^{Reviewed by Cursor Bugbot for commit a7f63ca. Configure here.}

[cursor]

Dashboard cost field wrong key

Medium Severity

candidate_dashboard_summary reads cost_projected_usd from each §16 candidate dict, but routing_outcomes JSONB stores per-candidate cost as projected_cost_usd. Live dashboard_candidates[].cost is always null even when projected costs were recorded.

 

^{Reviewed by Cursor Bugbot for commit a7f63ca. Configure here.}