margin-meter 0.1.0 → 0.3.0

package/dist/promptfoo.js

@@ -0,0 +1,446 @@
+/**
+ * margin-meter/promptfoo — turn a `promptfoo eval` result file into outcomes.
+ *
+ * The TypeScript twin of `sdk/python/margin_meter/promptfoo.py`. promptfoo is a
+ * Node tool, so a promptfoo user is already in the JS toolchain and this SDK is
+ * their natural bridge. `promptfoo eval -o results.json` writes a code-graded
+ * pass/fail file that maps one-to-one onto `POST /api/ingest/outcomes`
+ * (`docs/INTEGRATION_LADDER.md` rung 2), so the whole of rung 2 — "their evals
+ * report pass/fail" — is available with no hand-written POST:
+ *
+ *     promptfoo eval -o results.json
+ *
+ *     import { MarginMeter, promptfoo } from "margin-meter";
+ *     const meter = new MarginMeter();               // MARGIN_INGEST_URL/KEY from env
+ *     const data = JSON.parse(await readFile("results.json", "utf8"));
+ *     await promptfoo.recordResults(meter, data, "my-eval-suite");
+ *
+ * The mapping is identical to the Python adapter's, on purpose — the two SDKs
+ * must not drift:
+ *
+ *  - `passed`        ← `success` (the top-level aggregate verdict).
+ *  - `qualityScore`  ← `score` passed through when in [0, 1]; a score outside
+ *    that range (a raw metric from a custom assert) falls back to the coherent
+ *    binary, because the ingest layer rejects an out-of-range score and losing
+ *    the row is worse than losing the decimal. Always supplied (1.0/0.0 at
+ *    least): the ingest layer discards `quality_method`/`grader_kind` on a
+ *    scoreless outcome, so the score is what lights the grading provenance.
+ *  - `qualityMethod`/`graderKind` ← DERIVED from the assert types, never
+ *    assumed (see the honesty rule below).
+ *  - `link`          ← `testCase.description`, else the prompt id + index — never
+ *    `prompt.label`, which promptfoo defaults to the prompt text (MAR-1548).
+ *  - `valueUsd`      ← opt-in via `vars.margin_value` or
+ *    `testCase.metadata.margin_value` — the only route to value-per-outcome
+ *    (rung 8). Absent is the cost-per-outcome default, never coerced to 0.
+ *  - a result with no boolean `success` is not a verdict and is SKIPPED —
+ *    recording a non-verdict would fabricate an outcome the eval did not
+ *    produce.
+ *
+ * ## The honesty rule
+ *
+ * promptfoo grades two different ways and the adapter must not conflate them:
+ * code-graded asserts (`contains`, `equals`, `is-json`, `javascript`, `regex`,
+ * …) are `ground_truth`/`code`; model-graded asserts (`llm-rubric`,
+ * `factuality`, `similar`, `classifier`, `g-eval`, …) are `llm_judge`/`judge`.
+ * The WEAKER honest claim wins: any model-graded assert makes the whole outcome
+ * a judge grade; a code assert mixed with an assert type we do not recognise is
+ * downgraded to `unknown` (we cannot prove the unknown one was code); nothing
+ * recognisable at all is `unknown`. A rubric-graded eval reported as a
+ * ground-truth code grade would be the exact productivity illusion Margin
+ * exists to puncture.
+ *
+ * Two design promises, same as the Python adapter: it consumes the file the
+ * customer already produces (no new harness), and it never fabricates and is
+ * fail-safe — a delivery fault on one row warns and is counted, never aborting
+ * the batch.
+ */
+// Grading provenance strings — mirror `src/margin/grading.py`, kept as literals
+// so the SDK has no dependency on the server package.
+const GROUND_TRUTH = "ground_truth";
+const LLM_JUDGE = "llm_judge";
+const UNKNOWN_METHOD = "unknown";
+const GRADER_CODE = "code";
+const GRADER_JUDGE = "judge";
+const GRADER_UNKNOWN = "unknown";
+// `Outcome.link` is a `String(512)`; a longer link is truncated, not dropped (a
+// lossy link beats a lost outcome) — same rule as the pytest adapter.
+const MAX_LINK_LEN = 512;
+const VALUE_KEY = "margin_value";
+/** Mirror of `src/margin/ingest.MAX_VALUE_USD`: ingest refuses a value past this. */
+const MAX_VALUE_USD = 10_000_000;
+/** promptfoo assert types that are pure code: a deterministic comparison with no
+ *  model in the loop. Normalised lower-case, separators stripped so `is-json`
+ *  and `isjson` collapse together and the `not-` negation prefix is ignored. */
+const CODE_ASSERTS = new Set([
+    "equals",
+    "contains",
+    "icontains",
+    "containsall",
+    "containsany",
+    "icontainsall",
+    "icontainsany",
+    "startswith",
+    "regex",
+    "isjson",
+    "containsjson",
+    "issql",
+    "containssql",
+    "isxml",
+    "containsxml",
+    "isvalidopenaifunctioncall",
+    "isvalidopenaitoolscall",
+    "javascript",
+    "python",
+    "webhook",
+    "levenshtein",
+    "rougen",
+    "bleu",
+    "gleu",
+    "meteor",
+    "latency",
+    "cost",
+    "perplexity",
+    "perplexityscore",
+    "finishreason",
+    "guardrails",
+    "trace",
+]);
+/** promptfoo assert types that put a MODEL in the grading loop — an LLM judge,
+ *  an embedding-similarity model, or a classifier. Any one present means the
+ *  strongest honest claim is `llm_judge`/`judge`, never a code grade. */
+const MODEL_ASSERTS = new Set([
+    "llmrubric",
+    "modelgradedclosedqa",
+    "modelgradedfactuality",
+    "factuality",
+    "answerrelevance",
+    "contextrelevance",
+    "contextfaithfulness",
+    "contextrecall",
+    "similar",
+    "classifier",
+    "moderation",
+    "selectbest",
+    "pi",
+    "geval",
+    "gevalfactuality",
+]);
+const defaultWarn = (message) => {
+    // `process` may be absent in a non-Node runtime; fall back to console.
+    const p = globalThis
+        .process;
+    if (p && typeof p.emitWarning === "function")
+        p.emitWarning(message);
+    else
+        console.warn(message);
+};
+function isObject(x) {
+    return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+/** Normalise a promptfoo assert type for set membership: lower-case, drop
+ *  dashes/underscores/spaces, strip a leading `not` negation (`not-contains`
+ *  grades the same WAY as `contains`). Returns undefined for a missing/blank
+ *  type. */
+export function normAssertType(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    let t = raw.trim().toLowerCase().replace(/[-_ ]/g, "");
+    if (!t)
+        return undefined;
+    if (t.startsWith("not") && t !== "not")
+        t = t.slice(3);
+    return t || undefined;
+}
+/** Derive `(qualityMethod, graderKind)` from the assert types behind a result,
+ *  applying the weaker-claim-wins honesty rule:
+ *   - any model-graded assert  → llm_judge/judge
+ *   - only recognised code asserts → ground_truth/code
+ *   - anything else (no asserts, or a code assert mixed with an unrecognised
+ *     type we cannot vouch for) → unknown/unknown */
+export function gradingSignature(assertTypes) {
+    let hasModel = false;
+    let hasCode = false;
+    let hasUnknown = false;
+    for (const raw of assertTypes) {
+        const t = normAssertType(raw);
+        if (t === undefined)
+            continue;
+        if (MODEL_ASSERTS.has(t))
+            hasModel = true;
+        else if (CODE_ASSERTS.has(t))
+            hasCode = true;
+        else
+            hasUnknown = true;
+    }
+    if (hasModel)
+        return { qualityMethod: LLM_JUDGE, graderKind: GRADER_JUDGE };
+    if (hasCode && !hasUnknown)
+        return { qualityMethod: GROUND_TRUTH, graderKind: GRADER_CODE };
+    return { qualityMethod: UNKNOWN_METHOD, graderKind: GRADER_UNKNOWN };
+}
+/** Collect the assert types behind one promptfoo result. Prefers
+ *  `gradingResult.componentResults[].assertion.type` (what actually ran,
+ *  including expanded asserts) and its single top-level `assertion`; falls back
+ *  to the configured `testCase.assert[].type`. */
+export function assertTypesFromResult(result) {
+    const types = [];
+    if (!isObject(result))
+        return types;
+    const grading = result.gradingResult;
+    if (isObject(grading)) {
+        const components = grading.componentResults;
+        if (Array.isArray(components)) {
+            for (const comp of components) {
+                if (isObject(comp) && isObject(comp.assertion)) {
+                    types.push(comp.assertion.type);
+                }
+            }
+        }
+        if (isObject(grading.assertion))
+            types.push(grading.assertion.type);
+    }
+    if (types.length > 0)
+        return types;
+    const testCase = result.testCase;
+    if (isObject(testCase) && Array.isArray(testCase.assert)) {
+        for (const a of testCase.assert) {
+            if (isObject(a))
+                types.push(a.type);
+        }
+    }
+    return types;
+}
+// A finite DECIMAL number, the only string shape accepted. Deliberately narrower
+// than JS `Number()`, which also parses `0x10`/`0o7`/`0b1`/`Infinity`/`""` — a
+// `margin_value` typo like `"0x10"` must be a DROPPED value, never a silent $16.
+// This is the acceptance set of Python `float()` minus `inf`/`nan`, so the two
+// SDKs treat a stringly-typed tag the same and neither lets a non-number through.
+const DECIMAL_RE = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
+/** Coerce a raw `margin_value` tag to a finite number, tolerating a stringly-typed
+ *  var. A negative is a loss and is kept (MAR-1198). Throws on a bool, a non-decimal
+ *  string, a non-finite value, or one past +/-MAX_VALUE_USD — the caller warns and
+ *  drops the value while keeping the pass/fail. */
+function coerceValue(raw) {
+    if (typeof raw === "boolean")
+        throw new Error(`${VALUE_KEY} must be a number, got ${JSON.stringify(raw)}`);
+    let val;
+    if (typeof raw === "number") {
+        val = raw;
+    }
+    else if (typeof raw === "string") {
+        const s = raw.trim();
+        if (!DECIMAL_RE.test(s))
+            throw new Error(`${VALUE_KEY} must be a number, got ${JSON.stringify(raw)}`);
+        val = Number(s);
+    }
+    else {
+        throw new Error(`${VALUE_KEY} must be a number, got ${JSON.stringify(raw)}`);
+    }
+    if (!Number.isFinite(val))
+        throw new Error(`${VALUE_KEY} must be a finite number, got ${JSON.stringify(raw)}`);
+    // A loss is a real value (MAR-1198): ingest takes any finite amount within +/-MAX.
+    if (Math.abs(val) > MAX_VALUE_USD)
+        throw new Error(`${VALUE_KEY} implausible (|value| > ${MAX_VALUE_USD}), got ${val}`);
+    return val;
+}
+/** Read an opt-in `margin_value` off a result's `vars` or its test case's
+ *  `metadata`/`vars` — the value-per-outcome numerator (rung 8). Returns the USD
+ *  amount, or undefined when absent (the normal cost-per-outcome case). Throws
+ *  on a malformed value so the caller can warn and drop it. */
+export function valueFromResult(result) {
+    if (!isObject(result))
+        return undefined;
+    let raw = undefined;
+    const vars = result.vars;
+    if (isObject(vars) && VALUE_KEY in vars) {
+        raw = vars[VALUE_KEY];
+    }
+    else {
+        const testCase = result.testCase;
+        if (isObject(testCase)) {
+            const meta = testCase.metadata;
+            if (isObject(meta) && VALUE_KEY in meta)
+                raw = meta[VALUE_KEY];
+            const tv = testCase.vars;
+            // `== null` (not `=== undefined`) so an explicit `null` in metadata falls
+            // through to testCase.vars, matching the Python adapter's `raw is None`.
+            if (raw == null && isObject(tv) && VALUE_KEY in tv)
+                raw = tv[VALUE_KEY];
+        }
+    }
+    if (raw === undefined || raw === null)
+        return undefined;
+    return coerceValue(raw);
+}
+/** A traceable link back to the exact eval case: the test description if the
+ *  author wrote one, else the prompt id plus the row index. ⛔ Never
+ *  `prompt.label` (MAR-1548): promptfoo defaults it to the raw prompt text. */
+export function linkFromResult(result, index) {
+    if (isObject(result)) {
+        const testCase = result.testCase;
+        if (isObject(testCase) && typeof testCase.description === "string") {
+            const desc = testCase.description.trim();
+            if (desc)
+                return desc.slice(0, MAX_LINK_LEN);
+        }
+        // `||` (not `??`) so an empty-string label falls through to the next
+        // candidate, matching the Python adapter's `or` chain.
+        let label = undefined;
+        const prompt = result.prompt;
+        if (isObject(prompt))
+            label = prompt.id;
+        if (!label) {
+            label = result.promptId || result.provider;
+            if (isObject(label))
+                label = label.id || label.label;
+        }
+        if (typeof label === "string" && label)
+            return `${label}:${index}`.slice(0, MAX_LINK_LEN);
+        if (typeof label === "number")
+            return `${label}:${index}`.slice(0, MAX_LINK_LEN);
+    }
+    return `promptfoo:${index}`;
+}
+/** Return the `{ passed, score }` verdict for a real result, else undefined.
+ *  `passed` comes from a boolean `success`; a result without one is not a
+ *  verdict. `score` is passed through when in [0, 1]; out of that range (a raw
+ *  metric) falls back to the coherent binary and warns, because the ingest layer
+ *  rejects an out-of-range score and a lost row is worse than a lost decimal. */
+export function passedAndScore(result, onWarn = defaultWarn) {
+    if (!isObject(result))
+        return undefined;
+    const success = result.success;
+    if (typeof success !== "boolean")
+        return undefined;
+    const passed = success;
+    const score = result.score;
+    if (typeof score !== "number" || Number.isNaN(score)) {
+        return { passed, score: passed ? 1.0 : 0.0 };
+    }
+    if (score >= 0.0 && score <= 1.0)
+        return { passed, score };
+    onWarn(`promptfoo score ${score} is outside [0, 1]; recording the binary ` +
+        "pass/fail instead so the outcome is not dropped");
+    return { passed, score: passed ? 1.0 : 0.0 };
+}
+/** Translate one graded promptfoo result into `MarginMeter.recordOutcome` input.
+ *  The grader signature is derived from `assertTypes` (never assumed);
+ *  `valueUsd` rides only when a value was supplied. */
+export function outcomeInput(args) {
+    const { qualityMethod, graderKind } = gradingSignature(args.assertTypes);
+    const input = {
+        workflowId: args.workflowId,
+        passed: Boolean(args.passed),
+        qualityScore: Number(args.qualityScore),
+        qualityMethod,
+        graderKind,
+        link: String(args.link).slice(0, MAX_LINK_LEN),
+        isSimulated: Boolean(args.isSimulated),
+    };
+    if (args.valueUsd !== undefined)
+        input.valueUsd = Number(args.valueUsd);
+    return input;
+}
+/** Full translation of one promptfoo result, or undefined if it is not a real
+ *  verdict. A malformed `margin_value` warns and drops the value (keeping the
+ *  pass/fail), never throwing into the caller. */
+export function resultToOutcomeInput(result, opts) {
+    const onWarn = opts.onWarn ?? defaultWarn;
+    const index = opts.index ?? 0;
+    const verdict = passedAndScore(result, onWarn);
+    if (verdict === undefined)
+        return undefined;
+    let value;
+    try {
+        value = valueFromResult(result);
+    }
+    catch (exc) {
+        value = undefined;
+        onWarn(`${linkFromResult(result, index)}: ${exc.message}`);
+    }
+    return outcomeInput({
+        workflowId: opts.workflowId,
+        passed: verdict.passed,
+        qualityScore: verdict.score,
+        assertTypes: assertTypesFromResult(result),
+        link: linkFromResult(result, index),
+        valueUsd: value,
+        isSimulated: opts.isSimulated,
+    });
+}
+/** Pull the flat list of per-test results out of a parsed promptfoo output.
+ *  promptfoo has shipped several envelope shapes (the top-level OutputFile with
+ *  `results.results`, an older `results` list, a bare list); this walks the
+ *  known shapes rather than pinning one version. */
+export function extractResults(data) {
+    if (Array.isArray(data))
+        return data.filter(isObject);
+    if (!isObject(data))
+        return [];
+    const results = data.results;
+    // New shape: { results: { results: [...] } }
+    if (isObject(results) && Array.isArray(results.results)) {
+        return results.results.filter(isObject);
+    }
+    // Older shape: { results: [...] }
+    if (Array.isArray(results))
+        return results.filter(isObject);
+    return [];
+}
+/** Yield `recordOutcome` inputs for every real verdict in a parsed promptfoo
+ *  output (any envelope shape {@link extractResults} understands). */
+export function iterOutcomes(data, opts) {
+    const out = [];
+    const results = extractResults(data);
+    for (let i = 0; i < results.length; i++) {
+        const input = resultToOutcomeInput(results[i], {
+            workflowId: opts.workflowId,
+            index: i,
+            isSimulated: opts.isSimulated,
+            onWarn: opts.onWarn,
+        });
+        if (input !== undefined)
+            out.push(input);
+    }
+    return out;
+}
+/** Emit an outcome per verdict in a parsed promptfoo output through `meter`.
+ *  Fail-safe: a delivery fault on one row warns and counts an error; it never
+ *  aborts the batch. Non-verdict rows are counted as skipped. */
+export async function recordResults(meter, data, workflowId, opts = {}) {
+    const onWarn = opts.onWarn ?? defaultWarn;
+    const results = extractResults(data);
+    let recorded = 0;
+    let errors = 0;
+    let skipped = 0;
+    for (let i = 0; i < results.length; i++) {
+        const input = resultToOutcomeInput(results[i], {
+            workflowId,
+            index: i,
+            isSimulated: opts.isSimulated,
+            onWarn,
+        });
+        if (input === undefined) {
+            skipped++;
+            continue;
+        }
+        try {
+            await meter.recordOutcome(input);
+            recorded++;
+        }
+        catch (exc) {
+            // Never let a delivery fault abort the batch. (The meter is fail-safe by
+            // default and resolves rather than rejects; this guards a strict meter.)
+            errors++;
+            onWarn(`failed to record outcome for ${input.link}: ${exc.message}`);
+        }
+    }
+    try {
+        await meter.flush();
+    }
+    catch (exc) {
+        onWarn(`flush failed: ${exc.message}`);
+    }
+    return { recorded, errors, skipped };
+}
+//# sourceMappingURL=promptfoo.js.map

package/dist/promptfoo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptfoo.js","sourceRoot":"","sources":["../src/promptfoo.ts"],"names":[],"mappings":"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"}

package/dist/providers.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Read the measured economics of one LLM call straight off a provider response.
+ *
+ * The TS twin of `margin_meter.providers`: given the object an OpenAI /
+ * Anthropic / Gemini JS client returns, recover the `(provider, model, tokens)`
+ * a Margin call row needs — so auto-instrumentation is a few lines with no
+ * manual token bookkeeping.
+ *
+ * Dependency-free and duck-typed on purpose: it never imports the provider SDKs,
+ * reading fields by shape so it works on a real SDK object, a plain object (the
+ * shape a mocked provider returns in tests), or JSON. The three shapes, as the
+ * current JS SDKs publish them:
+ *
+ *  - **OpenAI** — `model`; `usage.prompt_tokens` / `completion_tokens`; cached
+ *    reads at `usage.prompt_tokens_details.cached_tokens` (Responses API:
+ *    `usage.input_tokens` / `output_tokens` / `input_tokens_details.cached_tokens`).
+ *  - **Anthropic** — `model`; `usage.input_tokens` / `output_tokens`; cached
+ *    reads at `usage.cache_read_input_tokens`; cache WRITES at
+ *    `usage.cache_creation_input_tokens` (a ~1.25x premium bucket).
+ *  - **Gemini** (`@google/generative-ai`) — `response.usageMetadata` (the
+ *    `generateContent` result nests it under `.response`), with
+ *    `promptTokenCount` / `candidatesTokenCount` / `cachedContentTokenCount`, plus
+ *    `thoughtsTokenCount` (thinking tokens, billed as output and folded in).
+ *    The model does not ride the response, so the caller passes it.
+ *  - **Cohere** (v2 `/chat`) — billed counts nest under `usage.billed_units`
+ *    (what is charged; raw `usage.tokens` is the fallback), each with
+ *    `input_tokens` / `output_tokens`. Cohere publishes no chat prompt-cache
+ *    discount, so cache reads bill as ordinary input (`cacheReadTokens` stays 0);
+ *    the model does not ride the response, so the caller passes it.
+ *  - **AWS Bedrock** (`@aws-sdk/client-bedrock-runtime`, Converse) — usage rides
+ *    `usage.inputTokens` / `outputTokens` in camelCase, with ADDITIVE cache
+ *    buckets `cacheReadInputTokens` / `cacheWriteInputTokens` (AWS documents
+ *    `totalTokens = inputTokens + outputTokens + cacheReadInputTokens +
+ *    cacheWriteInputTokens`), so the three input-side buckets are disjoint and
+ *    each reads verbatim, no subtraction. The Converse response omits the model
+ *    id, so the caller passes it (`instrumentBedrock` reads it off the command's
+ *    `input.modelId`); its gateway form (`us.anthropic.claude-…-v1:0`) prices
+ *    through the server's `normalize_model`.
+ *
+ * Numbers are read verbatim — never inflated. A field the provider didn't report
+ * reads 0; an unrecognised shape throws `UsageExtractionError` rather than
+ * emitting a silently-zero (free-looking) call.
+ */
+export declare const OPENAI = "openai";
+export declare const ANTHROPIC = "anthropic";
+export declare const GOOGLE = "google";
+export declare const COHERE = "cohere";
+export declare const BEDROCK = "bedrock";
+export type ProviderName = "openai" | "anthropic" | "google" | "cohere" | "bedrock";
+/** The metered economics of one call, recovered from a provider response. */
+export interface Usage {
+    provider: ProviderName;
+    /** May be undefined only when the provider omits it AND no override was passed. */
+    model?: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    /**
+     * Cache-CREATION (write) tokens — a premium bucket (Anthropic bills ~1.25x
+     * input to write a prompt-cache entry). 0 for providers that report no
+     * distinct write bucket (OpenAI/Gemini bill the writing call as ordinary
+     * input). Kept separate so the server never drops the premium. When a request
+     * pins a 1-hour TTL this holds ONLY the 5-minute portion; the 1-hour portion
+     * moves to `cacheCreation1hTokens` below.
+     */
+    cacheCreationTokens: number;
+    /**
+     * The portion of cache creation written with the LONGER 1-hour TTL, which
+     * Anthropic bills at a higher premium (~2x input vs the 5-minute ~1.25x).
+     * Disjoint from `cacheCreationTokens`. Optional/0 unless the provider reports a
+     * 1-hour breakdown, so a call using only the default cache is unchanged.
+     */
+    cacheCreation1hTokens?: number;
+    /**
+     * The hidden-thinking share of `outputTokens` (Gemini `thoughtsTokenCount`,
+     * OpenAI `completion_tokens_details.reasoning_tokens`). A SUBSET of output, not
+     * an addition — already priced at the output rate, so it is NEVER priced
+     * separately (that would double-bill). Carried only for visibility: the
+     * thinking-token share is what isolates the reasoning-effort lever from
+     * ordinary verbose output. Optional/0 on a call with no reasoning breakdown.
+     */
+    reasoningTokens?: number;
+    /**
+     * The provider's OWN reason the generation ended, read VERBATIM — Anthropic
+     * `stop_reason` (`end_turn` / `max_tokens` / `tool_use` / `refusal`), OpenAI &
+     * Gemini `finish_reason`, Cohere `finish_reason`, Bedrock `stopReason`. A raw
+     * SIGNAL, never a billing verdict: a blocked-and-fell-back call (Fable 5's safety
+     * fallback) is often NOT billed, but whether it was depends on the customer's
+     * opt-in config, so the stop reason alone can never be turned into "this was
+     * free" — that is settled by the invoice (MAR-209). Captured only so a downstream
+     * reconcile CAN ask the question; `undefined` is an honest UNKNOWN, first-class
+     * and never defaulted to a value.
+     */
+    stopReason?: string;
+    /**
+     * OpenRouter's own billed cost (`usage.cost`) for a FAN-OUT slug
+     * (`openrouter/fusion`), which runs N panel calls plus an analyst call per request,
+     * so no token rate prices it (MAR-1309). `undefined` for every other call — the
+     * server then prices tokens off its table exactly as before.
+     */
+    billedCostUsd?: number;
+}
+/** The response object matched no provider shape we can meter. */
+export declare class UsageExtractionError extends Error {
+    constructor(message: string);
+}
+type Any = Record<string, unknown> | null | undefined | unknown;
+/**
+ * Best-effort provider inference from a response's shape. Prefers unambiguous
+ * signals: Gemini exposes `usageMetadata`; Anthropic's usage carries
+ * `input_tokens` while OpenAI's carries `prompt_tokens`. Returns undefined when
+ * nothing distinguishes it — the caller must then name the provider (the
+ * instrumenter always does).
+ */
+export declare function detectProvider(response: Any): ProviderName | undefined;
+/** True for `openrouter/fusion` and its siblings (many billed calls per request). */
+export declare function isFanoutSlug(model?: string): boolean;
+/**
+ * Recover the metered `Usage` of one call from its provider response. `provider`
+ * forces the shape (the instrumenter always knows which client it patched);
+ * omit it and the provider is inferred from the response's shape. `model`
+ * overrides a response that omits its model (Gemini). Throws
+ * `UsageExtractionError` when the shape matches no known provider or carries no
+ * usage block, so a silently-free call is never emitted.
+ */
+export declare function extractUsage(response: Any, opts?: {
+    provider?: ProviderName;
+    model?: string;
+}): Usage;
+/**
+ * Read whatever usage ONE streaming chunk/event carries, or `undefined`.
+ *
+ * The three streamed shapes differ in WHERE (and whether) a chunk carries usage:
+ *
+ *  - **OpenAI** (needs `stream_options: { include_usage: true }`): every content
+ *    chunk has `usage: null`; only the FINAL chunk carries the full `.usage`.
+ *  - **Gemini**: every chunk carries a CUMULATIVE `usageMetadata` — the last is
+ *    authoritative, and the running max keeps it.
+ *  - **Anthropic**: no single event is complete — `message_start` carries the
+ *    input + cache counts nested under `event.message.usage`, while `message_delta`
+ *    carries the final `event.usage.output_tokens`. This reads BOTH carriers so the
+ *    merge can reunite them.
+ *
+ * Returns `undefined` (never throws) for a chunk with no usage, so an ordinary
+ * content chunk is skipped, not treated as an error.
+ */
+export declare function usageFromStreamChunk(chunk: Any, provider?: ProviderName, model?: string): Usage | undefined;
+/**
+ * Merge two per-chunk usages, taking the MAX of each token bucket.
+ *
+ * Every streamed token count is monotonic within one call — cumulative (Gemini),
+ * or populated exactly once (OpenAI's final chunk; Anthropic's input-here /
+ * output-there split) — so the running max reconstructs the final total no matter
+ * which chunk carried which field. The max never invents a token; it only keeps
+ * the largest REAL count each field reached.
+ */
+export declare function mergeStreamUsage(a: Usage, b: Usage): Usage;
+/**
+ * The stop reason one stream chunk carries, if any. Never throws.
+ *
+ * A stream rarely puts the reason and the usage on the same chunk (MAR-1516). OpenAI's
+ * finish chunk has no `usage` and the usage chunk after it has empty `choices`; Bedrock
+ * `converseStream` sends `stopReason` in `messageStop` and usage in a separate
+ * `metadata` event. A reader that only looks at usage-bearing chunks records every
+ * streamed call with no reason, so this reads it from whichever chunk holds it.
+ */
+export declare function streamChunkStopReason(chunk: Any): string | undefined;
+/**
+ * Accumulates the metered usage of one STREAMING call across its chunks.
+ *
+ * Feed every chunk to `observe` as the host iterates the stream, then call
+ * `finalize` once the stream is exhausted (or closed) to get the single `Usage`
+ * for the whole call — or `undefined` when the stream never carried a usage block
+ * (e.g. an OpenAI stream opened without `include_usage`, where there is genuinely
+ * no count to meter and inventing one would be a lie). Provider-agnostic: the
+ * per-chunk read + max-merge handles OpenAI, Anthropic and Gemini streams alike.
+ */
+export declare class StreamUsageAccumulator {
+    private provider?;
+    private model?;
+    private usage;
+    private stopReason;
+    constructor(provider?: ProviderName, model?: string);
+    /** Fold one chunk's usage (if any) into the running total. Never throws. */
+    observe(chunk: Any): void;
+    /** The accumulated usage, or `undefined` if the stream carried no usage. */
+    finalize(): Usage | undefined;
+}
+export {};
+//# sourceMappingURL=providers.d.ts.map

package/dist/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,SAAS,cAAc,CAAC;AACrC,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,OAAO,YAAY,CAAC;AAEjC,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEpF,6EAA6E;AAC7E,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,YAAY,CAAC;IACvB,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,kEAAkE;AAClE,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC;AAsDhE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,GAAG,GAAG,YAAY,GAAG,SAAS,CAuBtE;AAoBD,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAGpD;AAiND;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,GAAG,EACb,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,YAAY,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACrD,KAAK,CAUP;AAeD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,GAAG,EACV,QAAQ,CAAC,EAAE,YAAY,EACvB,KAAK,CAAC,EAAE,MAAM,GACb,KAAK,GAAG,SAAS,CAoBnB;AA+ED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,KAAK,CAqB1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAqBpE;AAED;;;;;;;;;GASG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,CAAe;IAChC,OAAO,CAAC,KAAK,CAAC,CAAS;IACvB,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,UAAU,CAAiC;gBAIvC,QAAQ,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,MAAM;IAKnD,4EAA4E;IAC5E,OAAO,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;IAYzB,4EAA4E;IAC5E,QAAQ,IAAI,KAAK,GAAG,SAAS;CAK9B"}