Cost attribution (per agent)

Purpose: Let each workspace define how much each POST /api/v1/evaluate call is worth for internal chargeback or showback, broken down by context.agent_id.

This is not automatic LLM token billing. You supply integer cents per evaluation (default for the workspace, optional override per agent_id). The amount is copied onto the evaluation row at evaluate time (attributed_cost_cents) so totals stay stable if you later change rates.

---

1. Configure rates (dashboard)

1. Open Cost attribution in the sidebar (/dashboard/cost-attribution).
2. Pick workspace and period for the rollup table.
3. As a workspace admin, set default cost (cents per evaluation) and optional currency label (display only; amounts are still stored as cents).
4. Add per-agent overrides where agent_id must match context.agent_id on evaluate exactly.

Members can see rollups and settings; only admins can edit.

---

2. API behavior

On each successful evaluate (new evaluation row), the server resolves:

1. If context.agent_id is set and an override exists for that agent → use override cost_cents.
2. Else → use default from workspace_evaluation_cost_settings (or 0 if no row).

The value is stored as evaluations.attributed_cost_cents and returned on the evaluate JSON body as attributed_cost_cents (and on idempotent replays).

Limits: 0–10,000,000 cents per rate (~$100k USD per evaluation cap) to avoid mistakes.

---

3. Rollups

The dashboard calls Postgres function workspace_evaluation_cost_by_agent(workspace_id, since), which sums attributed_cost_cents and counts evaluations grouped by agent_id (empty key = no agent_id on the row).

Requires the 20260331320000_evaluation_cost_attribution migration (or equivalent SQL).

---

4. Historical data

Evaluations created before this feature have attributed_cost_cents = 0 (column default). Changing defaults or overrides does not backfill old rows.

---

5. Related

• Governance analytics — approval metrics (separate from cost).
• Product & market report — feature inventory.