modelrig 0.0.1 → 0.2.0

package/dist/registry/parity.d.ts

@@ -0,0 +1,52 @@
+/**
+ * parity-50 — addendum A1 / provider-coverage-plan §3. The honest coverage
+ * KPI: how much of OpenRouter's top-50-by-usage list is PROBED (not merely
+ * listed) in our registry. A model counts as probed when ANY of its mapped
+ * registry keys carries probed schema samples — same weights on any host.
+ * Gaps are named on the leaderboard ("not yet probed"), never invisible.
+ */
+import type { Registry } from "./build";
+export interface ParityListEntry {
+    readonly name: string;
+    readonly registry_keys: readonly string[];
+}
+export interface ParityGap {
+    readonly name: string;
+    readonly status: "not yet probed" | "not in registry";
+}
+export interface ParityReport {
+    readonly total: number;
+    readonly probed: number;
+    readonly listedUnprobed: number;
+    readonly missing: number;
+    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

@@ -0,0 +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;;;;;;;;;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

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * parity-50 — addendum A1 / provider-coverage-plan §3. The honest coverage
+ * KPI: how much of OpenRouter's top-50-by-usage list is PROBED (not merely
+ * listed) in our registry. A model counts as probed when ANY of its mapped
+ * registry keys carries probed schema samples — same weights on any host.
+ * 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) => [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(normalizeParityKey(k)))
+            .filter((m) => m !== undefined);
+        if (matches.some((m) => (m.probed?.schema?.samples ?? 0) > 0)) {
+            probed += 1;
+        }
+        else if (matches.length > 0) {
+            listedUnprobed += 1;
+            gaps.push({ name: entry.name, status: "not yet probed" });
+        }
+        else {
+            missing += 1;
+            gaps.push({ name: entry.name, status: "not in registry" });
+        }
+    }
+    return {
+        total: list.length,
+        probed,
+        listedUnprobed,
+        missing,
+        probedPct: list.length === 0 ? 0 : probed / list.length,
+        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

@@ -0,0 +1,43 @@
+/**
+ * Thin pricing accessor over the vendored LiteLLM pricing snapshot
+ * (data/pricing-map.json, extracted at the pinned SHA — see
+ * upstream/litellm.pin.json). The full three-layer registry is Phase 2;
+ * Phase 1 needs only cost-per-token lookups for envelopes, prefer:[cost]
+ * ordering, and telemetry cost estimates.
+ *
+ * Data source: model_prices_and_context_window.json,
+ * 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;
+/**
+ * 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

@@ -0,0 +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;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

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Thin pricing accessor over the vendored LiteLLM pricing snapshot
+ * (data/pricing-map.json, extracted at the pinned SHA — see
+ * upstream/litellm.pin.json). The full three-layer registry is Phase 2;
+ * Phase 1 needs only cost-per-token lookups for envelopes, prefer:[cost]
+ * ordering, and telemetry cost estimates.
+ *
+ * Data source: model_prices_and_context_window.json,
+ * Copyright (c) 2023 Berri AI, MIT License (https://github.com/BerriAI/litellm).
+ */
+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");
+/** LiteLLM key prefixes per provider, most-specific first. Verified against
+ * the snapshot (see data/PROVENANCE.md): Gemini API entries live under
+ * "gemini/" (bare ids resolve to Vertex pricing — different product), OpenAI
+ * under bare ids, DeepSeek under both. */
+const KEY_PREFIXES = {
+    gemini: ["gemini/"],
+    openai: ["", "openai/"],
+    deepseek: ["deepseek/", ""],
+    anthropic: ["anthropic/", ""],
+    grok: ["xai/"],
+    // A1 hosts: DeepInfra models keep their org path ("Qwen/QwQ-32B");
+    // Fireworks pricing keys carry the accounts/… wire prefix.
+    deepinfra: ["deepinfra/"],
+    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 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;
+}
+function getPricing(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" &&
+            typeof entry.output_cost_per_token === "number") {
+            return {
+                inputUsdPerTok: entry.input_cost_per_token,
+                outputUsdPerTok: entry.output_cost_per_token,
+                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;
+}
+/**
+ * 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 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/registry/rows.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Registry → selection rows. One projection, used by every surface that
+ * asks a capability question from the FILES (the CLI, `modelrig init`, the
+ * docs build). The console projects from its Supabase mirror and the oracle
+ * from its own loader, but all three land on the same `ModelSelectRow`
+ * shape so the three cannot answer differently.
+ */
+import type { ModelSelectRow } from "./select";
+/**
+ * Load selection rows from registry.json (+ leaderboard.json for effective
+ * cost). Returns [] rather than throwing when the registry is absent or
+ * unreadable — a repo without a built registry should still get drafts,
+ * carrying the incumbent alone.
+ */
+export declare function loadRegistryRows(registryPath?: string): ModelSelectRow[];
+//# sourceMappingURL=rows.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rows.d.ts","sourceRoot":"","sources":["../../src/registry/rows.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAyC/C;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CA2BxE"}

package/dist/registry/rows.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Registry → selection rows. One projection, used by every surface that
+ * asks a capability question from the FILES (the CLI, `modelrig init`, the
+ * docs build). The console projects from its Supabase mirror and the oracle
+ * from its own loader, but all three land on the same `ModelSelectRow`
+ * shape so the three cannot answer differently.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadRegistryRows = loadRegistryRows;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function packagedRegistryDir() {
+    // dist/ and src/ both sit one level under the package root.
+    return (0, node_path_1.join)(__dirname, "..", "..", "registry");
+}
+function readJson(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Load selection rows from registry.json (+ leaderboard.json for effective
+ * cost). Returns [] rather than throwing when the registry is absent or
+ * unreadable — a repo without a built registry should still get drafts,
+ * carrying the incumbent alone.
+ */
+function loadRegistryRows(registryPath) {
+    const registryFile = registryPath ?? (0, node_path_1.join)(packagedRegistryDir(), "registry.json");
+    const registry = readJson(registryFile);
+    if (registry === null)
+        return [];
+    const dir = registryFile.slice(0, Math.max(registryFile.lastIndexOf("/"), 0));
+    const leaderboard = readJson((0, node_path_1.join)(dir, "leaderboard.json")) ?? [];
+    const effective = new Map(leaderboard.map((r) => [r.model_key, r.effective_usd_per_1k_conformant ?? null]));
+    return (registry.models ?? []).map((entry) => {
+        const [provider] = entry.model_key.split("/");
+        return {
+            key: entry.model_key,
+            provider: provider ?? entry.model_key,
+            inputUsdPerMtok: entry.declared?.pricing?.input_usd_per_mtok ?? null,
+            outputUsdPerMtok: entry.declared?.pricing?.output_usd_per_mtok ?? null,
+            conformRate: entry.probed?.schema?.conform_rate ?? null,
+            nativeRungRate: entry.probed?.schema?.native_rung_rate ?? null,
+            groundedRate: entry.probed?.grounding?.grounded_rate ?? null,
+            cacheHitRate: entry.probed?.caching?.cache_hit_rate ?? null,
+            effectiveUsdPer1k: effective.get(entry.model_key) ?? null,
+            discrepancies: entry.discrepancies?.length ?? 0,
+            probedAsOf: entry.probed?.as_of ?? null,
+        };
+    });
+}