modelrig 0.0.1 → 0.2.0

package/dist/feedback/coverage.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Optimization coverage, rungs 0–1 — Phase 4 WS2. Pure aggregation over
+ * telemetry + feedback rows; no store access, so the console, the server
+ * and tests all compute identically.
+ *
+ * Rungs (the eval ladder's bottom, per plan §4):
+ *   rung 0 — implicit signals only: conformance / repair / refusal rates
+ *            from telemetry. Enough confidence for schema-mechanical swap
+ *            proposals (the bake-off gate).
+ *   rung 1 — ≥ RUNG1_MIN_FEEDBACK human/agent verdicts attached: prose
+ *            routes (no schema to conform to) gain proposal confidence.
+ *   rung 2+ — judges; Phase 5+, out of scope by decision.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNG1_MIN_FEEDBACK = void 0;
+exports.computeCoverage = computeCoverage;
+exports.RUNG1_MIN_FEEDBACK = 10;
+/** Attribution: a feedback row joins a route via its inference id, or via
+ * its episode key matching a row's run_id tag. Unmatched feedback attaches
+ * to nothing (never guessed). */
+function computeCoverage(rows, feedback) {
+    const routeByInferenceId = new Map();
+    const routeByEpisode = new Map();
+    const byRoute = new Map();
+    for (const row of rows) {
+        // Exclude replay/shadow traffic (same convention as the console /routes
+        // view): bake-off replays are candidate-variant experiments, not the
+        // route's production serving — counting them skews conformance/repair
+        // rates with losing variants that never served a real request.
+        let replayTagged = false;
+        try {
+            replayTagged = JSON.parse(row.tagsJson).replay !== undefined;
+        }
+        catch {
+            replayTagged = false;
+        }
+        if (replayTagged)
+            continue;
+        const agg = byRoute.get(row.route) ?? {
+            samples: 0,
+            conform: 0,
+            repaired: 0,
+            refused: 0,
+            feedback: 0,
+        };
+        agg.samples += 1;
+        if (row.failureClass === null)
+            agg.conform += 1;
+        if (row.repairedBy !== null)
+            agg.repaired += 1;
+        if (row.failureClass === "refusal")
+            agg.refused += 1;
+        byRoute.set(row.route, agg);
+        routeByInferenceId.set(row.id, row.route);
+        try {
+            const tags = JSON.parse(row.tagsJson);
+            if (typeof tags.run_id === "string" && tags.run_id !== "") {
+                routeByEpisode.set(tags.run_id, row.route);
+            }
+        }
+        catch {
+            // Unparseable tags never break coverage — the row still counts above.
+        }
+    }
+    for (const f of feedback) {
+        const route = (f.inferenceId !== null ? routeByInferenceId.get(f.inferenceId) : undefined) ??
+            (f.episodeKey !== null ? routeByEpisode.get(f.episodeKey) : undefined);
+        if (route === undefined)
+            continue;
+        const agg = byRoute.get(route);
+        if (agg !== undefined)
+            agg.feedback += 1;
+    }
+    return [...byRoute.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([route, agg]) => {
+        const rung = agg.feedback >= exports.RUNG1_MIN_FEEDBACK ? 1 : 0;
+        const nextRungUnlock = rung === 0
+            ? `Attach ${exports.RUNG1_MIN_FEEDBACK - agg.feedback} more rig.feedback() verdicts ` +
+                `(${agg.feedback}/${exports.RUNG1_MIN_FEEDBACK}) to reach rung 1 — human-verdict confidence ` +
+                "for routes without a schema to conform to."
+            : "Rung 2 (LLM judges — value accuracy beyond mechanical conformance) arrives in Phase 5.";
+        return {
+            route,
+            samples: agg.samples,
+            conformRate: agg.samples === 0 ? 0 : agg.conform / agg.samples,
+            repairRate: agg.samples === 0 ? 0 : agg.repaired / agg.samples,
+            refusalRate: agg.samples === 0 ? 0 : agg.refused / agg.samples,
+            feedbackCount: agg.feedback,
+            rung,
+            nextRungUnlock,
+        };
+    });
+}

package/dist/feedback/feedback.d.ts

@@ -0,0 +1,35 @@
+/**
+ * rig.feedback() — Phase 4 WS2 (spec: judgment starts accumulating).
+ * The SDK surface normalizes a target (inference id or {episode}) + opts
+ * into a FeedbackRow; the write is a synchronous local SQLite insert
+ * (fire-and-forget from the caller's view — no network, never throws for
+ * sink reasons). The Supabase mirror rides the exporter, dual-store style.
+ */
+import type { FeedbackRow } from "../types/telemetry";
+export type FeedbackTarget = string | {
+    readonly episode: string;
+};
+export interface FeedbackOpts {
+    readonly verdict: "up" | "down";
+    /** Optional graded signal in [0, 1]; verdict remains the primary axis. */
+    readonly score?: number;
+    readonly note?: string;
+    /** Who judged: "sdk" (default), a review-agent name, "human", … */
+    readonly source?: string;
+    /**
+     * The org this verdict belongs to (Phase 6 WS2). Omit from application code
+     * — a rig has one org and the exporter knows it.
+     *
+     * Supplied by modelrig-server, and only ever with an org it has ALREADY
+     * authorized the caller into: a value that arrived in a request body and was
+     * passed through here would be a tenant chosen by the client (T3). Setting
+     * it is what lets one hosted server hold verdicts for many orgs without
+     * misfiling any of them (QA-P6-010).
+     */
+    readonly orgId?: string;
+    /** Authenticated user who recorded it. Same provenance rule as `orgId`:
+     * resolved from a session, never read off a request body. */
+    readonly createdBy?: string | null;
+}
+export declare function buildFeedbackRow(target: FeedbackTarget, opts: FeedbackOpts): FeedbackRow;
+//# sourceMappingURL=feedback.d.ts.map

package/dist/feedback/feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../src/feedback/feedback.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;iEAC6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,YAAY,GAAG,WAAW,CA0BxF"}

package/dist/feedback/feedback.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * rig.feedback() — Phase 4 WS2 (spec: judgment starts accumulating).
+ * The SDK surface normalizes a target (inference id or {episode}) + opts
+ * into a FeedbackRow; the write is a synchronous local SQLite insert
+ * (fire-and-forget from the caller's view — no network, never throws for
+ * sink reasons). The Supabase mirror rides the exporter, dual-store style.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFeedbackRow = buildFeedbackRow;
+const node_crypto_1 = require("node:crypto");
+function buildFeedbackRow(target, opts) {
+    let inferenceId = null;
+    let episodeKey = null;
+    if (typeof target === "string") {
+        inferenceId = target;
+    }
+    else {
+        episodeKey = target.episode;
+    }
+    if ((inferenceId === null || inferenceId === "") && (episodeKey === null || episodeKey === "")) {
+        throw new Error("feedback target must be a non-empty inference id or {episode}");
+    }
+    if (opts.score !== undefined && (!Number.isFinite(opts.score) || opts.score < 0 || opts.score > 1)) {
+        throw new Error(`feedback score must be in [0, 1], got ${opts.score}`);
+    }
+    return {
+        id: (0, node_crypto_1.randomUUID)(),
+        ts: new Date().toISOString(),
+        inferenceId,
+        episodeKey,
+        verdict: opts.verdict,
+        score: opts.score ?? null,
+        note: opts.note ?? null,
+        source: opts.source ?? "sdk",
+        orgId: opts.orgId !== undefined && opts.orgId !== "" ? opts.orgId : null,
+        createdBy: opts.createdBy ?? null,
+    };
+}

package/dist/gateway/http-protocol.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The HTTP gateway wire contract — G-1/G-5 (http-gateway spec §3, §4.3, §4.4).
+ *
+ * ONE definition of what a `/v1/chat/completions` request, response, and SSE
+ * chunk look like, plus the lane-disambiguation rule and the `x-modelrig-*`
+ * provenance headers. Both sides compile against it:
+ *
+ *   SDK (`packages/modelrig`)   — this repo; consumes the streaming/tool
+ *                                 surfaces the endpoint is built on.
+ *   `modelrig-server`           — separate repo (Phase B/C); implements the
+ *                                 endpoint and imports these types so the wire
+ *                                 shape cannot drift between the two.
+ *
+ * This mirrors `telemetry/ingest-protocol.ts`: a shared module is what makes
+ * "the two sides agree" enforceable rather than aspirational — a contract test
+ * round-trips the shapes on both sides instead of comparing two hand-written
+ * copies for similarity.
+ *
+ * TYPES + PURE FUNCTIONS ONLY. No transport, no auth, no I/O — the endpoint,
+ * SSE plumbing, and BYOK key resolution live server-side (spec §2).
+ */
+import type { ToolCall, ToolChoice, ToolDefinition } from "../types/provider";
+/** The endpoint path. Spelled once. */
+export declare const CHAT_COMPLETIONS_PATH = "/v1/chat/completions";
+/** The model-catalog path (routes + registry models) for SDK discovery. */
+export declare const MODELS_PATH = "/v1/models";
+/** Bumped only for a breaking change to the shapes below. */
+export declare const GATEWAY_PROTOCOL_VERSION = 1;
+export declare const MODELRIG_HEADERS: {
+    /** "slug" (verified pipeline) or "raw" (zero-margin BYOK passthrough). */
+    readonly lane: "x-modelrig-lane";
+    /** Phase D (spec §13.1 rule 4): where the slug lane resolved its bundle —
+     * "local" (this deployment's own routes, the self-host path) or "mirror" (the
+     * org-scoped `routes` mirror, the hosted path). A deployment serves ONE or the
+     * OTHER and SAYS WHICH; the two must never silently blend. Absent on the raw
+     * lane. */
+    readonly routeSource: "x-modelrig-route-source";
+    readonly provider: "x-modelrig-provider";
+    readonly model: "x-modelrig-model";
+    /** "true"/"false" — was the output schema-validated (slug lane only). */
+    readonly validated: "x-modelrig-validated";
+    /** "provider/model" that repaired the output, when repair fired. */
+    readonly repairedBy: "x-modelrig-repaired-by";
+    readonly costUsd: "x-modelrig-cost-usd";
+    /** The `rig.feedback()` handle (telemetry inference id). */
+    readonly inferenceId: "x-modelrig-inference-id";
+};
+export declare const MODELRIG_REQUEST_HEADERS: {
+    /** Per-run envelope key (budget). */
+    readonly envelope: "x-modelrig-envelope";
+    /** Named route variant to serve. */
+    readonly variant: "x-modelrig-variant";
+    /** "buffered" opts out of true streaming for validated-only output (§4.3). */
+    readonly stream: "x-modelrig-stream";
+};
+export type Lane = "slug" | "raw";
+/** The disambiguation verdict for a request's `model` field (spec §3.3). */
+export type LaneResolution = {
+    readonly lane: "slug";
+    readonly slug: string;
+} | {
+    readonly lane: "raw";
+    readonly provider: string;
+    readonly model: string;
+} | {
+    readonly lane: "unknown";
+    readonly reason: string;
+};
+/**
+ * The core routing rule (spec §3.3), as a pure function so both sides classify
+ * a `model` string identically:
+ *   1. `@rig/…` OR an exact known route slug  → slug lane (verified pipeline).
+ *   2. `^<providerId>/<model>$`, providerId ∈ PROVIDER_IDS → raw-model lane.
+ *   3. otherwise → unknown (the endpoint 404s; never silently guess).
+ *
+ * The namespaces don't collide: a route slug is a bare handle
+ * (`example.support_summarize`); a raw model always carries a known
+ * `provider/` prefix.
+ */
+export declare function classifyLane(model: string, knownRouteSlugs?: ReadonlySet<string>): LaneResolution;
+export interface ChatMessage {
+    readonly role: "system" | "user" | "assistant" | "tool";
+    readonly content: string | null;
+    /** Assistant turns that called tools carry them (echoed OpenAI shape). */
+    readonly tool_calls?: readonly ToolCall[];
+    /** `tool` role replies reference the call they answer. */
+    readonly tool_call_id?: string;
+    readonly name?: string;
+}
+export interface ChatCompletionRequest {
+    readonly model: string;
+    readonly messages: readonly ChatMessage[];
+    readonly stream?: boolean;
+    readonly temperature?: number;
+    readonly top_p?: number;
+    readonly max_tokens?: number;
+    readonly tools?: readonly ToolDefinition[];
+    readonly tool_choice?: ToolChoice;
+    /** OpenAI structured-output request; the slug lane maps it to the route. */
+    readonly response_format?: {
+        readonly type: "text";
+    } | {
+        readonly type: "json_object";
+    } | {
+        readonly type: "json_schema";
+        readonly json_schema: {
+            readonly name: string;
+            readonly schema: object;
+            readonly strict?: boolean;
+        };
+    };
+    /** ModelRig extensions may ride here instead of headers (spec §3.4). */
+    readonly modelrig?: {
+        readonly envelope?: string;
+        readonly variant?: string;
+        readonly stream?: "buffered";
+    };
+}
+export interface ChatCompletionUsage {
+    readonly prompt_tokens: number;
+    readonly completion_tokens: number;
+    readonly total_tokens: number;
+}
+export interface ChatCompletionChoice {
+    readonly index: number;
+    readonly message: {
+        readonly role: "assistant";
+        readonly content: string | null;
+        readonly tool_calls?: readonly ToolCall[];
+    };
+    readonly finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | null;
+}
+export interface ChatCompletionResponse {
+    readonly id: string;
+    readonly object: "chat.completion";
+    readonly created: number;
+    readonly model: string;
+    readonly choices: readonly ChatCompletionChoice[];
+    readonly usage: ChatCompletionUsage;
+}
+export interface ChatCompletionChunkChoice {
+    readonly index: number;
+    readonly delta: {
+        readonly role?: "assistant";
+        readonly content?: string | null;
+        readonly tool_calls?: readonly ToolCall[];
+    };
+    readonly finish_reason: ChatCompletionChoice["finish_reason"];
+}
+export interface ChatCompletionChunk {
+    readonly id: string;
+    readonly object: "chat.completion.chunk";
+    readonly created: number;
+    readonly model: string;
+    readonly choices: readonly ChatCompletionChunkChoice[];
+}
+/**
+ * The structured-route terminal event (spec §4.3). Streamed bytes on a
+ * structured route are PRE-validation; the endpoint closes the stream with this
+ * authoritative event (as a chunk with a `modelrig` extension) before
+ * `data: [DONE]`. It carries the validation verdict and, when repair fired, the
+ * repaired final object.
+ */
+export interface TerminalValidationEvent {
+    readonly object: "modelrig.validation";
+    readonly validated: boolean;
+    /** The validated (and possibly repaired) output object. */
+    readonly output: unknown;
+    readonly repairedBy: string | null;
+    readonly inferenceId: string;
+    readonly errors?: readonly string[];
+}
+/** The SSE sentinel that closes an OpenAI-compatible stream. */
+export declare const SSE_DONE = "[DONE]";
+//# sourceMappingURL=http-protocol.d.ts.map

package/dist/gateway/http-protocol.d.ts.map

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

package/dist/gateway/http-protocol.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * The HTTP gateway wire contract — G-1/G-5 (http-gateway spec §3, §4.3, §4.4).
+ *
+ * ONE definition of what a `/v1/chat/completions` request, response, and SSE
+ * chunk look like, plus the lane-disambiguation rule and the `x-modelrig-*`
+ * provenance headers. Both sides compile against it:
+ *
+ *   SDK (`packages/modelrig`)   — this repo; consumes the streaming/tool
+ *                                 surfaces the endpoint is built on.
+ *   `modelrig-server`           — separate repo (Phase B/C); implements the
+ *                                 endpoint and imports these types so the wire
+ *                                 shape cannot drift between the two.
+ *
+ * This mirrors `telemetry/ingest-protocol.ts`: a shared module is what makes
+ * "the two sides agree" enforceable rather than aspirational — a contract test
+ * round-trips the shapes on both sides instead of comparing two hand-written
+ * copies for similarity.
+ *
+ * TYPES + PURE FUNCTIONS ONLY. No transport, no auth, no I/O — the endpoint,
+ * SSE plumbing, and BYOK key resolution live server-side (spec §2).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSE_DONE = exports.MODELRIG_REQUEST_HEADERS = exports.MODELRIG_HEADERS = exports.GATEWAY_PROTOCOL_VERSION = exports.MODELS_PATH = exports.CHAT_COMPLETIONS_PATH = void 0;
+exports.classifyLane = classifyLane;
+const provider_1 = require("../types/provider");
+/** The endpoint path. Spelled once. */
+exports.CHAT_COMPLETIONS_PATH = "/v1/chat/completions";
+/** The model-catalog path (routes + registry models) for SDK discovery. */
+exports.MODELS_PATH = "/v1/models";
+/** Bumped only for a breaking change to the shapes below. */
+exports.GATEWAY_PROTOCOL_VERSION = 1;
+// ── Provenance headers (spec §3.4) ───────────────────────────────────────────
+// Response headers that make a completion auditable: which lane served it,
+// which provider/model actually ran, whether the output was verified, and the
+// feedback handle. Named once so the SDK, the server, and the console cannot
+// disagree about the spelling.
+exports.MODELRIG_HEADERS = {
+    /** "slug" (verified pipeline) or "raw" (zero-margin BYOK passthrough). */
+    lane: "x-modelrig-lane",
+    /** Phase D (spec §13.1 rule 4): where the slug lane resolved its bundle —
+     * "local" (this deployment's own routes, the self-host path) or "mirror" (the
+     * org-scoped `routes` mirror, the hosted path). A deployment serves ONE or the
+     * OTHER and SAYS WHICH; the two must never silently blend. Absent on the raw
+     * lane. */
+    routeSource: "x-modelrig-route-source",
+    provider: "x-modelrig-provider",
+    model: "x-modelrig-model",
+    /** "true"/"false" — was the output schema-validated (slug lane only). */
+    validated: "x-modelrig-validated",
+    /** "provider/model" that repaired the output, when repair fired. */
+    repairedBy: "x-modelrig-repaired-by",
+    costUsd: "x-modelrig-cost-usd",
+    /** The `rig.feedback()` handle (telemetry inference id). */
+    inferenceId: "x-modelrig-inference-id",
+};
+// Request-side extension headers (spec §3.4).
+exports.MODELRIG_REQUEST_HEADERS = {
+    /** Per-run envelope key (budget). */
+    envelope: "x-modelrig-envelope",
+    /** Named route variant to serve. */
+    variant: "x-modelrig-variant",
+    /** "buffered" opts out of true streaming for validated-only output (§4.3). */
+    stream: "x-modelrig-stream",
+};
+/**
+ * The core routing rule (spec §3.3), as a pure function so both sides classify
+ * a `model` string identically:
+ *   1. `@rig/…` OR an exact known route slug  → slug lane (verified pipeline).
+ *   2. `^<providerId>/<model>$`, providerId ∈ PROVIDER_IDS → raw-model lane.
+ *   3. otherwise → unknown (the endpoint 404s; never silently guess).
+ *
+ * The namespaces don't collide: a route slug is a bare handle
+ * (`example.support_summarize`); a raw model always carries a known
+ * `provider/` prefix.
+ */
+function classifyLane(model, knownRouteSlugs = new Set()) {
+    const trimmed = model.trim();
+    if (trimmed === "") {
+        return { lane: "unknown", reason: "empty model field" };
+    }
+    if (trimmed.startsWith("@rig/")) {
+        const slug = trimmed.slice("@rig/".length);
+        if (slug === "")
+            return { lane: "unknown", reason: "empty route slug after @rig/" };
+        return { lane: "slug", slug };
+    }
+    if (knownRouteSlugs.has(trimmed)) {
+        return { lane: "slug", slug: trimmed };
+    }
+    const slash = trimmed.indexOf("/");
+    if (slash > 0) {
+        const provider = trimmed.slice(0, slash);
+        const rest = trimmed.slice(slash + 1);
+        if (rest !== "" && provider_1.PROVIDER_IDS.includes(provider)) {
+            return { lane: "raw", provider, model: rest };
+        }
+    }
+    return {
+        lane: "unknown",
+        reason: `"${trimmed}" is neither a known route slug nor a <provider>/<model> for a supported provider`,
+    };
+}
+/** The SSE sentinel that closes an OpenAI-compatible stream. */
+exports.SSE_DONE = "[DONE]";