modelrig 0.8.1 → 0.10.0

package/dist/registry/pricing.js

@@ -29,6 +29,9 @@ const KEY_PREFIXES = {
     // Fireworks pricing keys carry the accounts/… wire prefix.
     deepinfra: ["deepinfra/"],
     fireworks: ["fireworks_ai/accounts/fireworks/models/", "fireworks_ai/"],
+    // Z.ai (B4a): GLM models keyed under "zai/" in the snapshot. Registry entries
+    // carry their own declared pricing, so this only gaps-fills a future snapshot.
+    zai: ["zai/"],
 };
 let cachedMap = null;
 /** Host-swept gap-filler (scripts/pricing-sweep.ts): prices for models the
@@ -77,11 +80,12 @@ function getPricing(provider, model) {
     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.
+ * The richer `ModelPricingV2` on file for a model, if any — resolved by the SAME
+ * key precedence as {@link getPricing} (snapshot wins on a shared key; a snapshot
+ * entry yields its hand-grafted `pricing_v2` when it has one — issue #2's gemini
+ * tiers — else null → the caller synthesizes from the flat rate; an overlay or
+ * manual entry yields its own block). Returns null when no richer shape is on
+ * file. Never guesses: absence is `base`-only downstream.
  */
 function getPricingV2(provider, model) {
     if (model === "")

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

@@ -1 +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"}
+{"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;AA0C/C;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CA4BxE"}

package/dist/registry/rows.js

@@ -49,6 +49,7 @@ function loadRegistryRows(registryPath) {
             nativeRungRate: entry.probed?.schema?.native_rung_rate ?? null,
             groundedRate: entry.probed?.grounding?.grounded_rate ?? null,
             cacheHitRate: entry.probed?.caching?.cache_hit_rate ?? null,
+            imageExtractRate: entry.probed?.image?.extract_rate ?? null,
             effectiveUsdPer1k: effective.get(entry.model_key) ?? null,
             discrepancies: entry.discrepancies?.length ?? 0,
             probedAsOf: entry.probed?.as_of ?? null,

package/dist/registry/select.d.ts

@@ -18,7 +18,7 @@ import type { CapabilityFlag } from "../types/provider";
 import type { Requirement } from "../types/route";
 /** The capability predicates a question can carry. Deliberately the probed
  * dimensions only — we answer from measurement, not from provider claims. */
-export type CapabilityPredicate = "structured-native" | "structured-coached" | "grounding" | "caching";
+export type CapabilityPredicate = "structured-native" | "structured-coached" | "grounding" | "caching" | "image_input";
 export declare const ALL_CAPABILITY_PREDICATES: readonly CapabilityPredicate[];
 /** Plain-language gloss per predicate — the explainability layer travels
  * WITH the answer (console-explainability.md §1), it is not a separate doc. */
@@ -34,6 +34,11 @@ export interface ModelSelectRow {
     readonly nativeRungRate: number | null;
     readonly groundedRate: number | null;
     readonly cacheHitRate: number | null;
+    /** Probed image-input schema-conformant extraction rate (UC-3 M0). `null` when
+     * the model has NOT been probed on the image class — which the filter treats
+     * as "does not qualify" (a match needs measured evidence), NEVER as "cannot"
+     * (that distinction is preserved by the surfaces that render it). */
+    readonly imageExtractRate: number | null;
     readonly effectiveUsdPer1k: number | null;
     readonly discrepancies: number;
     readonly probedAsOf: string | null;

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

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

package/dist/registry/select.js

@@ -28,6 +28,7 @@ exports.ALL_CAPABILITY_PREDICATES = [
     "structured-coached",
     "grounding",
     "caching",
+    "image_input",
 ];
 /** Plain-language gloss per predicate — the explainability layer travels
  * WITH the answer (console-explainability.md §1), it is not a separate doc. */
@@ -36,9 +37,12 @@ exports.PREDICATE_GLOSS = {
     "structured-coached": "output matched the schema at least 90% of probed samples, whether or not the provider enforced it natively",
     grounding: "at least half of probed answers cited real retrieved sources rather than answering from memory",
     caching: "repeat calls actually reported cached input tokens — a measured discount, not a claim",
+    image_input: "a probe sent a form image and the model returned schema-conformant JSON extracting the planted fields on at least 90% of samples — a MEASURED read of an image, never a provider's vision claim",
 };
 const CONFORMANCE_BAR = 0.9;
 const GROUNDED_BAR = 0.5;
+/** Image-input extraction bar (UC-3 M0) — the same 0.9 the schema bar uses. */
+const IMAGE_BAR = 0.9;
 function hasCapability(row, cap) {
     switch (cap) {
         case "structured-native":
@@ -49,6 +53,12 @@ function hasCapability(row, cap) {
             return (row.groundedRate ?? 0) >= GROUNDED_BAR;
         case "caching":
             return (row.cacheHitRate ?? 0) > 0;
+        case "image_input":
+            // Probed-only: an unprobed model (null) is never returned as image-capable
+            // — absence is not a match. It is also not "cannot": the filter answers
+            // "which models we MEASURED can do this", and the empty-selection prose
+            // says exactly that.
+            return (row.imageExtractRate ?? 0) >= IMAGE_BAR;
     }
 }
 /** Question scaffolding. A search box gets keywords; the MCP oracle gets a
@@ -71,6 +81,7 @@ const CAP_WORDS = [
     [["json", "strict", "structured", "schema"], "structured-native"],
     [["grounded", "grounding", "search", "web"], "grounding"],
     [["cache", "caching", "cached"], "caching"],
+    [["image", "images", "vision", "multimodal", "ocr"], "image_input"],
 ];
 /** The tiny grammar behind the query box and the oracle's free-text input:
  * capability words + an "under $N/M" price cap; everything else is a

package/dist/routes/call-config.d.ts

@@ -0,0 +1,199 @@
+/**
+ * SDK-side live call-config resolution (live-routing-evals spec §4, R-1; LRE-1a).
+ *
+ * A route's live call-config (which model/provider + sampling) can be edited in
+ * the console WITHOUT a redeploy. The SDK reads it just-before-call through
+ * `GET /v1/routes/:route/call-config`, caches the policy (short TTL, ETag-
+ * revalidated), and MERGES the pin over the resolved (mirrored/deploy-time)
+ * bundle before `run()`. This is R-1's cached-policy model: no per-call network
+ * cost when fresh, and outage-safe.
+ *
+ * ── FAIL-OPEN, ALWAYS — the hot path never throws ─────────────────────────
+ * `getCallConfig` NEVER throws. On any error it returns the LAST-KNOWN-GOOD
+ * cached policy; if there is none, it returns null — and a null resolution means
+ * "serve the mirrored/pinned bundle unchanged". A route with no override
+ * resolves BYTE-IDENTICAL to today (the golden invariant): `applyCallConfig`
+ * returns the SAME bundle reference when there is nothing to merge.
+ *
+ * ── PHASE 1 = PIN ONLY ────────────────────────────────────────────────────
+ * `mode='experiment'` (local weighted arm draw) and `mode='live'` (strict per-
+ * call read) are TYPED here so the wire shape is complete, but they are INERT:
+ * `applyCallConfig` acts on `mode='pin'` only and passes everything else through
+ * unchanged. Experiments ship in LRE-2.
+ */
+import type { RouteBundle } from "../types/route";
+export type CallConfigMode = "pin" | "experiment" | "live";
+export type CallConfigSource = "user" | "optimizer" | "yaml-default";
+/** The on-the-wire sampling block (snake_case, as the endpoint returns it). */
+export interface CallConfigSampling {
+    readonly temperature?: number;
+    readonly top_p?: number;
+    readonly max_output_tokens?: number;
+}
+/** A `mode='pin'` config: a single model + optional sampling/variant. */
+export interface CallConfigPin {
+    readonly provider: string;
+    readonly model: string;
+    readonly sampling?: CallConfigSampling;
+    readonly variant?: string;
+}
+/** A resolved current config, as the resolver caches it. `version===0` and
+ * `mode===null` is the INERT default (no override) — resolution is byte-identical
+ * to the mirrored bundle. */
+export interface ResolvedCallConfig {
+    readonly version: number;
+    readonly mode: CallConfigMode | null;
+    readonly config: unknown;
+    readonly etag: string;
+}
+/** Pulls one route's current config from the control plane, ETag-aware. Returns
+ * the config, `"not-modified"` (304 — keep the cache), or null (miss / error —
+ * the resolver keeps last-known-good). NEVER throws. */
+export interface CallConfigFetcher {
+    fetch(route: string, etag: string | undefined): Promise<ResolvedCallConfig | "not-modified" | null>;
+}
+export interface CallConfigResolver {
+    /** The effective config for a route. Reads the cache when fresh (within TTL);
+     * otherwise revalidates (ETag) and folds the result in. Fail-open: on error,
+     * returns last-known-good, else null. NEVER throws. `null` ⇒ no override ⇒
+     * serve the mirrored bundle unchanged. */
+    getCallConfig(route: string): Promise<ResolvedCallConfig | null>;
+    /** A copy of every resolved route's last-known config — for status/boot. */
+    snapshot(): ReadonlyMap<string, ResolvedCallConfig>;
+}
+export interface CallConfigResolverConfig {
+    readonly fetcher: CallConfigFetcher;
+    /** Cache freshness window (spec §4: ~30–60s). Within it, no fetch. */
+    readonly ttlMs: number;
+    /** Injectable clock for tests; defaults to Date.now. */
+    readonly now?: () => number;
+}
+/** Narrow an unknown endpoint body into a `ResolvedCallConfig`, or null when the
+ * shape is not what the endpoint promises (a malformed 200 is a miss, not
+ * trusted — we never fabricate an override from junk). */
+export declare function parseCallConfig(body: unknown): ResolvedCallConfig | null;
+/** Narrow a config to a `CallConfigPin`, or null (T7 — jsonb is not proof of
+ * shape). The single place a pin's shape is trusted on the SDK side. */
+export declare function narrowPin(config: unknown): CallConfigPin | null;
+/** The pin carried by a resolved config, or null when there is no pin override
+ * (no override, or a non-pin mode — inert in Phase 1). */
+export declare function pinFromResolved(resolved: ResolvedCallConfig | null): CallConfigPin | null;
+/**
+ * Merge a resolved call-config over a bundle, returning a runnable bundle.
+ *
+ * INERT BY DEFAULT: when `resolved` is null, or its mode is not `pin`, or the pin
+ * does not narrow, the SAME `bundle` reference is returned — byte-identical to
+ * today (the golden invariant). Otherwise the pin REPLACES the candidate set with
+ * the single pinned model (eligibility was gated at write, so it satisfies the
+ * route `require`) and merges its sampling into the policy.
+ *
+ * `mode='experiment'` is INERT here (returns the bundle unchanged): an experiment
+ * resolves through {@link resolveCallConfigForRun}, which draws an arm and returns
+ * the arm name for `inferences.meta.arm`. `applyCallConfig` stays pin-only so the
+ * pin/golden path is byte-identical.
+ */
+export declare function applyCallConfig(bundle: RouteBundle, resolved: ResolvedCallConfig | null): RouteBundle;
+/** One arm of an experiment: a resolved pin config + a positive weight + an
+ * optional stable name (defaults to the pin's variant or `provider/model`). The
+ * `ref` is a `CallConfigPin` so an arm merges over the bundle exactly like a pin. */
+export interface ExperimentArm {
+    readonly ref: CallConfigPin;
+    readonly weight: number;
+    readonly name?: string;
+}
+/** A `mode='experiment'` config (spec §2.1): weighted arms, an optional
+ * stickiness key (names the input field whose VALUE keys deterministic
+ * assignment), and a fallback pin (served when the experiment cannot draw). */
+export interface CallConfigExperiment {
+    readonly arms: readonly ExperimentArm[];
+    readonly stickyKey?: string;
+    readonly fallback: CallConfigPin;
+}
+/** The stable arm name stamped on `inferences.meta.arm` — the caller-declared
+ * name, else the pin's variant, else `provider/model`. Kept meta-safe (short, no
+ * whitespace) by construction: providers/models/variants are identifiers. */
+export declare function armName(arm: ExperimentArm): string;
+/** Narrow a jsonb `config` to a `CallConfigExperiment`, or null (T7 — jsonb is
+ * not proof of shape). Requires ≥1 well-formed arm (each `ref` a valid pin, each
+ * `weight` a positive finite number) and a fallback pin. Fail-open: a malformed
+ * experiment narrows to null and the caller serves the mirrored bundle. */
+export declare function narrowExperiment(config: unknown): CallConfigExperiment | null;
+/** FNV-1a 32-bit hash of a string → a stable uint32. Pure, dependency-free — the
+ * sticky-assignment key so the SAME unit key always draws the SAME arm (an A/B is
+ * measured honestly). Not cryptographic; a fast, well-distributed bucket hash. */
+export declare function hashUnitKey(key: string): number;
+export interface DrawArmOptions {
+    /** A stickiness unit key (already resolved from the input). When present the
+     * draw is DETERMINISTIC by `hash(unitKey)` — the same unit always lands on the
+     * same arm. Absent ⇒ a weighted random draw. */
+    readonly unitKey?: string;
+    /** Injectable RNG in [0,1) for the weighted-random path (tests seed it);
+     * defaults to Math.random. Ignored when `unitKey` is supplied. */
+    readonly rng?: () => number;
+}
+/**
+ * Draw one arm from an experiment (spec §4). Weighted by `weight`: an arm's draw
+ * probability is `weight / Σweights`. DETERMINISTIC by `hash(unitKey)` when a
+ * unit key is supplied (sticky assignment); weighted-random otherwise. Returns
+ * null only when there are no positive-weight arms (⇒ the caller serves the
+ * fallback). Pure over its inputs (the RNG/hash are the only entropy).
+ */
+export declare function drawArm(experiment: CallConfigExperiment, opts?: DrawArmOptions): ExperimentArm | null;
+/** The resolved bundle for a run PLUS the chosen arm name (or null for pin / no
+ * override / a non-experiment mode). The arm name is stamped on
+ * `inferences.meta.arm` (thread it into `run` via `RunOptions.arm`). */
+export interface ResolvedForRun {
+    readonly bundle: RouteBundle;
+    readonly arm: string | null;
+}
+/**
+ * Resolve a route's call-config into a runnable bundle for ONE call, drawing an
+ * experiment arm locally when `mode='experiment'` (spec §4, R-1). FAIL-OPEN and
+ * byte-identical for pin: `mode='pin'` merges exactly like {@link applyCallConfig}
+ * (arm null), a null/`live`/malformed resolution returns the bundle unchanged
+ * (arm null), and a malformed experiment falls back to the experiment's own
+ * fallback pin, else the mirrored bundle. NEVER throws.
+ *
+ * For an experiment, the stickiness unit key is `opts.unitKey` when given, else
+ * the value of `input[experiment.stickyKey]` (resolved from the run's input) —
+ * so the SAME unit is served the SAME arm across calls.
+ */
+export declare function resolveCallConfigForRun(bundle: RouteBundle, resolved: ResolvedCallConfig | null, opts?: {
+    readonly unitKey?: string;
+    readonly input?: Record<string, unknown>;
+    readonly rng?: () => number;
+}): ResolvedForRun;
+/**
+ * Build the cached call-config resolver. Holds a per-route cache with a fetch
+ * timestamp + ETag; a read within `ttlMs` returns the cache with no network; a
+ * stale read revalidates (If-None-Match) and folds the result in. Every fetch is
+ * fail-open: a rejection or a null leaves the last-known value in place, and a
+ * route never yet resolved returns null (⇒ serve the mirrored bundle unchanged).
+ */
+export declare function createCallConfigResolver(config: CallConfigResolverConfig): CallConfigResolver;
+export interface ApiCallConfigFetcherConfig {
+    /** Base URL of the hosted control plane — the SAME `ingestUrl` the api sink
+     * uses (the call-config path hangs off the host). */
+    readonly ingestUrl: string;
+    /** `rig_sk_…` key. GET needs no special scope (a read rides the readable route
+     * + config rows). Header only, never a URL (C2). */
+    readonly apiKey: string;
+    readonly fetchFn?: typeof fetch;
+}
+/**
+ * The api-mode call-config fetcher: one authenticated, ETag-aware GET per route.
+ * Mirrors the api sink's leak discipline (status only, never the body/URL in an
+ * error — C2). NEVER throws: a network/HTTP failure resolves null, a 304 resolves
+ * "not-modified", a malformed 200 resolves null — so the resolver stays fail-open.
+ */
+export declare function createApiCallConfigFetcher(config: ApiCallConfigFetcherConfig): CallConfigFetcher;
+/**
+ * Convenience: resolve `route`'s config through the resolver, then merge it over
+ * `bundle`. NEVER throws (delegates to `getCallConfig`'s fail-open) and returns
+ * the SAME bundle reference when there is no override (byte-identical).
+ */
+export declare function getCallConfig(route: string, deps: {
+    readonly resolver: CallConfigResolver;
+    readonly bundle: RouteBundle;
+}): Promise<RouteBundle>;
+//# sourceMappingURL=call-config.d.ts.map

package/dist/routes/call-config.d.ts.map

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