Eve library

Isis Cost-Tracking and Quota Contract

Guide

Revision 1

On this page

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.