decision-api 1.1.0 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 # decision-api
 
-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`.
+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 `typesafe/jev-1.13`), and returns the same answer shape from all of them. Jev also reads images. It depends only on `zod`.
 
 ```sh
 npm install decision-api
@@ -49,7 +49,42 @@ TypeScript enforces the setup:
 - **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.
+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`, `images-unsupported`, `image-detached` (see [Images](#images)), `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.
+
+## Images
+
+`jev` and `typesafe/jev-1.13` read images (`images: true` in `DECISION_MODELS`). Make one with `image()` from PNG or JPEG bytes or base64, and put it anywhere text can go: in the state, as a question's instructions or as a criterion. Inside a sentence, write it into a `withImages` template:
+
+```ts
+import { image, withImages } from 'decision-api'
+import { readFile } from 'node:fs/promises'
+
+const door = image(await readFile('door-camera.jpg'))
+const badge = image(await readFile('badge.jpg'))
+const thumbsUp = image(await readFile('thumbs-up.png'))
+
+const answers = await decide({
+	state: { door },
+	questions: {
+		same: {
+			type: 'noul',
+			instructions: withImages`Is the person in \`door\` the one on this badge: ${badge}?`
+		},
+		gesture: {
+			type: 'choice',
+			instructions: 'Which gesture does the hand in `door` make?',
+			criteria: { thumbs_up: thumbsUp, none: 'No hand, or another gesture' }
+		}
+	},
+	customerId: 'c_1'
+})
+```
+
+Each image is sent once, base64-encoded under a unique reference, however often it is used; every use still counts as input tokens. TypeSafe's image preview header is added for you. Put an image several questions use in the state, not in each question's instructions.
+
+- **TypeScript rejects an image on a model that reads none**, when the image's type is visible in the call. Questions typed as `Record<string, DecisionQuestion>` don't show it, so the call checks as well and answers `null` with `images-unsupported`.
+- **A plain template loses the image.** `` `Same as ${badge}?` `` writes only the reference; the call answers `null` with `image-detached` instead of asking about a bare string.
+- **Prepare images first.** `image()` throws for anything but PNG or JPEG. Jev rejects images, and never resizes them, outside 280 to 1568 px a side or over 16 MiB, and ignores EXIF orientation, so scale and rotate before sending ([limits](https://docs.typesafe.ai/images#limits)). TypeSafe calls images a preview: the format and accuracy may change between Jev releases.
 
 ## Benchmark
 

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

@@ -1,4 +1,5 @@
-import { type DecisionModel, type DecisionProvider, type DecisionProviderKeys, type ModelsFor } from './models.ts';
+import { type DecisionImage, type DecisionImageText, type DecisionText } from './images.ts';
+import { type DecisionImageModel, 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
@@ -18,6 +19,10 @@ export type DecisionUsage<Model extends DecisionModel = DecisionModel> = {
     latencyMs: number;
 };
 export type DecisionErrorKind = 'state-too-large'
+/** The call holds an image and the model reads none (`images: false`). */
+ | 'images-unsupported'
+/** An image's reference is in the text without the image: build that text with `withImages`. */
+ | 'image-detached'
 /** No answer within `timeoutMs`. */
  | 'timeout'
 /** The call's own signal (or `defaultSignal`) aborted it. */
@@ -51,9 +56,12 @@ export type DecisionFetch = (request: {
     /** 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;
+type DecisionCall<Q extends Record<string, DecisionQuestion>, State> = {
+    /**
+     * A string, or named fields - name them when the state has several parts.
+     * Images go in as values, on models that read them.
+     */
+    state: State;
     questions: Q;
     signal?: AbortSignal;
     timeoutMs?: number;
@@ -89,6 +97,17 @@ type DecisionApiOptions<Keys extends DecisionProviderKeys, Default, Context> = {
  * 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 type DecisionApi<Model extends DecisionModel, Default, Context> = <Q extends Record<string, DecisionQuestion>, State = unknown>(input: DecisionCall<Q, State> & Context, ...model: ModelArgument<HasImage<State> extends true ? Extract<Model, DecisionImageModel> : HasImage<Q> extends true ? Extract<Model, DecisionImageModel> : Model, Default>) => Promise<DecisionAnswers<Q> | null>;
+type ModelArgument<Model, Default> = [Default] extends [Model] ? [model?: Model] : [model: Model];
+/**
+ * Whether a call's state or questions hold an image, as far as their types
+ * tell: a value typed as any text (`DecisionText`, `unknown`, `any`) does not
+ * say, and the call checks it instead. Stops at a few levels deep, so a
+ * recursive JSON type cannot recurse forever.
+ */
+type HasImage<T, Depth extends unknown[] = []> = 0 extends 1 & T ? false : [DecisionText] extends [T] ? false : Depth['length'] extends 6 ? false : true extends ImageIn<T, [...Depth, unknown]> ? true : false;
+type ImageIn<T, Depth extends unknown[]> = T extends DecisionImage | DecisionImageText ? true : T extends readonly (infer Item)[] ? HasImage<Item, Depth> : T extends object ? {
+    [K in keyof T]-?: HasImage<T[K], Depth>;
+}[keyof T] : false;
 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

@@ -1,3 +1,4 @@
+import { collectImages, detachedReference } from "./images.js";
 import { buildDecisionRequest, DECISION_MODELS, readDecisionResponse } from "./models.js";
 import { matchesQuestion } from "./questions.js";
 /**
@@ -61,18 +62,27 @@ export function createDecisionApi(options) {
         if (Object.keys(questions).length === 0) {
             return {};
         }
+        // An image counts as its reference here: its tokens are the provider's to count.
         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 images = collectImages(questions, collectImages(state));
+        const detached = detachedReference(stateText + JSON.stringify(questions), images);
+        if (detached) {
+            return fail('image-detached', `${detached} is in the text without its image; write that text with withImages`);
+        }
+        if (images.size > 0 && !DECISION_MODELS[model].images) {
+            return fail('images-unsupported', `${model} does not read images`);
+        }
         const startedAt = Date.now();
         let text;
         try {
             text = await postWithRetry({
                 send,
                 model,
-                request: buildDecisionRequest(model, { state, questions }, options.keys),
+                request: buildDecisionRequest(model, { state, questions, images: [...images.values()] }, options.keys),
                 signal: signal ?? options.defaultSignal?.(),
                 timeoutMs: timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS
             });

package/dist/images.d.ts

@@ -0,0 +1,58 @@
+export type DecisionImageFormat = 'png' | 'jpg';
+/**
+ * A PNG or JPEG image, created by `image()`. Put it wherever text can go: as
+ * (part of) the state, a question's instructions or a criterion. Inside a
+ * sentence, write it into a `withImages` template.
+ */
+export declare class DecisionImage {
+    readonly type = "image";
+    /** The text the image is sent under; what `String(image)` and `JSON.stringify` write. */
+    readonly reference: string;
+    readonly format: DecisionImageFormat;
+    private bytes;
+    private encoded;
+    constructor(data: ArrayBuffer | ArrayBufferView | string);
+    /** The file in standard base64, encoded once on first use. */
+    get base64(): string;
+    toString(): string;
+    toJSON(): string;
+}
+/** Text from a `withImages` template: the images in it travel with the request. */
+export declare class DecisionImageText {
+    readonly text: string;
+    readonly images: readonly DecisionImage[];
+    constructor(text: string, images: readonly DecisionImage[]);
+    toString(): string;
+    toJSON(): string;
+}
+/** Text, an image on its own, or text with images in it: whatever a model may read. */
+export type DecisionText = string | DecisionImage | DecisionImageText;
+/**
+ * A PNG or JPEG image to put in a call, from its file bytes or base64 (a
+ * `data:` URL works too). Only models with `images: true` in
+ * `DECISION_MODELS` read images.
+ *
+ * Throws when the data is not a PNG or JPEG file. The provider rejects, never
+ * resizes, an image outside its limits: for Jev, 280 to 1568 px a side and at
+ * most 16 MiB, with EXIF orientation ignored, so rotate and scale first.
+ */
+export declare function image(data: ArrayBuffer | ArrayBufferView | string): DecisionImage;
+/**
+ * Tag a template whose text names images, so they are sent with it:
+ * withImages`Is the person in \`door\` the one on this badge: ${badge}?`
+ * A plain template would carry the reference without the image, and the call
+ * answers `null` (`image-detached`) rather than ask about a bare string.
+ */
+export declare function withImages(strings: TemplateStringsArray, ...values: unknown[]): DecisionImageText;
+/** Every image in a value, once each, keyed by its reference. Object keys stay text. */
+export declare function collectImages(value: unknown, into?: Map<string, DecisionImage>): Map<string, DecisionImage>;
+/** A reference written into the text whose image was not sent with it, if any. */
+export declare function detachedReference(text: string, images: ReadonlyMap<string, DecisionImage>): string | undefined;
+/** The `assets` map TypeSafe's API (and OpenRouter's, for Jev) reads. */
+export declare function toAssets(images: Iterable<DecisionImage>): {
+    [k: string]: {
+        type: string;
+        format: DecisionImageFormat;
+        data_base64: string;
+    };
+};

package/dist/images.js

@@ -0,0 +1,160 @@
+// Images in a decision call. Each image is sent once, base64-encoded in the
+// request's top-level `assets` map, and stands in the state, an instruction or
+// a criterion as its reference string:
+// https://docs.typesafe.ai/images
+/** Every reference starts with this, so a reference without its image can be caught. */
+const REFERENCE_PREFIX = 'decision-api-image-';
+const REFERENCE_PATTERN = new RegExp(`${REFERENCE_PREFIX}[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}`, 'g');
+/**
+ * A PNG or JPEG image, created by `image()`. Put it wherever text can go: as
+ * (part of) the state, a question's instructions or a criterion. Inside a
+ * sentence, write it into a `withImages` template.
+ */
+export class DecisionImage {
+    type = 'image';
+    /** The text the image is sent under; what `String(image)` and `JSON.stringify` write. */
+    reference = `${REFERENCE_PREFIX}${uuid()}`;
+    format;
+    bytes;
+    encoded;
+    constructor(data) {
+        if (typeof data === 'string') {
+            // A data URL's prefix is dropped; the API wants the bare base64.
+            const base64 = data.replace(/^data:image\/[a-z]+;base64,/, '');
+            if (!/^[A-Za-z0-9+/]+={0,2}$/.test(base64) || base64.length % 4 !== 0) {
+                throw new TypeError('image() needs padded standard base64');
+            }
+            this.encoded = base64;
+            this.format = formatOfBase64(base64);
+        }
+        else {
+            this.bytes = ArrayBuffer.isView(data)
+                ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+                : new Uint8Array(data);
+            this.format = formatOfBytes(this.bytes);
+        }
+    }
+    /** The file in standard base64, encoded once on first use. */
+    get base64() {
+        if (this.encoded === undefined && this.bytes) {
+            this.encoded = toBase64(this.bytes);
+            this.bytes = undefined;
+        }
+        return this.encoded ?? '';
+    }
+    toString() {
+        return this.reference;
+    }
+    toJSON() {
+        return this.reference;
+    }
+}
+/** Text from a `withImages` template: the images in it travel with the request. */
+export class DecisionImageText {
+    text;
+    images;
+    constructor(text, images) {
+        this.text = text;
+        this.images = images;
+    }
+    toString() {
+        return this.text;
+    }
+    toJSON() {
+        return this.text;
+    }
+}
+/**
+ * A PNG or JPEG image to put in a call, from its file bytes or base64 (a
+ * `data:` URL works too). Only models with `images: true` in
+ * `DECISION_MODELS` read images.
+ *
+ * Throws when the data is not a PNG or JPEG file. The provider rejects, never
+ * resizes, an image outside its limits: for Jev, 280 to 1568 px a side and at
+ * most 16 MiB, with EXIF orientation ignored, so rotate and scale first.
+ */
+export function image(data) {
+    return new DecisionImage(data);
+}
+/**
+ * Tag a template whose text names images, so they are sent with it:
+ * withImages`Is the person in \`door\` the one on this badge: ${badge}?`
+ * A plain template would carry the reference without the image, and the call
+ * answers `null` (`image-detached`) rather than ask about a bare string.
+ */
+export function withImages(strings, ...values) {
+    const images = [];
+    let text = strings[0] ?? '';
+    values.forEach((value, index) => {
+        if (value instanceof DecisionImage)
+            images.push(value);
+        if (value instanceof DecisionImageText)
+            images.push(...value.images);
+        text += String(value) + (strings[index + 1] ?? '');
+    });
+    return new DecisionImageText(text, images);
+}
+/** Every image in a value, once each, keyed by its reference. Object keys stay text. */
+export function collectImages(value, into = new Map()) {
+    if (value instanceof DecisionImage) {
+        into.set(value.reference, value);
+    }
+    else if (value instanceof DecisionImageText) {
+        for (const item of value.images)
+            into.set(item.reference, item);
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value)
+            collectImages(item, into);
+    }
+    else if (value && typeof value === 'object') {
+        for (const item of Object.values(value))
+            collectImages(item, into);
+    }
+    return into;
+}
+/** A reference written into the text whose image was not sent with it, if any. */
+export function detachedReference(text, images) {
+    if (!text.includes(REFERENCE_PREFIX))
+        return undefined;
+    return text.match(REFERENCE_PATTERN)?.find((found) => !images.has(found));
+}
+/** The `assets` map TypeSafe's API (and OpenRouter's, for Jev) reads. */
+export function toAssets(images) {
+    return Object.fromEntries(Array.from(images, (item) => [
+        item.reference,
+        { type: 'image', format: item.format, data_base64: item.base64 }
+    ]));
+}
+function formatOfBytes(bytes) {
+    const png = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+    if (png.every((byte, index) => bytes[index] === byte))
+        return 'png';
+    if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return 'jpg';
+    throw new TypeError('image() takes PNG or JPEG files only');
+}
+/** The same magic numbers, as they start a base64 string. */
+function formatOfBase64(base64) {
+    if (base64.startsWith('iVBORw0KGgo'))
+        return 'png';
+    if (base64.startsWith('/9j/'))
+        return 'jpg';
+    throw new TypeError('image() takes PNG or JPEG files only');
+}
+function toBase64(bytes) {
+    // In slices, because spreading megabytes into one call overflows the stack.
+    let binary = '';
+    for (let start = 0; start < bytes.length; start += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(start, start + 0x8000));
+    }
+    return btoa(binary);
+}
+/** `crypto.randomUUID` where the runtime has it (Node 18 and React Native may not). */
+function uuid() {
+    const random = globalThis.crypto;
+    if (random?.randomUUID)
+        return random.randomUUID();
+    const hex = Array.from({ length: 32 }, () => Math.floor(Math.random() * 16).toString(16)).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20)}`;
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 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 DecisionImage, type DecisionImageFormat, type DecisionImageText, type DecisionText, image, withImages } from './images.ts';
+export { DECISION_MODELS, type DecisionImageModel, 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

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

package/dist/models.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { type DecisionImage } from './images.ts';
 import { type DecisionQuestion } from './questions.ts';
 /** The credentials each provider needs; pass only the providers you use. */
 export type DecisionProviderKeys = {
@@ -13,34 +14,54 @@ export type DecisionProviderKeys = {
 };
 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).
+ * `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.
  */
 export declare const DECISION_MODELS: {
     readonly jev: {
         readonly provider: "typesafe";
         readonly inputUsdPerMTok: 0.042;
+        readonly images: true;
     };
     readonly clef: {
         readonly provider: "cloudflare";
         readonly inputUsdPerMTok: 0.24;
+        readonly images: false;
     };
     readonly 'clef-flash': {
         readonly provider: "cloudflare";
         readonly inputUsdPerMTok: 0.09;
+        readonly images: false;
     };
     readonly 'gpt-6-luna': {
         readonly provider: "openai";
         readonly inputUsdPerMTok: 0.1;
+        readonly images: false;
     };
     readonly 'microsoft/microsoft-decision-1': {
         readonly provider: "openrouter";
         readonly inputUsdPerMTok: 0.042;
+        readonly images: false;
+    };
+    readonly 'typesafe/jev-1.13': {
+        readonly provider: "openrouter";
+        readonly inputUsdPerMTok: 0.042;
+        readonly images: true;
     };
 };
 export type DecisionModel = keyof typeof DECISION_MODELS;
+/** The models that read images. */
+export type DecisionImageModel = {
+    [Model in DecisionModel]: (typeof DECISION_MODELS)[Model]['images'] extends true ? Model : never;
+}[DecisionModel];
 type ModelsOf<Provider> = {
     [Model in DecisionModel]: (typeof DECISION_MODELS)[Model]['provider'] extends Provider ? Model : never;
 }[DecisionModel];
@@ -51,6 +72,8 @@ export type ModelsFor<Keys extends DecisionProviderKeys> = ModelsOf<{
 type RequestInput = {
     state: unknown;
     questions: Record<string, DecisionQuestion>;
+    /** Sent only to models with `images: true`; the caller checks. */
+    images: DecisionImage[];
 };
 /** One POST: where it goes, and the headers and body it carries. */
 export declare function buildDecisionRequest(model: DecisionModel, input: RequestInput, keys: DecisionProviderKeys): {

package/dist/models.js

@@ -2,23 +2,43 @@
 // 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.
  */
 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 },
+    clef: { provider: 'cloudflare', inputUsdPerMTok: 0.24, images: false },
+    '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. 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
     }
 };
 /** One POST: where it goes, and the headers and body it carries. */
@@ -32,18 +52,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') {
@@ -51,13 +83,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. */

package/dist/questions.d.ts

@@ -1,27 +1,28 @@
 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 = {
@@ -45,7 +46,7 @@ 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;

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', [

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "decision-api",
-	"version": "1.1.0",
+	"version": "1.3.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",