decidekit 0.0.0-stage → 0.1.0

package/dist/fallback.js

@@ -0,0 +1,68 @@
+/** The label `withFallback()` learns `ask`'s `null` answers as. It shows in `route.head.labels` and `route.learned`. */
+export const NONE = "none_of_these";
+const isHead = (c) => typeof c === "object" && c !== null && "weights" in c;
+/**
+ * Routes each text to the local decision, or to `ask` when its confidence is below `minConfidence`.
+ *
+ * - With a trained head and its `examples`, answers from `ask` are kept as new examples.
+ * - With labels (`["refund", "bug"]` or described labels), it starts zero-shot and always learns: `retrain()` (or
+ *   `retrainEvery`) trains the first head from the answers. Labels with no answers yet start from their names.
+ */
+export function withFallback(decider, using, options) {
+    const { minConfidence = 0.9, ask, retrainEvery, trainOptions, learnNone = true, noneBelow = 0.6 } = options;
+    // A head saved from an earlier session may carry NONE; it isn't one of the labels `ask` chooses from.
+    const labels = (isHead(using) ? using.labels : Array.isArray(using) ? using : Object.keys(using)).filter((l) => l !== NONE);
+    const zeroShotChoices = isHead(using) ? labels : using;
+    const examples = options.examples ?? (isHead(using) ? undefined : []);
+    const learned = [...(options.restore?.learned ?? [])];
+    let current = using;
+    let retraining;
+    let sinceRetrain = 0;
+    // Zero-shot's confident answers: right about 93% of the time on BANKING77, and enough to calibrate on (eval/long-stream.ts).
+    // 4 per label, or more with few labels so the set can reach 50 (12 labels capped at 4 never did).
+    const confident = [...(options.restore?.confident ?? [])], perLabel = new Map(), perLabelCap = Math.max(4, Math.ceil(50 / labels.length));
+    for (const e of confident)
+        perLabel.set(e.label, (perLabel.get(e.label) ?? 0) + 1);
+    function retrain() {
+        if (!examples)
+            return Promise.reject(new Error("decidekit: withFallback() needs `examples` to retrain a head"));
+        if (!examples.length && !learned.length)
+            return Promise.reject(new Error("decidekit: nothing to train on yet: no answers from `ask`"));
+        const calibrateOn = trainOptions?.calibrateOn ?? (confident.length >= 50 ? confident : undefined);
+        const trainLabels = learned.some((e) => e.label === NONE) ? [...labels, NONE] : labels;
+        retraining ??= decider.train([...examples, ...learned], { ...trainOptions, labels: trainLabels, calibrateOn }).then((h) => {
+            current = h;
+            return h;
+        }).finally(() => (retraining = undefined));
+        return retraining;
+    }
+    async function route(text) {
+        const local = await decider.decide(text, current);
+        if (local.confidence >= minConfidence) {
+            if (!isHead(current) && (perLabel.get(local.choice) ?? 0) < perLabelCap) {
+                perLabel.set(local.choice, (perLabel.get(local.choice) ?? 0) + 1);
+                confident.push({ text, label: local.choice });
+            }
+            return local.choice === NONE ? { ...local, choice: null, source: "local" } : { ...local, source: "local" };
+        }
+        const answer = await ask(text, labels, local);
+        const choice = answer !== null && labels.includes(answer) ? answer : null;
+        const learnAsNone = examples && answer === null && learnNone && (!noneBelow || ((await decider.decide(text, zeroShotChoices)).similarity ?? 0) < noneBelow);
+        if (examples && (choice !== null || learnAsNone)) {
+            learned.push({ text, label: choice ?? NONE });
+            if (retrainEvery && ++sinceRetrain >= retrainEvery) {
+                sinceRetrain = 0;
+                // A failed background retrain keeps the current head; call retrain() yourself to see the error.
+                retrain().catch(() => { });
+            }
+        }
+        return { ...local, choice, source: "fallback" };
+    }
+    // defineProperties, not Object.assign: assign would copy the getters' values once.
+    return Object.defineProperties(route, {
+        retrain: { value: retrain },
+        saved: { value: () => ({ learned: [...learned], confident: [...confident] }) },
+        head: { get: () => (isHead(current) ? current : null) },
+        learned: { get: () => learned },
+    });
+}

package/dist/head-io.d.ts

@@ -0,0 +1,4 @@
+import type { Head } from "./index.ts";
+/** Serialises a head to JSON with base64 weights, for a static file next to the app. */
+export declare function saveHead(head: Head): string;
+export declare function loadHead<L extends string = string>(json: string): Head<L>;

package/dist/head-io.js

@@ -0,0 +1,16 @@
+/** Serialises a head to JSON with base64 weights, for a static file next to the app. */
+export function saveHead(head) {
+    const b64 = (a) => {
+        const bytes = new Uint8Array(a.buffer, a.byteOffset, a.byteLength);
+        let s = "";
+        for (let i = 0; i < bytes.length; i += 0x8000)
+            s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+        return btoa(s);
+    };
+    return JSON.stringify({ ...head, weights: b64(head.weights), bias: b64(head.bias) });
+}
+export function loadHead(json) {
+    const raw = JSON.parse(json);
+    const f32 = (s) => new Float32Array(Uint8Array.from(atob(s), (c) => c.charCodeAt(0)).buffer);
+    return { ...raw, weights: f32(raw.weights), bias: f32(raw.bias) };
+}

package/dist/head.d.ts

@@ -0,0 +1,14 @@
+import type { Head, TrainOptions } from "./index.ts";
+export declare function softmax(z: ArrayLike<number>, t: number): number[];
+export declare function logits(head: Pick<Head, "labels" | "dim" | "weights" | "bias">, x: ArrayLike<number>): Float64Array;
+/** Fits weights, biases and temperature to embeddings `X` with label indices `y`. */
+export declare function fitHead<L extends string>(X: ArrayLike<number>[], y: number[], labels: L[], opts?: TrainOptions, priors?: ArrayLike<number>[], priorWeight?: number, centroidScale?: number, smallFloor?: number, calibration?: {
+    X: ArrayLike<number>[];
+    y: number[];
+}): Promise<{
+    labels: L[];
+    dim: number;
+    weights: Float32Array<ArrayBuffer>;
+    bias: Float32Array<ArrayBuffer>;
+    temperature: number;
+}>;

package/dist/head.js

@@ -0,0 +1,155 @@
+const BATCH = 64;
+const CENTROID_SCALE = 20;
+// Lets a tab paint and handle input between training batches. A message-channel task, unlike setTimeout, isn't
+// throttled to once a second (or minute) when the tab is in the background.
+function yieldToPage() {
+    return new Promise((resolve) => {
+        const { port1, port2 } = new MessageChannel();
+        port1.onmessage = () => { port1.close(); resolve(); };
+        port2.postMessage(null);
+    });
+}
+export function softmax(z, t) {
+    let max = -Infinity;
+    for (let i = 0; i < z.length; i++)
+        max = Math.max(max, z[i]);
+    const e = Array.from(z, (v) => Math.exp((v - max) / t));
+    const sum = e.reduce((a, b) => a + b, 0);
+    return e.map((v) => v / sum);
+}
+export function logits(head, x) {
+    const { labels, dim, weights, bias } = head;
+    const z = new Float64Array(labels.length);
+    for (let c = 0; c < labels.length; c++) {
+        let s = bias[c];
+        const row = c * dim;
+        for (let j = 0; j < dim; j++)
+            s += weights[row + j] * x[j];
+        z[c] = s;
+    }
+    return z;
+}
+// Sums the softmax cross-entropy gradient over one batch into gW and gb. A plain function, not inline in the async
+// training loop: inline it took 777 s on the hill harness, here 340 s (the previous loop: 448 s).
+function batchGradient(ids, X, y, W, B, gW, gb, z, C, dim) {
+    for (const i of ids) {
+        const x = i * dim;
+        let max = -Infinity;
+        for (let c = 0; c < C; c++) {
+            let v = B[c];
+            const row = c * dim;
+            for (let j = 0; j < dim; j++)
+                v += W[row + j] * X[x + j];
+            z[c] = v;
+            if (v > max)
+                max = v;
+        }
+        let sum = 0;
+        for (let c = 0; c < C; c++)
+            sum += (z[c] = Math.exp(z[c] - max));
+        for (let c = 0; c < C; c++) {
+            const p = z[c] / sum - (c === y[i] ? 1 : 0);
+            gb[c] += p;
+            const row = c * dim;
+            for (let j = 0; j < dim; j++)
+                gW[row + j] += p * X[x + j];
+        }
+    }
+}
+/** Fits weights, biases and temperature to embeddings `X` with label indices `y`. */
+export async function fitHead(X, y, labels, opts = {}, priors, priorWeight = 1, centroidScale = CENTROID_SCALE, smallFloor = 1, calibration) {
+    // smallFloor: the lowest temperature a head with under 50 held-out answers may get; createDecider picks it per model.
+    // calibration: labelled examples known to be right to fit the temperature on instead of the training examples.
+    const { epochs = 60, learningRate = 2, l2 = 1e-4, holdout = 0.1, seed = 7, onEpoch } = opts;
+    const dim = X[0].length, C = labels.length;
+    // One flat buffer, so the inner loops read typed memory instead of an array of arrays.
+    const Xf = new Float64Array(X.length * dim);
+    X.forEach((x, i) => Xf.set(x, i * dim));
+    let s = seed;
+    const rand = () => (s = (s * 1103515245 + 12345) % 2 ** 31) / 2 ** 31;
+    const idx = X.map((_, i) => i).sort(() => rand() - 0.5);
+    const nVal = Math.max(1, Math.floor(idx.length * holdout));
+    const val = idx.slice(0, nVal);
+    // One training run on `rows`. With `check`, keeps the epoch that scores best on it.
+    async function run(rows, nEpochs, check) {
+        const head = { labels, dim, weights: new Float32Array(C * dim), bias: new Float32Array(C) };
+        // Start each label at the normalised mean of its examples (nearest centroid), scaled like zero-shot
+        // similarities. With a handful of examples per label this is most of the accuracy; gradient descent refines it.
+        for (const i of rows)
+            for (let j = 0; j < dim; j++)
+                head.weights[y[i] * dim + j] += X[i][j];
+        if (priors)
+            for (let c = 0; c < C; c++)
+                for (let j = 0; j < dim; j++)
+                    head.weights[c * dim + j] += priorWeight * priors[c][j];
+        for (let c = 0; c < C; c++) {
+            const row = head.weights.subarray(c * dim, (c + 1) * dim);
+            const norm = Math.hypot(...row) || 1;
+            for (let j = 0; j < dim; j++)
+                row[j] = (row[j] / norm) * centroidScale;
+        }
+        const acc = () => check.filter((i) => { const z = logits(head, X[i]); return z.indexOf(Math.max(...z)) === y[i]; }).length / check.length;
+        let best = { acc: check ? acc() : 0, weights: head.weights.slice(), bias: head.bias.slice(), epochs: 0 };
+        const gW = new Float64Array(C * dim), gb = new Float64Array(C), z = new Float64Array(C);
+        const W = head.weights, B = head.bias;
+        const order = [...rows];
+        for (let ep = 0; ep < nEpochs; ep++) {
+            order.sort(() => rand() - 0.5);
+            for (let b = 0; b < order.length; b += BATCH) {
+                const ids = order.slice(b, b + BATCH);
+                gW.fill(0);
+                gb.fill(0);
+                batchGradient(ids, Xf, y, W, B, gW, gb, z, C, dim);
+                await yieldToPage();
+                for (let c = 0; c < C; c++) {
+                    B[c] -= (learningRate * gb[c]) / ids.length;
+                    for (let j = 0; j < dim; j++) {
+                        const k = c * dim + j;
+                        W[k] -= learningRate * (gW[k] / ids.length + l2 * W[k]);
+                    }
+                }
+            }
+            if (!check)
+                continue;
+            const a = acc();
+            onEpoch?.(ep, a);
+            if (a > best.acc)
+                best = { acc: a, weights: head.weights.slice(), bias: head.bias.slice(), epochs: ep + 1 };
+        }
+        return check ? { ...head, weights: best.weights, bias: best.bias, epochs: best.epochs } : { ...head, epochs: nEpochs };
+    }
+    // Pick the epoch count and temperature on held-out examples, then retrain on every example for that many epochs:
+    // with 5 examples per label, a holdout would otherwise cost each label one of its five. A holdout under 200
+    // examples gave a temperature off by up to 0.40 calibration error, so small sets use 5 folds instead: every example
+    // is held out once and the temperature is fitted on all of them.
+    const folds = nVal < 200 ? Array.from({ length: 5 }, (_, f) => idx.filter((_, i) => i % 5 === f)) : [val];
+    const heldOut = [], foldEpochs = [];
+    for (const check of folds) {
+        const probe = await run(idx.filter((i) => !check.includes(i)), epochs, check);
+        foldEpochs.push(probe.epochs);
+        // A label whose only examples are all held out can never be chosen; counting those answers as misses pulled
+        // the temperature far too high (1 example per label: 93% right at 48% mean confidence).
+        const seen = new Set(idx.filter((i) => !check.includes(i)).map((i) => y[i]));
+        for (const i of check)
+            if (seen.has(y[i]))
+                heldOut.push({ z: logits(probe, X[i]), y: y[i] });
+    }
+    const head = await run(idx, foldEpochs.sort((a, b) => a - b)[foldEpochs.length >> 1]);
+    const fitOn = calibration ? calibration.X.map((x, i) => ({ z: logits(head, x), y: calibration.y[i] })) : heldOut;
+    let temperature = 1, bestNll = Infinity;
+    // Log-spaced from 0.01 to 10: encoders whose similarities sit close together (multilingual-e5) need far lower
+    // temperatures than bge; a grid starting at 0.2 left their heads at about half the confidence they earned.
+    for (let k = 0; k <= 120; k++) {
+        const t = 0.01 * 1000 ** (k / 120);
+        const nll = fitOn.reduce((sum, h) => sum - Math.log(softmax(h.z, t)[h.y] + 1e-12), 0);
+        if (nll < bestNll) {
+            bestNll = nll;
+            temperature = Number(t.toPrecision(3));
+        }
+    }
+    // Under 50 answers, a perfect score pulls the temperature to its floor and every answer to confidence 1.0 (seen
+    // with 6 examples). Never sharpen past the floor on that little evidence.
+    if (fitOn.length < 50)
+        temperature = Math.max(temperature, smallFloor);
+    return { labels, dim, weights: head.weights, bias: head.bias, temperature };
+}

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+/** The result of `decide()`. */
+export interface Decision<L extends string, C extends L | null = L> {
+    /** The most likely option or label; `null` when below `minConfidence`. */
+    choice: C;
+    /**
+     * Probability of `choice`, 0 to 1. Trained heads fit it on held-out examples. Zero-shot uses a fixed temperature
+     * per model (0.03 for the default bge-small, 0.05 for all-MiniLM-L6-v2), which measured close to calibrated on two
+     * intent datasets (error 0.03-0.04 on their dev splits); check it on your own options before thresholding.
+     */
+    confidence: number;
+    /** Probability of every option; sums to 1. */
+    probabilities: Record<L, number>;
+    /**
+     * Zero-shot only: the best cosine similarity between the text and any option's name or description. Low means the
+     * text is about none of them (with bge-small, off-topic text was mostly under 0.5 and in-scope text over 0.7).
+     */
+    similarity?: number;
+}
+/** A trained head: row-major weights (labels × dim), biases and the fitted temperature. */
+export interface Head<L extends string = string> {
+    model: string;
+    labels: readonly L[];
+    dim: number;
+    weights: Float32Array;
+    bias: Float32Array;
+    temperature: number;
+}
+/**
+ * What `decide()` chooses between: a list of labels, labels with descriptions (`{ refund: "wants their money back" }`,
+ * where the description is what gets compared), or a trained head.
+ */
+export type Choices<L extends string> = readonly L[] | Readonly<Record<L, string>> | Head<L>;
+/** Options for one `decide()` call. */
+export interface DecideOptions {
+    /**
+     * Below this confidence, `choice` is `null`: "none of these". Use it with trained heads, whose confidence is
+     * calibrated. On CLINC150, 0.93 returned null for 86.3% of out-of-scope queries.
+     */
+    minConfidence?: number;
+}
+/** One labelled example for `train()`. */
+export interface Example<L extends string> {
+    text: string;
+    label: L;
+}
+export interface TrainOptions<L extends string = string> {
+    /** Use label names as a hint (default true). Turn off when labels are opaque ids like `c17`. */
+    labelNames?: boolean;
+    /**
+     * Labels to include even without examples yet. They start from their readable name alone, as zero-shot does, and
+     * can still be chosen. Needs `labelNames`.
+     */
+    labels?: readonly L[];
+    /** Passes over the examples. Default 60; the best holdout epoch is kept. */
+    epochs?: number;
+    /** Default 2. */
+    learningRate?: number;
+    /** Weight decay. Default 1e-4. */
+    l2?: number;
+    /** Share of examples held out for early stopping and temperature fitting. Default 0.1. */
+    holdout?: number;
+    /** Seed for the holdout split and shuffling, so runs repeat. Default 7. */
+    seed?: number;
+    /**
+     * Examples known to be right, used only to fit the temperature (how far to trust the head). Pass them when the
+     * training examples come from a source that is sometimes wrong, such as an LLM through `withFallback()`: fitted on
+     * those, the temperature learns to doubt the head. 2 per label is enough (eval/long-stream.ts).
+     */
+    calibrateOn?: readonly Example<L>[];
+    /** Called after each epoch with accuracy on the holdout. */
+    onEpoch?: (epoch: number, holdoutAccuracy: number) => void;
+}
+export interface DeciderOptions {
+    /**
+     * A Hugging Face sentence-embedding model with ONNX weights. Default `Xenova/bge-small-en-v1.5` (34 MB at q8).
+     * Pre-release builds defaulted to `Xenova/all-MiniLM-L6-v2` (23 MB): smaller and 1.6x faster, 3 to 5 points less
+     * accurate. Pass it to keep using heads trained on it.
+     */
+    model?: string;
+    /** Defaults to transformers.js' choice: wasm in browsers, cpu in Node. */
+    device?: "wasm" | "webgpu" | "cpu";
+    /** Weight precision. Default `q8`. */
+    dtype?: "q8" | "fp16" | "fp32";
+    /** Called as model files download (first load only; later loads come from cache). */
+    onProgress?: (progress: {
+        file: string;
+        loaded: number;
+        total: number;
+    }) => void;
+    /**
+     * Softmax temperature for zero-shot similarities. Default 0.03 for bge-small (0.025 for described labels, which
+     * score higher), 0.05 for other models. Setting it uses the same value for both.
+     */
+    temperature?: number;
+}
+/**
+ * Loads the encoder (downloaded once, then cached by the browser or transformers.js) and returns `decide()` and
+ * `train()`. In a browser, prefer `createWorkerDecider()` from `decidekit/browser`: the encoder blocks the thread
+ * it runs on.
+ */
+export declare function createDecider({ model, device, dtype, temperature, onProgress }?: DeciderOptions): Promise<{
+    model: string;
+    decide: {
+        <const L extends string>(text: string, using: Choices<L>, options?: {
+            minConfidence?: undefined;
+        }): Promise<Decision<L>>;
+        <const L extends string>(text: string, using: Choices<L>, options: DecideOptions): Promise<Decision<L, L | null>>;
+    };
+    decideMany: {
+        <const L extends string>(texts: readonly string[], using: Choices<L>, options?: {
+            minConfidence?: undefined;
+        }): Promise<Decision<L>[]>;
+        <const L extends string>(texts: readonly string[], using: Choices<L>, options: DecideOptions): Promise<Decision<L, L | null>[]>;
+    };
+    train: <const L extends string>(examples: readonly Example<L>[], opts?: TrainOptions<L>) => Promise<Head<L>>;
+    /** Embeds texts with the encoder: unit-length vectors, one per text. */
+    embed: (texts: readonly string[]) => Promise<number[][]>;
+}>;
+export { saveHead, loadHead } from "./head-io.ts";
+export { withFallback, NONE, type FallbackOptions, type RoutedDecision, type Trainable } from "./fallback.ts";
+export { describeLabels, describePrompt, parseDescriptions, type DescribeOptions } from "./describe.ts";

package/dist/index.js

@@ -0,0 +1,137 @@
+// decide(text, options): typed, calibrated decisions on device. Zero-shot compares the text with each option's
+// embedding; a trained head (a softmax layer over the same embeddings, 156 KB for 77 labels) is far more
+// accurate. Both return the option literals as the choice type.
+import { pipeline } from "@huggingface/transformers";
+import { fitHead, logits, softmax } from "./head.js";
+function isHead(c) {
+    if (Array.isArray(c) || !("weights" in c))
+        return false;
+    if (!(c.weights instanceof Float32Array))
+        throw new Error("decidekit: this head's weights aren't a Float32Array. Read head files with loadHead(), not JSON.parse.");
+    return true;
+}
+const readable = (label) => label.replace(/[_-]+/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase();
+const BATCH = 64;
+const LABEL_NAME_WEIGHT = 1;
+// Zero-shot temperatures that measured calibrated on the BANKING77 and CLINC150 dev splits (eval/gains.ts). Models
+// differ in how spread out their similarities are: at 0.05, bge-small answered only 3% of texts at 0.9 confidence.
+// Described labels get their own: on bge-small, 0.025 halved their calibration error on CLINC150 (0.066 to 0.020) and
+// raised it on BANKING77 (0.032 to 0.042); names alone measured best at 0.03 (eval/descriptions.ts).
+// Small heads (under 50 held-out answers) can't fit a trustworthy temperature, so it has a floor. On bge-small a floor
+// of 1 left them underconfident (calibration error 0.09 to 0.13; only 43 to 69% of texts at 0.9, nearly all right);
+// 0.5 gave 0.009 to 0.017. MiniLM's similarities are spread differently and keep 1 (eval/small-floor.ts).
+// multilingual-e5-small's similarities sit close together, so it needs far lower temperatures: on MASSIVE in English
+// and Japanese, 0.0105 for label names (calibration error 0.03 to 0.04; descriptions not yet measured) and a floor of
+// 0.4 (eval/e5-settings.ts). It also expects "query: " before every text.
+const SMALL_HEAD_FLOOR = { "Xenova/bge-small-en-v1.5": 0.5, "Xenova/multilingual-e5-small": 0.4 };
+const TEMPERATURES = { "Xenova/bge-small-en-v1.5": [0.03, 0.025], "Xenova/all-MiniLM-L6-v2": [0.05, 0.05], "Xenova/multilingual-e5-small": [0.0105, 0.0105] };
+const PREFIX = { "Xenova/multilingual-e5-small": "query: " };
+function toDecision(labels, p) {
+    let best = 0;
+    for (let i = 1; i < p.length; i++)
+        if (p[i] > p[best])
+            best = i;
+    const probabilities = Object.fromEntries(labels.map((l, i) => [l, p[i]]));
+    return { choice: labels[best], confidence: p[best], probabilities };
+}
+/**
+ * Loads the encoder (downloaded once, then cached by the browser or transformers.js) and returns `decide()` and
+ * `train()`. In a browser, prefer `createWorkerDecider()` from `decidekit/browser`: the encoder blocks the thread
+ * it runs on.
+ */
+export async function createDecider({ model = "Xenova/bge-small-en-v1.5", device, dtype = "q8", temperature, onProgress } = {}) {
+    const embed = await pipeline("feature-extraction", model, {
+        device, dtype,
+        progress_callback: onProgress && ((p) => p.status === "progress" && onProgress({ file: p.file, loaded: p.loaded, total: p.total })),
+    });
+    const optionCache = new Map(), prefix = PREFIX[model] ?? "";
+    // The last training set's embeddings, so retraining after adding or fixing a few examples only encodes those.
+    let trainCache = new Map();
+    async function vectors(texts) {
+        const out = [];
+        for (let i = 0; i < texts.length; i += BATCH) {
+            const t = await embed(texts.slice(i, i + BATCH).map((x) => prefix + x), { pooling: "mean", normalize: true });
+            out.push(...t.tolist());
+        }
+        return out;
+    }
+    async function score(q, using, minConfidence) {
+        let d;
+        if (isHead(using)) {
+            if (using.model !== model)
+                throw new Error(`decidekit: this head was trained on ${using.model}, but the decider uses ${model}. Pass { model: "${using.model}" } to createDecider.`);
+            d = toDecision(using.labels, softmax(logits(using, q), using.temperature));
+        }
+        else {
+            const labels = (Array.isArray(using) ? using : Object.keys(using));
+            if (labels.length < 2)
+                throw new Error(`decidekit: decide() needs at least 2 options, got ${labels.length}`);
+            // Bare labels are compared as readable text ("card_arrival" as "card arrival"): 2.6 points better on CLINC150's
+            // dev split. A described label scores by the better of its name and its description: on the dev splits that
+            // beat the description alone by 0.5 (BANKING77) and 3.1 points (CLINC150), and names alone by 7 and 10.
+            const texts = Array.isArray(using) ? labels.map(readable) : labels.flatMap((l) => [readable(l), using[l]]);
+            const key = texts.join("\u0000");
+            let opts = optionCache.get(key);
+            if (!opts)
+                optionCache.set(key, (opts = await vectors(texts)));
+            const all = opts.map((o) => o.reduce((s, x, i) => s + x * q[i], 0));
+            const sims = Array.isArray(using) ? all : labels.map((_, c) => Math.max(all[2 * c], all[2 * c + 1]));
+            const [names, described] = temperature !== undefined ? [temperature, temperature] : TEMPERATURES[model] ?? [0.05, 0.05];
+            d = { ...toDecision(labels, softmax(sims, Array.isArray(using) ? names : described)), similarity: Math.max(...sims) };
+        }
+        return minConfidence !== undefined && d.confidence < minConfidence ? { ...d, choice: null } : d;
+    }
+    async function decide(text, using, { minConfidence } = {}) {
+        const [q] = await vectors([text]);
+        return score(q, using, minConfidence);
+    }
+    async function decideMany(texts, using, { minConfidence } = {}) {
+        const qs = await vectors(texts);
+        return Promise.all(qs.map((q) => score(q, using, minConfidence)));
+    }
+    /**
+     * Trains a head on labelled examples: mini-batch gradient descent on the embeddings, keeping the best holdout
+     * epoch, then a temperature fitted on the holdout so `confidence` is calibrated. Every label needs at least a few
+     * examples. Each label starts at the mean of its examples and its name, so 5 per label already gave 79% on BANKING77 and
+     * 87% on CLINC150 (see the README).
+     */
+    async function train(examples, opts = {}) {
+        const bad = examples.findIndex((e) => typeof e?.text !== "string" || typeof e?.label !== "string" || !e.label);
+        if (bad >= 0)
+            throw new Error(`decidekit: example ${bad} needs a string text and a non-empty string label, got ${JSON.stringify(examples[bad])}`);
+        if (!examples.length)
+            throw new Error("decidekit: train() needs at least 1 example");
+        const labels = [...new Set([...(opts.labels ?? []), ...examples.map((e) => e.label)])].sort();
+        if (opts.labels && opts.labelNames === false && labels.some((l) => !examples.some((e) => e.label === l))) {
+            throw new Error("decidekit: labels without examples need labelNames, which is what they start from");
+        }
+        if (labels.length < 2)
+            throw new Error(`decidekit: train() needs at least 2 labels, got ${labels.length}`);
+        const y = examples.map((e) => labels.indexOf(e.label));
+        const texts = [...new Set(examples.map((e) => e.text))];
+        const fresh = texts.filter((t) => !trainCache.has(t));
+        const encoded = await vectors(fresh);
+        const cache = new Map(texts.map((t) => [t, trainCache.get(t)]));
+        fresh.forEach((t, i) => cache.set(t, encoded[i]));
+        trainCache = cache;
+        const X = examples.map((e) => cache.get(e.text));
+        // Each label's readable name counts as 1 extra example in the starting point. With bge-small that beat no prior
+        // by 1 to 14 points at 1 to 5 examples per label on the dev splits, and beat weight 3 (the MiniLM setting) by 0.9
+        // to 2.5 points (eval/priors.ts).
+        const priors = opts.labelNames === false ? undefined : await vectors(labels.map(readable));
+        const cal = opts.calibrateOn;
+        const unknown = cal?.find((e) => !labels.includes(e.label));
+        if (unknown)
+            throw new Error(`decidekit: calibrateOn has label ${JSON.stringify(unknown.label)}, which isn't one of the head's labels`);
+        const calibration = cal?.length ? { X: await vectors(cal.map((e) => e.text)), y: cal.map((e) => labels.indexOf(e.label)) } : undefined;
+        return { model, ...(await fitHead(X, y, labels, opts, priors, LABEL_NAME_WEIGHT, undefined, SMALL_HEAD_FLOOR[model] ?? 1, calibration)) };
+    }
+    return {
+        model, decide, decideMany, train,
+        /** Embeds texts with the encoder: unit-length vectors, one per text. */
+        embed: vectors,
+    };
+}
+export { saveHead, loadHead } from "./head-io.js";
+export { withFallback, NONE } from "./fallback.js";
+export { describeLabels, describePrompt, parseDescriptions } from "./describe.js";

package/dist/react.d.ts

@@ -0,0 +1,39 @@
+import { createWorkerDecider } from "./browser.ts";
+import type { Choices, DeciderOptions, Decision } from "./index.ts";
+export type WorkerDecider = Awaited<ReturnType<typeof createWorkerDecider>>;
+export interface DeciderState {
+    /** The decider once the model has loaded; `null` before that. */
+    decider: WorkerDecider | null;
+    status: "loading" | "ready" | "error";
+    /** Bytes of model files downloaded so far, on a first visit. */
+    progress: {
+        loaded: number;
+        total: number;
+    } | null;
+    error: Error | null;
+}
+/**
+ * Starts a worker decider when the component mounts and terminates it on unmount. Call it once near the top of
+ * the tree and pass `decider` down: each call starts its own worker and loads its own copy of the model. Options are
+ * read on mount; change `model` or `dtype` by remounting (a `key`).
+ */
+export declare function useDecider(options?: Omit<DeciderOptions, "onProgress">): DeciderState;
+export interface DecisionState<D> {
+    /** The decision for the latest text, or `null` before the first one (and for empty text). */
+    decision: D | null;
+    /** True while a decision for newer text is on its way. */
+    pending: boolean;
+    error: Error | null;
+}
+/**
+ * Decides `text` whenever it (or `using`) changes, after `debounceMs` of quiet (default 150). Answers for text that
+ * has changed since are dropped. Keep `using` stable (a constant, state or useMemo), or every render decides again.
+ */
+export declare function useDecision<const L extends string>(decider: WorkerDecider | null, text: string, using: Choices<L> | null | undefined, options?: {
+    minConfidence?: undefined;
+    debounceMs?: number;
+}): DecisionState<Decision<L>>;
+export declare function useDecision<const L extends string>(decider: WorkerDecider | null, text: string, using: Choices<L> | null | undefined, options: {
+    minConfidence: number;
+    debounceMs?: number;
+}): DecisionState<Decision<L, L | null>>;

package/dist/react.js

@@ -0,0 +1,55 @@
+// React hooks over createWorkerDecider(): the encoder loads in a worker once per component tree that calls
+// useDecider(), and useDecision() decides as the text changes, dropping answers for text that has since changed.
+import { useEffect, useState } from "react";
+import { createWorkerDecider } from "./browser.js";
+/**
+ * Starts a worker decider when the component mounts and terminates it on unmount. Call it once near the top of
+ * the tree and pass `decider` down: each call starts its own worker and loads its own copy of the model. Options are
+ * read on mount; change `model` or `dtype` by remounting (a `key`).
+ */
+export function useDecider(options = {}) {
+    const [state, setState] = useState({ decider: null, status: "loading", progress: null, error: null });
+    useEffect(() => {
+        let alive = true, made;
+        const files = new Map();
+        createWorkerDecider({
+            ...options,
+            onProgress: ({ file, loaded, total }) => {
+                files.set(file, [loaded, total]);
+                let l = 0, t = 0;
+                for (const [a, b] of files.values()) {
+                    l += a;
+                    t += b;
+                }
+                if (alive)
+                    setState((s) => ({ ...s, progress: { loaded: l, total: t } }));
+            },
+        }).then((d) => {
+            made = d;
+            if (alive)
+                setState((s) => ({ ...s, decider: d, status: "ready" }));
+            else
+                d.terminate();
+        }, (e) => alive && setState((s) => ({ ...s, status: "error", error: e instanceof Error ? e : new Error(String(e)) })));
+        return () => { alive = false; made?.terminate(); };
+        // Options are read once; see the JSDoc.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return state;
+}
+export function useDecision(decider, text, using, { minConfidence, debounceMs = 150 } = {}) {
+    const [state, setState] = useState({ decision: null, pending: false, error: null });
+    useEffect(() => {
+        if (!decider || !using || !text.trim()) {
+            setState({ decision: null, pending: false, error: null });
+            return;
+        }
+        let current = true;
+        setState((s) => ({ ...s, pending: true }));
+        const timer = setTimeout(() => {
+            decider.decide(text, using, { minConfidence }).then((decision) => current && setState({ decision, pending: false, error: null }), (e) => current && setState({ decision: null, pending: false, error: e instanceof Error ? e : new Error(String(e)) }));
+        }, debounceMs);
+        return () => { current = false; clearTimeout(timer); };
+    }, [decider, text, using, minConfidence, debounceMs]);
+    return state;
+}