@stigg/agent-sdk-js 0.0.0-stage → 0.2.0

package/dist/bindings/shared/token-usage.d.ts

@@ -0,0 +1,345 @@
+/**
+ * Provider usage objects -> the SDK's neutral `TokenUsage`.
+ *
+ * The inputs are typed structurally rather than against each vendor's SDK, so this handful of
+ * readers covers a direct client, a gateway response and an orchestrator callback - and adding a
+ * provider whose response happens to match costs nothing. Hence the shape-named reader below:
+ * `fromFlatTokenUsage` is read by every vendor that counts that way, not by one of them.
+ */
+import { type Measurement, type Metrics, type MetricsMapper, type TokenUsage } from '../../types';
+import type { BedrockLikeUsage, FlatTokenUsage, GeminiLikeUsage, LangChainLikeUsage, MistralLikeUsage, DatabricksLikeUsage, DatabricksQueryLikeUsage, OllamaLikeUsage, OpenAILikeUsage, ResponsesLikeUsage } from './types';
+export declare function fromFlatTokenUsage(usage: FlatTokenUsage | null | undefined): TokenUsage;
+export declare function fromOpenAIUsage(usage: OpenAILikeUsage | null | undefined): TokenUsage;
+/**
+ * OpenAI's Responses API, which counts the same tokens under different names - `input_tokens`
+ * rather than `prompt_tokens`, and the cache detail one level along. Reading it with the Chat
+ * Completions extractor finds none of them and meters the call at zero.
+ */
+export declare function fromResponsesUsage(usage: ResponsesLikeUsage | null | undefined): TokenUsage;
+/**
+ * Bedrock's Converse usage, whose four counters are disjoint.
+ *
+ * Nothing is subtracted, unlike the OpenAI and Gemini readers: AWS states that `inputTokens`
+ * already excludes whatever was read from or written to the cache, so taking the cache back out
+ * would charge the call for less than it used.
+ *
+ * The total is read, not recomputed, like every other vendor that publishes one - but it is worth
+ * knowing what it covers. AWS documents `totalTokens` as the input and output of the call, and
+ * documents `inputTokens` as cache-exclusive, so on a cached call the stated total can be smaller
+ * than the four counters add up to. Both are reported: price the breakdown if the cache matters to
+ * you, the total if it does not, and see the README's overlap table before pricing both.
+ */
+export declare function fromBedrockUsage(usage: BedrockLikeUsage | null | undefined): TokenUsage;
+export declare function fromLangChainUsage(usage: LangChainLikeUsage | null | undefined): TokenUsage;
+/**
+ * Gemini's `usageMetadata`, whose two overlaps run in opposite directions - see `GeminiLikeUsage`
+ * for the vendor's own wording on each.
+ *
+ * The arithmetic is checked by the one invariant the vendor publishes: the four counters below
+ * add back up to `totalTokenCount`, which is why neither overlap may be read the other way.
+ */
+export declare function fromGeminiUsage(usage: GeminiLikeUsage | null | undefined): TokenUsage;
+/**
+ * Mistral's `UsageInfo` - the OpenAI three, camelCased by a generated SDK.
+ *
+ * Counts the same way OpenAI's chat usage does, so the arithmetic is the same: the vendor states
+ * its own total and it is read rather than recomputed. There is no cache counter to subtract -
+ * `UsageInfo` carries none, so unlike `fromOpenAIUsage` nothing is nested inside the prompt count.
+ */
+export declare function fromMistralUsage(usage: MistralLikeUsage | null | undefined): TokenUsage;
+/**
+ * Ollama's two counters, read off the response root rather than out of a `usage` block.
+ *
+ * Disjoint - the prompt evaluation and the generation are separate work - so their sum is the
+ * whole call and computing a total from them is the vendor's own arithmetic rather than ours.
+ * Ollama publishes no total of its own, which is why there is one to compute.
+ */
+export declare function fromOllamaUsage(usage: OllamaLikeUsage | null | undefined): TokenUsage;
+/**
+ * Any of the three shapes above, recognised by its own fields. Vendors disagree on names but not
+ * enough to be ambiguous, so the caller can pass whatever the response carried.
+ */
+export declare function normalizeUsage(usage: unknown): TokenUsage;
+export declare const addTokenUsage: (into: TokenUsage, add: TokenUsage) => TokenUsage;
+/**
+ * The name a computed total is reported under, for the vendors that publish none of their own.
+ *
+ * `total_tokens` rather than a name of ours, because it is what OpenAI calls the same number and
+ * what a reader expects to find - but it is worth knowing which vendors state it and which get it
+ * from {@link COMPUTED_TOTALS}: Anthropic and TypeSafe publish no total at all, so theirs is the
+ * SDK's arithmetic over counters the vendor *did* state, not a figure off their dashboard.
+ */
+export declare const TOTAL_TOKENS = "total_tokens";
+/** Anthropic's four counters. Disjoint - cache reads and writes are not inside `input_tokens`. */
+export declare const ANTHROPIC_COMPONENT_METRICS: readonly ["input_tokens", "output_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
+/** Those four, plus the total this SDK adds up for them. */
+export declare const ANTHROPIC_METRICS: readonly ["input_tokens", "output_tokens", "cache_read_input_tokens", "cache_creation_input_tokens", "total_tokens"];
+/**
+ * Gemini's five. Two of them overlap in opposite directions and both are reported verbatim, the
+ * way every vendor's are, because a number published under a vendor's field name has to reconcile
+ * against that vendor's own dashboard: `cachedContentTokenCount` is already *inside*
+ * `promptTokenCount`, while `thoughtsTokenCount` and `toolUsePromptTokenCount` sit *outside* the
+ * two headline counters. Price accordingly - or price `normalizedMetrics` instead, which is
+ * disjoint by construction.
+ */
+export declare const GEMINI_METRICS: readonly ["promptTokenCount", "candidatesTokenCount", "cachedContentTokenCount", "thoughtsTokenCount", "toolUsePromptTokenCount", "totalTokenCount"];
+/** What identifies a Gemini usage object: its breakdown, never its total. */
+export declare const GEMINI_COMPONENT_METRICS: readonly ["promptTokenCount", "candidatesTokenCount", "cachedContentTokenCount", "thoughtsTokenCount", "toolUsePromptTokenCount"];
+/**
+ * Chat Completions. `prompt_tokens` **includes** `cached_tokens`, so these two overlap - reported
+ * as the vendor states them, which is what reconciles against its invoice. Whoever prices
+ * `prompt_tokens` must know the cached ones are already inside it.
+ */
+export declare const OPENAI_CHAT_METRICS: readonly ["prompt_tokens", "completion_tokens", "cached_tokens", "total_tokens"];
+/** The Responses API, which overlaps the same way under its own names. */
+export declare const OPENAI_RESPONSES_METRICS: readonly ["input_tokens", "output_tokens", "cached_tokens", "total_tokens"];
+/**
+ * Where Mistral's counters are **read** and what each is **reported** as - the only vocabulary
+ * here where those are different strings.
+ *
+ * Every other vendor is reported under the key it was read from, which is why `METRIC_PATHS` is a
+ * list and `metricName` just takes the last segment. Mistral's generated SDK renames the wire on
+ * the way in - the API sends `prompt_tokens`, the client hands you `promptTokens` - so following
+ * that convention would report a camelCase feature id that matches nothing on Mistral's own
+ * dashboard, and would differ from what the same account reports through an `OpenAI` client
+ * pointed at `api.mistral.ai/v1`. One account, one invoice, one vocabulary: the wire's.
+ *
+ * So the map runs read-key -> reported-name, and `pickRenamedMetrics` is what applies it.
+ */
+export declare const MISTRAL_METRIC_NAME_MAP: {
+    readonly promptTokens: "prompt_tokens";
+    readonly completionTokens: "completion_tokens";
+    readonly totalTokens: "total_tokens";
+};
+/**
+ * Mistral's three, under the wire's own names.
+ *
+ * No cache counter: `UsageInfo` carries none. The cache and reasoning detail the v2 SDK models
+ * lives on a different type that chat responses do not use, so declaring it here would type a
+ * pricing table against a number that never arrives.
+ */
+export declare const MISTRAL_METRICS: readonly ["prompt_tokens", "completion_tokens", "total_tokens"];
+/**
+ * TypeSafe's two. No cache counters and no cost: the API reports what it charged for and stops
+ * there, which was confirmed against the wire rather than inferred from the SDK's types.
+ */
+export declare const TYPESAFE_COMPONENT_METRICS: readonly ["input_tokens", "output_tokens"];
+/** Those two, plus the total this SDK adds up for them. */
+export declare const TYPESAFE_METRICS: readonly ["input_tokens", "output_tokens", "total_tokens"];
+/**
+ * Ollama's two. Flat on the response root, so the paths are the names.
+ *
+ * No cache counter and no cost: Ollama is self-hosted, so there is no invoice behind these at all
+ * - they measure the customer's own capacity rather than a vendor's charge. The durations beside
+ * them on the response are nanoseconds, not tokens, and are deliberately absent from this list.
+ */
+export declare const OLLAMA_COMPONENT_METRICS: readonly ["prompt_eval_count", "eval_count"];
+/** Those two, plus the total this SDK adds up for them. */
+export declare const OLLAMA_METRICS: readonly ["prompt_eval_count", "eval_count", "total_tokens"];
+/** Both OpenAI surfaces, which is what one client can report across its two APIs. */
+export declare const OPENAI_METRICS: readonly ["prompt_tokens", "completion_tokens", "input_tokens", "output_tokens", "cached_tokens", "total_tokens"];
+/** A gateway speaks the OpenAI shape and adds the price it charged, under its own field name. */
+export declare const GATEWAY_METRICS: readonly ["prompt_tokens", "completion_tokens", "input_tokens", "output_tokens", "cached_tokens", "total_tokens", "cost"];
+/**
+ * A gateway that forwards the upstream body untouched, and so reports in two vocabularies.
+ *
+ * Unlike LiteLLM, which normalises every upstream to the OpenAI wire, Cloudflare AI Gateway's
+ * provider-native routes pass the provider's own body straight through - so `/openai` returns
+ * OpenAI's counter names and `/anthropic` returns Anthropic's. One recipe serves both wires, so
+ * this is the union of what its surfaces can report, which is what `metrics` is defined to be.
+ *
+ * No `cost`, and that is the defining fact rather than an oversight. Cloudflare states no price on
+ * any response: its figure lives in the gateway's own log, is explicitly an estimate, and is zero
+ * on a cache hit. So the recipe carries the log id as a dimension and lets spend be reconciled out
+ * of band, exactly as the gateway reference prescribes for a price that is only available
+ * asynchronously.
+ */
+export declare const CLOUDFLARE_METRICS: readonly ["prompt_tokens", "completion_tokens", "input_tokens", "output_tokens", "cached_tokens", "total_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
+/**
+ * Bedrock's five, under its own names and with no price among them.
+ *
+ * Reported verbatim rather than translated into the OpenAI spelling, which is the rule everywhere
+ * except where one service is reachable through two different clients - see `sdk-usage.ts` for
+ * that exception. Bedrock is reached one way, so its own names are the honest ones, and a reader
+ * comparing a Stigg meter against an AWS bill is comparing like with like.
+ *
+ * No `cost`: Bedrock states no price on the response, which is the thing that most separates it
+ * from the other two gateways here. See the recipe for what that costs a run.
+ */
+export declare const BEDROCK_PATHS: readonly ["inputTokens", "outputTokens", "cacheReadInputTokens", "cacheWriteInputTokens", "totalTokens"];
+/** Those five. Flat, so the paths are the names. */
+export declare const BEDROCK_METRICS: readonly ["inputTokens", "outputTokens", "cacheReadInputTokens", "cacheWriteInputTokens", "totalTokens"];
+/**
+ * Databricks' six, under its own names - and its own names are two vendors' names at once.
+ *
+ * The first three are OpenAI's spelling, because the serving endpoints speak the OpenAI wire. The
+ * two cache counters are *Anthropic's* spelling, flat on the usage block rather than nested under
+ * `prompt_tokens_details` where an OpenAI-shaped reader would look for them, and `reasoning_tokens`
+ * is Databricks' own. Reported exactly as Databricks spells them, per the rule that a number has to
+ * reconcile against the vendor's own dashboard - renaming the cache pair to `cached_tokens` would
+ * make one account read as two vocabularies and find nothing where it looked.
+ *
+ * No `cost`, and that is the fact that most shapes this binding: Databricks states no price on any
+ * response, on either route. See `databricks-recipe.ts` for what that costs a run.
+ */
+export declare const DATABRICKS_PATHS: readonly ["prompt_tokens", "completion_tokens", "total_tokens", "reasoning_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
+/**
+ * The same counters as the Responses API spells them.
+ *
+ * Databricks serves both OpenAI surfaces, and they do not share field names: Chat Completions
+ * sends `prompt_tokens`/`completion_tokens` and Responses sends `input_tokens`/`output_tokens`.
+ * Reading a Responses body with the list above finds neither, so the call would report its total
+ * and nothing else - a number with no breakdown under it, which prices wrongly rather than
+ * visibly. Each surface reads its own list.
+ */
+export declare const DATABRICKS_RESPONSES_PATHS: readonly ["input_tokens", "output_tokens", "total_tokens", "reasoning_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
+/** The union across both surfaces: what a Databricks call can report, which is what `metrics` is. */
+export declare const DATABRICKS_METRICS: readonly ["prompt_tokens", "completion_tokens", "input_tokens", "output_tokens", "total_tokens", "reasoning_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
+/**
+ * Where the **first-party client's** counters are read and what each is reported as.
+ *
+ * The second map in this file, and it exists for precisely the reason the Mistral one does.
+ * `@databricks/sdk-modelservingquery` is generated, and its zod schema parses `prompt_tokens` off
+ * the wire and transforms it to `promptTokens` before the caller ever sees it - so following the
+ * key it was read from would report a camelCase feature id for a call that the *same workspace*
+ * reports in snake_case when the application holds an `OpenAI` client instead.
+ *
+ * That is not a cosmetic difference. It is one Databricks account producing two different feature
+ * ids depending on which package the application happened to import, splitting one bill across two
+ * meters - which is the failure `pickRenamedMetrics` was built to prevent. Three entries rather
+ * than six because `ExternalModelUsageElement` carries only three; the cache pair and
+ * `reasoning_tokens` have no field on it, and a counter with no field is absent rather than zero.
+ */
+export declare const DATABRICKS_QUERY_METRIC_NAME_MAP: {
+    readonly promptTokens: "prompt_tokens";
+    readonly completionTokens: "completion_tokens";
+    readonly totalTokens: "total_tokens";
+};
+/**
+ * Workers AI's three, and only three.
+ *
+ * OpenAI's spelling, flat, with no cache detail nested underneath - so this is a narrower list
+ * than `OPENAI_CHAT_METRICS` rather than a reuse of it. Declaring `cached_tokens` here would type
+ * a pricing table against a counter Workers AI never sends.
+ *
+ * No neurons either, which is the counter a reader might expect. Cloudflare bills Workers AI in
+ * Neurons, and publishes none of them on any response - binding or REST - so the conversion from
+ * tokens is a price list this SDK does not hold. Tokens are what the response states and tokens
+ * are what this reports.
+ */
+export declare const WORKERS_AI_PATHS: readonly ["prompt_tokens", "completion_tokens", "total_tokens"];
+/** Those three. Flat, so the paths are the names. */
+export declare const WORKERS_AI_METRICS: readonly ["prompt_tokens", "completion_tokens", "total_tokens"];
+/**
+ * Databricks' usage block -> the neutral digest.
+ *
+ * `input` is `prompt_tokens` verbatim, *not* reduced by the cache reads the way `fromOpenAIUsage`
+ * reduces its own. OpenAI documents its cached tokens as counted inside `prompt_tokens`, so
+ * subtracting there is undoing a documented overlap. Databricks documents no such thing, and the
+ * spelling it chose for the pair is Anthropic's - whose cache counters sit *beside* the input
+ * count rather than inside it. So the Anthropic convention is the better guess and the overlap is
+ * left alone; the stated total is read rather than computed, which keeps the one number that gets
+ * invoiced right whichever way the overlap actually runs. The README's overlap table says the
+ * direction is unverified for Databricks, because it is.
+ */
+export declare function fromDatabricksUsage(usage: DatabricksLikeUsage | null | undefined): TokenUsage;
+/**
+ * The same block as read through the first-party client -> the neutral digest.
+ *
+ * Its own reader rather than a call into `fromDatabricksUsage`, because the field names genuinely
+ * differ: the generated client camelCases the wire on the way in, so a snake_case reader finds
+ * none of these and returns an all-zero digest without throwing. That is the shape of failure the
+ * invariants call out - an extractor that meters every call at nothing and trips no test.
+ *
+ * No cache arithmetic to get wrong here, which is the one simplification over the wire-shaped
+ * reader: `ExternalModelUsageElement` declares no cache counters at all, so there is no overlap of
+ * unknown direction to leave alone. The stated total is still read rather than recomputed.
+ */
+export declare function fromDatabricksQueryUsage(usage: DatabricksQueryLikeUsage | null | undefined): TokenUsage;
+/** The leaf a dotted path reports under - `prompt_tokens_details.cached_tokens` -> `cached_tokens`. */
+export declare const metricName: (path: string) => string;
+/**
+ * Which counters are summed to produce a vendor's total, for the vendors that publish none.
+ *
+ * Only ever disjoint sets: Anthropic's four do not overlap and neither do TypeSafe's two, so the
+ * sum is the whole call and nothing is counted twice. A vendor whose counters overlap - Gemini's
+ * cached tokens sit inside its prompt count, OpenAI's inside theirs - is not in this table,
+ * because adding those up would be arithmetic the vendor never agreed to. Those vendors state a
+ * total themselves and it is read, not computed.
+ */
+export declare const COMPUTED_TOTALS: Record<string, readonly string[]>;
+/**
+ * Adds the computed total to a metrics object, for a vendor that states none of its own.
+ *
+ * Absent rather than zero when nothing was counted, like every other metric here: a call that
+ * measured nothing reports nothing, instead of a zero somebody has to interpret.
+ */
+export declare function withComputedTotal(metrics: Metrics, keys: readonly string[]): Metrics;
+/**
+ * Whether a path list and a name list agree, for the test that keeps them from drifting.
+ *
+ * Two lists describing one thing is the cost of separating where a counter lives from what it is
+ * called. This is what makes that cost a compile-and-test problem rather than a billing one.
+ */
+export declare const metricNamesMatchPaths: (paths: readonly string[], names: readonly string[]) => boolean;
+/** The read paths, for the tests that hold them in step with the names above. */
+export declare const METRIC_PATHS: {
+    readonly anthropic: readonly ["input_tokens", "output_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
+    readonly openaiChat: readonly ["prompt_tokens", "completion_tokens", "prompt_tokens_details.cached_tokens", "total_tokens"];
+    readonly openaiResponses: readonly ["input_tokens", "output_tokens", "input_tokens_details.cached_tokens", "total_tokens"];
+    readonly typesafe: readonly ["input_tokens", "output_tokens"];
+    readonly gemini: readonly ["promptTokenCount", "candidatesTokenCount", "cachedContentTokenCount", "thoughtsTokenCount", "toolUsePromptTokenCount", "totalTokenCount"];
+    readonly bedrock: readonly ["inputTokens", "outputTokens", "cacheReadInputTokens", "cacheWriteInputTokens", "totalTokens"];
+    readonly databricks: readonly ["prompt_tokens", "completion_tokens", "total_tokens", "reasoning_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
+    readonly databricksResponses: readonly ["input_tokens", "output_tokens", "total_tokens", "reasoning_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
+    readonly workersAi: readonly ["prompt_tokens", "completion_tokens", "total_tokens"];
+    readonly ollama: readonly ["prompt_eval_count", "eval_count"];
+};
+/**
+ * Reads the named keys off a vendor's usage object, dotted paths included.
+ *
+ * A nested key reports under its leaf - `prompt_tokens_details.cached_tokens` becomes
+ * `cached_tokens` - because the leaf is the vendor's own name for it and a feature id with a dot
+ * in it reads badly everywhere. Anything absent, fractional or not a number is skipped: a metric
+ * the vendor did not report is not a zero, and Stigg rejects fractions.
+ */
+export declare function pickMetrics(usage: unknown, keys: readonly string[]): Metrics;
+/**
+ * Reads each key of a read -> reported map off a usage object, reporting under the mapped name.
+ *
+ * The counterpart to {@link pickMetrics} for a vendor whose SDK spells its counters differently
+ * from its own wire. Same guards, and for the same reasons: anything absent, fractional or not a
+ * number is skipped, because a metric the vendor did not report is not a zero and Stigg rejects
+ * fractions. Flat keys only - no vendor needing this nests its counters, and a dotted read here
+ * would make the map ambiguous about which half of the arrow the dot belongs to.
+ */
+export declare function pickRenamedMetrics(usage: unknown, map: Record<string, string>): Metrics;
+/** Accumulates metrics across a stream, which reports its counters in more than one chunk. */
+export declare const addMetrics: (into: Metrics, add: Metrics) => Metrics;
+/**
+ * The SDK's own four counters, under SDK-owned names, from the normalized measurement.
+ *
+ * The opt-out from vendor names, for an application running more than one provider: these are
+ * disjoint and mean the same thing whoever served the call, so one set of Stigg features covers
+ * every vendor. Pass it as a run's `metrics`.
+ */
+export declare const normalizedMetrics: MetricsMapper;
+/** The shapes a gateway can be told it observed, since guessing reports to the wrong features. */
+/**
+ * The shapes a proxy can be told it observed.
+ *
+ * Named for the vendor rather than for the shape, because a proxy operator knows what is behind
+ * them and not what its usage object looks like - but it is the shape that is being selected,
+ * which is why OpenAI appears twice. Its two APIs spell the same counters differently, and
+ * `openai-responses` is that surface rather than a vendor of its own.
+ */
+export type ObservedVendor = 'anthropic' | 'typesafe' | 'openai' | 'openai-responses' | 'gemini';
+/**
+ * Both views of a usage object a proxy observed, for the ingest path that has no recipe.
+ *
+ * The vendor is named rather than sniffed. `normalizeUsage` guesses from the object's own fields
+ * and says itself that Anthropic and the Responses API are ambiguous - both count `input_tokens`.
+ * A wrong guess would report to another meter entirely, which nothing downstream can undo - so
+ * an unnamed vendor reports nothing raw and leaves the normalized counters to a mapper.
+ */
+export declare function observedMeasurement(usage: unknown, vendor?: ObservedVendor): Measurement;