# AI Budget & Cost Governance Roadmap

> **Purpose:** Add per-tenant and per-agent controls for model spend, quotas,
> budgets, alerts, and invoiceable AI usage.
>
> **Primary Surface:** `services/platform-service/`
>
> **Status:** Planned
>
> **Estimated Effort:** 2-3 weeks

---

## Why This Is Missing

Model usage is often more volatile than standard API usage. Agent companies need
controls for:

- daily and monthly spend caps
- per-workspace or per-agent budgets
- model allowlists and deny rules
- burst protection
- usage attribution for billing

The repo has usage and billing modules, but not a dedicated AI cost governance layer.

---

## Recommended Stack

- `platform-service` cost governance module
- usage ledger in Cosmos or PostgreSQL
- provider-specific pricing tables
- alerting through Slack, Telegram, and email

### Recommendation

This fits naturally in `platform-service`. The key is not the datastore; it is the
quality of attribution and enforcement.

### Default Decision For This Repo

- Implement this inside `platform-service`
- Treat run/request attribution as mandatory
- Make budget checks part of the request path for expensive AI calls, not reporting-only

---

## Dependencies

- Org, Workspace & RBAC
- Agent Runtime & Orchestration

---

## V1 Non-Goals

- Full finance ERP integration
- Provider contract optimization tooling
- Perfect real-time cost accuracy across every vendor

---

## Phase 1 - Usage Ledger

- [ ] Create modules:
  - [ ] `ai-usage`
  - [ ] `ai-budgets`
  - [ ] `ai-pricing`
- [ ] Store:
  - [ ] tenant
  - [ ] workspace
  - [ ] agent
  - [ ] provider
  - [ ] model
  - [ ] tokens or units
  - [ ] cost estimate
  - [ ] request correlation ID

---

## Phase 2 - Enforcement

- [ ] Preflight budget checks before expensive calls
- [ ] rate and spend throttles
- [ ] model allowlists by tenant
- [ ] degrade-to-cheaper-model policy
- [ ] hard cap vs soft cap behavior

---

## Phase 3 - Visibility

- [ ] Admin reports by tenant, agent, provider, and model
- [ ] budget burn-down alerts
- [ ] anomaly detection for spend spikes
- [ ] export for finance and customer invoicing

---

## Tech Stack Options

| Option                                  | Pros                              | Cons                          | Fit                       |
| --------------------------------------- | --------------------------------- | ----------------------------- | ------------------------- |
| Platform-native ledger + pricing tables | Full control and tenant awareness | Requires pricing upkeep       | Best fit                  |
| External spend tool only                | Fast bootstrap                    | Weak product attribution      | Limited                   |
| Billing-module extension only           | Less module sprawl                | AI-specific logic gets buried | Acceptable but less clear |

---

## Risks

- Without spend controls, one bad prompt or loop can create material cost
- Without tenant attribution, enterprise billing becomes unreliable
- Without enforcement, dashboards become retrospective only
