# Isis Cost-Tracking and Quota Contract

**Status:** v1.0 **Date:** 2026-04-26 **Owner:** eng-isis **Backlog item:**
`V1-P2-0005`

This document defines the canonical contract between `IsisLLMClient`
(`libs/isis/llm-providers/src/client/`) and the cost-tracking subsystem
(`libs/isis/llm-providers/src/cost-calculator/` plus the consumer-facing
`@metis/cost-tracking` reporting suite). It covers the pricing unit, the
cost-recording path, the ledger query surface, and the per-tenant quota
enforcement guarantees.

---

## 1. Scope and audience

Audience: every consumer that issues LLM calls through `IsisLLMClient` (metis
content authoring, iris memory summaries, veritas explainers, psyche dialogues,
etc.) and every operator who reads cost reports via `@metis/cost-tracking` or
downstream BI surfaces.

The contract defines:

1. The canonical pricing unit (`microcents per 1 000 tokens`) — see §2.
2. The fields recorded on every LLM call — §3.
3. The query surface for the ledger — §4.
4. The quota model: per-tenant request / token / cost caps with warning and
   exhaustion semantics — §5.
5. Failure modes and observability — §6.

---

## 2. Pricing unit

All pricing flows through the canonical `LLMPriceMicrocentsPer1kTokens` integer
(1 microcent = 1e-6 cents = 1e-8 USD). See
`libs/contracts/src/llm/primitives.ts` and §6.5 of
`docs/releases/p2/isis-llm-gateway-audit.md` for the rationale (integer
arithmetic avoids floating-point drift across millions of per-token charges).

Conversion helpers:

- `usdPer1kToMicrocents(0.015) === 1_500_000` — Anthropic Sonnet input.
- `centsPer1kToMicrocents(1.5) === 1_500_000` — same value, different source
  unit.
- `microcentsToUsdPer1k(1_500_000) === 0.015`.
- `computeRequestMicrocents(pricing, usage)` — exact integer cost for a request,
  summing input/output/cache-read/cache-write contributions.

Ledger entries (`CostResult`) record costs in **fractional cents** (`number`)
for legacy compatibility with `@metis/cost-tracking` reports. Conversion:
`cents = microcents / 1_000_000`.

---

## 3. What gets recorded

`IsisLLMClient.complete()` records a ledger entry on **every successful
completion**, regardless of whether the resolved model has a pricing table
entry. When pricing is unknown, the entry is recorded with
`inputCostCents = outputCostCents = totalCostCents = 0`; the
`(provider, model, inputTokens, outputTokens, timestamp)` tuple is still
populated for audit and for back-population once pricing is known.

Recorded fields (`CostResult` in
`libs/isis/llm-providers/src/types.ts:272-286`):

| Field               | Source                              | Notes                                                                      |
| ------------------- | ----------------------------------- | -------------------------------------------------------------------------- |
| `id`                | `createCostEntryId()`               | Unique per entry                                                           |
| `provider`          | Successful `LLMResponse.provider`   | Lower-case enum (`anthropic`, `openai`, …) translated to `LLMProviderName` |
| `model`             | Successful `LLMResponse.model`      | Provider's reported model id                                               |
| `inputTokens`       | `LLMResponse.usage.inputTokens`     | From the provider's response                                               |
| `outputTokens`      | `LLMResponse.usage.outputTokens`    | From the provider's response                                               |
| `inputCostCents`    | `microcents / 1e6`                  | 0 if no pricing                                                            |
| `outputCostCents`   | `microcents / 1e6`                  | 0 if no pricing                                                            |
| `totalCostCents`    | `LLMResponse.cost.microcents / 1e6` | Sum incl. cache read/write                                                 |
| `pricingTier`       | `PricingTier.PAY_AS_YOU_GO`         | TODO: tier passthrough — V1-P2-0036                                        |
| `discountPercent`   | `0`                                 | TODO: V1-P2-0036                                                           |
| `originalCostCents` | Same as `totalCostCents`            | TODO: pre-discount — V1-P2-0036                                            |
| `timestamp`         | Gateway clock at end of call        | Millisecond epoch                                                          |

**Failed** calls are NOT recorded in the ledger (they are recorded in the
ring-buffered error log via `IsisLLMClient.recentErrors()`). Rationale: the
ledger reflects upstream charges; failed calls do not incur charges.

---

## 4. Ledger query surface

The `CostCalculator` instance behind every `IsisLLMClient` is exposed via
`IsisLLMClient.getCostCalculator()` so consumers can:

- `getEntriesByProvider(provider)` — entries for a specific provider.
- `getEntriesByModel(model)` — entries for a specific model.
- `getSummary(windowDays?)` — aggregate by provider, by model, projected monthly
  cost.
- `getBudgetStatus()` — total spend vs. configured monthly budget.
- `getProjectedMonthlyCost()` — projection from observed window.

Consumers MAY share a `CostCalculator` across multiple `IsisLLMClient` instances
by passing it via `createIsisLLMClient({ costCalculator, ... })`. This is the
default path for orchestrators that fan out to multiple gateways but want a
single ledger.

---

## 5. Quota model

Per-tenant quotas live in the `QuotaTracker`
(`libs/isis/llm-providers/src/client/quota-tracker.ts`). Each tenant has at most
one active quota spec; installing a new spec via `IsisLLMClient.setQuota()`
resets the consumption counters.

Quota dimensions (any combination, all enforced):

- `maxRequests` — request count over the rolling window.
- `maxInputTokens`
- `maxOutputTokens`
- `maxMicrocents` — fractional-cent-precision cost cap.

Window: `windowSeconds` (1 second to 1 year). Wall-clock — windows roll forward
when their duration elapses, not at calendar boundaries.

Behavior:

- **Pre-dispatch check** — `IsisLLMClient.complete()` calls
  `QuotaTracker.assertCapacity(tenantId)` before issuing the request. If any
  dimension is exhausted the gateway throws `LLMQuotaError` with `tenantId`,
  `windowEndsAtEpochMs`, and a human-readable reason. Retryable: false (quotas
  are not retryable in-window).
- **Post-success consumption** — on a successful response the tracker consumes
  `1 request`, `usage.inputTokens` input, `usage.outputTokens` output, and
  `cost.microcents`.
- **Warning threshold** — `warnAtBps` is a basis-points percentage (default
  `5_000` = 50%). The snapshot reports `warning: true` when any dimension
  crosses the threshold; consumers may emit telemetry off this.
- **Window roll** — the tracker rolls the window automatically when
  `clock() - windowStartedAtEpochMs >= windowSeconds * 1000`; counters reset to
  zero.

`getQuotaSnapshot(tenantId)` returns the current consumption tuple plus
`exhausted` and `warning` flags. Snapshots are read-only; consumers MUST NOT
mutate them.

---

## 6. Failure modes and observability

- A pricing-table miss produces a zero-cost entry — never a thrown error.
  Operators use `getEntriesByProvider` to identify untyped models and back-fill
  pricing via `setCustomPricing`.
- A `CostCalculator.recordCost` failure is swallowed in the gateway path (the
  ledger is observability, not a precondition for serving the request). The
  failure is logged at WARN level via the gateway's structured logger.
- Quota exhaustion produces `LLMQuotaError` and increments the `recentErrors`
  ring buffer. Operators wire this to an alarm.
- Cost ledger entries flow through to `@metis/cost-tracking` reporting via the
  `cost_recorded` event emitted by `CostCalculator`. Reporting modules
  (`ReportingEngine`, `BudgetManager`, `OptimizationAdvisor`) subscribe to this
  event when constructed with a shared calculator.

---

## 7. End-to-end verification

The e2e test
`libs/metis/llm-client/src/llm-client/llm-client.cost-ledger.test.ts`
constructs:

1. A real `IsisLLMClient` with a fetch mock that returns a recorded Anthropic
   response.
2. A `CostCalculator` shared with the IsisLLMClient via config.
3. A metis `LLMClient` wired to that IsisLLMClient.
4. Sends a metis `ContentType.LESSON` generation request.

The test asserts:

- `costCalculator.getEntriesByProvider(LLMProviderName.ANTHROPIC)` returns
  exactly one entry.
- The entry's `(provider, model, inputTokens, outputTokens)` tuple matches the
  recorded provider response (`claude-sonnet-4-20250514`, `24` input, `78`
  output).
- `entry.totalCostCents > 0` (real microcent arithmetic produced a non-zero
  cents figure).
- `entry.timestamp` is within the test's wall-clock window.

This is the canonical verification for `V1-P2-0005`. Any future re-verification
of this contract MUST run the same fixture against the same recorded payload and
assert identical ledger fields.
