@itsoltech/basal-client 0.2.0 → 0.4.0

package/dist/cjs/index.cjs

@@ -14,48 +14,26 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BasalClient = exports.BasalResponseTooLargeError = exports.BasalProtocolError = exports.BasalTransportError = exports.BasalHTTPError = exports.BasalError = void 0;
+exports.BasalClient = exports.parseBatchResults = exports.batchInput = void 0;
 const questions_cjs_1 = require("./questions.cjs");
+const errors_cjs_1 = require("./errors.cjs");
+const batches_cjs_1 = require("./batches.cjs");
 __exportStar(require("./questions.cjs"), exports);
 __exportStar(require("./media.cjs"), exports);
-class BasalError extends Error {
-}
-exports.BasalError = BasalError;
-/** Non-2xx response. Server body and Retry-After are available without logging them. */
-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 });
-    }
-}
-exports.BasalHTTPError = BasalHTTPError;
-class BasalTransportError extends BasalError {
-}
-exports.BasalTransportError = BasalTransportError;
-class BasalProtocolError extends BasalError {
-}
-exports.BasalProtocolError = BasalProtocolError;
-class BasalResponseTooLargeError extends BasalError {
-}
-exports.BasalResponseTooLargeError = BasalResponseTooLargeError;
+__exportStar(require("./tasks.cjs"), exports);
+__exportStar(require("./errors.cjs"), exports);
+var batches_cjs_2 = require("./batches.cjs");
+Object.defineProperty(exports, "batchInput", { enumerable: true, get: function () { return batches_cjs_2.batchInput; } });
+Object.defineProperty(exports, "parseBatchResults", { enumerable: true, get: function () { return batches_cjs_2.parseBatchResults; } });
 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 "";
+        return new Uint8Array();
     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;
@@ -68,20 +46,38 @@ async function readBody(response, limit, signal) {
             }
             bytes += value.byteLength;
             if (bytes > limit) {
-                throw new BasalResponseTooLargeError(`Basal response exceeds ${limit} bytes`);
+                throw new errors_cjs_1.BasalResponseTooLargeError(`Basal response exceeds ${limit} bytes`);
             }
-            parts.push(decoder.decode(value, { stream: true }));
+            parts.push(value);
         }
-        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.
+        // A read failure must also stop the underlying HTTP body, before releasing ownership.
         if (!complete)
             cancel();
         reader.releaseLock();
     }
+    if (parts.length === 1)
+        return parts[0];
+    const out = new Uint8Array(bytes);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.byteLength;
+    }
+    return out;
+}
+function positiveTimeout(value, name) {
+    if (!Number.isFinite(value) || value <= 0 || value > 2_147_483_647) {
+        throw new TypeError(`${name} must be positive and at most 2147483647`);
+    }
+    return value;
+}
+function byteLimit(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new TypeError(`${name} must be a positive safe integer`);
+    return value;
 }
 /** Reusable fetch client. Server root URL, optional proxy prefix, without /v1.
  * No automatic retries. AbortSignal cancels a request; timeout includes body reading.
@@ -117,55 +113,79 @@ class BasalClient {
             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);
+    request(method, path, body, signal) {
+        return this.call({ method, path, json: body, signal });
+    }
+    async call(call) {
+        // Serialization and option errors are local input errors, not failures of the HTTP transport.
+        const encoded = call.json === undefined ? undefined : JSON.stringify(call.json);
+        const timeoutMs = call.timeoutMs === undefined ? this.timeoutMs : positiveTimeout(call.timeoutMs, "timeoutMs");
+        const limit = call.maxBytes === undefined ? this.maxResponseBytes : byteLimit(call.maxBytes, "maxBytes");
+        const headers = { ...this.headers, ...call.headers };
+        if (encoded !== undefined)
+            headers["Content-Type"] = "application/json";
+        const { signal } = call;
         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);
+        const timer = setTimeout(() => controller.abort(new Error("Basal request timed out")), timeoutMs);
         let onAbort = () => { };
         const aborted = new Promise((_, reject) => {
-            onAbort = () => reject(new BasalTransportError("Basal HTTP request aborted", { cause: controller.signal.reason }));
+            onAbort = () => reject(new errors_cjs_1.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;
+            let content;
+            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",
-                });
+                const init = {
+                    method: call.method, headers, signal: controller.signal, redirect: "error", credentials: "omit", cache: "no-store",
+                };
+                if (encoded !== undefined)
+                    init.body = encoded;
+                else if (call.body instanceof Blob)
+                    init.body = call.body;
+                else if (call.body !== undefined) {
+                    // Streamed request bodies require half-duplex fetch (Node.js, Chromium over HTTP/2).
+                    init.body = call.body(controller.signal);
+                    init.duplex = "half";
+                }
+                response = await this.fetch(this.baseUrl + call.path, init);
                 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");
+                    throw new errors_cjs_1.BasalTransportError("Basal transport returned a redirect");
                 }
-                raw = await readBody(response, this.maxResponseBytes, controller.signal);
+                // A per-download cap limits successful artifact bytes. Error envelopes retain the client's normal cap
+                // so a small artifact cap does not hide an actionable 404/429 and its Retry-After.
+                content = await readBody(response, response.ok ? limit : this.maxResponseBytes, controller.signal);
+                if (!call.bytes || !response.ok)
+                    raw = new TextDecoder("utf-8", { fatal: true }).decode(content);
             }
             catch (cause) {
-                if (cause instanceof BasalError)
+                if (cause instanceof errors_cjs_1.BasalError)
                     throw cause;
-                throw new BasalTransportError("Basal HTTP transport failed", { cause });
+                throw new errors_cjs_1.BasalTransportError("Basal HTTP transport failed", { cause });
             }
+            if (call.bytes && response.ok)
+                return content;
             let data;
             try {
                 data = JSON.parse(raw);
             }
             catch (cause) {
                 if (response.ok)
-                    throw new BasalProtocolError("Basal returned invalid JSON", { cause });
+                    throw new errors_cjs_1.BasalProtocolError("Basal returned invalid JSON", { cause });
                 data = raw;
             }
             if (!response.ok)
-                throw new BasalHTTPError(response.status, data, response.headers.get("Retry-After"));
+                throw new errors_cjs_1.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");
+                throw new errors_cjs_1.BasalProtocolError("Basal returned a JSON value other than an object");
             }
             return data;
         };
@@ -178,6 +198,9 @@ class BasalClient {
             controller.signal.removeEventListener("abort", onAbort);
             clearTimeout(timer);
             signal?.removeEventListener("abort", abort);
+            // An answer can arrive before a streamed upload is fully sent (e.g. 413); stop its source.
+            if (typeof call.body === "function")
+                controller.abort(new Error("Basal request finished"));
         }
     }
     async decide(state, questionsOrSignal, options = {}) {
@@ -197,7 +220,7 @@ class BasalClient {
                 parsed.set(id, question.read(response, id));
         }
         catch (cause) {
-            throw new BasalProtocolError("Invalid typed Basal answer", { cause });
+            throw new errors_cjs_1.BasalProtocolError("Invalid typed Basal answer", { cause });
         }
         const typed = { ...response, answers: Object.fromEntries(parsed) };
         Object.defineProperty(typed, "raw", { value: response });
@@ -212,5 +235,46 @@ class BasalClient {
         return typed;
     }
     models(signal) { return this.request("GET", "v1/models", undefined, signal); }
+    /** Upload a JSONL input file (`purpose=batch`) from caller-owned bytes, a Blob or a stream; never fetches URLs. */
+    async uploadFile(request, options = {}) {
+        const form = (0, batches_cjs_1.uploadForm)(request);
+        return await this.call({
+            method: "POST", path: "v1/files", body: form.body, headers: { "Content-Type": form.contentType },
+            signal: options.signal, timeoutMs: options.timeoutMs,
+        });
+    }
+    async listFiles(options = {}) {
+        return await this.call({ method: "GET", path: (0, batches_cjs_1.listPath)("v1/files", options), signal: options.signal });
+    }
+    async getFile(fileId, options = {}) {
+        return await this.call({ method: "GET", path: (0, batches_cjs_1.resourcePath)("v1/files", fileId), signal: options.signal });
+    }
+    async deleteFile(fileId, options = {}) {
+        return await this.call({ method: "DELETE", path: (0, batches_cjs_1.resourcePath)("v1/files", fileId), signal: options.signal });
+    }
+    /** Raw file bytes (JSONL), buffered up to `maxBytes` (default `maxResponseBytes`); never JSON-parsed. */
+    async downloadFile(fileId, options = {}) {
+        return await this.call({
+            method: "GET", path: (0, batches_cjs_1.resourcePath)("v1/files", fileId, "/content"), bytes: true,
+            headers: { Accept: "application/jsonl, application/json" },
+            signal: options.signal, timeoutMs: options.timeoutMs, maxBytes: options.maxBytes,
+        });
+    }
+    async createBatch(request, options = {}) {
+        const headers = (0, batches_cjs_1.idempotencyHeader)(options.idempotencyKey);
+        return await this.call({ method: "POST", path: "v1/batches", json: (0, batches_cjs_1.createBody)(request), headers, signal: options.signal });
+    }
+    async listBatches(options = {}) {
+        const { after, limit } = options;
+        const query = { ...(after === undefined ? {} : { after }), ...(limit === undefined ? {} : { limit }) };
+        return await this.call({ method: "GET", path: (0, batches_cjs_1.listPath)("v1/batches", query), signal: options.signal });
+    }
+    async getBatch(batchId, options = {}) {
+        return await this.call({ method: "GET", path: (0, batches_cjs_1.resourcePath)("v1/batches", batchId), signal: options.signal });
+    }
+    /** Request cancellation; the batch moves to `cancelling` and later `cancelled`. Does not wait. */
+    async cancelBatch(batchId, options = {}) {
+        return await this.call({ method: "POST", path: (0, batches_cjs_1.resourcePath)("v1/batches", batchId, "/cancel"), signal: options.signal });
+    }
 }
 exports.BasalClient = BasalClient;

package/dist/cjs/index.d.cts

@@ -1,6 +1,12 @@
 import { type QuestionSet, type TypedDecisionResponse, type DecisionOptions } from "./questions.cjs";
+import { type Batch, type BatchList, type CreateBatchOptions, type CreateBatchRequest, type DeletedFile, type DownloadOptions, type FileList, type FileObject, type ListFilesOptions, type ListOptions, type RequestOptions, type TransferOptions, type UploadFileRequest } from "./batches.cjs";
 export * from "./questions.cjs";
 export * from "./media.cjs";
+export * from "./tasks.cjs";
+export * from "./errors.cjs";
+export { batchInput, parseBatchResults } from "./batches.cjs";
+export type { Batch, BatchErrorCode, BatchErrorEntry, BatchErrors, BatchInputLine, BatchList, BatchResultLine, BatchStatus, CreateBatchOptions, CreateBatchRequest, DeletedFile, DownloadOptions, ExpiresAfter, FileList, FileObject, FilePurpose, ListFilesOptions, ListOptions, ListPage, Metadata, RequestCounts, RequestOptions, TransferOptions, UploadContent, UploadFileRequest, } from "./batches.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;
@@ -23,7 +29,7 @@ export interface ToolRanking {
 }
 export type ToolDefinition = Record<string, JsonValue>;
 export interface Question {
-    type?: "choice" | "noul" | "score" | "multi" | "act" | "tool";
+    type?: "choice" | "noul" | "score" | "multi" | "act" | "tool" | "classify" | "verify" | "compress" | "extract";
     instructions?: JsonValue;
     criteria?: Record<string, JsonValue> | JsonValue[];
     levels?: Record<string, JsonValue> | JsonValue[];
@@ -35,7 +41,7 @@ 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;
@@ -43,7 +49,17 @@ export interface Question {
     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;
@@ -122,7 +138,7 @@ export interface ActAnswer<K extends string = string, A extends string = string>
     max_error?: string;
     deferred?: boolean;
 }
-export type Answer = ChoiceAnswer | NoulAnswer | ScoreAnswer | MultiAnswer | ActAnswer | ToolAnswer;
+export type Answer = ChoiceAnswer | NoulAnswer | ScoreAnswer | MultiAnswer | ActAnswer | ToolAnswer | TaskAnswer;
 export interface Usage {
     input_tokens: number;
     output_tokens: number;
@@ -152,21 +168,6 @@ export interface ModelMetadata {
 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. */
@@ -190,7 +191,20 @@ export declare class BasalClient {
     private readonly fetch;
     constructor(options?: BasalClientOptions);
     private request;
+    private call;
     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>;
+    /** Upload a JSONL input file (`purpose=batch`) from caller-owned bytes, a Blob or a stream; never fetches URLs. */
+    uploadFile(request: UploadFileRequest, options?: TransferOptions): Promise<FileObject>;
+    listFiles(options?: ListFilesOptions): Promise<FileList>;
+    getFile(fileId: string, options?: RequestOptions): Promise<FileObject>;
+    deleteFile(fileId: string, options?: RequestOptions): Promise<DeletedFile>;
+    /** Raw file bytes (JSONL), buffered up to `maxBytes` (default `maxResponseBytes`); never JSON-parsed. */
+    downloadFile(fileId: string, options?: DownloadOptions): Promise<Uint8Array>;
+    createBatch(request: CreateBatchRequest, options?: CreateBatchOptions): Promise<Batch>;
+    listBatches(options?: ListOptions): Promise<BatchList>;
+    getBatch(batchId: string, options?: RequestOptions): Promise<Batch>;
+    /** Request cancellation; the batch moves to `cancelling` and later `cancelled`. Does not wait. */
+    cancelBatch(batchId: string, options?: RequestOptions): Promise<Batch>;
 }

package/dist/cjs/questions.cjs

@@ -40,13 +40,13 @@ 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 = {
@@ -216,6 +216,11 @@ class ToolQuestion extends QuestionSpec {
         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');

package/dist/cjs/questions.d.cts

@@ -33,6 +33,8 @@ export interface ToolOptions extends MultiOptions {
     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>;

package/dist/cjs/tasks.cjs

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtractQuestion = exports.CompressQuestion = exports.VerifyQuestion = exports.ClassifyQuestion = void 0;
+exports.classify = classify;
+exports.verify = verify;
+exports.compress = compress;
+exports.extract = extract;
+const questions_cjs_1 = require("./questions.cjs");
+function object(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        throw new TypeError('expected task object');
+    return v;
+}
+function probability(v) { if (typeof v !== 'number' || !Number.isFinite(v) || v < 0 || v > 1)
+    throw new TypeError('invalid probability'); }
+function probabilities(v) { for (const n of Object.values(object(v)))
+    probability(n); }
+function automation(v) { if (Object.values(object(v)).some(n => n !== null && typeof n !== 'boolean'))
+    throw new TypeError('invalid automation'); }
+function strings(v) { if (!Array.isArray(v) || v.some(k => typeof k !== 'string'))
+    throw new TypeError('expected string list'); }
+function offset(v) { if (!Number.isSafeInteger(v) || v < 0)
+    throw new TypeError('invalid Unicode code point offset/count'); }
+function span(v) { offset(v.start); offset(v.end); if (v.end < v.start)
+    throw new TypeError('reversed source span'); }
+function risks(v) {
+    if (v === undefined)
+        return;
+    const a = Array.isArray(v) ? v : [v];
+    if (a.length > 64 || a.some(n => typeof n !== 'number' || !Number.isFinite(n) || n <= 0 || n >= 1))
+        throw new TypeError('invalid max_error');
+}
+function instructions(v) { if (typeof v !== 'string')
+    throw new TypeError('instructions must be a string'); return v; }
+class TaskQuestion extends questions_cjs_1.QuestionSpec {
+    constructor(kind, text, fields) { super(kind, instructions(text), fields); }
+    read(response, id) {
+        const d = object(response.answers?.[id]);
+        if (d.type !== this.toJSON().type || d.experimental !== true)
+            throw new TypeError('Basal returned a missing or mismatched task');
+        if (d.type === 'classify') {
+            probabilities(d.scores);
+            const scores = object(d.scores);
+            if (this.toJSON().multi_label) {
+                strings(d.labels);
+                if (d.labels.some(k => !Object.hasOwn(scores, k)))
+                    throw new TypeError('unknown label');
+                probability(d.set_confidence);
+            }
+            else {
+                if (typeof d.label !== 'string' || !Object.hasOwn(scores, d.label) || d.top_label !== d.label)
+                    throw new TypeError('invalid label');
+                probability(d.confidence);
+                automation(d.automated);
+            }
+        }
+        else if (d.type === 'verify') {
+            const claims = object(d.claims);
+            for (const raw of Object.values(claims)) {
+                const c = object(raw);
+                const p = object(c.probabilities);
+                probabilities(p);
+                if (typeof c.verdict !== 'string' || !['supported', 'contradicted', 'not_stated', 'not_supported'].includes(c.verdict) || !Object.hasOwn(p, c.verdict))
+                    throw new TypeError('invalid verdict');
+                probability(c.confidence);
+                automation(c.automated);
+            }
+            strings(d.not_supported);
+            if (typeof d.all_supported !== 'boolean' || d.not_supported.some(k => !Object.hasOwn(claims, k)))
+                throw new TypeError('invalid verification summary');
+        }
+        else if (d.type === 'compress') {
+            if (typeof d.compressed !== 'string' || !['sentence', 'line', 'paragraph'].includes(d.unit) || !Array.isArray(d.units) || !Array.isArray(d.kept))
+                throw new TypeError('invalid compression');
+            for (const u of d.units) {
+                const v = object(u);
+                span(v);
+                probability(v.probability);
+            }
+            for (const k of d.kept) {
+                offset(k);
+                if (k >= d.units.length)
+                    throw new TypeError('invalid kept unit');
+            }
+            offset(d.original_chars);
+            offset(d.compressed_chars);
+            if (typeof d.ratio !== 'number' || !Number.isFinite(d.ratio) || d.ratio < 0)
+                throw new TypeError('invalid ratio');
+        }
+        else {
+            object(d.data);
+            for (const raw of Object.values(object(d.fields))) {
+                const f = object(raw);
+                if (!Object.hasOwn(f, 'value') || !['choice', 'span'].includes(f.source) || !['validated', 'per decision'].includes(f.calibration))
+                    throw new TypeError('invalid extraction field');
+                probability(f.confidence);
+                if (f.probabilities !== undefined)
+                    probabilities(f.probabilities);
+                for (const k of ['present_probability', 'line_probability', 'span_probability'])
+                    if (f[k] !== undefined)
+                        probability(f[k]);
+                if (f.text !== undefined) {
+                    if (typeof f.text !== 'string')
+                        throw new TypeError('invalid source text');
+                    span(f);
+                }
+            }
+        }
+        return structuredClone(d);
+    }
+}
+class ClassifyQuestion extends TaskQuestion {
+    constructor(text, labels, options = {}) {
+        if (!labels || typeof labels !== 'object' || Object.keys(labels).length < 1 || Object.keys(labels).length > 256)
+            throw new TypeError('classify requires 1..256 labels');
+        risks(options.max_error);
+        for (const k of ['multi_label', 'none'])
+            if (options[k] !== undefined && typeof options[k] !== 'boolean')
+                throw new TypeError(`invalid ${k}`);
+        if (options.option_keys !== undefined && !['show', 'hide'].includes(options.option_keys))
+            throw new TypeError('invalid option_keys');
+        if (options.threshold !== undefined) {
+            probability(options.threshold);
+            if (options.objective !== undefined && options.objective !== 'threshold')
+                throw new TypeError('threshold requires threshold objective');
+        }
+        for (const k of ['min', 'max'])
+            if (options[k] !== undefined)
+                offset(options[k]);
+        if (options.min !== undefined && options.max !== undefined && options.min > options.max)
+            throw new TypeError('min exceeds max');
+        if (options.objective !== undefined && !['threshold', 'exact', 'iou', 'f1'].includes(options.objective))
+            throw new TypeError('invalid objective');
+        if (!options.multi_label && ['threshold', 'min', 'max', 'objective'].some(k => Object.hasOwn(options, k)))
+            throw new TypeError('selection options require multi_label');
+        super('classify', text, { labels: structuredClone(labels), ...options });
+    }
+}
+exports.ClassifyQuestion = ClassifyQuestion;
+class VerifyQuestion extends TaskQuestion {
+    constructor(text, claims, options = {}) {
+        if (!claims || typeof claims !== 'object' || !Object.keys(claims).length)
+            throw new TypeError('verify requires claims');
+        risks(options.max_error);
+        if (options.binary !== undefined && typeof options.binary !== 'boolean')
+            throw new TypeError('invalid binary');
+        super('verify', text, { claims: structuredClone(claims), ...options });
+    }
+}
+exports.VerifyQuestion = VerifyQuestion;
+class CompressQuestion extends TaskQuestion {
+    constructor(text = '', options = {}) {
+        if (options.unit !== undefined && !['sentence', 'line', 'paragraph'].includes(options.unit))
+            throw new TypeError('invalid unit');
+        if (options.keep_ratio !== undefined) {
+            probability(options.keep_ratio);
+            if (options.keep_ratio === 0)
+                throw new TypeError('keep_ratio must be positive');
+        }
+        if (options.threshold !== undefined)
+            probability(options.threshold);
+        if (options.min_keep !== undefined)
+            offset(options.min_keep);
+        super('compress', text, options);
+    }
+}
+exports.CompressQuestion = CompressQuestion;
+class ExtractQuestion extends TaskQuestion {
+    constructor(text, schema) { object(schema); super('extract', text, { schema }); }
+}
+exports.ExtractQuestion = ExtractQuestion;
+function classify(text, labels, options) { return new ClassifyQuestion(text, labels, options); }
+function verify(text, claims, options) { return new VerifyQuestion(text, claims, options); }
+function compress(text = '', options) { return new CompressQuestion(text, options); }
+function extract(text, schema) { return new ExtractQuestion(text, schema); }