modelrig 0.1.0 → 0.3.0

package/dist/registry/parity.d.ts

@@ -22,5 +22,31 @@ export interface ParityReport {
     readonly probedPct: number;
     readonly gaps: readonly ParityGap[];
 }
+/**
+ * Normalize a model key for the parity join. The parity list is a hand-curated
+ * monthly snapshot; the registry is machine-generated from probe result files.
+ * Two keys that differ only by CASE or surrounding whitespace name the same
+ * model, so we match modulo those — a benign rename (e.g. `Qwen` vs `qwen` in a
+ * host catalog) must not silently drop coverage and force another manual
+ * id_repair. This is deliberately conservative: it collapses case/whitespace
+ * only, never leaf variants, so distinct ids (`grok/grok-4-2` vs `grok/grok-4.3`)
+ * stay distinct and an unprobed model is never falsely counted as probed.
+ */
+export declare function normalizeParityKey(key: string): string;
 export declare function computeParity(list: readonly ParityListEntry[], registry: Registry): ParityReport;
+/** Does the registry contain at least one model with probed schema samples?
+ * The precondition for the zero-coverage gate below: a 0 coverage number is
+ * only suspicious when there IS probed data that failed to join. */
+export declare function registryHasProbedModels(registry: Registry): boolean;
+/**
+ * Mechanical zero-coverage gate — makes the parity-list ↔ registry join
+ * regression un-forgettable. If parity coverage computes 0 probed WHILE the
+ * registry actually contains probed models, the join is broken (an id/namespace
+ * mismatch between the curated list and the machine-generated registry, exactly
+ * the failure the id_repair_note documents), and a leaderboard rendered from it
+ * would publish 0% coverage as if it were true. Throw rather than render that.
+ * A legitimately-empty registry (no probed models yet) computes 0 and is fine.
+ * Call this wherever computeParity feeds a rendered/published surface.
+ */
+export declare function assertParityCoverageSane(report: ParityReport, registry: Registry): void;
 //# sourceMappingURL=parity.d.ts.map

package/dist/registry/parity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parity.d.ts","sourceRoot":"","sources":["../../src/registry/parity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB,CAAC;CACvD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;CACrC;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,EAAE,QAAQ,EAAE,QAAQ,GAAG,YAAY,CA4BhG"}
+{"version":3,"file":"parity.d.ts","sourceRoot":"","sources":["../../src/registry/parity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB,CAAC;CACvD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,EAAE,QAAQ,EAAE,QAAQ,GAAG,YAAY,CA4BhG;AAED;;oEAEoE;AACpE,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAEnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAUvF"}

package/dist/registry/parity.js

@@ -7,16 +7,32 @@
  * Gaps are named on the leaderboard ("not yet probed"), never invisible.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeParityKey = normalizeParityKey;
 exports.computeParity = computeParity;
+exports.registryHasProbedModels = registryHasProbedModels;
+exports.assertParityCoverageSane = assertParityCoverageSane;
+/**
+ * Normalize a model key for the parity join. The parity list is a hand-curated
+ * monthly snapshot; the registry is machine-generated from probe result files.
+ * Two keys that differ only by CASE or surrounding whitespace name the same
+ * model, so we match modulo those — a benign rename (e.g. `Qwen` vs `qwen` in a
+ * host catalog) must not silently drop coverage and force another manual
+ * id_repair. This is deliberately conservative: it collapses case/whitespace
+ * only, never leaf variants, so distinct ids (`grok/grok-4-2` vs `grok/grok-4.3`)
+ * stay distinct and an unprobed model is never falsely counted as probed.
+ */
+function normalizeParityKey(key) {
+    return key.trim().toLowerCase();
+}
 function computeParity(list, registry) {
-    const byKey = new Map(registry.models.map((m) => [m.model_key, m]));
+    const byKey = new Map(registry.models.map((m) => [normalizeParityKey(m.model_key), m]));
     let probed = 0;
     let listedUnprobed = 0;
     let missing = 0;
     const gaps = [];
     for (const entry of list) {
         const matches = entry.registry_keys
-            .map((k) => byKey.get(k))
+            .map((k) => byKey.get(normalizeParityKey(k)))
             .filter((m) => m !== undefined);
         if (matches.some((m) => (m.probed?.schema?.samples ?? 0) > 0)) {
             probed += 1;
@@ -39,3 +55,28 @@ function computeParity(list, registry) {
         gaps,
     };
 }
+/** Does the registry contain at least one model with probed schema samples?
+ * The precondition for the zero-coverage gate below: a 0 coverage number is
+ * only suspicious when there IS probed data that failed to join. */
+function registryHasProbedModels(registry) {
+    return registry.models.some((m) => (m.probed?.schema?.samples ?? 0) > 0);
+}
+/**
+ * Mechanical zero-coverage gate — makes the parity-list ↔ registry join
+ * regression un-forgettable. If parity coverage computes 0 probed WHILE the
+ * registry actually contains probed models, the join is broken (an id/namespace
+ * mismatch between the curated list and the machine-generated registry, exactly
+ * the failure the id_repair_note documents), and a leaderboard rendered from it
+ * would publish 0% coverage as if it were true. Throw rather than render that.
+ * A legitimately-empty registry (no probed models yet) computes 0 and is fine.
+ * Call this wherever computeParity feeds a rendered/published surface.
+ */
+function assertParityCoverageSane(report, registry) {
+    if (report.probed === 0 && registryHasProbedModels(registry)) {
+        throw new Error("parity-50 coverage computed 0 probed, but the registry contains probed models — " +
+            "the parity-list↔registry join is broken (likely an id/namespace mismatch between the " +
+            "curated list keys and the registry model_keys). Refusing to render a leaderboard that " +
+            "hides real coverage. Fix the registry_keys in registry/parity-50.json or the " +
+            "normalization in src/registry/parity.ts.");
+    }
+}

package/dist/registry/pricing-shape.d.ts

@@ -0,0 +1,113 @@
+/**
+ * First-class pricing shape — spec `pricing-first-class/spec.md` §2.1.
+ *
+ * A structured, additive representation of a model's price that can carry
+ * every component a vendor publishes (serving-tier multipliers, cache-write,
+ * context-length bands, batch discounts, per-modality input rates), each with
+ * `source` + `as_of`, and — required — a `basis` string stating what the
+ * headline number *is*. It exists ALONGSIDE the flat three-component
+ * `DeclaredLayer.pricing` (which is not retired this pass — S3 order of
+ * destruction); a snapshot-only entry maps trivially via `synthesizeFromFlat`.
+ *
+ * GOVERNING RULE (dev-rule L5, spec §3): never fabricate a component you have
+ * not verified against the vendor's published number. Tier multipliers are
+ * MULTIPLIERS on `base` (1.0 = base), not absolute rates — a mis-read
+ * multiplier is worse than a missing one, so absent data degrades to
+ * `base`-only, never to a guessed tier.
+ *
+ * Units: every `TokenRates` field is USD PER TOKEN (not per-Mtok) — the same
+ * unit as `ModelPricing.inputUsdPerTok`, so synthesis is a pure passthrough.
+ */
+export interface TokenRates {
+    readonly input: number;
+    readonly output: number;
+    /** context-cache READ rate. */
+    readonly cache_read?: number | null;
+    /** context-cache WRITE rate (Anthropic-class 5m TTL / OpenAI 5.6+). */
+    readonly cache_write?: number | null;
+    /** 1h-TTL context-cache WRITE rate (Anthropic 2×; WS-A). Additive — absent
+     * ⇒ the 1h write bucket bills at `cache_write` (fail-closed, dev-rule L5). */
+    readonly cache_write_1h?: number | null;
+}
+/** MULTIPLIERS on `base` (1.0 = base), NOT absolute rates. */
+export interface ServingTiers {
+    readonly priority?: number | null;
+    readonly fast?: number | null;
+    readonly region_us?: number | null;
+}
+/** A rate change that applies above a token threshold. */
+export interface ContextBand {
+    readonly above_tokens: number;
+    readonly rates: TokenRates;
+}
+/** Non-text input units, USD per unit. */
+export interface ModalityRates {
+    readonly image_per_unit?: number | null;
+    readonly audio_per_second?: number | null;
+}
+export interface ModelPricingV2 {
+    /** standard-tier text — the only REQUIRED rates block. */
+    readonly base: TokenRates;
+    readonly tiers?: ServingTiers | null;
+    readonly context_bands?: readonly ContextBand[] | null;
+    readonly batch_discount?: number | null;
+    readonly modality?: ModalityRates | null;
+    /** provenance: host-api / website / snapshot. */
+    readonly source: string;
+    readonly as_of: string;
+    /** What `base` represents, rendered verbatim on the surface (P5, in code). */
+    readonly basis: string;
+}
+/** The basis string for a snapshot-synthesized (base-only, standard, text)
+ * entry — the honest caveat when nothing richer than three components exists. */
+export declare const SNAPSHOT_BASIS = "base \u00B7 standard tier \u00B7 text";
+/**
+ * Map a flat three-component price (USD per token) to a `ModelPricingV2` with
+ * `base` only — `tiers`, `context_bands`, `batch`, `modality` all null. This is
+ * the fail-closed default for every model the sweep could not enrich: it
+ * asserts nothing beyond the standard text rate the flat field already carried.
+ *
+ * `asOf`/`source` are provenance the shape requires (spec §2.1 marks both
+ * required); the plan names the three rate values as the essential inputs, and
+ * the caller supplies provenance. `source` defaults to the snapshot lane.
+ */
+export declare function synthesizeFromFlat(input: number, output: number, cache_read: number | null, asOf: string, source?: string): ModelPricingV2;
+export type ServingTierName = "priority" | "fast" | "region_us";
+/**
+ * Absolute rates for a serving tier = `base × multiplier`. Returns `null` when
+ * the tier's multiplier is absent — fail-closed, so no surface can render a
+ * tier price the model never published. The multiplier scales every rate
+ * component present on `base`.
+ */
+export declare function tierRates(pricing: ModelPricingV2, tier: ServingTierName): TokenRates | null;
+/** A display-ready projection of a price. `basis` is always present, so a
+ * surface built from this object can never show a number without its caveat. */
+export interface PricingV2Display {
+    /** what the headline number IS — always present (the render caveat). */
+    readonly basis: string;
+    /** "$3.00 in · $15.00 out per Mtok" — the base rates. */
+    readonly base: string;
+    readonly cacheRead: string | null;
+    readonly cacheWrite: string | null;
+    /** 1h-TTL cache-write rate per Mtok (Anthropic 2×); null when unpublished. */
+    readonly cacheWrite1h: string | null;
+    /** absolute tier rates, base × multiplier, per Mtok. */
+    readonly tiers: readonly {
+        readonly name: ServingTierName;
+        readonly rate: string;
+    }[];
+    readonly contextBands: readonly string[];
+    readonly batch: string | null;
+    readonly modality: readonly string[];
+    readonly source: string;
+    readonly asOf: string;
+    /** vendor page URL if the `source` embeds one, for a "full terms" link. */
+    readonly vendorUrl: string | null;
+}
+/**
+ * Build the display projection. Every returned object carries `basis`; the
+ * base rate string is only ever produced together with it — the render-caveat
+ * guarantee lives here, in code, so no consumer can bypass it.
+ */
+export declare function describePricingV2(pricing: ModelPricingV2): PricingV2Display;
+//# sourceMappingURL=pricing-shape.d.ts.map

package/dist/registry/pricing-shape.d.ts.map

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

package/dist/registry/pricing-shape.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * First-class pricing shape — spec `pricing-first-class/spec.md` §2.1.
+ *
+ * A structured, additive representation of a model's price that can carry
+ * every component a vendor publishes (serving-tier multipliers, cache-write,
+ * context-length bands, batch discounts, per-modality input rates), each with
+ * `source` + `as_of`, and — required — a `basis` string stating what the
+ * headline number *is*. It exists ALONGSIDE the flat three-component
+ * `DeclaredLayer.pricing` (which is not retired this pass — S3 order of
+ * destruction); a snapshot-only entry maps trivially via `synthesizeFromFlat`.
+ *
+ * GOVERNING RULE (dev-rule L5, spec §3): never fabricate a component you have
+ * not verified against the vendor's published number. Tier multipliers are
+ * MULTIPLIERS on `base` (1.0 = base), not absolute rates — a mis-read
+ * multiplier is worse than a missing one, so absent data degrades to
+ * `base`-only, never to a guessed tier.
+ *
+ * Units: every `TokenRates` field is USD PER TOKEN (not per-Mtok) — the same
+ * unit as `ModelPricing.inputUsdPerTok`, so synthesis is a pure passthrough.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SNAPSHOT_BASIS = void 0;
+exports.synthesizeFromFlat = synthesizeFromFlat;
+exports.tierRates = tierRates;
+exports.describePricingV2 = describePricingV2;
+/** The basis string for a snapshot-synthesized (base-only, standard, text)
+ * entry — the honest caveat when nothing richer than three components exists. */
+exports.SNAPSHOT_BASIS = "base · standard tier · text";
+/**
+ * Map a flat three-component price (USD per token) to a `ModelPricingV2` with
+ * `base` only — `tiers`, `context_bands`, `batch`, `modality` all null. This is
+ * the fail-closed default for every model the sweep could not enrich: it
+ * asserts nothing beyond the standard text rate the flat field already carried.
+ *
+ * `asOf`/`source` are provenance the shape requires (spec §2.1 marks both
+ * required); the plan names the three rate values as the essential inputs, and
+ * the caller supplies provenance. `source` defaults to the snapshot lane.
+ */
+function synthesizeFromFlat(input, output, cache_read, asOf, source = "litellm-snapshot") {
+    return {
+        base: { input, output, cache_read },
+        tiers: null,
+        context_bands: null,
+        batch_discount: null,
+        modality: null,
+        source,
+        as_of: asOf,
+        basis: exports.SNAPSHOT_BASIS,
+    };
+}
+function scale(rate, mult) {
+    return rate === null || rate === undefined ? null : rate * mult;
+}
+/**
+ * Absolute rates for a serving tier = `base × multiplier`. Returns `null` when
+ * the tier's multiplier is absent — fail-closed, so no surface can render a
+ * tier price the model never published. The multiplier scales every rate
+ * component present on `base`.
+ */
+function tierRates(pricing, tier) {
+    const mult = pricing.tiers?.[tier];
+    if (mult === null || mult === undefined)
+        return null;
+    return {
+        input: pricing.base.input * mult,
+        output: pricing.base.output * mult,
+        cache_read: scale(pricing.base.cache_read, mult),
+        cache_write: scale(pricing.base.cache_write, mult),
+        cache_write_1h: scale(pricing.base.cache_write_1h, mult),
+    };
+}
+const TIER_ORDER = ["priority", "fast", "region_us"];
+/** USD-per-token → "$X.XX" per Mtok. Adaptive precision: a pricing-authority
+ * surface must not misrepresent a rate — `$0.075/M` renders as `$0.075`, not a
+ * rounded `$0.07`/`$0.08`. Shows up to 6 decimals, trailing zeros trimmed, with
+ * a 2-decimal floor for readability. */
+function perMtok(perToken) {
+    const v = perToken * 1e6;
+    const trimmed = v.toFixed(6).replace(/\.?0+$/, "");
+    const decimals = trimmed.includes(".") ? trimmed.split(".")[1].length : 0;
+    return `$${decimals >= 2 ? trimmed : v.toFixed(2)}`;
+}
+function inOut(rates) {
+    return `${perMtok(rates.input)} in · ${perMtok(rates.output)} out per Mtok`;
+}
+const URL_RE = /https?:\/\/[^\s)]+/;
+/**
+ * Build the display projection. Every returned object carries `basis`; the
+ * base rate string is only ever produced together with it — the render-caveat
+ * guarantee lives here, in code, so no consumer can bypass it.
+ */
+function describePricingV2(pricing) {
+    const tiers = [];
+    for (const name of TIER_ORDER) {
+        const rates = tierRates(pricing, name);
+        if (rates !== null)
+            tiers.push({ name, rate: inOut(rates) });
+    }
+    const contextBands = (pricing.context_bands ?? []).map((b) => `above ${b.above_tokens.toLocaleString()} tok: ${inOut(b.rates)}`);
+    const modality = [];
+    if (pricing.modality?.image_per_unit != null) {
+        modality.push(`image: $${pricing.modality.image_per_unit.toFixed(4)} per unit`);
+    }
+    if (pricing.modality?.audio_per_second != null) {
+        modality.push(`audio: $${pricing.modality.audio_per_second.toFixed(4)} per second`);
+    }
+    const urlMatch = URL_RE.exec(pricing.source);
+    return {
+        basis: pricing.basis,
+        base: inOut(pricing.base),
+        cacheRead: pricing.base.cache_read != null ? `${perMtok(pricing.base.cache_read)} per Mtok` : null,
+        cacheWrite: pricing.base.cache_write != null ? `${perMtok(pricing.base.cache_write)} per Mtok` : null,
+        cacheWrite1h: pricing.base.cache_write_1h != null ? `${perMtok(pricing.base.cache_write_1h)} per Mtok` : null,
+        tiers,
+        contextBands,
+        batch: pricing.batch_discount != null ? `${(pricing.batch_discount * 100).toFixed(0)}% off base` : null,
+        modality,
+        source: pricing.source,
+        asOf: pricing.as_of,
+        vendorUrl: urlMatch ? urlMatch[0] : null,
+    };
+}

package/dist/registry/pricing.d.ts

@@ -9,11 +9,35 @@
  * Copyright (c) 2023 Berri AI, MIT License (https://github.com/BerriAI/litellm).
  */
 import type { ProviderId } from "../types/provider";
+import type { ModelPricingV2 } from "./pricing-shape";
 export interface ModelPricing {
     readonly inputUsdPerTok: number;
     readonly outputUsdPerTok: number;
     readonly cachedInputUsdPerTok: number | null;
+    /** Cache-CREATION (write) rate, USD/tok (WS-A). From LiteLLM
+     * `cache_creation_input_token_cost`. null ⇒ unverified: cache writes bill at
+     * the input rate (1.0×), never a guessed premium (dev-rule L5). */
+    readonly cacheWriteUsdPerTok: number | null;
+    /** 1h-TTL cache-write rate, USD/tok (Anthropic 2×; WS-A). From LiteLLM
+     * `cache_creation_input_token_cost_above_1hr`. null ⇒ the 1h portion falls
+     * back to `cacheWriteUsdPerTok` (then to input) — fail-closed. */
+    readonly cacheWrite1hUsdPerTok: number | null;
 }
 export declare function getPricing(provider: ProviderId, model: string): ModelPricing | null;
-export declare function estimateCostUsd(pricing: ModelPricing, tokensIn: number, tokensOut: number, tokensCached: number): number;
+/**
+ * The richer `ModelPricingV2` a vendor overlay/manual entry carries, if any —
+ * resolved by the SAME key precedence as {@link getPricing} (snapshot wins on a
+ * shared key, and the snapshot never carries `pricing_v2`, so a shared key
+ * yields null → the caller synthesizes from the flat rate). Returns null when
+ * no richer shape is on file. Never guesses: absence is `base`-only downstream.
+ */
+export declare function getPricingV2(provider: ProviderId, model: string): ModelPricingV2 | null;
+export declare function estimateCostUsd(pricing: ModelPricing, tokensIn: number, tokensOut: number, tokensCached: number, 
+/** Cache-CREATION (write) tokens — a subset of tokensIn, WS-A (spec §4.1).
+ * Defaults to 0: with a zero write the whole expression collapses to the
+ * pre-WS-A formula BYTE-IDENTICALLY (the regression pin), so every existing
+ * caller and stored cost is unchanged. */
+tokensCacheWrite?: number, 
+/** 1h-TTL portion of the write (bills at the higher multiplier when known). */
+tokensCacheWrite1h?: number): number;
 //# sourceMappingURL=pricing.d.ts.map

package/dist/registry/pricing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../src/registry/pricing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C;AAmCD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAqBnF;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,MAAM,CAWR"}
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../src/registry/pricing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C;;uEAEmE;IACnE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C;;sEAEkE;IAClE,QAAQ,CAAC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/C;AAyDD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA6BnF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAYvF;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM;AACpB;;;0CAG0C;AAC1C,gBAAgB,SAAI;AACpB,+EAA+E;AAC/E,kBAAkB,SAAI,GACrB,MAAM,CAsBR"}

package/dist/registry/pricing.js

@@ -11,6 +11,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPricing = getPricing;
+exports.getPricingV2 = getPricingV2;
 exports.estimateCostUsd = estimateCostUsd;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -30,10 +31,22 @@ const KEY_PREFIXES = {
     fireworks: ["fireworks_ai/accounts/fireworks/models/", "fireworks_ai/"],
 };
 let cachedMap = null;
+/** Host-swept gap-filler (scripts/pricing-sweep.ts): prices for models the
+ * pinned LiteLLM snapshot has not caught up to. Merged BENEATH the snapshot —
+ * the snapshot wins on any shared key (stability); the overlay only fills gaps.
+ * Absent file ⇒ no overlay, unchanged behaviour. */
+function loadOverlay(dataDir) {
+    const path = (0, node_path_1.join)(dataDir, "pricing-overlay.json");
+    if (!(0, node_fs_1.existsSync)(path))
+        return {};
+    const parsed = JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+    return parsed.prices ?? {};
+}
 function loadMap() {
     if (cachedMap === null) {
-        const raw = (0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "..", "data", "pricing-map.json"), "utf8");
-        cachedMap = JSON.parse(raw);
+        const dataDir = (0, node_path_1.join)(__dirname, "..", "..", "data");
+        const snapshot = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dataDir, "pricing-map.json"), "utf8"));
+        cachedMap = { ...loadOverlay(dataDir), ...snapshot };
     }
     return cachedMap;
 }
@@ -52,18 +65,63 @@ function getPricing(provider, model) {
                 cachedInputUsdPerTok: typeof entry.cache_read_input_token_cost === "number"
                     ? entry.cache_read_input_token_cost
                     : null,
+                cacheWriteUsdPerTok: typeof entry.cache_creation_input_token_cost === "number"
+                    ? entry.cache_creation_input_token_cost
+                    : null,
+                cacheWrite1hUsdPerTok: typeof entry.cache_creation_input_token_cost_above_1hr === "number"
+                    ? entry.cache_creation_input_token_cost_above_1hr
+                    : null,
             };
         }
     }
     return null;
 }
-function estimateCostUsd(pricing, tokensIn, tokensOut, tokensCached) {
-    // Providers report tokensCached as a subset of tokensIn; bill the cached
-    // part at the cached rate (input rate when none) and never negatively.
+/**
+ * The richer `ModelPricingV2` a vendor overlay/manual entry carries, if any —
+ * resolved by the SAME key precedence as {@link getPricing} (snapshot wins on a
+ * shared key, and the snapshot never carries `pricing_v2`, so a shared key
+ * yields null → the caller synthesizes from the flat rate). Returns null when
+ * no richer shape is on file. Never guesses: absence is `base`-only downstream.
+ */
+function getPricingV2(provider, model) {
+    if (model === "")
+        return null;
+    const map = loadMap();
+    for (const prefix of KEY_PREFIXES[provider]) {
+        const entry = map[`${prefix}${model}`];
+        if (entry !== undefined && typeof entry.input_cost_per_token === "number") {
+            // Resolve on the same entry getPricing would pick; only that entry's
+            // pricing_v2 counts (a later-prefix match must not shadow it).
+            return entry.pricing_v2 ?? null;
+        }
+    }
+    return null;
+}
+function estimateCostUsd(pricing, tokensIn, tokensOut, tokensCached, 
+/** Cache-CREATION (write) tokens — a subset of tokensIn, WS-A (spec §4.1).
+ * Defaults to 0: with a zero write the whole expression collapses to the
+ * pre-WS-A formula BYTE-IDENTICALLY (the regression pin), so every existing
+ * caller and stored cost is unchanged. */
+tokensCacheWrite = 0, 
+/** 1h-TTL portion of the write (bills at the higher multiplier when known). */
+tokensCacheWrite1h = 0) {
+    // Providers report tokensCached and tokensCacheWrite as subsets of tokensIn;
+    // bill each at its rate, the remainder at the input rate, never negatively.
     const cached = Math.min(Math.max(tokensCached, 0), Math.max(tokensIn, tokensCached));
-    const uncachedIn = Math.max(tokensIn - cached, 0);
+    const write = Math.max(tokensCacheWrite, 0);
+    const write1h = Math.min(Math.max(tokensCacheWrite1h, 0), write);
+    // uncached subtracts BOTH cache buckets. With write === 0 this is exactly the
+    // former `max(tokensIn − cached, 0)`, so a zero-write call is unchanged.
+    const uncachedIn = Math.max(tokensIn - cached - write, 0);
     const cachedRate = pricing.cachedInputUsdPerTok ?? pricing.inputUsdPerTok;
+    // L5 fail-closed: an unverified write rate degrades to the INPUT rate (1.0×),
+    // never a guessed premium; the 1h rate degrades to the 5m write rate, then to
+    // input. Below-min / non-cache-write callers pass 0 and touch none of this.
+    const writeRate = pricing.cacheWriteUsdPerTok ?? pricing.inputUsdPerTok;
+    const write1hRate = pricing.cacheWrite1hUsdPerTok ?? writeRate;
     return (uncachedIn * pricing.inputUsdPerTok +
         cached * cachedRate +
+        (write - write1h) * writeRate +
+        write1h * write1hRate +
         Math.max(tokensOut, 0) * pricing.outputUsdPerTok);
 }

package/dist/rigindex/bootstrap.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Hierarchical bootstrap CI — RATIFIED PER THE ERRATUM (stop2-architect-review
+ * §1): per rep, (1) resample fixtures within the subtype with replacement,
+ * then (2) ONE resample of each (model, fixture)'s samples, used consistently
+ * across ALL of that model's comparisons in the rep (NOT per model-pair — the
+ * archived prototype's per-pair form injects extra noise and is superseded).
+ * ≥200 reps; 2.5/97.5 percentiles. RNG is seeded and injectable so a fixed
+ * seed reproduces scores and tiers exactly.
+ *
+ * Any change to the resampling scheme re-opens STOP-2.
+ */
+import type { SubtypeSamples } from "./types";
+export declare const BOOTSTRAP_REPS = 200;
+export declare const CI_LO = 0.025;
+export declare const CI_HI = 0.975;
+/** Deterministic PRNG (mulberry32) — seedable, dependency-free. */
+export declare function mulberry32(seed: number): () => number;
+/**
+ * The per-rep resampling plan, exposed for the determinism test family (f):
+ * one fixture multiset draw + exactly ONE per-(model, fixture) sample
+ * resample, keyed so the same array object serves every comparison the model
+ * enters that rep.
+ */
+export declare function drawRep(samples: SubtypeSamples, fixtures: readonly string[], rng: () => number): {
+    readonly fixtureDraws: readonly string[];
+    readonly resampled: SubtypeSamples;
+};
+/**
+ * Bootstrap CIs for one subtype's anchored scores. Returns modelKey →
+ * [2.5th, 97.5th] percentile of the rep RigIndex distribution. A rep where the
+ * basket cannot anchor (all basket members drew empty) is skipped — with the
+ * probe corpus every model has every fixture, so this is a degenerate-input
+ * guard, not a data path.
+ */
+export declare function bootstrapCis(samples: SubtypeSamples, basket: readonly string[], reps: number, rng: () => number): Record<string, readonly [number, number]>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/rigindex/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/rigindex/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5D,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,eAAO,MAAM,KAAK,QAAQ,CAAC;AAC3B,eAAO,MAAM,KAAK,QAAQ,CAAC;AAE3B,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,MAAM,CASrD;AAOD;;;;;GAKG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,GAAG,EAAE,MAAM,MAAM,GAChB;IACD,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;CACpC,CAYA;AAWD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAsB3C"}

package/dist/rigindex/bootstrap.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Hierarchical bootstrap CI — RATIFIED PER THE ERRATUM (stop2-architect-review
+ * §1): per rep, (1) resample fixtures within the subtype with replacement,
+ * then (2) ONE resample of each (model, fixture)'s samples, used consistently
+ * across ALL of that model's comparisons in the rep (NOT per model-pair — the
+ * archived prototype's per-pair form injects extra noise and is superseded).
+ * ≥200 reps; 2.5/97.5 percentiles. RNG is seeded and injectable so a fixed
+ * seed reproduces scores and tiers exactly.
+ *
+ * Any change to the resampling scheme re-opens STOP-2.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CI_HI = exports.CI_LO = exports.BOOTSTRAP_REPS = void 0;
+exports.mulberry32 = mulberry32;
+exports.drawRep = drawRep;
+exports.bootstrapCis = bootstrapCis;
+const graph_1 = require("./graph");
+const fit_1 = require("./fit");
+exports.BOOTSTRAP_REPS = 200;
+exports.CI_LO = 0.025;
+exports.CI_HI = 0.975;
+/** Deterministic PRNG (mulberry32) — seedable, dependency-free. */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** One with-replacement resample of `list`, same length. */
+function resample(list, rng) {
+    return list.map(() => list[Math.floor(rng() * list.length)]);
+}
+/**
+ * The per-rep resampling plan, exposed for the determinism test family (f):
+ * one fixture multiset draw + exactly ONE per-(model, fixture) sample
+ * resample, keyed so the same array object serves every comparison the model
+ * enters that rep.
+ */
+function drawRep(samples, fixtures, rng) {
+    const fixtureDraws = resample(fixtures, rng);
+    // ONE resample per (model, fixture) — iterate in stable sorted order so a
+    // fixed seed reproduces the plan exactly.
+    const resampled = {};
+    for (const model of Object.keys(samples).sort()) {
+        resampled[model] = {};
+        for (const fixtureId of Object.keys(samples[model]).sort()) {
+            resampled[model][fixtureId] = resample(samples[model][fixtureId], rng);
+        }
+    }
+    return { fixtureDraws, resampled };
+}
+function percentile(sorted, q) {
+    if (sorted.length === 0)
+        return NaN;
+    const idx = q * (sorted.length - 1);
+    const lo = Math.floor(idx);
+    const hi = Math.ceil(idx);
+    if (lo === hi)
+        return sorted[lo];
+    return sorted[lo] + (sorted[hi] - sorted[lo]) * (idx - lo);
+}
+/**
+ * Bootstrap CIs for one subtype's anchored scores. Returns modelKey →
+ * [2.5th, 97.5th] percentile of the rep RigIndex distribution. A rep where the
+ * basket cannot anchor (all basket members drew empty) is skipped — with the
+ * probe corpus every model has every fixture, so this is a degenerate-input
+ * guard, not a data path.
+ */
+function bootstrapCis(samples, basket, reps, rng) {
+    const models = Object.keys(samples).sort();
+    const fixtures = [...new Set(models.flatMap((m) => Object.keys(samples[m])))].sort();
+    const draws = Object.fromEntries(models.map((m) => [m, []]));
+    for (let rep = 0; rep < reps; rep += 1) {
+        const { fixtureDraws, resampled } = drawRep(samples, fixtures, rng);
+        const graph = (0, graph_1.buildSubtypeGraph)(resampled, fixtureDraws);
+        const scores = (0, fit_1.anchorScores)((0, fit_1.fitBradleyTerry)(graph), basket);
+        if (scores === null)
+            continue;
+        for (const m of models) {
+            if (scores[m] !== undefined)
+                draws[m].push(scores[m]);
+        }
+    }
+    const out = {};
+    for (const m of models) {
+        const sorted = [...draws[m]].sort((a, b) => a - b);
+        if (sorted.length === 0)
+            continue;
+        out[m] = [percentile(sorted, exports.CI_LO), percentile(sorted, exports.CI_HI)];
+    }
+    return out;
+}

package/dist/rigindex/fit.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Bradley-Terry fit + frontier anchor — RATIFIED (stop2-architect-review §1):
+ * Hunter's MM algorithm, 400 iterations or convergence, symmetric 0.01
+ * pseudo-wins per ordered pair (keeps saturated all-tie graphs finite and the
+ * graph connected), geometric-mean-normalized per iteration. Anchor:
+ * RigIndex_i = 100 × p_i / GM(basket strengths) — scores >100 are expected
+ * ("above the frontier average").
+ *
+ * Any change to the solver, regularization, or anchor re-opens STOP-2.
+ */
+import type { SubtypeGraph } from "./types";
+export declare const MM_MAX_ITERS = 400;
+export declare const MM_CONVERGENCE = 1e-10;
+export declare const PSEUDO_WINS = 0.01;
+/** Fit BT strengths over the graph's models. Returns modelKey → p, GM-normalized
+ * to 1. Deterministic — no randomness in the fit. */
+export declare function fitBradleyTerry(graph: SubtypeGraph): Record<string, number>;
+/** Geometric mean of the basket members' strengths, over the members present
+ * in the fit. Null when NO basket member is in the graph — the subtype cannot
+ * be anchored (and must not publish a score). */
+export declare function basketGeometricMean(strengths: Readonly<Record<string, number>>, basket: readonly string[]): number | null;
+/** RigIndex_i = 100 × p_i / GM(basket) (review §1). Null when unanchorable. */
+export declare function anchorScores(strengths: Readonly<Record<string, number>>, basket: readonly string[]): Record<string, number> | null;
+//# sourceMappingURL=fit.d.ts.map