modelrig 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -10,6 +10,17 @@ published package diverge.
 This project adheres to [Semantic Versioning](https://semver.org/). Dates are
 UTC.
 
+## [0.8.1] — 2026-08-24
+
+Docs — deploy guidance for the native `better-sqlite3` dependency. The SDK loads
+a native SQLite buffer on import (the local telemetry row written before each run
+returns), so the README Install section and `quickstart.md` now tell customers to
+run on a Node runtime (not Edge/Workers), mark `modelrig` external when bundling
+server code (Next.js `serverExternalPackages`, esbuild `--external:better-sqlite3`,
+webpack `externals`), and set `MODELRIG_API_KEY` on every service/worker/cron;
+plus a short monorepo workspace-source caveat. Docs/packaging only — no SDK
+behaviour change.
+
 ## [0.8.0] — 2026-08-24
 
 Packaging (GS-3) — the tarball now ships the customer-facing runs docs

package/README.md

@@ -22,6 +22,29 @@ npm i modelrig
 > macOS and Linux on x64/arm64 (nearly everyone); an unusual platform will
 > compile it at install time and needs a C++ toolchain. Node ≥ 20 is assumed.
 
+`modelrig` is a normal dependency: your existing `npm install` (or `pnpm` /
+`yarn`) step installs it **prebuilt** — there is no separate "build modelrig"
+step. Three things to get right when you deploy:
+
+- **Run it on a Node runtime, not an Edge/Workers runtime.** `better-sqlite3`
+  is a native module and loads on import, so an Edge runtime can't run it. A
+  standard Node host — server, container, or a Node serverless function — works
+  after `npm install`.
+- **If your deploy _bundles_ server code, mark modelrig external** so the native
+  binary is loaded at runtime instead of bundled:
+  - **Next.js** — `serverExternalPackages: ['modelrig']` in `next.config.js`
+    (Next 13/14: `experimental.serverComponentsExternalPackages`)
+  - **esbuild** — `--external:better-sqlite3` (and `--external:modelrig`)
+  - **webpack** — add `better-sqlite3` to `externals`
+- **Set `MODELRIG_API_KEY` on every service, worker, and cron** that runs a rig
+  — each process reports its own telemetry, so the key belongs on all of them,
+  not just your web service.
+
+(In a monorepo that vendors ModelRig as a workspace package — the SDK source
+rather than the published tarball — build that package before the app that
+imports it, so its `dist/` types resolve. Consuming the published package needs
+none of this.)
+
 ## Quickstart
 
 This runs with **only a provider key** — no account, no signup.

package/docs/llms.txt

@@ -4,7 +4,7 @@
 > grounding, and caching measured empirically, with a capability-aware
 > gateway that routes by them. Registry data CC BY 4.0; code Apache-2.0.
 
-_This reference is as of modelrig v0.8.0 (the published npm package). Any surface below that a newer workspace adds is marked "unreleased — workspace only" until its release; nothing is so marked as of this version._
+_This reference is as of modelrig v0.8.1 (the published npm package). Any surface below that a newer workspace adds is marked "unreleased — workspace only" until its release; nothing is so marked as of this version._
 
 ## Docs
 

package/docs/quickstart.md

@@ -87,8 +87,14 @@ reviewed. The full autonomy ladder and same-model guarantees are in the
 pnpm add modelrig      # or npm i modelrig — Node >= 20
 ```
 
-It builds a native module (`better-sqlite3`) on install, so the machine needs a
-toolchain.
+It installs a native module (`better-sqlite3`) — prebuilt for macOS/Linux on
+x64/arm64; an unusual platform compiles it and needs a C++ toolchain.
+
+**Deploying:** `modelrig` installs prebuilt (no separate build step), but it
+needs a **Node** runtime (not Edge/Workers), and if your deploy bundles server
+code you must mark it external — Next.js `serverExternalPackages: ['modelrig']`,
+esbuild `--external:better-sqlite3`, webpack `externals`. Set `MODELRIG_API_KEY`
+on every service, worker, and cron that runs a rig.
 
 ```ts
 import { createRig, loadConfigFromEnv } from "modelrig";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelrig",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "private": false,
   "description": "ModelRig — capability-aware AI gateway: routes-as-code, provider adapters, typed failures, budget envelopes, and local-first telemetry.",
   "license": "Apache-2.0",

package/dist/telemetry/supabase-exporter.d.ts

@@ -1,64 +0,0 @@
-/**
- * Async batch exporter: SQLite telemetry → ModelRig Supabase project.
- * Spec §5 (cloud sink) + §6 criteria 8–9. Fire-and-forget from the run loop:
- * the inference path NEVER blocks on, or fails because of, this sink.
- * At-least-once delivery with idempotent ids; unexported rows queue locally in
- * SQLite (the inferences table itself, behind a rowid watermark) and flush on
- * recovery; watermark bookkeeping per source instance.
- *
- * Transport is raw PostgREST over fetch (dependency-light, service-role key).
- */
-import type { RigManifest } from "../routes/manifest";
-import type { ServeabilityWarning } from "../routes/serveability";
-import type { ExportableTelemetryStore } from "./store";
-export interface ExportedRouteMirror {
-    readonly route: string;
-    readonly version: number;
-    readonly candidates: ReadonlyArray<{
-        readonly provider: string;
-        readonly model: string;
-    }>;
-    /** Capture opt-in FLAG (Phase 3 WS4) — status only; capture content never
-     * has a cloud surface. */
-    readonly capture?: boolean;
-}
-export interface ExporterConfig {
-    readonly supabaseUrl: string;
-    /** Service-role key — server-side only; never reaches the console. */
-    readonly serviceRoleKey: string;
-    readonly sourceId: string;
-    /**
-     * Tenant for every row this exporter writes (Phase 6 WS1). Defaults to the
-     * house org, which is the right answer for a self-hosted control plane —
-     * there is exactly one org there and everything belongs to it.
-     *
-     * This is DIRECT mode only. In api mode the server resolves org and project
-     * from the `rig_sk_` key and stamps them itself: a client that could choose
-     * its own tenant would not be a tenant boundary (T3).
-     */
-    readonly orgId?: string;
-    /** Finer scope inside the org. Null is legitimate — not every rig has one. */
-    readonly projectId?: string | null;
-    readonly batchSize?: number;
-    readonly intervalMs?: number;
-    /** Loaded route bundles, mirrored to the `routes` table for the console. */
-    readonly routes?: readonly ExportedRouteMirror[];
-    /** Rig manifest, mirrored to the `rig_manifests` table for the console
-     * (dimension NAMES only — tag values never leave the telemetry rows). */
-    readonly manifest?: RigManifest | null;
-    /** Inert-candidate warnings for THIS deployment (F1) — mirrored onto the
-     * manifest row so console /setup can say "2 candidates inert here, set
-     * XAI_API_KEY" instead of the fact living only in a boot log. Names only:
-     * route, provider, model, env var. */
-    readonly serveability?: readonly ServeabilityWarning[];
-    /** Injectable for tests; defaults to global fetch. */
-    readonly fetchFn?: typeof fetch;
-}
-export interface Exporter {
-    start(): void;
-    /** Flush pending rows now (used by tests and process-exit hooks). */
-    flush(): Promise<void>;
-    stop(): Promise<void>;
-}
-export declare function createSupabaseExporter(store: ExportableTelemetryStore, config: ExporterConfig): Exporter;
-//# sourceMappingURL=supabase-exporter.d.ts.map

package/dist/telemetry/supabase-exporter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"supabase-exporter.d.ts","sourceRoot":"","sources":["../../src/telemetry/supabase-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAIlE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1F;8BAC0B;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD;6EACyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC;;;0CAGsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACvD,sDAAsD;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,qEAAqE;IACrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAiFD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,wBAAwB,EAC/B,MAAM,EAAE,cAAc,GACrB,QAAQ,CA4KV"}

package/dist/telemetry/supabase-exporter.js

@@ -1,211 +0,0 @@
-"use strict";
-/**
- * Async batch exporter: SQLite telemetry → ModelRig Supabase project.
- * Spec §5 (cloud sink) + §6 criteria 8–9. Fire-and-forget from the run loop:
- * the inference path NEVER blocks on, or fails because of, this sink.
- * At-least-once delivery with idempotent ids; unexported rows queue locally in
- * SQLite (the inferences table itself, behind a rowid watermark) and flush on
- * recovery; watermark bookkeeping per source instance.
- *
- * Transport is raw PostgREST over fetch (dependency-light, service-role key).
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createSupabaseExporter = createSupabaseExporter;
-const constants_1 = require("../tenancy/constants");
-const DEFAULT_BATCH_SIZE = 200;
-const DEFAULT_INTERVAL_MS = 10000;
-/** After a sink failure, skip this many intervals, doubling per consecutive
- * failure (simple exponential backoff, capped). */
-const BACKOFF_MAX_SKIPS = 32;
-function toRemote(row, tenancy) {
-    return {
-        ...tenancy,
-        id: row.id,
-        ts: row.ts,
-        route: row.route,
-        route_version: row.routeVersion,
-        provider: row.provider,
-        model: row.model,
-        requested_tier: row.requestedTier,
-        served_tier: row.servedTier,
-        tokens_in: row.tokensIn,
-        tokens_out: row.tokensOut,
-        tokens_cached: row.tokensCached,
-        cost_estimate_usd: row.costEstimateUsd,
-        latency_ms: row.latencyMs,
-        ttfb_ms: row.ttfbMs,
-        failure_class: row.failureClass,
-        attempts: JSON.parse(row.attemptsJson),
-        tags: JSON.parse(row.tagsJson),
-        fingerprint_cell: row.fingerprintCell,
-        served_variant: row.servedVariant,
-        repaired_by: row.repairedBy,
-        pricing_missing: row.pricingMissing,
-    };
-}
-function feedbackToRemote(row, tenancy) {
-    return {
-        org_id: tenancy.org_id,
-        project_id: tenancy.project_id,
-        id: row.id,
-        ts: row.ts,
-        inference_id: row.inferenceId,
-        episode_key: row.episodeKey,
-        verdict: row.verdict,
-        score: row.score,
-        note: row.note,
-        source: row.source,
-    };
-}
-function createSupabaseExporter(store, config) {
-    const batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
-    const intervalMs = config.intervalMs ?? DEFAULT_INTERVAL_MS;
-    const fetchFn = config.fetchFn ?? fetch;
-    const base = config.supabaseUrl.replace(/\/$/, "");
-    const tenancy = {
-        org_id: config.orgId ?? constants_1.HOUSE_ORG_ID,
-        project_id: config.projectId ?? null,
-        source_id: config.sourceId,
-    };
-    let timer = null;
-    let flushing = false;
-    let skipsRemaining = 0;
-    let consecutiveFailures = 0;
-    let routesMirrored = false;
-    let manifestMirrored = false;
-    async function post(table, body, upsert) {
-        const response = await fetchFn(`${base}/rest/v1/${table}`, {
-            method: "POST",
-            headers: {
-                "content-type": "application/json",
-                apikey: config.serviceRoleKey,
-                authorization: `Bearer ${config.serviceRoleKey}`,
-                prefer: upsert
-                    ? "resolution=merge-duplicates,return=minimal"
-                    : "resolution=ignore-duplicates,return=minimal",
-            },
-            body: JSON.stringify(body),
-        });
-        if (!response.ok) {
-            throw new Error(`sink POST ${table} → ${response.status} ${await response.text().catch(() => "")}`);
-        }
-    }
-    async function flushOnce() {
-        // Routes mirror first (idempotent upsert; retried until it succeeds once).
-        if (!routesMirrored && config.routes !== undefined && config.routes.length > 0) {
-            await post("routes", config.routes.map((r) => ({
-                org_id: tenancy.org_id,
-                route: r.route,
-                version: r.version,
-                candidates: r.candidates,
-                capture: r.capture ?? false,
-                updated_at: new Date().toISOString(),
-            })), true);
-            routesMirrored = true;
-        }
-        // Manifest mirror (idempotent upsert, once per process — like routes).
-        if (!manifestMirrored && config.manifest !== undefined && config.manifest !== null) {
-            await post("rig_manifests", [
-                {
-                    org_id: tenancy.org_id,
-                    source_id: config.sourceId,
-                    name: config.manifest.name,
-                    dimensions: config.manifest.dimensions,
-                    contribution: config.manifest.contribution,
-                    // F1: names only — route, provider/model, and the env var to set.
-                    serveability: (config.serveability ?? []).map((w) => ({
-                        route: w.route,
-                        inert: w.inert.map((c) => ({ provider: c.provider, model: c.model })),
-                        serveable_count: w.serveableCount,
-                        fix_hint: w.fixHint,
-                    })),
-                    updated_at: new Date().toISOString(),
-                },
-            ], true);
-            manifestMirrored = true;
-        }
-        // Inferences past the watermark, in batches. Watermark advances ONLY
-        // after a confirmed write (at-least-once; remote id conflicts ignored).
-        for (;;) {
-            const watermark = store.getExportWatermark(config.sourceId);
-            const pending = store.readInferencesAfter(watermark, batchSize);
-            if (pending.length === 0)
-                break;
-            await post("inferences", pending.map(({ row }) => toRemote(row, tenancy)), false);
-            store.setExportWatermark(config.sourceId, pending[pending.length - 1].rowid);
-            await post("export_watermarks", [{ org_id: tenancy.org_id, source_id: config.sourceId, last_exported_ts: new Date().toISOString() }], true);
-            if (pending.length < batchSize)
-                break;
-        }
-        // Feedback mirror (Phase 4 WS2): same at-least-once watermark dance as
-        // inferences, behind its own export_state key so the two streams never
-        // block each other.
-        const feedbackSource = `${config.sourceId}:feedback`;
-        for (;;) {
-            const watermark = store.getExportWatermark(feedbackSource);
-            const pending = store.readFeedbackAfter(watermark, batchSize);
-            if (pending.length === 0)
-                break;
-            await post("feedback", pending.map(({ row }) => feedbackToRemote(row, tenancy)), false);
-            store.setExportWatermark(feedbackSource, pending[pending.length - 1].rowid);
-            if (pending.length < batchSize)
-                break;
-        }
-        // Envelopes: small table, full upsert each flush.
-        const envelopes = store.listEnvelopes();
-        if (envelopes.length > 0) {
-            await post("envelopes", envelopes.map((e) => ({
-                org_id: tenancy.org_id,
-                envelope_key: e.envelopeKey,
-                budget_usd: e.budgetUsd,
-                spent_usd: e.spentUsd,
-                status: e.status,
-                exported_at: new Date().toISOString(),
-            })), true);
-        }
-    }
-    async function guardedFlush() {
-        if (flushing)
-            return;
-        flushing = true;
-        try {
-            await flushOnce();
-            consecutiveFailures = 0;
-        }
-        catch (err) {
-            // Swallow-and-log, ALWAYS — sink failures must never reach the run loop.
-            consecutiveFailures += 1;
-            skipsRemaining = Math.min(2 ** consecutiveFailures, BACKOFF_MAX_SKIPS);
-            console.warn(`[modelrig exporter] sink flush failed (attempt ${consecutiveFailures}, backing off ` +
-                `${skipsRemaining} intervals): ${err instanceof Error ? err.message : String(err)}`);
-        }
-        finally {
-            flushing = false;
-        }
-    }
-    return {
-        start() {
-            if (timer !== null)
-                return;
-            timer = setInterval(() => {
-                if (skipsRemaining > 0) {
-                    skipsRemaining -= 1;
-                    return;
-                }
-                void guardedFlush();
-            }, intervalMs);
-            // Never keep the process alive for telemetry export.
-            timer.unref?.();
-        },
-        async flush() {
-            await guardedFlush();
-        },
-        async stop() {
-            if (timer !== null) {
-                clearInterval(timer);
-                timer = null;
-            }
-            await guardedFlush();
-        },
-    };
-}