decision-api 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kristoffer Hansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# decision-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One client for decision models: models that answer typed questions with calibrated probabilities instead of text. It speaks TypeSafe's Jev, Cloudflare's Clef and Clef-flash (Workers AI), OpenAI's gpt-6-luna and the decision models on OpenRouter (such as `microsoft/microsoft-decision-1`), and returns the same answer shape from all of them. It depends only on `zod`.
+
+```sh
+npm install decision-api
+```
+
+```ts
+import { createDecisionApi } from 'decision-api'
+
+const decide = createDecisionApi({
+	keys: {
+		typesafe: '…',
+		cloudflare: { apiToken: '…', accountId: '…' },
+		openai: '…',
+		openrouter: '…' // every OpenRouter model, named by its slug
+	},
+	defaultModel: 'jev',
+	registerUsage: (usage, context: { customerId: string }) => {
+		// usage: model, provider, inputTokens, outputTokens, costUsd, latencyMs
+	},
+	onError: (error, context) => console.warn(error.kind, error.message)
+})
+
+const answers = await decide(
+	{
+		state: { message: 'I was charged twice' },
+		questions: {
+			refund: { type: 'noul', instructions: 'Does the customer want money back?' },
+			team: {
+				type: 'choice',
+				instructions: 'Which team handles this?',
+				criteria: { billing: 'Payments and refunds', other: 'Anything else' }
+			}
+		},
+		customerId: 'c_1'
+	},
+	'gpt-6-luna' // optional when defaultModel is set
+)
+
+answers?.refund.noul // number
+answers?.team.choice // 'billing' | 'other'
+```
+
+TypeScript enforces the setup:
+
+- **Keys select models.** Only models whose provider key you passed can be named, as `defaultModel` or per call. A key typed `string | undefined` (a raw `process.env` read) does not count; narrow it first. One `openrouter` key opens every OpenRouter model at once; a new one is added as its slug and price in `DECISION_MODELS`.
+- **The model is optional only with a default.** Without `defaultModel`, every call must name one.
+- **Usage context is required when typed.** The type of `registerUsage`'s second parameter is required on every call and passed back to `registerUsage` and `onError`.
+
+A call answers `null` instead of throwing, and `onError` says why: `timeout`, `aborted` (the call's own signal), `unauthorized` (401/403, a bad key), `out-of-credits` (402), `rate-limited` (429 after the retry), `request-failed` (any other status, or a transport error), `state-too-large`, `unreadable-response` or `answer-mismatch`. Every error carries its `model` and `provider`, and `status` when the provider answered; a throwing `registerUsage` reports `usage-failed` without failing the call. Retryable statuses (429 and 5xx) are retried once, after the provider's `Retry-After` when it asks for 2 s or less, and not at all when it asks for more. `fetch` replaces the transport, for example to route calls through your own rate limits, and `defaultSignal` supplies the signal for calls that pass none. A call with no questions answers `{}` without a request. The one throw is a call with no model and no `defaultModel`, which TypeScript already rejects.
+
+## Benchmark
+
+`bun run bench` asks every model with a key the fixed questions in [`bench/cases.ts`](bench/cases.ts) and writes `.artifacts/bench/report.html`: accuracy against the expected answers, probability on the right answer, latency p50/p90 and cost per model, every answer side by side, and a closing leaderboard that scores each model out of 100 (one point per right answer, a failed call scores zero). Keys come from the environment or `.env`: copy [`.env.example`](.env.example) to `.env` and fill in the providers you have; `--runs=5` and `--models=jev,clef` narrow or widen a run.
+
+Results from 2026-10-10 (12 cases, 21 questions, 3 runs per case):
+
+| # | Model | Score | Points | p(correct) | Latency p50 / p90 | Cost / 1k calls |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | `jev` | 100 | 21 / 21 | 96% | 262 / 292 ms | $0.017 |
+| 2 | `clef` | 100 | 21 / 21 | 94% | 292 / 550 ms | $0.067 |
+| 3 | `microsoft/microsoft-decision-1` | 95.2 | 20 / 21 | 95% | 354 / 819 ms | $0.005 |
+| 4 | `gpt-6-luna` | 95.2 | 20 / 21 | 94% | 149 / 264 ms | $0.029 |
+| 5 | `clef-flash` | 95.2 | 20 / 21 | 85% | 227 / 662 ms | $0.025 |
+
+## Releasing
+
+Squash PRs with conventional titles (`fix:`, `feat:`, or `feat!:`). Release Please keeps the version and changelog in a release PR; merge that PR to publish with release notes and npm provenance. See [release and recovery instructions](docs/releasing.md).
+
+## License
+
+[MIT](LICENSE).

package/dist/create-decision-api.d.ts

@@ -0,0 +1,94 @@
+import { type DecisionModel, type DecisionProvider, type DecisionProviderKeys, type ModelsFor } from './models.ts';
+import { type DecisionAnswers, type DecisionQuestion } from './questions.ts';
+/**
+ * Jev answers `400 max_tokens_exceeded` past roughly 32.5k input tokens (96k
+ * chars passed, 128k did not). A state over this is refused before it leaves
+ * the process; keep well under the wall, since tokenization varies. Clef takes
+ * 64k tokens but silently truncates long state, so the same guard keeps it
+ * from judging half a corpus.
+ */
+export declare const DECISION_MAX_STATE_CHARS = 90000;
+/** What one answered call cost; `costUsd` is priced from `DECISION_MODELS`. */
+export type DecisionUsage<Model extends DecisionModel = DecisionModel> = {
+    model: Model;
+    provider: DecisionProvider;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+    latencyMs: number;
+};
+export type DecisionErrorKind = 'state-too-large'
+/** No answer within `timeoutMs`. */
+ | 'timeout'
+/** The call's own signal (or `defaultSignal`) aborted it. */
+ | 'aborted'
+/** 401 or 403: the provider rejected the key. Retrying will not help. */
+ | 'unauthorized'
+/** 402: the provider's account is out of credits. Retrying will not help. */
+ | 'out-of-credits'
+/** 429 that outlasted the retry, or asked to wait longer than a call can. */
+ | 'rate-limited'
+/** Any other refused request (see `status`), or a transport error (no `status`). */
+ | 'request-failed' | 'unreadable-response' | 'answer-mismatch' | 'usage-failed';
+export declare class DecisionError extends Error {
+    readonly kind: DecisionErrorKind;
+    readonly model: DecisionModel;
+    /** The HTTP status, when the provider answered. */
+    readonly status?: number | undefined;
+    readonly provider: DecisionProvider;
+    constructor(kind: DecisionErrorKind, model: DecisionModel, message: string, 
+    /** The HTTP status, when the provider answered. */
+    status?: number | undefined);
+}
+/** Sends one request. Replace it to route calls through your own budget or proxy. */
+export type DecisionFetch = (request: {
+    url: string;
+    init: RequestInit;
+}, info: {
+    model: DecisionModel;
+    provider: DecisionProvider;
+    attempt: number;
+    /** The same signal `init` carries: the call's own, plus its timeout. */
+    signal: AbortSignal;
+}) => Promise<Response>;
+type DecisionCall<Q extends Record<string, DecisionQuestion>> = {
+    /** A string, or named fields - name them when the state has several parts. */
+    state: unknown;
+    questions: Q;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+type DecisionApiOptions<Keys extends DecisionProviderKeys, Default, Context> = {
+    keys: Keys;
+    /** Lets a call leave out its model. */
+    defaultModel?: Default;
+    /**
+     * Called after every answered call. Whatever its second parameter is typed
+     * as becomes required on every call, so usage can be attributed.
+     */
+    registerUsage?: (usage: DecisionUsage<ModelsFor<Keys>>, context: Context) => unknown;
+    /** Every reason a call answered `null`. */
+    onError?: (error: DecisionError, context: Context) => void;
+    /** The signal of a call that passes none. */
+    defaultSignal?: () => AbortSignal | undefined;
+    fetch?: DecisionFetch;
+    timeoutMs?: number;
+    maxStateChars?: number;
+};
+/**
+ * Ask one or more independent judgments about the same state.
+ *
+ * **Send every independent question in ONE call**: questions are evaluated
+ * together, so extra ones are close to free, and latency tracks the size of
+ * `state`, not the number of questions.
+ *
+ * **Answers `null` rather than throwing** - on a timeout, an abort, a
+ * transport error, a rejected request or an answer that does not match its
+ * question; `onError` says which. The right fallback belongs to the caller: a
+ * tagging job treats `null` as "no tags this time", a policy guard as "refuse".
+ * It throws only when there is no model at all - a setup bug TypeScript
+ * already rejects, which a silent `null` would hide.
+ */
+export type DecisionApi<Model extends DecisionModel, Default, Context> = <Q extends Record<string, DecisionQuestion>>(input: DecisionCall<Q> & Context, ...model: [Default] extends [Model] ? [model?: Model] : [model: Model]) => Promise<DecisionAnswers<Q> | null>;
+export declare function createDecisionApi<const Keys extends DecisionProviderKeys, Default extends ModelsFor<Keys> | undefined = undefined, Context extends object = Record<never, never>>(options: DecisionApiOptions<Keys, Default, Context>): DecisionApi<ModelsFor<Keys>, Default, Context>;
+export {};

package/dist/create-decision-api.js

@@ -0,0 +1,219 @@
+import { buildDecisionRequest, DECISION_MODELS, readDecisionResponse } from "./models.js";
+import { matchesQuestion } from "./questions.js";
+/**
+ * Jev answers `400 max_tokens_exceeded` past roughly 32.5k input tokens (96k
+ * chars passed, 128k did not). A state over this is refused before it leaves
+ * the process; keep well under the wall, since tokenization varies. Clef takes
+ * 64k tokens but silently truncates long state, so the same guard keeps it
+ * from judging half a corpus.
+ */
+export const DECISION_MAX_STATE_CHARS = 90_000;
+/**
+ * A generous ceiling rather than a target (Jev's p90 is ~280 ms for ten
+ * questions): past it the caller is better served by its own fallback.
+ */
+const DEFAULT_TIMEOUT_MS = 4_000;
+/** Retried once: the providers' own guidance for these is to back off and retry. */
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 529]);
+const RETRY_DELAY_MS = 250;
+/**
+ * A provider asking for a longer pause (`Retry-After`) will not be ready within
+ * this call's budget: failing now beats paying for a doomed retry.
+ */
+const MAX_RETRY_DELAY_MS = 2_000;
+export class DecisionError extends Error {
+    kind;
+    model;
+    status;
+    provider;
+    constructor(kind, model, message, 
+    /** The HTTP status, when the provider answered. */
+    status) {
+        super(message);
+        this.kind = kind;
+        this.model = model;
+        this.status = status;
+        this.name = 'DecisionError';
+        this.provider = DECISION_MODELS[model].provider;
+    }
+}
+/** The kind a refused response maps to; anything unlisted is `request-failed`. */
+const KIND_BY_STATUS = {
+    401: 'unauthorized',
+    402: 'out-of-credits',
+    403: 'unauthorized',
+    429: 'rate-limited'
+};
+export function createDecisionApi(options) {
+    const send = options.fetch ?? ((request) => fetch(request.url, request.init));
+    const maxStateChars = options.maxStateChars ?? DECISION_MAX_STATE_CHARS;
+    return async (input, ...[requestedModel]) => {
+        const { state, questions, signal, timeoutMs, ...rest } = input;
+        const context = rest;
+        const model = requestedModel ?? options.defaultModel;
+        if (!model)
+            throw new Error('No model given and no defaultModel set');
+        const report = (error) => {
+            options.onError?.(error, context);
+            return null;
+        };
+        const fail = (kind, message) => report(new DecisionError(kind, model, message));
+        if (Object.keys(questions).length === 0) {
+            return {};
+        }
+        const stateText = typeof state === 'string' ? state : JSON.stringify(state);
+        const stateChars = stateText.length;
+        if (stateChars > maxStateChars) {
+            return fail('state-too-large', `State is ${stateChars} chars, over ${maxStateChars}`);
+        }
+        const startedAt = Date.now();
+        let text;
+        try {
+            text = await postWithRetry({
+                send,
+                model,
+                request: buildDecisionRequest(model, { state, questions }, options.keys),
+                signal: signal ?? options.defaultSignal?.(),
+                timeoutMs: timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+            });
+        }
+        catch (error) {
+            if (error instanceof DecisionError)
+                return report(error);
+            return fail('request-failed', messageOf(error));
+        }
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch (error) {
+            return fail('unreadable-response', messageOf(error));
+        }
+        const parsed = readDecisionResponse(model, json);
+        if (!parsed.success) {
+            return fail('unreadable-response', parsed.error.issues[0]?.message ?? 'unknown');
+        }
+        const { usage, answers } = parsed.data;
+        reportUsage({
+            model,
+            provider: DECISION_MODELS[model].provider,
+            inputTokens: usage.input_tokens,
+            outputTokens: usage.output_tokens,
+            costUsd: (usage.input_tokens * DECISION_MODELS[model].inputUsdPerMTok) /
+                1_000_000,
+            latencyMs: Date.now() - startedAt
+        }, context);
+        for (const [key, question] of Object.entries(questions)) {
+            if (!matchesQuestion(question, answers[key])) {
+                return fail('answer-mismatch', `Answer to "${key}" does not fit it`);
+            }
+        }
+        // Every requested key, kind and option set was validated above.
+        return answers;
+    };
+    /**
+     * Only a call that reached the provider is reported - a state over the
+     * wall, a timeout or an unreadable body reports nothing, so a 0 ms row can
+     * never flatter a latency percentile. A failing hook never fails the call.
+     */
+    function reportUsage(usage, context) {
+        const { registerUsage } = options;
+        if (!registerUsage)
+            return;
+        if (usage.inputTokens <= 0 && usage.outputTokens <= 0)
+            return;
+        // One path for a hook that throws and one that rejects.
+        Promise.resolve()
+            .then(() => registerUsage(usage, context))
+            .catch((error) => {
+            const failure = new DecisionError('usage-failed', usage.model, messageOf(error));
+            options.onError?.(failure, context);
+        });
+    }
+}
+/** The body of the first OK response, read under the same timeout as the request. */
+async function postWithRetry(input) {
+    const provider = DECISION_MODELS[input.model].provider;
+    const failure = (kind, message) => new DecisionError(kind, input.model, message);
+    for (let attempt = 0;; attempt++) {
+        if (input.signal?.aborted)
+            throw failure('aborted', 'Aborted by the caller');
+        // A fresh timeout per attempt, so a retry gets its own budget.
+        const timeout = AbortSignal.timeout(input.timeoutMs);
+        const { signal, release } = linkSignals(timeout, input.signal);
+        try {
+            const response = await input.send({
+                url: input.request.url,
+                init: {
+                    method: 'POST',
+                    headers: input.request.headers,
+                    body: input.request.body,
+                    // React Native's fetch types declare an AbortSignal of their own.
+                    signal: signal
+                }
+            }, { model: input.model, provider, attempt, signal });
+            if (response.ok)
+                return await response.text();
+            const delayMs = retryDelayMs(response);
+            if (attempt > 0 ||
+                !RETRYABLE_STATUSES.has(response.status) ||
+                delayMs > MAX_RETRY_DELAY_MS) {
+                const body = (await response.text()).slice(0, 200);
+                throw new DecisionError(KIND_BY_STATUS[response.status] ?? 'request-failed', input.model, `${input.model} ${response.status}: ${body}`, response.status);
+            }
+            // An unread body holds its connection until garbage collection.
+            await response.body?.cancel().catch(() => { });
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+        catch (error) {
+            if (error instanceof DecisionError)
+                throw error;
+            if (input.signal?.aborted)
+                throw failure('aborted', messageOf(error));
+            if (timeout.aborted) {
+                throw failure('timeout', `No answer within ${input.timeoutMs} ms`);
+            }
+            throw error;
+        }
+        finally {
+            release();
+        }
+    }
+}
+/** The pause a response asks for, in seconds or as a date; our own without one. */
+function retryDelayMs(response) {
+    const header = response.headers.get('retry-after')?.trim();
+    if (!header)
+        return RETRY_DELAY_MS;
+    const seconds = Number(header);
+    const ms = Number.isFinite(seconds)
+        ? seconds * 1000
+        : Date.parse(header) - Date.now();
+    return Number.isNaN(ms) ? RETRY_DELAY_MS : Math.max(0, ms);
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The timeout plus the caller's signal, whichever fires first. Combined by hand
+ * rather than with `AbortSignal.any`, which older DOM libs (React Native's
+ * among them) do not declare. `release` unhooks the caller's signal, which may
+ * outlive every call made with it.
+ */
+function linkSignals(timeout, signal) {
+    if (!signal)
+        return { signal: timeout, release: () => { } };
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    if (timeout.aborted || signal.aborted)
+        abort();
+    timeout.addEventListener('abort', abort, { once: true });
+    signal.addEventListener('abort', abort, { once: true });
+    return {
+        signal: controller.signal,
+        release: () => {
+            timeout.removeEventListener('abort', abort);
+            signal.removeEventListener('abort', abort);
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createDecisionApi, DECISION_MAX_STATE_CHARS, type DecisionApi, DecisionError, type DecisionErrorKind, type DecisionFetch, type DecisionUsage } from './create-decision-api.ts';
+export { DECISION_MODELS, type DecisionModel, type DecisionProvider, type DecisionProviderKeys, type ModelsFor } from './models.ts';
+export type { DecisionAnswers, DecisionChoice, DecisionNoul, DecisionQuestion, DecisionScore } from './questions.ts';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createDecisionApi, DECISION_MAX_STATE_CHARS, DecisionError } from "./create-decision-api.js";
+export { DECISION_MODELS } from "./models.js";

package/dist/models.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import { type DecisionQuestion } from './questions.ts';
+/** The credentials each provider needs; pass only the providers you use. */
+export type DecisionProviderKeys = {
+    typesafe?: string;
+    cloudflare?: {
+        apiToken: string;
+        accountId: string;
+    };
+    openai?: string;
+    /** One key for every model OpenRouter hosts (the `vendor/model` names). */
+    openrouter?: string;
+};
+export type DecisionProvider = keyof DecisionProviderKeys;
+/**
+ * USD per million input tokens; output is free on every provider, because an
+ * answer is a few tokens of enum rather than generated prose. Jev's rate is
+ * from TypeSafe's launch material (the docs publish no price sheet); the rest
+ * are the providers' list prices (2026-10).
+ */
+export declare const DECISION_MODELS: {
+    readonly jev: {
+        readonly provider: "typesafe";
+        readonly inputUsdPerMTok: 0.042;
+    };
+    readonly clef: {
+        readonly provider: "cloudflare";
+        readonly inputUsdPerMTok: 0.24;
+    };
+    readonly 'clef-flash': {
+        readonly provider: "cloudflare";
+        readonly inputUsdPerMTok: 0.09;
+    };
+    readonly 'gpt-6-luna': {
+        readonly provider: "openai";
+        readonly inputUsdPerMTok: 0.1;
+    };
+    readonly 'microsoft/microsoft-decision-1': {
+        readonly provider: "openrouter";
+        readonly inputUsdPerMTok: 0.042;
+    };
+};
+export type DecisionModel = keyof typeof DECISION_MODELS;
+type ModelsOf<Provider> = {
+    [Model in DecisionModel]: (typeof DECISION_MODELS)[Model]['provider'] extends Provider ? Model : never;
+}[DecisionModel];
+/** The models a set of keys can call: a provider counts only when its key is surely there. */
+export type ModelsFor<Keys extends DecisionProviderKeys> = ModelsOf<{
+    [Provider in keyof Keys]-?: undefined extends Keys[Provider] ? never : Provider;
+}[keyof Keys]>;
+type RequestInput = {
+    state: unknown;
+    questions: Record<string, DecisionQuestion>;
+};
+/** One POST: where it goes, and the headers and body it carries. */
+export declare function buildDecisionRequest(model: DecisionModel, input: RequestInput, keys: DecisionProviderKeys): {
+    url: string;
+    headers: {
+        authorization: string;
+        'content-type': string;
+    };
+    body: string;
+};
+/** The provider's response read into the shared shape, unvalidated against the questions. */
+export declare function readDecisionResponse(model: DecisionModel, json: unknown): z.ZodSafeParseResult<{
+    answers: Record<string, {
+        type: "noul";
+        noul: number;
+    } | {
+        type: "choice";
+        choice: string;
+        confidence: number;
+        probabilities: Record<string, number>;
+    } | {
+        type: "score";
+        score: number;
+        confidence: number;
+        probabilities: Record<string, number>;
+    }>;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+}>;
+export {};

package/dist/models.js

@@ -0,0 +1,176 @@
+// Every decision model, the provider that serves it, what it costs, and how
+// that provider's wire format maps onto the shared question shapes
+// (`questions.ts`).
+import { z } from 'zod';
+import { DecisionResponseSchema } from "./questions.js";
+/**
+ * USD per million input tokens; output is free on every provider, because an
+ * answer is a few tokens of enum rather than generated prose. Jev's rate is
+ * from TypeSafe's launch material (the docs publish no price sheet); the rest
+ * are the providers' list prices (2026-10).
+ */
+export const DECISION_MODELS = {
+    jev: { provider: 'typesafe', inputUsdPerMTok: 0.042 },
+    clef: { provider: 'cloudflare', inputUsdPerMTok: 0.24 },
+    'clef-flash': { provider: 'cloudflare', inputUsdPerMTok: 0.09 },
+    'gpt-6-luna': { provider: 'openai', inputUsdPerMTok: 0.1 },
+    // OpenRouter models are named by their OpenRouter slug, so adding one is
+    // one line here: https://openrouter.ai/rankings/decisions
+    'microsoft/microsoft-decision-1': {
+        provider: 'openrouter',
+        inputUsdPerMTok: 0.042
+    }
+};
+/** One POST: where it goes, and the headers and body it carries. */
+export function buildDecisionRequest(model, input, keys) {
+    const provider = DECISION_MODELS[model].provider;
+    const headers = (token) => {
+        if (!token)
+            throw new Error(`No ${provider} key for ${model}`);
+        return {
+            authorization: `Bearer ${token}`,
+            'content-type': 'application/json'
+        };
+    };
+    if (provider === 'typesafe') {
+        return {
+            url: 'https://api.typesafe.ai/v1/systemone',
+            headers: headers(keys.typesafe),
+            body: JSON.stringify({ ...input, model: 'jev-latest' })
+        };
+    }
+    if (provider === 'cloudflare') {
+        return {
+            url: `https://api.cloudflare.com/client/v4/accounts/${keys.cloudflare?.accountId}/ai/run/@cf/cloudflare/${model}`,
+            headers: headers(keys.cloudflare?.apiToken),
+            body: JSON.stringify({ ...input, model })
+        };
+    }
+    if (provider === 'openrouter') {
+        // https://openrouter.ai/docs/api/api-reference/alphadecisions/submit-a-decisions-request
+        return {
+            url: 'https://openrouter.ai/api/alpha/decisions',
+            headers: headers(keys.openrouter),
+            body: JSON.stringify({ ...input, model })
+        };
+    }
+    return {
+        url: 'https://api.openai.com/v1/decisions',
+        headers: headers(keys.openai),
+        body: JSON.stringify(toOpenAiRequest(model, input))
+    };
+}
+/** The provider's response read into the shared shape, unvalidated against the questions. */
+export function readDecisionResponse(model, json) {
+    return responseSchemas[DECISION_MODELS[model].provider].safeParse(json);
+}
+// ───────────────────────────── OpenAI Decisions ─────────────────────────────
+// https://developers.openai.com/api/docs/guides/decisions - the same three
+// question kinds under other names: `predicate` for noul, choices and levels as
+// arrays of objects, answers as an array keyed by `name`.
+function toOpenAiQuestion(name, question) {
+    if (question.type === 'noul') {
+        // No criteria field on a predicate: the gloss rides in the instructions.
+        const gloss = question.criteria
+            ? `\nTrue means: ${question.criteria.true}\nFalse means: ${question.criteria.false}`
+            : '';
+        return {
+            type: 'predicate',
+            name,
+            instructions: `${question.instructions}${gloss}`
+        };
+    }
+    if (question.type === 'choice') {
+        return {
+            type: 'choice',
+            name,
+            instructions: question.instructions,
+            choices: Object.entries(question.criteria).map(([value, description]) => ({ value, description }))
+        };
+    }
+    return {
+        type: 'score',
+        name,
+        instructions: question.instructions,
+        levels: question.criteria.map((description, index) => ({
+            label: String(index),
+            description
+        }))
+    };
+}
+function toOpenAiRequest(model, input) {
+    return {
+        model,
+        input: typeof input.state === 'string'
+            ? input.state
+            : JSON.stringify(input.state),
+        questions: Object.entries(input.questions).map(([name, question]) => toOpenAiQuestion(name, question))
+    };
+}
+const OpenAiProbabilitiesSchema = z.array(z.object({
+    value: z.union([z.string(), z.number()]),
+    probability: z.number()
+}));
+const OpenAiResponseSchema = z.object({
+    answers: z.array(z.discriminatedUnion('type', [
+        z.object({
+            type: z.literal('predicate'),
+            name: z.string(),
+            probability: z.number()
+        }),
+        z.object({
+            type: z.literal(['choice', 'score']),
+            name: z.string(),
+            choice: z.string().optional(),
+            score: z.number().optional(),
+            confidence: z.number(),
+            probabilities: OpenAiProbabilitiesSchema
+        })
+    ])),
+    usage: z.object({ input_tokens: z.number(), output_tokens: z.number() })
+});
+function fromOpenAiResponse(response) {
+    const answers = response.answers.map((answer) => {
+        if (answer.type === 'predicate') {
+            return [answer.name, { type: 'noul', noul: answer.probability }];
+        }
+        // Score levels come back as numeric indices; the shared shape keys them as strings.
+        const probabilities = Object.fromEntries(answer.probabilities.map((option) => [
+            String(option.value),
+            option.probability
+        ]));
+        return [
+            answer.name,
+            answer.type === 'choice'
+                ? {
+                    type: 'choice',
+                    choice: answer.choice,
+                    confidence: answer.confidence,
+                    probabilities
+                }
+                : {
+                    type: 'score',
+                    score: answer.score,
+                    confidence: answer.confidence,
+                    probabilities
+                }
+        ];
+    });
+    return {
+        answers: Object.fromEntries(answers),
+        usage: {
+            input_tokens: response.usage.input_tokens,
+            output_tokens: response.usage.output_tokens
+        }
+    };
+}
+const responseSchemas = {
+    typesafe: DecisionResponseSchema,
+    // OpenRouter's Decisions API speaks System One's shape for every model.
+    openrouter: DecisionResponseSchema,
+    // Workers AI wraps every model's output in its own envelope.
+    cloudflare: z
+        .object({ result: DecisionResponseSchema })
+        .transform((response) => response.result),
+    openai: OpenAiResponseSchema.transform(fromOpenAiResponse).pipe(DecisionResponseSchema)
+};

package/dist/questions.d.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+/** Probability that the condition holds. No separate confidence: this IS it. */
+export type DecisionNoul = {
+    type: 'noul';
+    instructions: string;
+    /** Optional, but a `true`/`false` gloss is what keeps a noul from drifting. */
+    criteria?: {
+        true: string;
+        false: string;
+    };
+};
+/** One option from a defined set, with the distribution across all of them. */
+export type DecisionChoice<Option extends string = string> = {
+    type: 'choice';
+    instructions: string;
+    /** Option -> what that option means. Include a no-match option when one may fit nothing. */
+    criteria: Record<Option, string>;
+};
+/** A position on ordered, concretely described levels. */
+export type DecisionScore = {
+    type: 'score';
+    instructions: string;
+    /** Two or more levels, lowest first; each must stand on its own. */
+    criteria: string[];
+};
+export type DecisionQuestion = DecisionNoul | DecisionChoice | DecisionScore;
+type DecisionNoulAnswer = {
+    type: 'noul';
+    noul: number;
+};
+type DecisionChoiceAnswer<Option extends string = string> = {
+    type: 'choice';
+    choice: Option;
+    confidence: number;
+    probabilities: Record<Option, number>;
+};
+type DecisionScoreAnswer = {
+    type: 'score';
+    score: number;
+    confidence: number;
+    probabilities: Record<string, number>;
+};
+/** The answer a given question shape produces, so call sites need no casts. */
+type AnswerFor<Q> = Q extends {
+    type: 'noul';
+} ? DecisionNoulAnswer : Q extends {
+    type: 'choice';
+    criteria: Record<infer Option extends string, string>;
+} ? DecisionChoiceAnswer<Option> : Q extends {
+    type: 'score';
+} ? DecisionScoreAnswer : never;
+export type DecisionAnswers<Q extends Record<string, DecisionQuestion>> = {
+    [K in keyof Q]: AnswerFor<Q[K]>;
+};
+declare const AnswerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"noul">;
+    noul: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"choice">;
+    choice: z.ZodString;
+    confidence: z.ZodNumber;
+    probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"score">;
+    score: z.ZodNumber;
+    confidence: z.ZodNumber;
+    probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
+}, z.core.$strip>], "type">;
+/** What every vendor's response is read into. */
+export declare const DecisionResponseSchema: z.ZodObject<{
+    answers: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"noul">;
+        noul: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"choice">;
+        choice: z.ZodString;
+        confidence: z.ZodNumber;
+        probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"score">;
+        score: z.ZodNumber;
+        confidence: z.ZodNumber;
+        probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strip>], "type">>;
+    usage: z.ZodObject<{
+        input_tokens: z.ZodNumber;
+        output_tokens: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DecisionResponse = z.infer<typeof DecisionResponseSchema>;
+/** The contract depends on the question, not just the answer's own tag. */
+export declare function matchesQuestion(question: DecisionQuestion, answer: z.infer<typeof AnswerSchema> | undefined): boolean;
+export {};

package/dist/questions.js

@@ -0,0 +1,51 @@
+// The question and answer shapes every call speaks. They are System One's own
+// (TypeSafe's Jev, Cloudflare's Clef); a provider with another wire format
+// translates to and from them in `models.ts`.
+import { z } from 'zod';
+const ProbabilitySchema = z.number().min(0).max(1);
+const AnswerSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('noul'), noul: ProbabilitySchema }),
+    z.object({
+        type: z.literal('choice'),
+        choice: z.string(),
+        confidence: ProbabilitySchema,
+        probabilities: z.record(z.string(), ProbabilitySchema)
+    }),
+    z.object({
+        type: z.literal('score'),
+        score: z.number(),
+        confidence: ProbabilitySchema,
+        probabilities: z.record(z.string(), ProbabilitySchema)
+    })
+]);
+/** What every vendor's response is read into. */
+export const DecisionResponseSchema = z.object({
+    answers: z.record(z.string(), AnswerSchema),
+    usage: z.object({
+        input_tokens: z.number().int().nonnegative(),
+        output_tokens: z.number().int().nonnegative()
+    })
+});
+/** The contract depends on the question, not just the answer's own tag. */
+export function matchesQuestion(question, answer) {
+    if (!answer || answer.type !== question.type)
+        return false;
+    if (question.type === 'noul')
+        return true;
+    if (question.type === 'choice' && answer.type === 'choice') {
+        return (Object.hasOwn(question.criteria, answer.choice) &&
+            matchesOptions(Object.keys(question.criteria), answer.probabilities));
+    }
+    // Scores are fractional positions on zero-based rubric levels:
+    // https://docs.typesafe.ai/api#score-answer
+    if (question.type === 'score' && answer.type === 'score') {
+        return (answer.score >= 0 &&
+            answer.score <= question.criteria.length - 1 &&
+            matchesOptions(question.criteria.map((_, index) => String(index)), answer.probabilities));
+    }
+    return false;
+}
+function matchesOptions(options, probabilities) {
+    return (Object.keys(probabilities).length === options.length &&
+        options.every((option) => Object.hasOwn(probabilities, option)));
+}

package/package.json

@@ -1,6 +1,70 @@
 {
-  "name": "decision-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "decision-api",
+	"version": "1.1.0",
+	"description": "One typed client for decision models (TypeSafe Jev, Cloudflare Clef, OpenAI gpt-6-luna, OpenRouter models such as Microsoft-Decision-1) that answer questions with calibrated probabilities",
+	"license": "MIT",
+	"author": "Kristoffer Hansen",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/HansKristoffer/decision-api.git"
+	},
+	"homepage": "https://github.com/HansKristoffer/decision-api#readme",
+	"bugs": {
+		"url": "https://github.com/HansKristoffer/decision-api/issues"
+	},
+	"type": "module",
+	"engines": {
+		"node": ">=18"
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"!dist/**/*.test.*"
+	],
+	"sideEffects": false,
+	"keywords": [
+		"llm",
+		"classification",
+		"decision",
+		"zod",
+		"openai",
+		"cloudflare",
+		"typesafe",
+		"openrouter"
+	],
+	"scripts": {
+		"build": "rm -rf dist && tsc -p tsconfig.build.json",
+		"typecheck": "tsc --noEmit",
+		"test": "bun test",
+		"lint": "bun run typecheck && biome check",
+		"lint:write": "bun run typecheck && biome check --write",
+		"prepublishOnly": "bun run build",
+		"verify:package": "node scripts/verify-package.mjs",
+		"bench": "bun bench/run.ts",
+		"prepare": "husky"
+	},
+	"dependencies": {
+		"zod": "^4.4.3"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.4",
+		"@types/bun": "1.4.1",
+		"typescript": "6.0.3",
+		"husky": "^9.1.7"
+	},
+	"peerDependencies": {
+		"typescript": ">=6.0.0"
+	},
+	"peerDependenciesMeta": {
+		"typescript": {
+			"optional": true
+		}
+	}
+}