AI cost caps

Pact meters every model call into the ai_usage ledger — input tokens, output tokens, resolved cost_cents, feature, provider, and user. That ledger powers both the spend visibility dashboards and the hard caps that stop cost-drain.

There are two halves to AI cost control, and they are deliberately separate:

Visibility — dashboards that answer "what did AI cost, and where is it trending". Read-only, backed by the ai_usage ledger.
Enforcement — the AI budget gate that refuses calls once a cap is hit. This is the part that actually caps spend.

Metering is real

Cost is computed per call from real token counts and written to ai_usage (alembic 0143_ai_usage), with a daily materialized view (0187_mv_ai_usage_daily) for fast dashboards. Nothing here is a placeholder number.

Spend dashboards

Three admin/owner-only, tenant-scoped surfaces:

code

GET /v1/admin/ai-cost/overview       # KPI cards: totals, top features, projected MTD, budget alert
GET /v1/admin/ai-cost/by-provider    # per-provider spend
GET /v1/admin/ai-cost/ledger         # call-level drill-down (raw ai_usage rows)
GET /v1/admin/ai/cost-breakdown      # per-feature spend (with per-user drill-down)
GET /v1/admin/ai-usage/summary       # aggregate usage: totals + daily timeseries (also /by-feature, /by-user)

The overview and by-provider endpoints read the daily materialized view when present and fall back to the raw ai_usage table otherwise, so the numbers are correct even before the view refreshes. The overview returns totals, the top-spending features, a per-provider time series, and a linear month-to-date projection — average daily spend extrapolated across the remaining days of the month — so you see where you'll land, not just where you are.

Budget-alert level

The overview folds in your configured cap: if a tenant_ai_budget row exists, the response includes a _cap_alert_level computed from month-to-date spend against the cap and the alert_threshold_pct (default 80%). This is the same threshold surfaced on the budget page, so the visibility and enforcement surfaces agree.

Capping spend

Dashboards show you the trend; to actually stop spend you set caps on the AI budget page. Monthly and daily caps, per-user sub-caps, and call-rate limits are all enforced inside the AI client on every call — a breach raises an error and is logged to ai_budget_blocks.

Per-feature cost recommendations

The AI Hub surfaces per-feature cost via core.ai.cost_recommendations, so you can spot which features dominate spend and, where a cheaper model tier would do, adjust the feature's configuration.

AI budgetSet the caps that enforce this spend.Cost overviewAll-in per-tenant cost: AI, email, and infra.AI featuresInventory of every AI capability and its live state.AI data sharingControl what each feature sends to the model.