decision-api 1.2.0 → 2.0.0

package/dist/eval.d.ts

@@ -0,0 +1,115 @@
+import type { DecisionResult } from './create-decision-api.ts';
+import type { DecisionModel } from './models.ts';
+import type { DecisionAnswer, DecisionQuestion } from './questions.ts';
+/** One call and the answers a careful human would give to its questions. */
+export type DecisionCase = {
+    name: string;
+    state: unknown;
+    questions: Record<string, DecisionQuestion>;
+    /** By question key: a noul's truth, a choice's option, a score's level. */
+    expected: Record<string, boolean | string | number>;
+};
+export type GradedAnswer = {
+    expected: boolean | string | number;
+    value: string;
+    /** At 0.5 for a noul; `report` regrades nouls at your thresholds. */
+    correct: boolean;
+    /** The probability the model put on the expected answer. */
+    pCorrect: number;
+    /** A noul's probability, kept for the threshold sweep and calibration. */
+    noul?: number;
+};
+export type CaseLog = {
+    model: DecisionModel;
+    caseName: string;
+    run: number;
+    latencyMs: number;
+    inputTokens?: number;
+    costUsd?: number;
+    /** `kind: message` of a failed call. */
+    error?: string;
+    answers?: Record<string, GradedAnswer>;
+};
+/** Right or wrong, plus the probability the model put on the right answer. */
+export declare function grade(answer: DecisionAnswer, expected: boolean | string | number): GradedAnswer;
+/** What `runCases` needs of a client: `decide` from `createDecisionApi` fits. */
+type CaseClient = {
+    result(input: {
+        state: unknown;
+        questions: Record<string, DecisionQuestion>;
+    }, model?: DecisionModel): Promise<DecisionResult<Record<string, DecisionQuestion>>>;
+};
+/**
+ * Asks every case `runs` times on each of `models` (the client's default
+ * model when left out). Models run side by side; each model's calls run one
+ * at a time, so they never queue behind each other. `context` is the usage
+ * context the client requires, if it requires one.
+ */
+export declare function runCases(input: {
+    decide: CaseClient;
+    cases: DecisionCase[];
+    runs?: number;
+    models?: DecisionModel[];
+    context?: object;
+    onCall?: (log: CaseLog) => void;
+}): Promise<CaseLog[]>;
+export declare function percentile(values: number[], p: number): number;
+export declare const mean: (values: number[]) => number;
+/**
+ * Per model and question: accuracy at its threshold (`thresholds[key]`, 0.5
+ * when unset; a noul is positive at or above it), and for nouls the misses
+ * and false positives there and at every threshold from 0.05 to 0.95, the
+ * margin between the lowest positive and the highest negative (below zero
+ * means no threshold separates them), the Brier score and a 10-bin
+ * reliability table. `ok` is false when any call failed or any answer was
+ * wrong: `if (!summary.ok) process.exitCode = 1`.
+ */
+export declare function report(logs: CaseLog[], options?: {
+    thresholds?: Record<string, number>;
+}): {
+    ok: boolean;
+    models: {
+        model: "jev" | "clef" | "clef-flash" | "gpt-6-luna" | "microsoft/microsoft-decision-1" | "typesafe/jev-1.13";
+        calls: number;
+        failed: number;
+        wrong: number;
+        brier: number;
+        latencyP50: number;
+        latencyP90: number;
+        inputTokens: number;
+        costUsd: number;
+        questions: ({
+            key: string;
+            answers: number;
+            threshold: undefined;
+            wrong: number;
+            accuracy: number;
+            noul: undefined;
+        } | {
+            key: string;
+            answers: number;
+            threshold: number;
+            wrong: number;
+            accuracy: number;
+            noul: {
+                misses: number;
+                falsePositives: number;
+                margin: number;
+                brier: number;
+                sweep: {
+                    threshold: number;
+                    misses: number;
+                    falsePositives: number;
+                }[];
+                reliability: {
+                    from: number;
+                    to: number;
+                    answers: number;
+                    meanP: number;
+                    observed: number;
+                }[];
+            };
+        })[];
+    }[];
+};
+export {};

package/dist/eval.js

@@ -0,0 +1,182 @@
+// Labelled cases against a live client: run them, then read accuracy at the
+// thresholds the app ships, a threshold sweep and calibration per question.
+// The app brings the cases; nothing here knows its domain.
+/** Right or wrong, plus the probability the model put on the right answer. */
+export function grade(answer, expected) {
+    if (answer.type === 'noul') {
+        const pCorrect = expected ? answer.noul : 1 - answer.noul;
+        return {
+            expected,
+            value: answer.noul.toFixed(2),
+            correct: pCorrect >= 0.5,
+            pCorrect,
+            noul: answer.noul
+        };
+    }
+    const pCorrect = answer.probabilities[String(expected)] ?? 0;
+    if (answer.type === 'choice') {
+        return {
+            expected,
+            value: answer.choice,
+            correct: answer.choice === expected,
+            pCorrect
+        };
+    }
+    return {
+        expected,
+        value: answer.score.toFixed(2),
+        correct: Math.round(answer.score) === expected,
+        pCorrect
+    };
+}
+/**
+ * Asks every case `runs` times on each of `models` (the client's default
+ * model when left out). Models run side by side; each model's calls run one
+ * at a time, so they never queue behind each other. `context` is the usage
+ * context the client requires, if it requires one.
+ */
+export async function runCases(input) {
+    const runs = input.runs ?? 1;
+    const perModel = await Promise.all((input.models ?? [undefined]).map(async (model) => {
+        const logs = [];
+        for (let run = 1; run <= runs; run++) {
+            for (const decisionCase of input.cases) {
+                const outcome = await input.decide.result({
+                    ...input.context,
+                    state: decisionCase.state,
+                    questions: decisionCase.questions
+                }, model);
+                const log = outcome.ok
+                    ? {
+                        model: outcome.usage?.model ?? model ?? 'jev',
+                        caseName: decisionCase.name,
+                        run,
+                        latencyMs: outcome.usage?.latencyMs ?? 0,
+                        inputTokens: outcome.usage?.inputTokens,
+                        costUsd: outcome.usage?.costUsd,
+                        answers: Object.fromEntries(Object.entries(decisionCase.expected).map(([key, expected]) => [
+                            key,
+                            grade(outcome.answers[key], expected)
+                        ]))
+                    }
+                    : {
+                        model: outcome.error.model,
+                        caseName: decisionCase.name,
+                        run,
+                        latencyMs: outcome.error.latencyMs,
+                        error: `${outcome.error.kind}: ${outcome.error.message}`
+                    };
+                input.onCall?.(log);
+                logs.push(log);
+            }
+        }
+        return logs;
+    }));
+    return perModel.flat();
+}
+export function percentile(values, p) {
+    if (values.length === 0)
+        return Number.NaN;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.max(0, Math.ceil(p * sorted.length) - 1)];
+}
+export const mean = (values) => values.length === 0
+    ? Number.NaN
+    : values.reduce((sum, value) => sum + value, 0) / values.length;
+const SWEEP = Array.from({ length: 19 }, (_, index) => (index + 1) / 20);
+/**
+ * Per model and question: accuracy at its threshold (`thresholds[key]`, 0.5
+ * when unset; a noul is positive at or above it), and for nouls the misses
+ * and false positives there and at every threshold from 0.05 to 0.95, the
+ * margin between the lowest positive and the highest negative (below zero
+ * means no threshold separates them), the Brier score and a 10-bin
+ * reliability table. `ok` is false when any call failed or any answer was
+ * wrong: `if (!summary.ok) process.exitCode = 1`.
+ */
+export function report(logs, options = {}) {
+    const models = [...new Set(logs.map((log) => log.model))];
+    const perModel = models.map((model) => {
+        const own = logs.filter((log) => log.model === model);
+        const answered = own.filter((log) => log.answers);
+        const keys = [
+            ...new Set(answered.flatMap((log) => Object.keys(log.answers ?? {})))
+        ];
+        const questions = keys.map((key) => summarizeQuestion(key, answered.flatMap((log) => log.answers?.[key] ?? []), options.thresholds?.[key] ?? 0.5));
+        const nouls = answered.flatMap((log) => Object.values(log.answers ?? {}).filter((a) => a.noul !== undefined));
+        const latencies = answered.map((log) => log.latencyMs);
+        return {
+            model,
+            calls: own.length,
+            failed: own.length - answered.length,
+            wrong: questions.reduce((sum, question) => sum + question.wrong, 0),
+            brier: brier(nouls),
+            latencyP50: percentile(latencies, 0.5),
+            latencyP90: percentile(latencies, 0.9),
+            inputTokens: sum(answered.map((log) => log.inputTokens ?? 0)),
+            costUsd: sum(answered.map((log) => log.costUsd ?? 0)),
+            questions
+        };
+    });
+    return {
+        ok: perModel.every((row) => row.failed === 0 && row.wrong === 0),
+        models: perModel
+    };
+}
+function summarizeQuestion(key, graded, threshold) {
+    const nouls = graded.filter((answer) => answer.noul !== undefined);
+    if (nouls.length === 0 || nouls.length !== graded.length) {
+        const wrong = graded.filter((answer) => !answer.correct).length;
+        return {
+            key,
+            answers: graded.length,
+            threshold: undefined,
+            wrong,
+            accuracy: 1 - wrong / graded.length,
+            noul: undefined
+        };
+    }
+    const errorsAt = (at) => ({
+        threshold: at,
+        misses: nouls.filter((a) => a.expected && a.noul < at).length,
+        falsePositives: nouls.filter((a) => !a.expected && a.noul >= at).length
+    });
+    const at = errorsAt(threshold);
+    const positives = nouls.filter((a) => a.expected).map((a) => a.noul);
+    const negatives = nouls.filter((a) => !a.expected).map((a) => a.noul);
+    const wrong = at.misses + at.falsePositives;
+    return {
+        key,
+        answers: graded.length,
+        threshold,
+        wrong,
+        accuracy: 1 - wrong / graded.length,
+        noul: {
+            misses: at.misses,
+            falsePositives: at.falsePositives,
+            margin: positives.length && negatives.length
+                ? Math.min(...positives) - Math.max(...negatives)
+                : Number.NaN,
+            brier: brier(nouls),
+            sweep: SWEEP.map(errorsAt),
+            reliability: reliability(nouls)
+        }
+    };
+}
+const sum = (values) => values.reduce((total, v) => total + v, 0);
+/** Mean squared distance from the truth: 0 is perfect, 0.25 is a coin. */
+function brier(nouls) {
+    return mean(nouls.map((a) => ((a.noul ?? 0) - (a.expected ? 1 : 0)) ** 2));
+}
+/** Answers binned by probability: a calibrated model's `observed` tracks `meanP`. */
+function reliability(nouls) {
+    return Array.from({ length: 10 }, (_, bin) => {
+        const inBin = nouls.filter((a) => Math.min(9, Math.floor(a.noul * 10)) === bin);
+        return {
+            from: bin / 10,
+            to: (bin + 1) / 10,
+            answers: inBin.length,
+            meanP: mean(inBin.map((a) => a.noul)),
+            observed: mean(inBin.map((a) => (a.expected ? 1 : 0)))
+        };
+    }).filter((row) => row.answers > 0);
+}

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 { DecisionAnswers, DecisionChoice, DecisionNoul, DecisionQuestion, DecisionScore } from './questions.ts';
+export { createDecisionApi, DECISION_MAX_REQUEST_CHARS, type DecisionApi, DecisionError, type DecisionErrorKind, type DecisionFetch, type DecisionResult, type DecisionUsage } from './create-decision-api.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 DecisionAnswer, type DecisionAnswers, type DecisionChoice, type DecisionChoiceAnswer, type DecisionNoul, type DecisionNoulAnswer, type DecisionQuestion, type DecisionScore, type DecisionScoreAnswer, perItem } from './questions.ts';

package/dist/index.js

@@ -1,2 +1,4 @@
-export { createDecisionApi, DECISION_MAX_STATE_CHARS, DecisionError } from "./create-decision-api.js";
+export { createDecisionApi, DECISION_MAX_REQUEST_CHARS, DecisionError } from "./create-decision-api.js";
+export { image, withImages } from "./images.js";
 export { DECISION_MODELS } from "./models.js";
+export { perItem } from "./questions.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,38 +14,65 @@ 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.
+ *
+ * `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 declare const DECISION_MODELS: {
     readonly jev: {
         readonly provider: "typesafe";
         readonly inputUsdPerMTok: 0.042;
+        readonly images: true;
+        readonly maxChoices: 255;
+        readonly maxLevels: 10;
     };
     readonly clef: {
         readonly provider: "cloudflare";
         readonly inputUsdPerMTok: 0.24;
+        readonly images: false;
+        readonly maxQuestions: 64;
     };
     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;
+        readonly maxChoices: 255;
+        readonly maxLevels: 10;
     };
 };
 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];
@@ -52,9 +80,13 @@ type ModelsOf<Provider> = {
 export type ModelsFor<Keys extends DecisionProviderKeys> = ModelsOf<{
     [Provider in keyof Keys]-?: undefined extends Keys[Provider] ? never : Provider;
 }[keyof Keys]>;
+/** Why a model would refuse these questions, or undefined when it takes them. */
+export declare function overModelLimit(model: DecisionModel, questions: Record<string, DecisionQuestion>): string | undefined;
 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): {
@@ -85,5 +117,6 @@ export declare function readDecisionResponse(model: DecisionModel, json: unknown
         input_tokens: number;
         output_tokens: number;
     };
+    model?: string | undefined;
 }>;
 export {};