AI FinOps — spend governance

​

Motivation / problem

​

Theory & background

​

Design

​

Real per-turn cost on every chat log (W3)

​

Data model / contract

• PHP — the ai-finops:* Artisan commands (report, capture-prices, check-alerts, prune) + the package services.
• HTTP — api/admin/ai-finops/* (read dashboard/kpis, usage, budgets, footprint/summary, forecast, audit, … ; write budgets, policies, cost-centers, settings/kill-switch, …).
• MCP — three read tools on the enterprise-kb server (v8.16/W4), tenant-scoped (R30) and OFF-path safe (R43): FinOpsSpendSummaryTool (total cost + tokens + per-(provider, model) breakdown over a window), FinOpsTopModelsTool (costliest models with cost-share), and FinOpsBudgetStatusTool (each tenant-scoped budget’s limit / spend / state, delegating to Budget::status()).

AI_FINOPS_ENABLED=true          # master switch (routes + metering hook)
AI_FINOPS_METERING=true         # record usage into the ledger + resolve chat cost
AI_FINOPS_ENFORCEMENT=false     # hard budget/policy HTTP-402 blocks (opt-in)
AI_FINOPS_CURRENCY=USD          # base = provider list-price currency
AI_FINOPS_DISPLAY_CURRENCY=EUR
AI_FINOPS_RETENTION_DAYS=730
AI_FINOPS_ADMIN_ENABLED=false   # React cockpit at /admin/ai-finops (opt-in)

​

Security & flags (R32 / R30 / R43)

• Method-aware authorization. Every privileged route sits behind App\Http\Middleware\FinOpsAuthorize: safe methods (GET/HEAD) require the viewAiFinOps gate (super-admin + admin); mutating methods (POST/PUT/PATCH/DELETE) require manageAiFinOps (super-admin only). The package controllers do no internal authorization — this middleware is the boundary, and it is regression-locked in AdminAuthorizationMatrixTest (R32).
• Secure-by-host override. The package default route stack is ['api'] + ['auth'] (no Sanctum, no tenant scope). The host config/ai-finops.php replaces it with EncryptCookies + StartSession + auth:sanctum + tenant.authorize (+ finops.authorize). The package’s health probe is wrapped too, so it is authenticated, not an anonymous uptime endpoint.
• Tenant isolation (R30). HostTenantResolver binds every ledger row to the active tenant; the MCP read tools filter every ledger / budget query by the active tenant and deliberately exclude global/cross-scope budgets (whose spend aggregates across tenants) — cross-tenant cost leakage is not possible through the API or MCP.
• Default-OFF surfaces (R43). Both master AI_FINOPS_ENABLED and the admin SPA AI_FINOPS_ADMIN_ENABLED degrade cleanly when off (routes unregistered → 404, never a 500); the MCP tools return an empty, well-formed payload when the ledger/budgets tables are absent. Hard enforcement (AI_FINOPS_ENFORCEMENT) is also default-OFF — observe first, then turn on blocking once budgets/policies are seeded.

​

Decision rationale (ADR-style)

• Package over a hand-rolled cost table. AskMyDocs used to keep static cost_rates in config/ai.php, but that is a price sheet, not governance — no ledger, no budgets, no per-tenant rollup, no enforcement. Adopting the maintained package buys the entire FinOps loop (and multi-source live pricing) instead of reinventing it. See architecture decisions.
• Provider transport migrated to the SDK (ADR 0015). v8.16/W2 reversed the long-standing raw-Http:: decision for the metered providers: routing chat + embeddings through laravel/ai makes metering, pricing and tenant attribution fire natively on the SDK’s own lifecycle events, instead of being bolted on by a bridge. Anthropic / Gemini / Regolo are fully SDK; OpenAI / OpenRouter are SDK for chat + embeddings.
• A bounded residual bridge, not a half-migration. The single path still on raw Http:: is the OpenAI / OpenRouter MCP with-tools turn, whose tool-call shape the SDK does not yet match the host’s loop on. AiCallMeter bridges only that turn into the same pricing pipeline, gated by bridgeShouldMeterChat() so nothing is double-counted. It retires entirely once the SDK’s tool surface lands.
• Server-side cost authority (W3). Per-turn cost is resolved once, server-side, at ChatLogManager time and persisted on chat_logs with a trace_id join to the ledger. The client no longer guesses cost from a static sheet — it renders the authoritative server number. The whole resolver is gated on AI_FINOPS_METERING so an off deployment pays nothing and stamps no dangling trace id.

​

Worked example

SELECT provider, model, tokens_input, tokens_output, cost_total, tenant_id, cost_method
FROM ai_finops_usage_ledger
ORDER BY id DESC LIMIT 1;
-- openrouter | openai/gpt-4o-mini | 812 | 143 | 0.00024100 | acme | computed

SELECT ai_provider, cost, cost_currency, trace_id FROM chat_logs ORDER BY id DESC LIMIT 1;
-- openrouter | 0.00024100 | USD | 9f1c…  (== the ledger row's trace_id)

curl https://host/api/admin/ai-finops/dashboard/kpis \
  -H "Cookie: <authenticated SPA session>" \
  -H "X-Tenant-Id: acme"
# 200 → { "spend_today": 1.84, "spend_month": 47.10, "top_model": "...", ... }

​

Gotchas & operations

• Currency. Budgets compare against spend in the base currency (USD, matching provider list prices); EUR is display-only. Set an FX provider to budget in another currency.
• Enforcement is off by default. Seed budgets/policies first, then flip AI_FINOPS_ENFORCEMENT=true — turning it on with no budgets does nothing; with a mis-scoped hard budget it can 402 live traffic.
• Pre-flight enforcement is bounded to the SDK path. Hard budget/policy blocks (HTTP 402) fire on the SDK-metered calls; the residual raw-Http:: MCP tool turn is metered after the call, so it is recorded but not pre-flight blocked. It closes when the bridge retires.
• Cost resolution follows AI_FINOPS_METERING. With metering off, chat_logs rows carry null cost + no trace_id, and the resolver never touches the price feed — by design, so the off path is free and side-effect-less.
• Regolo manual pricing. Regolo is feed-less; enter its rates via pricing/overrides or it prices at zero.
• Fixed-precision decimal money (since v8.18, laravel-ai-finops v1.3.0). The package now also exposes every money value as a fixed-precision 8-dp decimal string under additive *_decimal keys, so small per-token costs survive serialisation without float-rounding drift. The host runs ^1.3; the three MCP read tools and ChatTurnCostResolver read the new shape while the existing numeric keys stay in place (additive — R27), so older clients are unaffected.