decision-api 1.2.0 → 2.0.0

package/dist/models.js

@@ -2,27 +2,83 @@
 // that provider's wire format maps onto the shared question shapes
 // (`questions.ts`).
 import { z } from 'zod';
+import { toAssets } from "./images.js";
 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).
+ * `inputUsdPerMTok` is 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). Images are
+ * billed as input tokens at the same rate.
+ *
+ * `images` marks the models this client sends images to. Jev reads them
+ * anywhere in the state, instructions and criteria (1.13 and later:
+ * https://docs.typesafe.ai/images). Clef and gpt-6-luna read images too, but
+ * in wire formats this client does not speak yet.
+ *
+ * `maxQuestions`, `maxChoices` (options in one choice) and `maxLevels` (levels
+ * in one score) are the limits a call is checked against before it is sent,
+ * where a provider documents or was measured to enforce one. Jev's come from
+ * its API schema (https://docs.typesafe.ai/api); Clef's question limit was
+ * measured (it refuses more than 64).
  */
 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 },
+    jev: {
+        provider: 'typesafe',
+        inputUsdPerMTok: 0.042,
+        images: true,
+        maxChoices: 255,
+        maxLevels: 10
+    },
+    clef: {
+        provider: 'cloudflare',
+        inputUsdPerMTok: 0.24,
+        images: false,
+        maxQuestions: 64
+    },
+    'clef-flash': {
+        provider: 'cloudflare',
+        inputUsdPerMTok: 0.09,
+        images: false
+    },
+    'gpt-6-luna': { provider: 'openai', inputUsdPerMTok: 0.1, images: false },
     // 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
+        inputUsdPerMTok: 0.042,
+        images: false
     },
-    // TypeSafe's Jev 1.13 on OpenRouter, served on OpenRouter's zero-data-retention list
-    'typesafe/jev-1.13': { provider: 'openrouter', inputUsdPerMTok: 0.042 }
+    // TypeSafe's Jev 1.13 on OpenRouter, served on OpenRouter's
+    // zero-data-retention list. OpenRouter forwards `assets` to Jev as written:
+    // https://openrouter.ai/docs/guides/community/multimodal-decisions
+    'typesafe/jev-1.13': {
+        provider: 'openrouter',
+        inputUsdPerMTok: 0.042,
+        images: true,
+        maxChoices: 255,
+        maxLevels: 10
+    }
 };
+/** Why a model would refuse these questions, or undefined when it takes them. */
+export function overModelLimit(model, questions) {
+    const limits = DECISION_MODELS[model];
+    const count = Object.keys(questions).length;
+    if (limits.maxQuestions !== undefined && count > limits.maxQuestions) {
+        return `${count} questions, over ${model}'s ${limits.maxQuestions}`;
+    }
+    for (const [key, question] of Object.entries(questions)) {
+        if (question.type === 'noul')
+            continue;
+        const [size, limit, what] = question.type === 'choice'
+            ? [Object.keys(question.criteria).length, limits.maxChoices, 'options']
+            : [question.criteria.length, limits.maxLevels, 'levels'];
+        if (limit !== undefined && size > limit) {
+            return `"${key}" has ${size} ${what}, over ${model}'s ${limit}`;
+        }
+    }
+    return undefined;
+}
 /** One POST: where it goes, and the headers and body it carries. */
 export function buildDecisionRequest(model, input, keys) {
     const provider = DECISION_MODELS[model].provider;
@@ -34,18 +90,30 @@ export function buildDecisionRequest(model, input, keys) {
             'content-type': 'application/json'
         };
     };
+    const { state, questions, images } = input;
+    // A text-only request goes out exactly as it did before images existed.
+    const assets = images.length > 0 ? { assets: toAssets(images) } : {};
     if (provider === 'typesafe') {
         return {
             url: 'https://api.typesafe.ai/v1/systemone',
-            headers: headers(keys.typesafe),
-            body: JSON.stringify({ ...input, model: 'jev-latest' })
+            headers: {
+                ...headers(keys.typesafe),
+                // Images are opt-in per request while TypeSafe calls them a preview.
+                ...(images.length > 0 && { 'typesafe-danger-zone-images': 'true' })
+            },
+            body: JSON.stringify({
+                state,
+                questions,
+                ...assets,
+                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 })
+            body: JSON.stringify({ state, questions, model })
         };
     }
     if (provider === 'openrouter') {
@@ -53,13 +121,13 @@ export function buildDecisionRequest(model, input, keys) {
         return {
             url: 'https://openrouter.ai/api/alpha/decisions',
             headers: headers(keys.openrouter),
-            body: JSON.stringify({ ...input, model })
+            body: JSON.stringify({ state, questions, ...assets, model })
         };
     }
     return {
         url: 'https://api.openai.com/v1/decisions',
         headers: headers(keys.openai),
-        body: JSON.stringify(toOpenAiRequest(model, input))
+        body: JSON.stringify(toOpenAiRequest(model, { state, questions }))
     };
 }
 /** The provider's response read into the shared shape, unvalidated against the questions. */
@@ -114,6 +182,7 @@ const OpenAiProbabilitiesSchema = z.array(z.object({
     probability: z.number()
 }));
 const OpenAiResponseSchema = z.object({
+    model: z.string().optional(),
     answers: z.array(z.discriminatedUnion('type', [
         z.object({
             type: z.literal('predicate'),
@@ -159,6 +228,7 @@ function fromOpenAiResponse(response) {
         ];
     });
     return {
+        model: response.model,
         answers: Object.fromEntries(answers),
         usage: {
             input_tokens: response.usage.input_tokens,

package/dist/questions.d.ts

@@ -1,73 +1,62 @@
 import { z } from 'zod';
+import type { DecisionText } from './images.ts';
 /** Probability that the condition holds. No separate confidence: this IS it. */
 export type DecisionNoul = {
     type: 'noul';
-    instructions: string;
+    instructions: DecisionText;
     /** Optional, but a `true`/`false` gloss is what keeps a noul from drifting. */
     criteria?: {
-        true: string;
-        false: string;
+        true: DecisionText;
+        false: DecisionText;
     };
 };
 /** One option from a defined set, with the distribution across all of them. */
 export type DecisionChoice<Option extends string = string> = {
     type: 'choice';
-    instructions: string;
+    instructions: DecisionText;
     /** Option -> what that option means. Include a no-match option when one may fit nothing. */
-    criteria: Record<Option, string>;
+    criteria: Record<Option, DecisionText>;
 };
 /** A position on ordered, concretely described levels. */
 export type DecisionScore = {
     type: 'score';
-    instructions: string;
+    instructions: DecisionText;
     /** Two or more levels, lowest first; each must stand on its own. */
-    criteria: string[];
+    criteria: DecisionText[];
 };
 export type DecisionQuestion = DecisionNoul | DecisionChoice | DecisionScore;
-type DecisionNoulAnswer = {
+export type DecisionNoulAnswer = {
     type: 'noul';
     noul: number;
 };
-type DecisionChoiceAnswer<Option extends string = string> = {
+export type DecisionChoiceAnswer<Option extends string = string> = {
     type: 'choice';
     choice: Option;
     confidence: number;
     probabilities: Record<Option, number>;
 };
-type DecisionScoreAnswer = {
+export type DecisionScoreAnswer = {
     type: 'score';
     score: number;
     confidence: number;
     probabilities: Record<string, number>;
 };
+export type DecisionAnswer = DecisionNoulAnswer | DecisionChoiceAnswer | DecisionScoreAnswer;
 /** The answer a given question shape produces, so call sites need no casts. */
-type AnswerFor<Q> = Q extends {
+export type AnswerFor<Q> = Q extends {
     type: 'noul';
 } ? DecisionNoulAnswer : Q extends {
     type: 'choice';
-    criteria: Record<infer Option extends string, string>;
+    criteria: Record<infer Option extends string, DecisionText>;
 } ? 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<{
+    model: z.ZodOptional<z.ZodString>;
     answers: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"noul">;
         noul: z.ZodNumber;
@@ -89,5 +78,18 @@ export declare const DecisionResponseSchema: z.ZodObject<{
 }, 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 {};
+export declare function matchesQuestion(question: DecisionQuestion, answer: DecisionAnswer | undefined): boolean;
+/**
+ * The same question about each item of a list, under keys `${prefix}_${index}`.
+ * Spread `questions` into a call (next to other questions if you like) and
+ * pass its answers to `read`, which pairs each item with its typed answer.
+ */
+export declare function perItem<Item, const Q extends DecisionQuestion, const Prefix extends string>(items: readonly Item[], prefix: Prefix, ask: (item: Item, index: number) => Q): {
+    questions: Record<`${Prefix}_${number}`, Q>;
+    /** Every key is there: a call answers all its questions or `null`. */
+    read: (answers: { readonly [K in `${Prefix}_${number}`]: AnswerFor<Q>; }) => {
+        item: Item;
+        index: number;
+        answer: AnswerFor<Q>;
+    }[];
+};

package/dist/questions.js

@@ -1,6 +1,7 @@
 // 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`.
+// translates to and from them in `models.ts`. Instructions and criteria take
+// images (`DecisionText`) on the models that read them.
 import { z } from 'zod';
 const ProbabilitySchema = z.number().min(0).max(1);
 const AnswerSchema = z.discriminatedUnion('type', [
@@ -20,6 +21,8 @@ const AnswerSchema = z.discriminatedUnion('type', [
 ]);
 /** What every vendor's response is read into. */
 export const DecisionResponseSchema = z.object({
+    /** The model that answered, when the provider says (it may resolve an alias). */
+    model: z.string().optional(),
     answers: z.record(z.string(), AnswerSchema),
     usage: z.object({
         input_tokens: z.number().int().nonnegative(),
@@ -49,3 +52,20 @@ function matchesOptions(options, probabilities) {
     return (Object.keys(probabilities).length === options.length &&
         options.every((option) => Object.hasOwn(probabilities, option)));
 }
+/**
+ * The same question about each item of a list, under keys `${prefix}_${index}`.
+ * Spread `questions` into a call (next to other questions if you like) and
+ * pass its answers to `read`, which pairs each item with its typed answer.
+ */
+export function perItem(items, prefix, ask) {
+    const questions = Object.fromEntries(items.map((item, index) => [`${prefix}_${index}`, ask(item, index)]));
+    return {
+        questions,
+        /** Every key is there: a call answers all its questions or `null`. */
+        read: (answers) => items.map((item, index) => ({
+            item,
+            index,
+            answer: answers[`${prefix}_${index}`]
+        }))
+    };
+}

package/dist/testing.d.ts

@@ -0,0 +1,27 @@
+import { DecisionError } from './create-decision-api.ts';
+import { type DecisionModel } from './models.ts';
+import { type DecisionAnswer, type DecisionQuestion } from './questions.ts';
+/** One call the code under test made: its input (context included) and model. */
+export type FakeDecisionCall = {
+    state: unknown;
+    questions: Record<string, DecisionQuestion>;
+    model: DecisionModel | undefined;
+    [field: string]: unknown;
+};
+/**
+ * Answers by question key: a number is a noul's probability or a score, a
+ * string is the choice, or give the full answer.
+ */
+export type FakeAnswers = Record<string, number | string | DecisionAnswer>;
+type Respond = (call: FakeDecisionCall) => FakeAnswers | DecisionError | null | Promise<FakeAnswers | DecisionError | null>;
+/**
+ * A fake `decide`, typed as the real one: `fakeDecide<typeof decide>(...)`.
+ * `respond` answers each call; `null` fails it as `request-failed`, and a
+ * `DecisionError` fails it with that error. An answer that does not fit its
+ * question, or a missing one, throws in the test, since the real client would
+ * never return it. `calls` records every call.
+ */
+export declare function fakeDecide<Api>(respond: Respond): Api & {
+    calls: FakeDecisionCall[];
+};
+export {};

package/dist/testing.js

@@ -0,0 +1,74 @@
+// A stand-in for `createDecisionApi`'s client in tests: no network, typed as
+// the real one, and as strict about answers as the real one.
+import { DecisionError } from "./create-decision-api.js";
+import { DECISION_MODELS } from "./models.js";
+import { matchesQuestion } from "./questions.js";
+/**
+ * A fake `decide`, typed as the real one: `fakeDecide<typeof decide>(...)`.
+ * `respond` answers each call; `null` fails it as `request-failed`, and a
+ * `DecisionError` fails it with that error. An answer that does not fit its
+ * question, or a missing one, throws in the test, since the real client would
+ * never return it. `calls` records every call.
+ */
+export function fakeDecide(respond) {
+    const calls = [];
+    const result = async (input, model) => {
+        const call = { ...input, model };
+        calls.push(call);
+        const used = model ?? 'jev';
+        const response = await respond(call);
+        if (response === null || response instanceof DecisionError) {
+            const error = response ?? new DecisionError('request-failed', used, 'fakeDecide');
+            return { ok: false, error };
+        }
+        const usage = {
+            model: used,
+            provider: DECISION_MODELS[used].provider,
+            inputTokens: 0,
+            outputTokens: 0,
+            costUsd: 0,
+            latencyMs: 0,
+            attempts: 1
+        };
+        return {
+            ok: true,
+            answers: expand(call.questions, response),
+            usage
+        };
+    };
+    const decide = async (input, model) => {
+        const outcome = await result(input, model);
+        return outcome.ok ? outcome.answers : null;
+    };
+    return Object.assign(decide, { result, calls });
+}
+function expand(questions, given) {
+    return Object.fromEntries(Object.entries(questions).map(([key, question]) => {
+        const answer = toAnswer(question, given[key]);
+        if (!matchesQuestion(question, answer)) {
+            throw new Error(`fakeDecide: the answer to "${key}" (${JSON.stringify(given[key])}) does not fit its ${question.type} question`);
+        }
+        return [key, answer];
+    }));
+}
+/** Shorthand to a full answer: all the probability on the given value. */
+function toAnswer(question, value) {
+    if (value === undefined || typeof value === 'object')
+        return value;
+    if (question.type === 'noul') {
+        return typeof value === 'number' ? { type: 'noul', noul: value } : undefined;
+    }
+    const options = question.type === 'choice'
+        ? Object.keys(question.criteria)
+        : question.criteria.map((_, index) => String(index));
+    const picked = String(question.type === 'score' ? Math.round(Number(value)) : value);
+    const probabilities = Object.fromEntries(options.map((option) => [option, option === picked ? 1 : 0]));
+    if (question.type === 'choice') {
+        return typeof value === 'string'
+            ? { type: 'choice', choice: value, confidence: 1, probabilities }
+            : undefined;
+    }
+    return typeof value === 'number'
+        ? { type: 'score', score: value, confidence: 1, probabilities }
+        : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "decision-api",
-	"version": "1.2.0",
+	"version": "2.0.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",
@@ -22,6 +22,14 @@
 		".": {
 			"types": "./dist/index.d.ts",
 			"default": "./dist/index.js"
+		},
+		"./eval": {
+			"types": "./dist/eval.d.ts",
+			"default": "./dist/eval.js"
+		},
+		"./testing": {
+			"types": "./dist/testing.d.ts",
+			"default": "./dist/testing.js"
 		}
 	},
 	"files": [