@itsoltech/basal-client 0.0.0-stage → 0.1.0

package/dist/cjs/questions.cjs

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActQuestion = 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.buildRequest = buildRequest;
+function text(value, name) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError(`${name} must be a nonempty string`);
+    return value;
+}
+function criteria(values, min, max = Infinity) {
+    if (!values || typeof values !== 'object' || Array.isArray(values))
+        throw new TypeError('criteria must be an object');
+    const entries = Object.entries(values);
+    if (entries.length < min || entries.length > max)
+        throw new TypeError('invalid number of criteria');
+    for (const [key, value] of entries) {
+        text(key, 'criterion key');
+        text(value, 'criterion description');
+    }
+    return Object.fromEntries(entries);
+}
+function number(value, name, probability = false) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || (probability && (value < 0 || value > 1))) {
+        throw new TypeError(`invalid ${name}`);
+    }
+    return value;
+}
+function evidence(options) {
+    if (options.evidence !== undefined && typeof options.evidence !== 'boolean')
+        throw new TypeError('evidence must be boolean');
+    return options.evidence ? { evidence: true } : {};
+}
+/** Immutable snapshot of a typed question. Use factories or the concrete constructors. */
+class QuestionSpec {
+    wire;
+    constructor(kind, instructions, fields) {
+        this.wire = structuredClone({ ...fields, type: kind, 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)) {
+            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' },
+            act: { action: 'string', answer: 'string', expected_costs: 'object', confidence: 'number', calibration: 'string' },
+        };
+        const data = answer;
+        for (const [field, kind] of Object.entries(fields[answer.type])) {
+            if (typeof data[field] !== kind || data[field] === null || (kind === 'number' && !Number.isFinite(data[field]))) {
+                throw new TypeError('Basal returned an invalid answer field');
+            }
+        }
+        for (const value of Object.values(answer.probabilities))
+            number(value, 'probability', true);
+        const expectedKeys = this.wire.type === 'noul' || (this.wire.type === 'act' && this.wire.criteria === undefined)
+            ? ['true', 'false'] : Array.isArray(this.wire.criteria)
+            ? this.wire.criteria.map((_, index) => String(index)) : Object.keys(this.wire.criteria ?? {});
+        if (expectedKeys.some(key => !Object.hasOwn(answer.probabilities, key)))
+            throw new TypeError('missing outcome probability');
+        if (answer.evidence !== undefined) {
+            if (!Array.isArray(answer.evidence))
+                throw new TypeError('invalid evidence');
+            for (const span of answer.evidence) {
+                if (!span || typeof span.text !== 'string' || !Number.isSafeInteger(span.start) || !Number.isSafeInteger(span.end)
+                    || span.start < 0 || span.end < 0)
+                    throw new TypeError('invalid evidence span');
+                number(span.probability, 'evidence probability', true);
+            }
+        }
+        if (answer.type === 'choice' && !Object.hasOwn(this.wire.criteria ?? {}, answer.choice))
+            throw new TypeError('unknown choice');
+        if (answer.type === 'multi' && (!Array.isArray(answer.selected) || answer.selected.some(k => typeof k !== 'string' || !Object.hasOwn(this.wire.criteria ?? {}, k))))
+            throw new TypeError('invalid selected labels');
+        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))
+                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 ?? [] }) };
+    }
+}
+exports.QuestionSpec = QuestionSpec;
+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' } : {}) });
+    }
+}
+exports.ChoiceQuestion = ChoiceQuestion;
+class NoulQuestion extends QuestionSpec {
+    constructor(instructions, options = {}) { super('noul', instructions, evidence(options)); }
+}
+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');
+        super('score', instructions, { criteria: levels.map(v => text(v, 'level')), ...evidence(options) });
+    }
+}
+exports.ScoreQuestion = ScoreQuestion;
+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);
+    }
+}
+exports.MultiQuestion = MultiQuestion;
+class ActQuestion extends QuestionSpec {
+    constructor(instructions, costs, options = {}) {
+        const optionsMap = options.criteria === undefined ? undefined : criteria(options.criteria, 2, 10);
+        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');
+        const matrix = {};
+        for (const [action, row] of Object.entries(costs)) {
+            text(action, 'action');
+            if (!row || typeof row !== 'object' || Array.isArray(row) || Object.keys(row).length !== outcomes.length || outcomes.some(k => !Object.hasOwn(row, k)))
+                throw new TypeError('each cost row must cover every outcome exactly');
+            Object.defineProperty(matrix, action, { value: Object.fromEntries(Object.entries(row).map(([k, v]) => [k, number(v, 'cost')])), enumerable: true });
+        }
+        if (options.defer_action !== undefined && !Object.hasOwn(matrix, options.defer_action))
+            throw new TypeError('unknown defer_action');
+        super('act', instructions, { costs: matrix, ...evidence(options), ...(optionsMap ? { criteria: optionsMap } : {}),
+            ...(options.defer_action === undefined ? {} : { defer_action: options.defer_action }),
+            ...(options.max_error === undefined ? {} : { max_error: number(options.max_error, 'max_error', true) }) });
+    }
+}
+exports.ActQuestion = ActQuestion;
+function choice(instructions, values, options) { return new ChoiceQuestion(instructions, values, options); }
+function noul(instructions, options) { return new NoulQuestion(instructions, options); }
+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 buildRequest(state, questions, options) {
+    if (state === null || state === undefined)
+        throw new TypeError('state must not be null/undefined');
+    if (!questions || !Object.keys(questions).length)
+        throw new TypeError('questions must not be empty');
+    if (Object.getOwnPropertySymbols(questions).length)
+        throw new TypeError('question keys must be strings or numbers');
+    const entries = Object.entries(questions).map(([id, q]) => { text(id, 'question ID'); if (!(q instanceof QuestionSpec))
+        throw new TypeError('expected typed question'); return [id, q.toJSON()]; });
+    if (options.model !== undefined)
+        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 }) };
+}

package/dist/cjs/questions.d.cts

@@ -0,0 +1,78 @@
+import type { ActAnswer, Answer, ChoiceAnswer, DecisionResponse, EvidenceSpan, JsonValue, MultiAnswer, NoulAnswer, Question, ScoreAnswer } 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[];
+};
+export type TypedNoulAnswer = NoulAnswer & {
+    evidence: EvidenceSpan[];
+};
+export type TypedScoreAnswer = ScoreAnswer & {
+    evidence: EvidenceSpan[];
+};
+export type TypedMultiAnswer<K extends string = string> = Omit<MultiAnswer<K>, 'evidence'>;
+export type TypedActAnswer<K extends string = string, A extends string = string> = ActAnswer<K, A> & {
+    evidence: EvidenceSpan[];
+};
+export interface EvidenceOptions {
+    evidence?: boolean;
+}
+export interface ChoiceOptions extends EvidenceOptions {
+    option_keys?: 'show' | 'hide';
+}
+export interface MultiOptions {
+    threshold?: number;
+    min?: number;
+    max?: 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';
+    signal?: AbortSignal;
+}
+/** Immutable snapshot of a typed question. Use factories or the concrete constructors. */
+export declare abstract class QuestionSpec<A extends Answer = Answer> {
+    private readonly wire;
+    protected constructor(kind: A['type'], instructions: string, fields: Question);
+    toJSON(): Question;
+    /** Validate and retrieve an answer with this question's result type. */
+    read(response: DecisionResponse, id: string): A;
+}
+export declare class ChoiceQuestion<K extends string = string> extends QuestionSpec<TypedChoiceAnswer<K>> {
+    constructor(instructions: string, values: Record<K, string>, options?: ChoiceOptions);
+}
+export declare class NoulQuestion extends QuestionSpec<TypedNoulAnswer> {
+    constructor(instructions: string, options?: EvidenceOptions);
+}
+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);
+}
+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>>);
+}
+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 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 type QuestionSet = Record<string, QuestionSpec>;
+export type TypedDecisionResponse<Q extends QuestionSet> = Omit<DecisionResponse, 'answers'> & {
+    answers: {
+        [K in keyof Q]: Q[K] extends QuestionSpec<infer A> ? A : never;
+    };
+    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';
+};

package/dist/esm/index.d.ts

@@ -0,0 +1,134 @@
+import { type QuestionSet, type TypedDecisionResponse, type DecisionOptions } from "./questions.js";
+export * from "./questions.js";
+/** Native Basal wire types. Criterion order is significant; do not sort keys. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface Question {
+    type?: "choice" | "noul" | "score" | "multi" | "act";
+    instructions?: JsonValue;
+    criteria?: Record<string, JsonValue> | JsonValue[];
+    levels?: Record<string, JsonValue> | JsonValue[];
+    option_keys?: "show" | "hide";
+    evidence?: boolean;
+    threshold?: number;
+    min?: number;
+    max?: number;
+    base?: "noul" | "choice" | "score";
+    costs?: Record<string, number> | Record<string, Record<string, number>>;
+    defer_action?: string;
+    max_error?: number;
+}
+export interface DecisionRequest {
+    state: JsonValue;
+    questions: Record<string, Question>;
+    model?: string;
+    facts?: "off" | "auto";
+}
+export interface EvidenceSpan {
+    text: string;
+    start: number;
+    end: number;
+    probability: number;
+}
+interface BaseAnswer<K extends string = string> {
+    probabilities: Record<K, number>;
+    evidence?: EvidenceSpan[];
+}
+export interface ChoiceAnswer<K extends string = string> extends BaseAnswer<K> {
+    type: "choice";
+    choice: K;
+    confidence: number;
+}
+export interface NoulAnswer extends BaseAnswer<"true" | "false"> {
+    type: "noul";
+    noul: number;
+    confidence: number;
+}
+export interface ScoreAnswer extends BaseAnswer {
+    type: "score";
+    score: number;
+    legend: Record<string, string>;
+    confidence: number;
+}
+export interface MultiAnswer<K extends string = string> extends BaseAnswer<K> {
+    type: "multi";
+    selected: K[];
+    threshold: number;
+    set_confidence: number;
+}
+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";
+    refused?: string;
+    max_error?: string;
+}
+export type Answer = ChoiceAnswer | NoulAnswer | ScoreAnswer | MultiAnswer | ActAnswer;
+export interface Usage {
+    input_tokens: number;
+    output_tokens: number;
+    questions?: number;
+    branches?: number;
+    latency_ms?: number;
+}
+export interface DecisionResponse {
+    model: string;
+    answers: Record<string, Answer>;
+    usage: Usage;
+}
+export interface ModelMetadata {
+    name: string;
+    description?: string;
+    release_date?: string;
+    mode?: string;
+    early_exit?: JsonValue[];
+}
+export interface ModelsResponse {
+    models: ModelMetadata[];
+}
+export declare class BasalError extends Error {
+}
+/** Non-2xx response. Server body and Retry-After are available without logging them. */
+export declare class BasalHTTPError extends BasalError {
+    readonly statusCode: number;
+    readonly body: unknown;
+    readonly retryAfter: string | null;
+    constructor(statusCode: number, body: unknown, retryAfter: string | null);
+}
+export declare class BasalTransportError extends BasalError {
+}
+export declare class BasalProtocolError extends BasalError {
+}
+export declare class BasalResponseTooLargeError extends BasalError {
+}
+/** Web Fetch input accepted by browsers and server runtimes. */
+export type RequestInput = string | URL | Request;
+/** A transport adapter must honor signal/redirect and return a standard Web Response. */
+export type Fetch = (input: RequestInput, init?: RequestInit) => Promise<Response>;
+export interface BasalClientOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+    /** Defaults to the runtime's native fetch; custom HTTP clients can supply a Fetch adapter. */
+    fetch?: Fetch;
+}
+/** Reusable fetch client. Server root URL, optional proxy prefix, without /v1.
+ * No automatic retries. AbortSignal cancels a request; timeout includes body reading.
+ */
+export declare class BasalClient {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly timeoutMs;
+    private readonly maxResponseBytes;
+    private readonly fetch;
+    constructor(options?: BasalClientOptions);
+    private request;
+    decide(request: DecisionRequest, signal?: AbortSignal): Promise<DecisionResponse>;
+    decide<const Q extends QuestionSet>(state: JsonValue, questions: Q, options?: DecisionOptions): Promise<TypedDecisionResponse<Q>>;
+    models(signal?: AbortSignal): Promise<ModelsResponse>;
+}

package/dist/esm/index.js

@@ -0,0 +1,192 @@
+import { buildRequest } from "./questions.js";
+export * from "./questions.js";
+export class BasalError extends Error {
+}
+/** Non-2xx response. Server body and Retry-After are available without logging them. */
+export class BasalHTTPError extends BasalError {
+    statusCode;
+    body;
+    retryAfter;
+    constructor(statusCode, body, retryAfter) {
+        super(`Basal HTTP ${statusCode}`);
+        this.statusCode = statusCode;
+        this.body = body;
+        this.retryAfter = retryAfter;
+        this.name = "BasalHTTPError";
+        // Node's default inspection and JSON.stringify must not print reflected state or credentials.
+        Object.defineProperty(this, "body", { enumerable: false });
+    }
+}
+export class BasalTransportError extends BasalError {
+}
+export class BasalProtocolError extends BasalError {
+}
+export class BasalResponseTooLargeError extends BasalError {
+}
+async function readBody(response, limit, signal) {
+    // Count bytes from the actual stream, including decompressed responses; never trust Content-Length alone.
+    const reader = response.body?.getReader();
+    if (!reader)
+        return "";
+    const cancel = () => { void reader.cancel().catch(() => { }); };
+    signal.addEventListener("abort", cancel, { once: true });
+    if (signal.aborted)
+        cancel();
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    const parts = [];
+    let bytes = 0;
+    let complete = false;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                complete = true;
+                break;
+            }
+            bytes += value.byteLength;
+            if (bytes > limit) {
+                throw new BasalResponseTooLargeError(`Basal response exceeds ${limit} bytes`);
+            }
+            parts.push(decoder.decode(value, { stream: true }));
+        }
+        parts.push(decoder.decode());
+        return parts.join("");
+    }
+    finally {
+        signal.removeEventListener("abort", cancel);
+        // A decoder/read failure must also stop the underlying HTTP body, before releasing ownership.
+        if (!complete)
+            cancel();
+        reader.releaseLock();
+    }
+}
+/** Reusable fetch client. Server root URL, optional proxy prefix, without /v1.
+ * No automatic retries. AbortSignal cancels a request; timeout includes body reading.
+ */
+export class BasalClient {
+    baseUrl;
+    headers;
+    timeoutMs;
+    maxResponseBytes;
+    fetch;
+    constructor(options = {}) {
+        const url = new URL(options.baseUrl ?? "http://127.0.0.1:8000");
+        if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.href.includes("?") || url.href.includes("#")) {
+            throw new TypeError("baseUrl must be an HTTP(S) server URL without credentials, query or fragment");
+        }
+        if (url.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)) {
+            throw new TypeError("baseUrl requires HTTPS or loopback HTTP (e.g. an SSH tunnel)");
+        }
+        this.baseUrl = url.href.replace(/\/+$/, "") + "/";
+        this.timeoutMs = options.timeoutMs ?? 120_000;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0 || this.timeoutMs > 2_147_483_647) {
+            throw new TypeError("timeoutMs must be positive and at most 2147483647");
+        }
+        this.headers = { Accept: "application/json" };
+        this.maxResponseBytes = options.maxResponseBytes ?? 8 * 1024 * 1024;
+        if (!Number.isSafeInteger(this.maxResponseBytes) || this.maxResponseBytes <= 0) {
+            throw new TypeError("maxResponseBytes must be a positive safe integer");
+        }
+        this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        if (options.apiKey !== undefined) {
+            if (!options.apiKey || /[\r\n]/.test(options.apiKey))
+                throw new TypeError("apiKey must be a nonempty, single-line token");
+            this.headers.Authorization = `Bearer ${options.apiKey}`;
+        }
+    }
+    async request(method, path, body, signal) {
+        // Serialization errors are local input errors, not failures of the HTTP transport.
+        const encoded = body === undefined ? undefined : JSON.stringify(body);
+        const controller = new AbortController();
+        const abort = () => controller.abort(signal?.reason);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        const timer = setTimeout(() => controller.abort(new Error("Basal request timed out")), this.timeoutMs);
+        let onAbort = () => { };
+        const aborted = new Promise((_, reject) => {
+            onAbort = () => reject(new BasalTransportError("Basal HTTP request aborted", { cause: controller.signal.reason }));
+            controller.signal.addEventListener("abort", onAbort, { once: true });
+            if (controller.signal.aborted)
+                onAbort();
+        });
+        const work = async () => {
+            let response;
+            let raw;
+            try {
+                response = await this.fetch(this.baseUrl + path, {
+                    method, headers: body === undefined ? this.headers : { ...this.headers, "Content-Type": "application/json" },
+                    ...(encoded === undefined ? {} : { body: encoded }),
+                    signal: controller.signal, redirect: "error", credentials: "omit", cache: "no-store",
+                });
+                if (response.redirected || ([301, 302, 303, 307, 308].includes(response.status) && response.headers.has("Location"))) {
+                    await response.body?.cancel().catch(() => { });
+                    throw new BasalTransportError("Basal transport returned a redirect");
+                }
+                raw = await readBody(response, this.maxResponseBytes, controller.signal);
+            }
+            catch (cause) {
+                if (cause instanceof BasalError)
+                    throw cause;
+                throw new BasalTransportError("Basal HTTP transport failed", { cause });
+            }
+            let data;
+            try {
+                data = JSON.parse(raw);
+            }
+            catch (cause) {
+                if (response.ok)
+                    throw new BasalProtocolError("Basal returned invalid JSON", { cause });
+                data = raw;
+            }
+            if (!response.ok)
+                throw new BasalHTTPError(response.status, data, response.headers.get("Retry-After"));
+            if (data === null || typeof data !== "object" || Array.isArray(data)) {
+                throw new BasalProtocolError("Basal returned a JSON value other than an object");
+            }
+            return data;
+        };
+        try {
+            if (controller.signal.aborted)
+                return await aborted;
+            return await Promise.race([work(), aborted]);
+        }
+        finally {
+            controller.signal.removeEventListener("abort", onAbort);
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+    async decide(state, questionsOrSignal, options = {}) {
+        if (questionsOrSignal === undefined || ("aborted" in questionsOrSignal && typeof questionsOrSignal.addEventListener === "function")) {
+            return this.request("POST", "v1/basal", state, questionsOrSignal);
+        }
+        const questions = { ...questionsOrSignal };
+        const response = await this.request("POST", "v1/basal", buildRequest(state, questions, options), options.signal);
+        const parsed = new Map();
+        try {
+            if (typeof response.model !== "string" || !response.model || !response.usage || Array.isArray(response.usage)
+                || !Number.isSafeInteger(response.usage.input_tokens) || response.usage.input_tokens < 0
+                || !Number.isSafeInteger(response.usage.output_tokens) || response.usage.output_tokens < 0
+                || !response.answers || Array.isArray(response.answers))
+                throw new TypeError("invalid decision envelope");
+            for (const [id, question] of Object.entries(questions))
+                parsed.set(id, question.read(response, id));
+        }
+        catch (cause) {
+            throw new BasalProtocolError("Invalid typed Basal answer", { cause });
+        }
+        const typed = { ...response, answers: Object.fromEntries(parsed) };
+        Object.defineProperty(typed, "raw", { value: response });
+        Object.defineProperty(typed, "answer", { value: (key) => {
+                if (typeof key !== "string" && typeof key !== "number")
+                    throw new TypeError("answer key must be a string or number");
+                const answer = parsed.get(String(key));
+                if (answer === undefined)
+                    throw new TypeError("answer key was not part of this response");
+                return answer;
+            } });
+        return typed;
+    }
+    models(signal) { return this.request("GET", "v1/models", undefined, signal); }
+}

package/dist/esm/questions.d.ts

@@ -0,0 +1,78 @@
+import type { ActAnswer, Answer, ChoiceAnswer, DecisionResponse, EvidenceSpan, JsonValue, MultiAnswer, NoulAnswer, Question, ScoreAnswer } from './index.js';
+/** Required result metadata on the typed path; missing spans become an empty array. */
+export type TypedChoiceAnswer<K extends string = string> = ChoiceAnswer<K> & {
+    evidence: EvidenceSpan[];
+};
+export type TypedNoulAnswer = NoulAnswer & {
+    evidence: EvidenceSpan[];
+};
+export type TypedScoreAnswer = ScoreAnswer & {
+    evidence: EvidenceSpan[];
+};
+export type TypedMultiAnswer<K extends string = string> = Omit<MultiAnswer<K>, 'evidence'>;
+export type TypedActAnswer<K extends string = string, A extends string = string> = ActAnswer<K, A> & {
+    evidence: EvidenceSpan[];
+};
+export interface EvidenceOptions {
+    evidence?: boolean;
+}
+export interface ChoiceOptions extends EvidenceOptions {
+    option_keys?: 'show' | 'hide';
+}
+export interface MultiOptions {
+    threshold?: number;
+    min?: number;
+    max?: 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';
+    signal?: AbortSignal;
+}
+/** Immutable snapshot of a typed question. Use factories or the concrete constructors. */
+export declare abstract class QuestionSpec<A extends Answer = Answer> {
+    private readonly wire;
+    protected constructor(kind: A['type'], instructions: string, fields: Question);
+    toJSON(): Question;
+    /** Validate and retrieve an answer with this question's result type. */
+    read(response: DecisionResponse, id: string): A;
+}
+export declare class ChoiceQuestion<K extends string = string> extends QuestionSpec<TypedChoiceAnswer<K>> {
+    constructor(instructions: string, values: Record<K, string>, options?: ChoiceOptions);
+}
+export declare class NoulQuestion extends QuestionSpec<TypedNoulAnswer> {
+    constructor(instructions: string, options?: EvidenceOptions);
+}
+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);
+}
+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>>);
+}
+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 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 type QuestionSet = Record<string, QuestionSpec>;
+export type TypedDecisionResponse<Q extends QuestionSet> = Omit<DecisionResponse, 'answers'> & {
+    answers: {
+        [K in keyof Q]: Q[K] extends QuestionSpec<infer A> ? A : never;
+    };
+    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';
+};