@itsoltech/basal-client 0.1.0 → 0.3.0

package/README.md

@@ -57,8 +57,8 @@ in `cause`. `BasalHTTPError.body` remains directly accessible but is non-enumera
 inspection and JSON.stringify do not log it. There are no automatic retries or redirects. Types describe the native contract; successful
 responses are checked to be JSON objects without full schema validation. Unknown JSON fields are preserved.
 
-Supports `choice`, `noul`, `score`, `multi`, `act`, `facts` and `evidence`. Native choice/score accepts 2–10
-options. Criterion insertion order matters; JavaScript enumerates integer-like object keys numerically,
+Supports `choice`, `noul`, `score`, `multi`, `act` and `tool`, with model-dependent `facts` and `evidence` capabilities. Native choice/score accepts 2–255
+options for format-2 models (older model limits are checked by the server). Criterion insertion order matters; JavaScript enumerates integer-like object keys numerically,
 so use textual keys (e.g. `low`, `high`) or an ordered score array. Evidence offsets count Unicode code
 points; use the returned text, or `Array.from(state).slice(start, end).join("")` for textual states.
 
@@ -76,3 +76,55 @@ retains the native JSON without those defaults. The one-argument raw `decide(req
 
 
 [Full documentation and publication setup](https://github.com/itsoltech/basal-rs/blob/main/docs/SDK.md).
+
+
+## Basal 2.0 and Omni
+
+Typed choice/score and act outcomes allow 2–255 options. The server remains
+responsible for limits of older models and for calibration/model capabilities.
+`tool` accepts OpenAI, MCP and Anthropic definition objects, optional non-tool
+choices (`answer_directly`, `ask_user`, `none`), ranking, multi selection and
+certified deferral. The SDK returns the decision; it never executes tools.
+
+Multi selection supports `threshold`, `exact`, `iou` and `f1`, count limits,
+`exclusive`, `fallback` and `fallback_threshold`. `threshold` is optional in
+results because objective-based responses instead contain `objective` and
+`expected_score`; constraint diagnostics remain available. Single tool selection
+can be null on certified deferral, while multi mode returns a tool list.
+
+Typed request options include `lang` (`pl`/`en`), ordered inline `media` and
+`detail` (`default`/`high`). Media helpers accept encoded bytes, base64 or a data
+URL; they never fetch URLs. Read files explicitly in your application. Decoding,
+model support and resource limits are checked by the server. Omni requires a
+CUDA server started with media enabled. `calibration: "text"` means text
+calibration applied to media, not validated calibration for images/audio.
+
+Usage exposes `longest_prompt_tokens`, `second_order_branches` and media counts,
+soft tokens and detail. Discovery exposes `prompt_format`, `orders`, enabled
+media and calibration temperatures. Model names remain strings: use exact names
+from model discovery, not a hardcoded model enumeration. Keep old models and
+raw JSON access available. The server validates each model’s capabilities.
+Basal 2.1 task helpers are described below.
+
+```typescript
+import { BasalClient, image, tool, multi } from "@itsoltech/basal-client";
+const response = await new BasalClient().decide("Inspect the supplied material.", {
+  route: tool("Choose a tool.", [{name:"inspect", description:"Inspect material", inputSchema:{type:"object"}}], {extra:["none"], rank:2, description_chars:120}),
+  labels: multi("Select visible objects.", {animal:"An animal", vehicle:"A vehicle"}, {objective:"f1"}),
+}, {model:"basal-omni-1.0-mini", lang:"en", media:[image(new Uint8Array(await file.arrayBuffer()))]});
+console.log(response.answers.route, response.answers.labels.expected_score);
+```
+
+Tool descriptions are normalized by the server. Omit `description_chars`
+(`DescriptionChars` in .NET) to keep the default cap of 300 Unicode code points;
+use `0` to disable truncation. Descriptions longer than a positive cap are
+shortened at a word boundary where possible, with an ellipsis appended. The SDK forwards this option
+without changing the supplied tool definitions.
+
+## Experimental Basal 2.1 tasks
+
+Typed classify, verify, compress and extract factories preserve nullable task automation,
+Unicode code point offsets and nested JSON extraction values. Task answers do not share
+the primitive probabilities field. See [task semantics](../../docs/TASKS.md) and
+[SDK examples](../../docs/SDK.md#zadania-basal-21). These source changes require a server
+with the experimental task layer; installing an SDK does not update the inference server.

package/dist/cjs/index.cjs

@@ -17,6 +17,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BasalClient = exports.BasalResponseTooLargeError = exports.BasalProtocolError = exports.BasalTransportError = exports.BasalHTTPError = exports.BasalError = void 0;
 const questions_cjs_1 = require("./questions.cjs");
 __exportStar(require("./questions.cjs"), exports);
+__exportStar(require("./media.cjs"), exports);
+__exportStar(require("./tasks.cjs"), exports);
 class BasalError extends Error {
 }
 exports.BasalError = BasalError;

package/dist/cjs/index.d.cts

@@ -1,11 +1,31 @@
 import { type QuestionSet, type TypedDecisionResponse, type DecisionOptions } from "./questions.cjs";
 export * from "./questions.cjs";
+export * from "./media.cjs";
+export * from "./tasks.cjs";
+import type { TaskAnswer } from "./tasks.cjs";
 /** Native Basal wire types. Criterion order is significant; do not sort keys. */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
+export type Calibration = "validated" | "unvalidated" | "text";
+export type MultiObjective = "threshold" | "exact" | "iou" | "f1";
+export interface MediaInput {
+    type: "image" | "audio";
+    data: string;
+}
+export interface MediaUsage {
+    images: number;
+    audio: number;
+    media_tokens: number;
+    detail: "default" | "high";
+}
+export interface ToolRanking {
+    tool: string;
+    probability: number;
+}
+export type ToolDefinition = Record<string, JsonValue>;
 export interface Question {
-    type?: "choice" | "noul" | "score" | "multi" | "act";
+    type?: "choice" | "noul" | "score" | "multi" | "act" | "tool" | "classify" | "verify" | "compress" | "extract";
     instructions?: JsonValue;
     criteria?: Record<string, JsonValue> | JsonValue[];
     levels?: Record<string, JsonValue> | JsonValue[];
@@ -17,13 +37,34 @@ export interface Question {
     base?: "noul" | "choice" | "score";
     costs?: Record<string, number> | Record<string, Record<string, number>>;
     defer_action?: string;
-    max_error?: number;
+    max_error?: number | readonly number[];
+    objective?: MultiObjective;
+    exclusive?: readonly string[];
+    fallback?: string;
+    fallback_threshold?: number;
+    tools?: readonly ToolDefinition[];
+    extra?: readonly ("answer_directly" | "ask_user" | "none")[];
+    rank?: number;
+    description_chars?: number;
+    multi?: boolean;
+    labels?: Record<string, JsonValue> | JsonValue[];
+    multi_label?: boolean;
+    none?: boolean;
+    claims?: Record<string, JsonValue> | JsonValue[];
+    binary?: boolean;
+    unit?: 'sentence' | 'line' | 'paragraph';
+    keep_ratio?: number;
+    min_keep?: number;
+    schema?: Record<string, JsonValue>;
 }
 export interface DecisionRequest {
     state: JsonValue;
     questions: Record<string, Question>;
     model?: string;
     facts?: "off" | "auto";
+    lang?: "pl" | "en";
+    media?: readonly MediaInput[];
+    detail?: "default" | "high";
 }
 export interface EvidenceSpan {
     text: string;
@@ -34,6 +75,7 @@ export interface EvidenceSpan {
 interface BaseAnswer<K extends string = string> {
     probabilities: Record<K, number>;
     evidence?: EvidenceSpan[];
+    calibration?: Calibration;
 }
 export interface ChoiceAnswer<K extends string = string> extends BaseAnswer<K> {
     type: "choice";
@@ -51,29 +93,57 @@ export interface ScoreAnswer extends BaseAnswer {
     legend: Record<string, string>;
     confidence: number;
 }
-export interface MultiAnswer<K extends string = string> extends BaseAnswer<K> {
+export interface SelectionResult<K extends string = string> {
+    threshold?: number;
+    objective?: MultiObjective;
+    expected_score?: number | null;
+    constraints_applied?: JsonValue;
+    set_confidence: number;
+}
+export interface MultiAnswer<K extends string = string> extends BaseAnswer<K>, SelectionResult<K> {
     type: "multi";
     selected: K[];
-    threshold: number;
-    set_confidence: number;
 }
+export interface SingleToolAnswer extends BaseAnswer {
+    type: "tool";
+    multi?: false;
+    tool: string | null;
+    call: boolean;
+    confidence: number;
+    ranking?: ToolRanking[];
+    deferred?: boolean;
+    refused?: string;
+    max_error?: string;
+}
+export interface MultiToolAnswer extends BaseAnswer, SelectionResult {
+    type: "tool";
+    multi: true;
+    tools: string[];
+    call: boolean;
+    ranking?: ToolRanking[];
+}
+export type ToolAnswer = SingleToolAnswer | MultiToolAnswer;
 export interface ActAnswer<K extends string = string, A extends string = string> extends BaseAnswer<K> {
     type: "act";
     action: A;
     answer: K;
     expected_costs: Record<A, number>;
     confidence: number;
-    calibration: "validated" | "unvalidated";
+    calibration: Calibration;
     refused?: string;
     max_error?: string;
+    deferred?: boolean;
 }
-export type Answer = ChoiceAnswer | NoulAnswer | ScoreAnswer | MultiAnswer | ActAnswer;
+export type Answer = ChoiceAnswer | NoulAnswer | ScoreAnswer | MultiAnswer | ActAnswer | ToolAnswer | TaskAnswer;
 export interface Usage {
     input_tokens: number;
     output_tokens: number;
     questions?: number;
     branches?: number;
     latency_ms?: number;
+    longest_prompt_tokens?: number;
+    second_order_branches?: number;
+    media?: MediaUsage;
 }
 export interface DecisionResponse {
     model: string;
@@ -86,6 +156,10 @@ export interface ModelMetadata {
     release_date?: string;
     mode?: string;
     early_exit?: JsonValue[];
+    prompt_format?: number;
+    orders?: JsonValue;
+    temperature_per_prim?: Record<string, number>;
+    media?: ("image" | "audio")[];
 }
 export interface ModelsResponse {
     models: ModelMetadata[];

package/dist/cjs/media.cjs

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.image = image;
+exports.audio = audio;
+function media(type, data) {
+    if (data instanceof Uint8Array) {
+        // Bounded chunks avoid the argument limit of spreading a whole image/audio file.
+        const chunks = [];
+        for (let offset = 0; offset < data.length; offset += 8192)
+            chunks.push(String.fromCharCode(...data.subarray(offset, offset + 8192)));
+        data = btoa(chunks.join(''));
+    }
+    if (typeof data !== 'string' || !data.trim() || /^https?:\/\//i.test(data))
+        throw new TypeError('media data must be bytes, base64 or a data URL');
+    return { type, data };
+}
+/** Inline image; never fetches a URL or reads a file. */
+function image(data) { return media('image', data); }
+/** Inline audio; never fetches a URL or reads a file. */
+function audio(data) { return media('audio', data); }

package/dist/cjs/media.d.cts

@@ -0,0 +1,5 @@
+import type { MediaInput } from './index.cjs';
+/** Inline image; never fetches a URL or reads a file. */
+export declare function image(data: Uint8Array | string): MediaInput;
+/** Inline audio; never fetches a URL or reads a file. */
+export declare function audio(data: Uint8Array | string): MediaInput;

package/dist/cjs/questions.cjs

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ActQuestion = exports.MultiQuestion = exports.ScoreQuestion = exports.NoulQuestion = exports.ChoiceQuestion = exports.QuestionSpec = void 0;
+exports.ActQuestion = exports.ToolQuestion = exports.MultiQuestion = exports.ScoreQuestion = exports.NoulQuestion = exports.ChoiceQuestion = exports.QuestionSpec = void 0;
 exports.choice = choice;
 exports.noul = noul;
 exports.score = score;
 exports.multi = multi;
 exports.act = act;
+exports.tool = tool;
 exports.buildRequest = buildRequest;
 function text(value, name) {
     if (typeof value !== 'string' || !value.trim())
@@ -39,19 +40,20 @@ function evidence(options) {
 class QuestionSpec {
     wire;
     constructor(kind, instructions, fields) {
-        this.wire = structuredClone({ ...fields, type: kind, instructions: text(instructions, 'instructions') });
+        this.wire = structuredClone({ ...fields, type: kind, ...(['classify', 'verify', 'compress', 'extract'].includes(kind) ? (instructions ? { instructions } : {}) : { instructions: text(instructions, 'instructions') }) });
     }
     toJSON() { return structuredClone(this.wire); }
     /** Validate and retrieve an answer with this question's result type. */
     read(response, id) {
         const answer = response.answers?.[id];
-        if (!answer || answer.type !== this.wire.type || !answer.probabilities || typeof answer.probabilities !== 'object' || Array.isArray(answer.probabilities)) {
+        if (!answer || !('probabilities' in answer) || answer.type !== this.wire.type || !answer.probabilities || typeof answer.probabilities !== 'object' || Array.isArray(answer.probabilities)) {
             throw new TypeError('Basal returned a missing or mismatched answer');
         }
         const fields = {
             choice: { choice: 'string', confidence: 'number' }, noul: { noul: 'number', confidence: 'number' },
             score: { score: 'number', legend: 'object', confidence: 'number' },
-            multi: { selected: 'object', threshold: 'number', set_confidence: 'number' },
+            multi: { selected: 'object', set_confidence: 'number' },
+            tool: answer.type === 'tool' && answer.multi ? { tools: 'object', call: 'boolean', set_confidence: 'number' } : { call: 'boolean', confidence: 'number' },
             act: { action: 'string', answer: 'string', expected_costs: 'object', confidence: 'number', calibration: 'string' },
         };
         const data = answer;
@@ -84,14 +86,45 @@ class QuestionSpec {
         if (answer.type === 'score' && (Array.isArray(answer.legend) || Object.values(answer.legend).some(v => typeof v !== 'string')))
             throw new TypeError('invalid legend');
         if (answer.type === 'act') {
-            if (!['validated', 'unvalidated'].includes(answer.calibration) || !Object.hasOwn(this.wire.costs ?? {}, answer.action) || !expectedKeys.includes(answer.answer))
+            if (!['validated', 'unvalidated', 'text'].includes(answer.calibration) || !Object.hasOwn(this.wire.costs ?? {}, answer.action) || !expectedKeys.includes(answer.answer))
                 throw new TypeError('invalid action');
             if (Array.isArray(answer.expected_costs) || Object.keys(this.wire.costs ?? {}).some(key => !Object.hasOwn(answer.expected_costs, key)))
                 throw new TypeError('invalid expected costs');
             for (const value of Object.values(answer.expected_costs))
                 number(value, 'expected cost');
         }
-        return { ...answer, ...(answer.type === 'multi' ? {} : { evidence: answer.evidence ?? [] }) };
+        if (answer.type === 'multi' || (answer.type === 'tool' && answer.multi)) {
+            validateSelection(answer, this.wire.objective ?? 'threshold');
+        }
+        if (answer.type === 'tool') {
+            if ((answer.multi ?? false) !== (this.wire.multi ?? false))
+                throw new TypeError('mismatched tool mode');
+            if (answer.multi) {
+                if (!Array.isArray(answer.tools) || answer.tools.some(k => typeof k !== 'string' || !Object.hasOwn(answer.probabilities, k)))
+                    throw new TypeError('invalid selected tools');
+            }
+            else {
+                if (answer.tool === null ? answer.deferred !== true : typeof answer.tool !== 'string' || !Object.hasOwn(answer.probabilities, answer.tool))
+                    throw new TypeError('invalid selected tool');
+                if (answer.deferred !== undefined && typeof answer.deferred !== 'boolean')
+                    throw new TypeError('invalid deferred');
+                for (const key of ['refused', 'max_error'])
+                    if (answer[key] !== undefined && typeof answer[key] !== 'string')
+                        throw new TypeError('invalid tool metadata');
+            }
+            if (answer.ranking !== undefined) {
+                if (!Array.isArray(answer.ranking))
+                    throw new TypeError('invalid ranking');
+                for (const entry of answer.ranking) {
+                    if (!entry || typeof entry.tool !== 'string' || !Object.hasOwn(answer.probabilities, entry.tool))
+                        throw new TypeError('invalid ranking entry');
+                    number(entry.probability, 'ranking probability', true);
+                }
+            }
+        }
+        if (answer.type === 'act' && answer.deferred !== undefined && typeof answer.deferred !== 'boolean')
+            throw new TypeError('invalid deferred');
+        return { ...answer, ...(answer.type === 'multi' || answer.type === 'tool' ? {} : { evidence: answer.evidence ?? [] }) };
     }
 }
 exports.QuestionSpec = QuestionSpec;
@@ -99,7 +132,7 @@ class ChoiceQuestion extends QuestionSpec {
     constructor(instructions, values, options = {}) {
         if (options.option_keys !== undefined && !['show', 'hide'].includes(options.option_keys))
             throw new TypeError('invalid option_keys');
-        super('choice', instructions, { criteria: criteria(values, 2, 10), ...evidence(options), ...(options.option_keys === 'hide' ? { option_keys: 'hide' } : {}) });
+        super('choice', instructions, { criteria: criteria(values, 2, 255), ...evidence(options), ...(options.option_keys === 'hide' ? { option_keys: 'hide' } : {}) });
     }
 }
 exports.ChoiceQuestion = ChoiceQuestion;
@@ -109,36 +142,106 @@ class NoulQuestion extends QuestionSpec {
 exports.NoulQuestion = NoulQuestion;
 class ScoreQuestion extends QuestionSpec {
     constructor(instructions, levels, options = {}) {
-        if (!Array.isArray(levels) || levels.length < 2 || levels.length > 10)
-            throw new TypeError('score requires 2–10 ordered levels');
+        if (!Array.isArray(levels) || levels.length < 2 || levels.length > 255)
+            throw new TypeError('score requires 2–255 ordered levels');
         super('score', instructions, { criteria: levels.map(v => text(v, 'level')), ...evidence(options) });
     }
 }
 exports.ScoreQuestion = ScoreQuestion;
+function selectionOptions(options, keys) {
+    const fields = {};
+    const objective = options.objective ?? 'threshold';
+    if (!['threshold', 'exact', 'iou', 'f1'].includes(objective))
+        throw new TypeError('invalid objective');
+    if (objective !== 'threshold')
+        fields.objective = objective;
+    if (options.threshold !== undefined) {
+        if (objective !== 'threshold')
+            throw new TypeError('threshold applies only to objective threshold');
+        fields.threshold = number(options.threshold, 'threshold', true);
+    }
+    for (const key of ['min', 'max']) {
+        const v = options[key];
+        if (v !== undefined) {
+            if (!Number.isSafeInteger(v) || v < 0 || (keys && v > keys.length))
+                throw new TypeError(`invalid ${key}`);
+            fields[key] = v;
+        }
+    }
+    if (options.min !== undefined && options.max !== undefined && options.min > options.max)
+        throw new TypeError('min exceeds max');
+    if (options.exclusive !== undefined) {
+        if (!Array.isArray(options.exclusive))
+            throw new TypeError('exclusive must be an array');
+        fields.exclusive = options.exclusive.map(k => { text(k, 'exclusive key'); if (keys && !keys.includes(k))
+            throw new TypeError('unknown exclusive key'); return k; });
+    }
+    if (options.fallback !== undefined) {
+        fields.fallback = text(options.fallback, 'fallback');
+        if (keys && !keys.includes(options.fallback))
+            throw new TypeError('unknown fallback');
+    }
+    if (options.fallback_threshold !== undefined) {
+        if (options.fallback === undefined)
+            throw new TypeError('fallback_threshold requires fallback');
+        fields.fallback_threshold = number(options.fallback_threshold, 'fallback_threshold', true);
+    }
+    return fields;
+}
+function validateSelection(answer, objective) {
+    number(answer.set_confidence, 'set_confidence', true);
+    if (objective === 'threshold')
+        number(answer.threshold, 'threshold', true);
+    else {
+        if (answer.objective !== objective)
+            throw new TypeError('mismatched objective');
+        if (answer.expected_score !== null && answer.expected_score !== undefined)
+            number(answer.expected_score, 'expected_score', true);
+    }
+}
 class MultiQuestion extends QuestionSpec {
     constructor(instructions, values, options = {}) {
         if ('evidence' in options)
             throw new TypeError('multi does not support evidence');
-        const fields = { criteria: criteria(values, 1) };
-        if (options.threshold !== undefined)
-            fields.threshold = number(options.threshold, 'threshold', true);
-        for (const key of ['min', 'max']) {
-            const value = options[key];
-            if (value !== undefined) {
-                if (!Number.isInteger(value) || value < 0 || value > Object.keys(values).length)
-                    throw new TypeError(`invalid ${key}`);
-                fields[key] = value;
-            }
-        }
-        if (options.min !== undefined && options.max !== undefined && options.min > options.max)
-            throw new TypeError('min exceeds max');
-        super('multi', instructions, fields);
+        super('multi', instructions, { criteria: criteria(values, 1), ...selectionOptions(options, Object.keys(values)) });
     }
 }
 exports.MultiQuestion = MultiQuestion;
+class ToolQuestion extends QuestionSpec {
+    constructor(instructions, tools, options = {}) {
+        if (!Array.isArray(tools) || tools.some(t => !t || typeof t !== 'object' || Array.isArray(t)))
+            throw new TypeError('tools must contain definition objects');
+        if (options.extra !== undefined && (!Array.isArray(options.extra) || options.extra.some(k => !['answer_directly', 'ask_user', 'none'].includes(k))))
+            throw new TypeError('invalid extra tool option');
+        if (options.multi !== undefined && typeof options.multi !== 'boolean')
+            throw new TypeError('invalid multi');
+        const fields = { tools, ...(options.extra === undefined ? {} : { extra: options.extra }) };
+        if (options.description_chars !== undefined) {
+            if (!Number.isSafeInteger(options.description_chars) || options.description_chars < 0)
+                throw new TypeError('description_chars must be a non-negative safe integer');
+            fields.description_chars = options.description_chars;
+        }
+        if (options.rank !== undefined) {
+            if (!Number.isSafeInteger(options.rank) || options.rank < 1)
+                throw new TypeError('rank must be a positive integer');
+            fields.rank = options.rank;
+        }
+        if (options.max_error !== undefined)
+            fields.max_error = number(options.max_error, 'max_error', true);
+        const selection = selectionOptions(options);
+        if (!options.multi && Object.keys(selection).length)
+            throw new TypeError('selection options require multi');
+        if (options.multi) {
+            fields.multi = true;
+            Object.assign(fields, selection);
+        }
+        super('tool', instructions, fields);
+    }
+}
+exports.ToolQuestion = ToolQuestion;
 class ActQuestion extends QuestionSpec {
     constructor(instructions, costs, options = {}) {
-        const optionsMap = options.criteria === undefined ? undefined : criteria(options.criteria, 2, 10);
+        const optionsMap = options.criteria === undefined ? undefined : criteria(options.criteria, 2, 255);
         const outcomes = Object.keys(optionsMap ?? { 'true': 'Yes', 'false': 'No' });
         if (!costs || typeof costs !== 'object' || Array.isArray(costs) || !Object.keys(costs).length)
             throw new TypeError('act requires a cost matrix');
@@ -162,6 +265,7 @@ function noul(instructions, options) { return new NoulQuestion(instructions, opt
 function score(instructions, levels, options) { return new ScoreQuestion(instructions, levels, options); }
 function multi(instructions, values, options) { return new MultiQuestion(instructions, values, options); }
 function act(instructions, costs, options) { return new ActQuestion(instructions, costs, options); }
+function tool(instructions, tools, options) { return new ToolQuestion(instructions, tools, options); }
 function buildRequest(state, questions, options) {
     if (state === null || state === undefined)
         throw new TypeError('state must not be null/undefined');
@@ -175,5 +279,11 @@ function buildRequest(state, questions, options) {
         text(options.model, 'model');
     if (options.facts !== undefined && !['off', 'auto'].includes(options.facts))
         throw new TypeError('invalid facts');
-    return { state, questions: Object.fromEntries(entries), ...(options.model === undefined ? {} : { model: options.model }), ...(options.facts === undefined ? {} : { facts: options.facts }) };
+    if (options.lang !== undefined && !['pl', 'en'].includes(options.lang))
+        throw new TypeError('invalid lang');
+    if (options.detail !== undefined && !['default', 'high'].includes(options.detail))
+        throw new TypeError('invalid detail');
+    if (options.media !== undefined && (!Array.isArray(options.media) || options.media.length < 1 || options.media.length > 8 || options.media.some(m => !m || !['image', 'audio'].includes(m.type) || typeof m.data !== 'string' || !m.data.trim())))
+        throw new TypeError('invalid media');
+    return { state, questions: Object.fromEntries(entries), ...(options.lang === undefined ? {} : { lang: options.lang }), ...(options.detail === undefined ? {} : { detail: options.detail }), ...(options.media === undefined ? {} : { media: structuredClone(options.media) }), ...(options.model === undefined ? {} : { model: options.model }), ...(options.facts === undefined ? {} : { facts: options.facts }) };
 }

package/dist/cjs/questions.d.cts

@@ -1,4 +1,4 @@
-import type { ActAnswer, Answer, ChoiceAnswer, DecisionResponse, EvidenceSpan, JsonValue, MultiAnswer, NoulAnswer, Question, ScoreAnswer } from './index.cjs';
+import type { ActAnswer, Answer, ChoiceAnswer, DecisionResponse, EvidenceSpan, JsonValue, MultiAnswer, NoulAnswer, Question, ScoreAnswer, ToolAnswer, ToolDefinition, MultiObjective, DecisionRequest } from './index.cjs';
 /** Required result metadata on the typed path; missing spans become an empty array. */
 export type TypedChoiceAnswer<K extends string = string> = ChoiceAnswer<K> & {
     evidence: EvidenceSpan[];
@@ -19,19 +19,29 @@ export interface EvidenceOptions {
 export interface ChoiceOptions extends EvidenceOptions {
     option_keys?: 'show' | 'hide';
 }
-export interface MultiOptions {
+export interface MultiOptions<K extends string = string> {
     threshold?: number;
     min?: number;
     max?: number;
+    objective?: MultiObjective;
+    exclusive?: readonly K[];
+    fallback?: K;
+    fallback_threshold?: number;
+}
+export interface ToolOptions extends MultiOptions {
+    extra?: readonly ("answer_directly" | "ask_user" | "none")[];
+    rank?: number;
+    multi?: boolean;
+    max_error?: number;
+    /** Tool-description truncation cap; omitted keeps the server default (300), zero disables truncation. */
+    description_chars?: number;
 }
 export interface ActOptions<K extends string = string, A extends string = string> extends EvidenceOptions {
     criteria?: Record<K, string>;
     defer_action?: A;
     max_error?: number;
 }
-export interface DecisionOptions {
-    model?: string;
-    facts?: 'off' | 'auto';
+export interface DecisionOptions extends Pick<DecisionRequest, 'model' | 'facts' | 'lang' | 'media' | 'detail'> {
     signal?: AbortSignal;
 }
 /** Immutable snapshot of a typed question. Use factories or the concrete constructors. */
@@ -52,7 +62,10 @@ export declare class ScoreQuestion extends QuestionSpec<TypedScoreAnswer> {
     constructor(instructions: string, levels: readonly string[], options?: EvidenceOptions);
 }
 export declare class MultiQuestion<K extends string = string> extends QuestionSpec<TypedMultiAnswer<K>> {
-    constructor(instructions: string, values: Record<K, string>, options?: MultiOptions);
+    constructor(instructions: string, values: Record<K, string>, options?: MultiOptions<K>);
+}
+export declare class ToolQuestion extends QuestionSpec<ToolAnswer> {
+    constructor(instructions: string, tools: readonly ToolDefinition[], options?: ToolOptions);
 }
 export declare class ActQuestion<K extends string = 'true' | 'false', A extends string = string> extends QuestionSpec<TypedActAnswer<K, A>> {
     constructor(instructions: string, costs: Record<A, Record<NoInfer<K>, number>>, options?: ActOptions<K, NoInfer<A>>);
@@ -60,8 +73,9 @@ export declare class ActQuestion<K extends string = 'true' | 'false', A extends
 export declare function choice<const K extends string>(instructions: string, values: Record<K, string>, options?: ChoiceOptions): ChoiceQuestion<K>;
 export declare function noul(instructions: string, options?: EvidenceOptions): NoulQuestion;
 export declare function score(instructions: string, levels: readonly string[], options?: EvidenceOptions): ScoreQuestion;
-export declare function multi<const K extends string>(instructions: string, values: Record<K, string>, options?: MultiOptions): MultiQuestion<K>;
+export declare function multi<const K extends string>(instructions: string, values: Record<K, string>, options?: MultiOptions<K>): MultiQuestion<K>;
 export declare function act<const K extends string = 'true' | 'false', const A extends string = string>(instructions: string, costs: Record<A, Record<NoInfer<K>, number>>, options?: ActOptions<K, NoInfer<A>>): ActQuestion<K, A>;
+export declare function tool(instructions: string, tools: readonly ToolDefinition[], options?: ToolOptions): ToolQuestion;
 export type QuestionSet = Record<string, QuestionSpec>;
 export type TypedDecisionResponse<Q extends QuestionSet> = Omit<DecisionResponse, 'answers'> & {
     answers: {
@@ -70,9 +84,4 @@ export type TypedDecisionResponse<Q extends QuestionSet> = Omit<DecisionResponse
     answer<K extends keyof Q & (string | number)>(key: K): Q[K] extends QuestionSpec<infer A> ? A : never;
     raw: DecisionResponse;
 };
-export declare function buildRequest(state: JsonValue, questions: QuestionSet, options: DecisionOptions): {
-    state: JsonValue;
-    questions: Record<string, Question>;
-    model?: string;
-    facts?: 'off' | 'auto';
-};
+export declare function buildRequest(state: JsonValue, questions: QuestionSet, options: DecisionOptions): DecisionRequest;