decidekit 0.0.0-stage → 0.1.0

package/dist/switch.d.ts

@@ -0,0 +1,103 @@
+import { type Trainable } from "./fallback.ts";
+import type { Choices, Decision, Head } from "./index.ts";
+type Json = string | number | boolean | null | readonly Json[] | {
+    readonly [key: string]: Json;
+};
+type Question = {
+    readonly type: "bool";
+    readonly instructions: string;
+    readonly criteria: {
+        readonly true: string;
+        readonly false: string;
+    };
+} | {
+    readonly type: "choice";
+    readonly instructions: string;
+    readonly criteria: Readonly<Record<string, string>>;
+} | {
+    readonly type: "score";
+    readonly instructions: string;
+    readonly criteria: readonly string[];
+};
+type Answer = {
+    readonly type: "bool";
+    readonly probability: number;
+} | {
+    readonly type: "choice";
+    readonly choice: string;
+    readonly probabilities: Readonly<Record<string, number>>;
+    readonly confidence: number;
+} | {
+    readonly type: "score";
+    readonly score: number;
+    readonly confidence: number;
+};
+/** switch's decision request: the state the model reads and the questions, by id. */
+export interface SwitchRequest {
+    readonly decisionState: {
+        readonly [key: string]: Json;
+    };
+    readonly decisionImages?: readonly unknown[];
+    readonly decisionQuestions: Readonly<Record<string, Question>>;
+}
+/** switch's decision result, with the fields switch reads. */
+export interface SwitchResult {
+    readonly decisionAnswers: Readonly<Record<string, Answer>>;
+    readonly decisionUsage?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        totalTokens: number;
+        cost: {
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+            total: number;
+        };
+    };
+    readonly api: string;
+    readonly provider: string;
+    readonly model: string;
+    readonly stopReason: "stop" | "error" | "aborted";
+    readonly errorMessage?: string;
+    readonly timestamp: number;
+    readonly tooLong: boolean;
+    readonly milliseconds: number;
+}
+/** switch's `Decider`. */
+export interface SwitchDecider {
+    readonly model: string;
+    readonly window: number;
+    readonly charsPerToken: number;
+    decide(request: SwitchRequest): Promise<SwitchResult>;
+}
+type Local = Trainable & {
+    model: string;
+    decide<const L extends string>(text: string, using: Choices<L>): Promise<Decision<L>>;
+};
+export interface SwitchOptions {
+    /** Trained heads for questions that repeat, by question id. Questions without one are decided zero-shot. */
+    heads?: Readonly<Record<string, Head>>;
+    /**
+     * A stronger decider to ask when decidekit isn't sure, such as Jev through switch's pi-ai decider. Its answers to
+     * choice questions train a head for that question, so a question that repeats asks it less and less (see `withFallback`).
+     */
+    teacher?: SwitchDecider;
+    /** Below this confidence, choice questions go to `teacher`. Default 0.9. */
+    minConfidence?: number;
+    /**
+     * What decidekit reads for a question. Its encoder reads about 256 tokens and drops the rest, so a long state or long
+     * instructions can push out what matters; pick it here, such as the target of a search. Default: `textOf`.
+     */
+    text?: (state: SwitchRequest["decisionState"], question: Question, id: string) => string;
+}
+/** The text decidekit reads for a question: its instructions, then the state as plain lines rather than JSON. */
+export declare function textOf(instructions: string, state: Json): string;
+/**
+ * Wraps a decidekit decider as a switch decider. Choice, bool and score questions become decidekit decisions over the
+ * question's criteria; images are ignored. Every call is local, so usage costs nothing.
+ */
+export declare function switchDecider(local: Local, options?: SwitchOptions): SwitchDecider;
+export type { Question as SwitchQuestion, Answer as SwitchAnswer };

package/dist/switch.js

@@ -0,0 +1,94 @@
+// decidekit as a decision model for switch (github.com/osolmaz/switch), a harness that runs a decision model through a
+// task by asking it typed questions. The types below copy the parts of switch's `Decider` that this needs, so decidekit
+// doesn't depend on switch: pass the result wherever switch takes a decider.
+import { withFallback } from "./fallback.js";
+/** The text decidekit reads for a question: its instructions, then the state as plain lines rather than JSON. */
+export function textOf(instructions, state) {
+    const lines = [];
+    const walk = (v, key) => {
+        if (v === null || typeof v !== "object")
+            lines.push(key ? `${key}: ${v}` : String(v));
+        else if (Array.isArray(v) && v.every((x) => x === null || typeof x !== "object"))
+            lines.push(key ? `${key}: ${v.join(", ")}` : v.join(", "));
+        else
+            for (const [k, x] of Object.entries(v))
+                walk(x, Array.isArray(v) ? key : k);
+    };
+    walk(state, "");
+    return [instructions, ...lines].filter(Boolean).join("\n");
+}
+/**
+ * Wraps a decidekit decider as a switch decider. Choice, bool and score questions become decidekit decisions over the
+ * question's criteria; images are ignored. Every call is local, so usage costs nothing.
+ */
+export function switchDecider(local, options = {}) {
+    const { heads = {}, teacher, minConfidence = 0.9, text: textFor = (state, q) => textOf(q.instructions, state) } = options;
+    // One router per repeating choice question, keyed by its instructions and options.
+    const routers = new Map();
+    // The state each pending text came from, so the teacher reads the same request.
+    const states = new Map();
+    function routerFor(id, q) {
+        const key = JSON.stringify([q.instructions, q.criteria]);
+        let r = routers.get(key);
+        if (!r) {
+            r = withFallback(local, heads[id] ?? q.criteria, {
+                minConfidence,
+                retrainEvery: 8,
+                ask: async (text) => {
+                    const res = await teacher.decide({ decisionState: states.get(text), decisionQuestions: { [id]: q } });
+                    const a = res.decisionAnswers[id];
+                    return a?.type === "choice" ? a.choice : null;
+                },
+            });
+            routers.set(key, r);
+        }
+        return r;
+    }
+    async function answer(id, q, state) {
+        const text = textFor(state, q, id);
+        if (q.type === "choice") {
+            const keys = Object.keys(q.criteria);
+            // decidekit compares two or more options; a single one is the answer.
+            if (keys.length === 1)
+                return { type: "choice", choice: keys[0], probabilities: { [keys[0]]: 1 }, confidence: 1 };
+            if (teacher)
+                states.set(text, state);
+            const d = teacher ? await routerFor(id, q)(text).finally(() => states.delete(text)) : await local.decide(text, heads[id] ?? q.criteria);
+            const choice = d.choice ?? Object.entries(d.probabilities).sort((a, b) => b[1] - a[1])[0][0];
+            return { type: "choice", choice, probabilities: d.probabilities, confidence: d.confidence };
+        }
+        if (q.type === "bool") {
+            const d = await local.decide(text, heads[id] ?? { true: q.criteria.true, false: q.criteria.false });
+            return { type: "bool", probability: d.probabilities.true };
+        }
+        const levels = Object.fromEntries(q.criteria.map((c, i) => [String(i), c]));
+        const d = await local.decide(text, heads[id] ?? levels);
+        return { type: "score", score: Number(d.choice), confidence: d.confidence };
+    }
+    return {
+        model: `decidekit/${local.model}`,
+        // The encoder reads about 256 tokens and cuts the rest, so a long state still fits; tell switch the window is big
+        // so it doesn't trim the choices to fit.
+        window: 1_000_000,
+        charsPerToken: 4,
+        async decide(request) {
+            const started = performance.now();
+            const base = { api: "decidekit", provider: "decidekit", model: `decidekit/${local.model}`, timestamp: Date.now(), tooLong: false };
+            try {
+                const entries = await Promise.all(Object.entries(request.decisionQuestions).map(async ([id, q]) => [id, await answer(id, q, request.decisionState)]));
+                const input = Math.round(JSON.stringify(request.decisionState).length / 4);
+                const zero = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+                return {
+                    ...base,
+                    decisionAnswers: Object.fromEntries(entries),
+                    decisionUsage: { input, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: input, cost: zero },
+                    stopReason: "stop",
+                    milliseconds: performance.now() - started,
+                };
+            }
+            catch (e) {
+                return { ...base, decisionAnswers: {}, stopReason: "error", errorMessage: e instanceof Error ? e.message : String(e), milliseconds: performance.now() - started };
+            }
+        },
+    };
+}

package/dist/typesafe.d.ts

@@ -0,0 +1,36 @@
+import type { Choices, Decision, Head } from "./index.ts";
+/** What this layer needs from a decider: `createDecider()` and `createWorkerDecider()` both fit. */
+export interface Decides {
+    decide<const L extends string>(text: string, using: Choices<L>): Promise<Decision<L>>;
+}
+export interface ChoiceQuestion<L extends string = string> {
+    type: "choice";
+    /** Kept for compatibility and ignored: decidekit compares the state with the options, it doesn't read a question. */
+    instructions: string;
+    /** Option names to descriptions (`null` for none), as in TypeSafe's API, or a trained head. */
+    criteria: Readonly<Record<L, string | null>> | Head<L>;
+}
+export declare function choice<const L extends string>(instructions: string, criteria: Readonly<Record<L, string | null>> | Head<L>): ChoiceQuestion<L>;
+export declare const noul: (instructions: string) => never;
+export declare const score: (instructions: string, levels: unknown) => never;
+export interface ChoiceAnswer<L extends string> {
+    type: "choice";
+    choice: L;
+    /** TypeSafe's measure: 1 with all probability on one option, 0 when evenly spread, `(n * top - 1) / (n - 1)`. */
+    confidence: number;
+    probabilities: Record<L, number>;
+}
+/**
+ * Wraps a decider in TypeSafe's client shape. `confidence` follows TypeSafe's formula, so it reads lower than
+ * `decide()`'s: 0.61 on the top of three options is 0.42 here. `Math.max(...probabilities)` is the calibrated chance of
+ * being right. Thresholds carry over from neither model to the other.
+ */
+export declare function typesafeClient(decider: Decides): {
+    systemOne<const Q extends Record<string, ChoiceQuestion<string>>>({ state, questions }: {
+        state: string | Readonly<Record<string, unknown>>;
+        questions: Q;
+    }): Promise<{
+        model: string;
+        answers: { [K in keyof Q]: Q[K] extends ChoiceQuestion<infer L> ? ChoiceAnswer<L> : never; };
+    }>;
+};

package/dist/typesafe.js

@@ -0,0 +1,47 @@
+export function choice(instructions, criteria) {
+    return { type: "choice", instructions, criteria };
+}
+const unsupported = (type) => () => {
+    throw new Error(`decidekit: ${type} questions aren't supported locally, only choice. Ask a yes/no as a choice between two described options.`);
+};
+export const noul = unsupported("noul");
+export const score = unsupported("score");
+/** A string, or an object whose string values are joined: braces and keys only add noise for an encoder. */
+function stateText(state) {
+    if (typeof state === "string")
+        return state;
+    return Object.values(state).map((v) => {
+        if (typeof v === "string")
+            return v;
+        if (typeof v === "number" || typeof v === "boolean")
+            return String(v);
+        throw new Error("decidekit: state values must be text, numbers or booleans");
+    }).join("\n");
+}
+function options(criteria) {
+    if ("weights" in criteria)
+        return criteria;
+    const entries = Object.entries(criteria);
+    if (entries.every(([, d]) => d === null))
+        return entries.map(([l]) => l);
+    // Same as a plain label: an option with no description is compared by its readable name.
+    return Object.fromEntries(entries.map(([l, d]) => [l, d ?? l.replace(/[_-]+/g, " ")]));
+}
+/**
+ * Wraps a decider in TypeSafe's client shape. `confidence` follows TypeSafe's formula, so it reads lower than
+ * `decide()`'s: 0.61 on the top of three options is 0.42 here. `Math.max(...probabilities)` is the calibrated chance of
+ * being right. Thresholds carry over from neither model to the other.
+ */
+export function typesafeClient(decider) {
+    return {
+        async systemOne({ state, questions }) {
+            const text = stateText(state), answers = {};
+            for (const [id, q] of Object.entries(questions)) {
+                const { choice, confidence, probabilities } = await decider.decide(text, options(q.criteria));
+                const n = Object.keys(probabilities).length;
+                answers[id] = { type: "choice", choice, confidence: Math.max(0, (n * confidence - 1) / (n - 1)), probabilities };
+            }
+            return { model: "decidekit", answers: answers };
+        },
+    };
+}

package/dist/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/worker.js

@@ -0,0 +1,26 @@
+// Runs a decider off the main thread. The encoder's wasm work never gives the page a turn (measured: a 171 s freeze
+// while training in Chrome), so in a browser it belongs here.
+import { createDecider } from "./index.js";
+let decider;
+self.onmessage = async ({ data }) => {
+    try {
+        let value;
+        if (data.op === "init")
+            decider = await createDecider({ ...data.options, onProgress: (progress) => self.postMessage({ id: data.id, progress }) });
+        else if (!decider)
+            throw new Error("decider not initialised");
+        else if (data.op === "decideMany")
+            value = await decider.decideMany(data.args[0], data.args[1], data.args[2] ?? {});
+        else if (data.op === "decide")
+            value = await decider.decide(data.args[0], data.args[1], data.args[2] ?? {});
+        else
+            value = await decider.train(data.args[0], {
+                ...data.args[1],
+                onEpoch: (epoch, accuracy) => self.postMessage({ id: data.id, progress: { epoch, accuracy } }),
+            });
+        self.postMessage({ id: data.id, value });
+    }
+    catch (e) {
+        self.postMessage({ id: data.id, error: e instanceof Error ? e.message : String(e) });
+    }
+};

package/package.json

@@ -1,6 +1,93 @@
-{
-  "name": "decidekit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "decidekit",
+  "version": "0.1.0",
+  "description": "A System One model in the browser: typed, calibrated text decisions on the user's device. Learns from an LLM when it isn't sure.",
+  "license": "MIT",
+  "repository": "github:debuffjp/decidekit",
+  "keywords": [
+    "decision model",
+    "system one",
+    "classification",
+    "intent",
+    "zero-shot",
+    "calibration",
+    "llm",
+    "embeddings",
+    "browser",
+    "typescript",
+    "text classification",
+    "transformers.js",
+    "on-device",
+    "llm fallback"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./switch": {
+      "types": "./dist/switch.d.ts",
+      "default": "./dist/switch.js"
+    },
+    "./typesafe": {
+      "types": "./dist/typesafe.d.ts",
+      "default": "./dist/typesafe.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "eval": "node --experimental-strip-types eval/banking77.ts",
+    "bench": "esbuild src/worker.ts src/browser.ts --bundle --format=esm --platform=browser --outdir=bench --alias:onnxruntime-web/webgpu=onnxruntime-web/wasm && node bench/serve.mjs",
+    "playground": "node playground/build.mjs",
+    "heads": "node --experimental-strip-types heads/build.ts",
+    "bench:run": "node bench/run.mjs",
+    "eval:suite": "node --experimental-strip-types eval/suite.ts",
+    "eval:hill": "node --experimental-strip-types eval/hill.ts",
+    "test": "node --test --experimental-strip-types \"test/*.test.ts\"",
+    "lint:prose": "node scripts/lint-prose.mjs",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "4.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.15.3",
+    "@types/react": "19.3.0",
+    "esbuild": "0.25.10",
+    "playwright-core": "1.64.1",
+    "react": "19.3.1",
+    "spryte": "0.11.0",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "homepage": "https://debuff.jp/decidekit/",
+  "bugs": "https://github.com/debuffjp/decidekit/issues",
+  "bin": {
+    "decidekit": "./dist/cli.js"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}