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:
- The canonical pricing unit (
microcents per 1 000 tokens) — see §2. - The fields recorded on every LLM call — §3.
- The query surface for the ledger — §4.
- The quota model: per-tenant request / token / cost caps with warning and exhaustion semantics — §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.maxInputTokensmaxOutputTokensmaxMicrocents— 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()callsQuotaTracker.assertCapacity(tenantId)before issuing the request. If any dimension is exhausted the gateway throwsLLMQuotaErrorwithtenantId,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.inputTokensinput,usage.outputTokensoutput, andcost.microcents. - Warning threshold —
warnAtBpsis a basis-points percentage (default5_000= 50%). The snapshot reportswarning: truewhen 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
getEntriesByProviderto identify untyped models and back-fill pricing viasetCustomPricing. - A
CostCalculator.recordCostfailure 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
LLMQuotaErrorand increments therecentErrorsring buffer. Operators wire this to an alarm. - Cost ledger entries flow through to
@metis/cost-trackingreporting via thecost_recordedevent emitted byCostCalculator. 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:
- A real
IsisLLMClientwith a fetch mock that returns a recorded Anthropic response. - A
CostCalculatorshared with the IsisLLMClient via config. - A metis
LLMClientwired to that IsisLLMClient. - Sends a metis
ContentType.LESSONgeneration 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,24input,78output). entry.totalCostCents > 0(real microcent arithmetic produced a non-zero cents figure).entry.timestampis 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.