@swissspidy/belay-core 0.1.0 → 0.1.1

package/dist/calibration.d.ts

@@ -0,0 +1,11 @@
+import type { CalibrationFile } from './types.js';
+export declare const CALIBRATION_VERSION = 1;
+/**
+ * Validates an unknown value as a v1 calibration file. When `task` is given, also checks
+ * that the file belongs to that task. Throws `BelayError('invalid-calibration')`.
+ */
+export declare function parseCalibration(data: unknown, task?: string): CalibrationFile;
+/** Threshold for a local top label: the per-label override if present, else the global one. */
+export declare function thresholdFor(calibration: Pick<CalibrationFile, 'threshold' | 'thresholds'>, label?: string): number;
+export declare function loadCalibration(source: CalibrationFile | string | URL | (() => Promise<CalibrationFile>), task?: string): Promise<CalibrationFile>;
+//# sourceMappingURL=calibration.d.ts.map

package/dist/calibration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calibration.d.ts","sourceRoot":"","sources":["../src/calibration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAOrC;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,CA2B9E;AAED,+FAA+F;AAC/F,wBAAgB,YAAY,CAAC,WAAW,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,YAAY,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAKnH;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,eAAe,GAAG,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC,EACzE,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,eAAe,CAAC,CAU1B"}

package/dist/calibration.js

@@ -0,0 +1,68 @@
+import { BelayError } from './errors.js';
+export const CALIBRATION_VERSION = 1;
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+const isProb = (v) => isNum(v) && v >= 0 && v <= 1;
+/** A threshold above 1 keeps nothing local: every run escalates. */
+const isThreshold = (v) => isNum(v) && v >= 0;
+/**
+ * Validates an unknown value as a v1 calibration file. When `task` is given, also checks
+ * that the file belongs to that task. Throws `BelayError('invalid-calibration')`.
+ */
+export function parseCalibration(data, task) {
+    const fail = (msg) => {
+        throw new BelayError('invalid-calibration', `Invalid calibration file: ${msg}`);
+    };
+    if (!data || typeof data !== 'object')
+        fail('not an object');
+    const c = data;
+    if (c.version !== CALIBRATION_VERSION)
+        fail(`unsupported version ${String(c.version)}`);
+    if (typeof c.task !== 'string')
+        fail('missing task');
+    if (task !== undefined && c.task !== task)
+        fail(`file is for task "${c.task}", not "${task}"`);
+    if (typeof c.schemaFingerprint !== 'string')
+        fail('missing schemaFingerprint');
+    if (!isThreshold(c.threshold))
+        fail('threshold must be a number ≥ 0');
+    if (c.thresholds !== undefined) {
+        if (typeof c.thresholds !== 'object' || c.thresholds === null)
+            fail('thresholds must be an object');
+        for (const [label, t] of Object.entries(c.thresholds)) {
+            if (!isThreshold(t))
+                fail(`thresholds["${label}"] must be a number ≥ 0`);
+        }
+    }
+    if (!c.expected || !isProb(c.expected.localShare) || !isProb(c.expected.accuracy)) {
+        fail('expected.accuracy and expected.localShare must be numbers in [0, 1]');
+    }
+    if (!Array.isArray(c.curve))
+        fail('curve must be an array');
+    if (!c.confidenceHistogram || !Array.isArray(c.confidenceHistogram.edges) || !Array.isArray(c.confidenceHistogram.counts)) {
+        fail('confidenceHistogram must have edges and counts');
+    }
+    else if (c.confidenceHistogram.edges.length !== c.confidenceHistogram.counts.length + 1) {
+        fail('confidenceHistogram.edges must have one more entry than counts');
+    }
+    return c;
+}
+/** Threshold for a local top label: the per-label override if present, else the global one. */
+export function thresholdFor(calibration, label) {
+    if (label !== undefined && calibration.thresholds && Object.hasOwn(calibration.thresholds, label)) {
+        return calibration.thresholds[label];
+    }
+    return calibration.threshold;
+}
+export async function loadCalibration(source, task) {
+    if (typeof source === 'function')
+        return parseCalibration(await source(), task);
+    if (typeof source === 'string' || source instanceof URL) {
+        const res = await fetch(source);
+        if (!res.ok) {
+            throw new BelayError('invalid-calibration', `Failed to fetch calibration ${String(source)}: HTTP ${res.status}`);
+        }
+        return parseCalibration(await res.json(), task);
+    }
+    return parseCalibration(source, task);
+}
+//# sourceMappingURL=calibration.js.map

package/dist/calibration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calibration.js","sourceRoot":"","sources":["../src/calibration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAErC,MAAM,KAAK,GAAG,CAAC,CAAU,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AACvF,MAAM,MAAM,GAAG,CAAC,CAAU,EAAe,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzE,oEAAoE;AACpE,MAAM,WAAW,GAAG,CAAC,CAAU,EAAe,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEpE;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAa,EAAE,IAAa;IAC3D,MAAM,IAAI,GAAG,CAAC,GAAW,EAAS,EAAE;QAClC,MAAM,IAAI,UAAU,CAAC,qBAAqB,EAAE,6BAA6B,GAAG,EAAE,CAAC,CAAC;IAClF,CAAC,CAAC;IACF,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,IAAI,CAAC,eAAe,CAAC,CAAC;IAC7D,MAAM,CAAC,GAAG,IAAgC,CAAC;IAC3C,IAAI,CAAC,CAAC,OAAO,KAAK,mBAAmB;QAAE,IAAI,CAAC,uBAAuB,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACxF,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAAE,IAAI,CAAC,cAAc,CAAC,CAAC;IACrD,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI;QAAE,IAAI,CAAC,qBAAqB,CAAC,CAAC,IAAI,WAAW,IAAI,GAAG,CAAC,CAAC;IAC/F,IAAI,OAAO,CAAC,CAAC,iBAAiB,KAAK,QAAQ;QAAE,IAAI,CAAC,2BAA2B,CAAC,CAAC;IAC/E,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;QAAE,IAAI,CAAC,gCAAgC,CAAC,CAAC;IACtE,IAAI,CAAC,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,CAAC,UAAU,KAAK,IAAI;YAAE,IAAI,CAAC,8BAA8B,CAAC,CAAC;QACpG,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,UAAoB,CAAC,EAAE,CAAC;YAChE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;gBAAE,IAAI,CAAC,eAAe,KAAK,yBAAyB,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC;IACD,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClF,IAAI,CAAC,qEAAqE,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAAE,IAAI,CAAC,wBAAwB,CAAC,CAAC;IAC5D,IAAI,CAAC,CAAC,CAAC,mBAAmB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1H,IAAI,CAAC,gDAAgD,CAAC,CAAC;IACzD,CAAC;SAAM,IAAI,CAAC,CAAC,mBAAmB,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1F,IAAI,CAAC,gEAAgE,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,CAAoB,CAAC;AAC9B,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,YAAY,CAAC,WAA8D,EAAE,KAAc;IACzG,IAAI,KAAK,KAAK,SAAS,IAAI,WAAW,CAAC,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC;QAClG,OAAO,WAAW,CAAC,UAAU,CAAC,KAAK,CAAE,CAAC;IACxC,CAAC;IACD,OAAO,WAAW,CAAC,SAAS,CAAC;AAC/B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAyE,EACzE,IAAa;IAEb,IAAI,OAAO,MAAM,KAAK,UAAU;QAAE,OAAO,gBAAgB,CAAC,MAAM,MAAM,EAAE,EAAE,IAAI,CAAC,CAAC;IAChF,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,YAAY,GAAG,EAAE,CAAC;QACxD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;QAChC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,UAAU,CAAC,qBAAqB,EAAE,+BAA+B,MAAM,CAAC,MAAM,CAAC,UAAU,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACnH,CAAC;QACD,OAAO,gBAAgB,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC"}

package/dist/cloud.d.ts

@@ -0,0 +1,37 @@
+import type { CloudRequest, CloudRunner, CloudUsage, TaskSchema } from './types.js';
+export type CloudFn<S extends TaskSchema = TaskSchema> = (request: CloudRequest<S>, options: {
+    signal?: AbortSignal;
+    /** Report the call's token usage, so calibration and `savingsMeter()` can measure its cost. */
+    reportUsage: (usage: CloudUsage | CloudUsage[]) => void;
+}) => Promise<unknown>;
+/**
+ * Wraps a plain async function as a cloud runner. The function returns the raw output:
+ * the bare value, the `{ value }` wrapper, or a JSON string of either. The task validates it.
+ * Token usage goes through `reportUsage`, since the output itself may be a `{ value }` object.
+ *
+ * ```ts
+ * cloudAdapter(async ({ instruction, input, jsonSchema }, { signal }) => {
+ *   const res = await fetch('/api/classify', { method: 'POST', body: JSON.stringify({ instruction, input, jsonSchema }), signal });
+ *   return res.json();
+ * });
+ * ```
+ */
+export declare function cloudAdapter<S extends TaskSchema = TaskSchema>(fn: CloudFn<S>, options?: {
+    id?: string;
+}): CloudRunner<S>;
+export interface FetchAdapterOptions<S extends TaskSchema = TaskSchema> {
+    /** Your backend endpoint. Never put provider API keys in the browser. */
+    url: string | URL;
+    headers?: Record<string, string>;
+    /** Builds the request body. Defaults to the JSON-serialized request (functions dropped). */
+    body?: (request: CloudRequest<S>) => unknown;
+    /** Extracts the output from the parsed JSON response. Defaults to the whole response. */
+    select?: (json: unknown) => unknown;
+    /** Extracts token usage from the parsed JSON response, if your backend passes it through. */
+    usage?: (json: unknown) => CloudUsage | CloudUsage[] | undefined;
+    id?: string;
+    fetch?: typeof fetch;
+}
+/** A cloud runner that POSTs the request as JSON to your endpoint. */
+export declare function fetchAdapter<S extends TaskSchema = TaskSchema>(options: FetchAdapterOptions<S>): CloudRunner<S>;
+//# sourceMappingURL=cloud.d.ts.map

package/dist/cloud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["../src/cloud.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEjG,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IAAI,CACvD,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EACxB,OAAO,EAAE;IACP,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+FAA+F;IAC/F,WAAW,EAAE,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,EAAE,KAAK,IAAI,CAAC;CACzD,KACE,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EAC5D,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,EACd,OAAO,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5B,WAAW,CAAC,CAAC,CAAC,CAShB;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IACpE,yEAAyE;IACzE,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,4FAA4F;IAC5F,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC;IAC7C,yFAAyF;IACzF,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;IACpC,6FAA6F;IAC7F,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,UAAU,GAAG,UAAU,EAAE,GAAG,SAAS,CAAC;IACjE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAmB/G"}

package/dist/cloud.js

@@ -0,0 +1,43 @@
+/**
+ * Wraps a plain async function as a cloud runner. The function returns the raw output:
+ * the bare value, the `{ value }` wrapper, or a JSON string of either. The task validates it.
+ * Token usage goes through `reportUsage`, since the output itself may be a `{ value }` object.
+ *
+ * ```ts
+ * cloudAdapter(async ({ instruction, input, jsonSchema }, { signal }) => {
+ *   const res = await fetch('/api/classify', { method: 'POST', body: JSON.stringify({ instruction, input, jsonSchema }), signal });
+ *   return res.json();
+ * });
+ * ```
+ */
+export function cloudAdapter(fn, options = {}) {
+    return {
+        id: options.id ?? 'cloud',
+        async run(request, opts) {
+            let usage;
+            const value = await fn(request, { ...opts, reportUsage: (u) => void (usage = u) });
+            return usage ? { value, usage } : { value };
+        },
+    };
+}
+/** A cloud runner that POSTs the request as JSON to your endpoint. */
+export function fetchAdapter(options) {
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    return cloudAdapter(async (request, { signal, reportUsage }) => {
+        const body = options.body ? options.body(request) : request;
+        const res = await doFetch(options.url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...options.headers },
+            body: JSON.stringify(body),
+            ...(signal ? { signal } : {}),
+        });
+        if (!res.ok)
+            throw new Error(`Cloud endpoint responded with HTTP ${res.status}`);
+        const json = await res.json();
+        const usage = options.usage?.(json);
+        if (usage)
+            reportUsage(usage);
+        return options.select ? options.select(json) : json;
+    }, { id: options.id ?? 'fetch' });
+}
+//# sourceMappingURL=cloud.js.map

package/dist/cloud.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.js","sourceRoot":"","sources":["../src/cloud.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAC1B,EAAc,EACd,OAAO,GAAoB,EAAE;IAE7B,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,OAAO;QACzB,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI;YACrB,IAAI,KAA4C,CAAC;YACjD,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;YACnF,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;QAC9C,CAAC;KACF,CAAC;AACJ,CAAC;AAgBD,sEAAsE;AACtE,MAAM,UAAU,YAAY,CAAoC,OAA+B;IAC7F,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACnE,OAAO,YAAY,CACjB,KAAK,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE;QACzC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAC5D,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE;YACrC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE;YACnE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAC1B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACjF,MAAM,IAAI,GAAY,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,KAAK;YAAE,WAAW,CAAC,KAAK,CAAC,CAAC;QAC9B,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtD,CAAC,EACD,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,OAAO,EAAE,CAC9B,CAAC;AACJ,CAAC"}

package/dist/confidence.d.ts

@@ -0,0 +1,22 @@
+import type { ProbabilityEntry } from './types.js';
+/** Probability of the top option: the confidence signal for classifier tasks. */
+export declare function topProbability(probabilities: readonly ProbabilityEntry[]): number;
+export interface ConfidenceSignals {
+    /** Whether the output passed schema validation. */
+    valid: boolean;
+    /** Confidence reported by the local runner itself, if any. */
+    runner?: number | undefined;
+    /** P(correct) from the classifier-as-judge, if any. */
+    judge?: number | undefined;
+}
+/**
+ * Combines the signals into one confidence (ADR 0001, "Confidence signal"):
+ *
+ * - schema validation is a hard gate: an invalid output has confidence 0;
+ * - with only one of `runner` / `judge`, that value is the confidence;
+ * - with both, the minimum (the more pessimistic signal wins);
+ * - with neither, `undefined`: the task cannot decide and reports a configuration error.
+ */
+export declare function combineConfidence(signals: ConfidenceSignals): number | undefined;
+export declare function clamp01(n: number): number;
+//# sourceMappingURL=confidence.d.ts.map

package/dist/confidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.d.ts","sourceRoot":"","sources":["../src/confidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,aAAa,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,CAIjF;AAED,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAKhF;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGzC"}

package/dist/confidence.js

@@ -0,0 +1,30 @@
+/** Probability of the top option: the confidence signal for classifier tasks. */
+export function topProbability(probabilities) {
+    let top = 0;
+    for (const p of probabilities)
+        if (p.probability > top)
+            top = p.probability;
+    return clamp01(top);
+}
+/**
+ * Combines the signals into one confidence (ADR 0001, "Confidence signal"):
+ *
+ * - schema validation is a hard gate: an invalid output has confidence 0;
+ * - with only one of `runner` / `judge`, that value is the confidence;
+ * - with both, the minimum (the more pessimistic signal wins);
+ * - with neither, `undefined`: the task cannot decide and reports a configuration error.
+ */
+export function combineConfidence(signals) {
+    if (!signals.valid)
+        return 0;
+    const values = [signals.runner, signals.judge].filter((v) => typeof v === 'number');
+    if (values.length === 0)
+        return undefined;
+    return clamp01(Math.min(...values));
+}
+export function clamp01(n) {
+    if (Number.isNaN(n))
+        return 0;
+    return n < 0 ? 0 : n > 1 ? 1 : n;
+}
+//# sourceMappingURL=confidence.js.map

package/dist/confidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.js","sourceRoot":"","sources":["../src/confidence.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,MAAM,UAAU,cAAc,CAAC,aAA0C;IACvE,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,CAAC,IAAI,aAAa;QAAE,IAAI,CAAC,CAAC,WAAW,GAAG,GAAG;YAAE,GAAG,GAAG,CAAC,CAAC,WAAW,CAAC;IAC5E,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAWD;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA0B;IAC1D,IAAI,CAAC,OAAO,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;IACjG,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,CAAS;IAC/B,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnC,CAAC"}

package/dist/cost.d.ts

@@ -0,0 +1,60 @@
+import type { BelayEvent, CloudUsage, PriceTable, TokenPrices } from './types.js';
+/** Normalizes a runner's usage report to a list of per-model parts. */
+export declare function usageParts(usage: CloudUsage | readonly CloudUsage[] | undefined): CloudUsage[];
+/**
+ * Cost of one cloud call from its token usage. Prices are per million tokens. A price table is
+ * keyed by the model id the provider reports, so a call that a fallback model served is priced
+ * at that model's rates. Throws when a model has no price: guessing would make every saving wrong.
+ */
+export declare function costOf(usage: CloudUsage | readonly CloudUsage[], prices: PriceTable | TokenPrices): number;
+export interface SavingsMeterOptions {
+    /** Per-token prices, to measure the cost of each cloud call from the usage its runner reports. */
+    prices?: PriceTable | TokenPrices;
+    /**
+     * Cost of one cloud call, used when calls report no usage, and to value the calls the cascade
+     * avoided before any cloud call has been measured. A calibration file's `cost.cloudPerRun` fits.
+     */
+    cloudPerRun?: number;
+    currency?: string;
+}
+export interface SavingsSummary {
+    currency: string | null;
+    runs: number;
+    /** Answered on device because the local confidence met the threshold. */
+    local: number;
+    /** Answered by the cloud runner. */
+    cloud: number;
+    /** Answered on device only because escalation was blocked (policy, consent, cloud error). */
+    blocked: number;
+    /** Spent on cloud calls: measured where usage was reported, otherwise `cloudPerRun` each. */
+    cloudSpend: number | null;
+    /** Mean cost of one cloud call (measured when possible). */
+    costPerCloudRun: number | null;
+    /** What the `local` runs would have cost in the cloud: `local × costPerCloudRun`. */
+    saved: number | null;
+    /** `saved / (saved + cloudSpend)`: the share of the cloud-only bill the cascade avoided. */
+    savedShare: number | null;
+    /** How many cloud calls were priced from reported usage. */
+    measuredCalls: number;
+}
+export interface SavingsMeter {
+    /** Pass as the task's `onEvent` (or call it from yours). */
+    readonly onEvent: (event: BelayEvent) => void;
+    /** Totals so far, for all tasks or one. */
+    summary(task?: string): SavingsSummary;
+    reset(): void;
+}
+/**
+ * Counts what the cascade saves in production. Only runs that stayed on device because the
+ * local answer was confident count as saved; runs kept local because escalation was blocked
+ * are reported separately. Unmeasured calls, and the value of avoided ones, use the mean
+ * measured cost per call, falling back to `cloudPerRun`.
+ *
+ * ```ts
+ * const meter = savingsMeter({ prices, cloudPerRun: calibration.cost?.cloudPerRun });
+ * const triage = task({ ..., onEvent: meter.onEvent });
+ * meter.summary(); // { runs, local, cloud, cloudSpend, saved, savedShare, ... }
+ * ```
+ */
+export declare function savingsMeter(options?: SavingsMeterOptions): SavingsMeter;
+//# sourceMappingURL=cost.d.ts.map

package/dist/cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAElF,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,UAAU,EAAE,GAAG,SAAS,GAAG,UAAU,EAAE,CAG9F;AAUD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,UAAU,EAAE,EAAE,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,MAAM,CAW1G;AAED,MAAM,WAAW,mBAAmB;IAClC,kGAAkG;IAClG,MAAM,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;IAClC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4DAA4D;IAC5D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,qFAAqF;IACrF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,4FAA4F;IAC5F,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC9C,2CAA2C;IAC3C,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC;IACvC,KAAK,IAAI,IAAI,CAAC;CACf;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAoD5E"}

package/dist/cost.js

@@ -0,0 +1,99 @@
+/** Normalizes a runner's usage report to a list of per-model parts. */
+export function usageParts(usage) {
+    if (!usage)
+        return [];
+    return Array.isArray(usage) ? [...usage] : [usage];
+}
+function pricesFor(prices, model) {
+    if (typeof prices.input === 'number')
+        return prices;
+    const table = prices;
+    if (model !== undefined && Object.hasOwn(table, model))
+        return table[model];
+    const known = Object.keys(table).join(', ') || 'none';
+    throw new Error(model === undefined ? `usage names no model and the price table has several (${known})` : `no price for model "${model}" (prices for: ${known})`);
+}
+/**
+ * Cost of one cloud call from its token usage. Prices are per million tokens. A price table is
+ * keyed by the model id the provider reports, so a call that a fallback model served is priced
+ * at that model's rates. Throws when a model has no price: guessing would make every saving wrong.
+ */
+export function costOf(usage, prices) {
+    let total = 0;
+    for (const part of usageParts(usage)) {
+        const p = pricesFor(prices, part.model);
+        total +=
+            part.inputTokens * p.input +
+                part.outputTokens * p.output +
+                (part.cacheReadInputTokens ?? 0) * (p.cacheRead ?? p.input) +
+                (part.cacheWriteInputTokens ?? 0) * (p.cacheWrite ?? p.input);
+    }
+    return total / 1e6;
+}
+/**
+ * Counts what the cascade saves in production. Only runs that stayed on device because the
+ * local answer was confident count as saved; runs kept local because escalation was blocked
+ * are reported separately. Unmeasured calls, and the value of avoided ones, use the mean
+ * measured cost per call, falling back to `cloudPerRun`.
+ *
+ * ```ts
+ * const meter = savingsMeter({ prices, cloudPerRun: calibration.cost?.cloudPerRun });
+ * const triage = task({ ..., onEvent: meter.onEvent });
+ * meter.summary(); // { runs, local, cloud, cloudSpend, saved, savedShare, ... }
+ * ```
+ */
+export function savingsMeter(options = {}) {
+    const tallies = new Map();
+    const tallyFor = (task) => {
+        let t = tallies.get(task);
+        if (!t)
+            tallies.set(task, (t = { runs: 0, local: 0, cloud: 0, blocked: 0, measuredCalls: 0, measuredSpend: 0 }));
+        return t;
+    };
+    const onEvent = (event) => {
+        if (event.type !== 'run')
+            return;
+        const t = tallyFor(event.task);
+        t.runs++;
+        if (event.source === 'cloud') {
+            t.cloud++;
+            if (options.prices && event.cloudUsage?.length) {
+                t.measuredSpend += costOf(event.cloudUsage, options.prices);
+                t.measuredCalls++;
+            }
+        }
+        else if (event.escalationBlocked) {
+            t.blocked++;
+        }
+        else if (event.escalationReason === null) {
+            t.local++;
+        }
+    };
+    const summary = (task) => {
+        const parts = task === undefined ? [...tallies.values()] : tallies.has(task) ? [tallies.get(task)] : [];
+        const sum = (key) => parts.reduce((a, t) => a + t[key], 0);
+        const runs = sum('runs');
+        const local = sum('local');
+        const cloud = sum('cloud');
+        const measuredCalls = sum('measuredCalls');
+        const measuredSpend = sum('measuredSpend');
+        const costPerCloudRun = measuredCalls ? measuredSpend / measuredCalls : (options.cloudPerRun ?? null);
+        const cloudSpend = costPerCloudRun === null ? null : measuredSpend + (cloud - measuredCalls) * costPerCloudRun;
+        const saved = costPerCloudRun === null ? null : local * costPerCloudRun;
+        const denominator = saved === null || cloudSpend === null ? 0 : saved + cloudSpend;
+        return {
+            currency: options.currency ?? null,
+            runs,
+            local,
+            cloud,
+            blocked: sum('blocked'),
+            cloudSpend,
+            costPerCloudRun,
+            saved,
+            savedShare: denominator > 0 ? saved / denominator : null,
+            measuredCalls,
+        };
+    };
+    return { onEvent, summary, reset: () => tallies.clear() };
+}
+//# sourceMappingURL=cost.js.map

package/dist/cost.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+export type BelayErrorCode = 
+/** No local output and escalation was not possible or not permitted. */
+'no-result'
+/** The cloud runner threw or returned an output that does not match the schema. */
+ | 'cloud-error' | 'cloud-invalid-output'
+/** The task definition is invalid. */
+ | 'invalid-task'
+/** The calibration file is malformed or does not belong to this task. */
+ | 'invalid-calibration';
+export declare class BelayError extends Error {
+    readonly name = "BelayError";
+    readonly code: BelayErrorCode;
+    constructor(code: BelayErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown by a local runner from `run()` when the model is not usable (e.g. it would need
+ * a download). The cascade treats it as escalation reason `local-unavailable`.
+ */
+export declare class LocalUnavailableError extends Error {
+    readonly name = "LocalUnavailableError";
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc;AACxB,wEAAwE;AACtE,WAAW;AACb,mFAAmF;GACjF,aAAa,GACb,sBAAsB;AACxB,sCAAsC;GACpC,cAAc;AAChB,yEAAyE;GACvE,qBAAqB,CAAC;AAE1B,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAkB,IAAI,gBAAgB;IACtC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAE9B,YAAY,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAG/E;CACF;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAkB,IAAI,2BAA2B;CAClD"}

package/dist/errors.js

@@ -0,0 +1,16 @@
+export class BelayError extends Error {
+    name = 'BelayError';
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/**
+ * Thrown by a local runner from `run()` when the model is not usable (e.g. it would need
+ * a download). The cascade treats it as escalation reason `local-unavailable`.
+ */
+export class LocalUnavailableError extends Error {
+    name = 'LocalUnavailableError';
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,UAAW,SAAQ,KAAK;IACjB,IAAI,GAAG,YAAY,CAAC;IAC7B,IAAI,CAAiB;IAE9B,YAAY,IAAoB,EAAE,OAAe,EAAE,OAA6B;QAC9E,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC5B,IAAI,GAAG,uBAAuB,CAAC;CAClD"}

package/dist/hash.d.ts

@@ -0,0 +1,5 @@
+/** 32-bit FNV-1a over UTF-16 code units, hex encoded. Not cryptographic; used for fingerprints. */
+export declare function fnv1a(text: string): string;
+/** JSON.stringify with sorted object keys, so equal values serialize identically. */
+export declare function canonicalJson(value: unknown): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO1C;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CASpD"}

package/dist/hash.js

@@ -0,0 +1,19 @@
+/** 32-bit FNV-1a over UTF-16 code units, hex encoded. Not cryptographic; used for fingerprints. */
+export function fnv1a(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+/** JSON.stringify with sorted object keys, so equal values serialize identically. */
+export function canonicalJson(value) {
+    return JSON.stringify(value, (_key, v) => {
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            return Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+        }
+        return v;
+    });
+}
+//# sourceMappingURL=hash.js.map

package/dist/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,MAAM,UAAU,KAAK,CAAC,IAAY;IAChC,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACpD,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAU,EAAE,EAAE;QAChD,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,CAA4B,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAC9F,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { task } from './task.js';
+export { cloudAdapter, fetchAdapter } from './cloud.js';
+export type { CloudFn, FetchAdapterOptions } from './cloud.js';
+export { costOf, savingsMeter, usageParts } from './cost.js';
+export type { SavingsMeter, SavingsMeterOptions, SavingsSummary } from './cost.js';
+export { combineConfidence, topProbability, clamp01 } from './confidence.js';
+export type { ConfidenceSignals } from './confidence.js';
+export { CALIBRATION_VERSION, loadCalibration, parseCalibration, thresholdFor } from './calibration.js';
+export { assertValidSchema, buildInstruction, labelOf, normalizeOptions, optionLabels, parseValue, schemaFingerprint, toJsonSchema, } from './schema.js';
+export type { ParseResult } from './schema.js';
+export { BelayError, LocalUnavailableError } from './errors.js';
+export type { BelayErrorCode } from './errors.js';
+export { canonicalJson, fnv1a } from './hash.js';
+export type * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACxD,YAAY,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACxG,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,OAAO,EACP,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACjD,mBAAmB,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export { task } from './task.js';
+export { cloudAdapter, fetchAdapter } from './cloud.js';
+export { costOf, savingsMeter, usageParts } from './cost.js';
+export { combineConfidence, topProbability, clamp01 } from './confidence.js';
+export { CALIBRATION_VERSION, loadCalibration, parseCalibration, thresholdFor } from './calibration.js';
+export { assertValidSchema, buildInstruction, labelOf, normalizeOptions, optionLabels, parseValue, schemaFingerprint, toJsonSchema, } from './schema.js';
+export { BelayError, LocalUnavailableError } from './errors.js';
+export { canonicalJson, fnv1a } from './hash.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE7E,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACxG,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,OAAO,EACP,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,33 @@
+import type { OptionInput, OptionSpec, TaskSchema, ValueOf } from './types.js';
+export declare function normalizeOptions(options: readonly OptionInput[]): OptionSpec[];
+export declare function optionLabels(schema: TaskSchema): string[];
+/** Throws `BelayError('invalid-task')` if the schema is malformed. */
+export declare function assertValidSchema(schema: TaskSchema): void;
+/**
+ * Fingerprint of everything in the schema that influences model behavior (type, prompt,
+ * option labels and descriptions, JSON Schema). Stored in calibration files so a task can
+ * tell when its calibration was produced for a different schema.
+ */
+export declare function schemaFingerprint(schema: TaskSchema): string;
+/**
+ * JSON Schema of the output. Non-structured outputs are wrapped as `{ "value": ... }`
+ * because many providers require an object at the root.
+ */
+export declare function toJsonSchema(schema: TaskSchema): Record<string, unknown>;
+/** A provider-neutral instruction for cloud runners that build their own prompt from it. */
+export declare function buildInstruction(schema: TaskSchema, context?: string): string;
+export type ParseResult<V> = {
+    ok: true;
+    value: V;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Coerces a runner output into the schema's value type. Accepts the bare value or the
+ * `{ value }` wrapper from {@link toJsonSchema}, and JSON strings of either.
+ */
+export declare function parseValue<S extends TaskSchema>(schema: S, raw: unknown): ParseResult<ValueOf<S>>;
+/** Label of a value for telemetry and per-label thresholds; `undefined` for structured tasks. */
+export declare function labelOf(schema: TaskSchema, value: unknown): string | undefined;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE/E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,UAAU,EAAE,CAE9E;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAUzD;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CA0B1D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAM5D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgBxE;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAyB7E;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnF;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CA6CjG;AAED,iGAAiG;AACjG,wBAAgB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG9E"}