@itsoltech/basal-client 0.2.0 → 0.3.0

package/README.md

@@ -103,14 +103,28 @@ 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. These SDKs cover server-supported format-2 decisions;
-upstream 2.1 task types are not implemented by this server.
+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}),
+  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

@@ -18,6 +18,7 @@ exports.BasalClient = exports.BasalResponseTooLargeError = exports.BasalProtocol
 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,6 +1,8 @@
 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;
@@ -23,7 +25,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 +37,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 +45,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 +134,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;

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); }

package/dist/cjs/tasks.d.cts

@@ -0,0 +1,108 @@
+import { QuestionSpec } from './questions.cjs';
+import type { DecisionResponse, JsonValue, Question, MultiObjective } from './index.cjs';
+/** Task automation is unknown (null) without a threshold certified for that task/error target. */
+export type Automation = Record<string, boolean | null>;
+export interface ClassifyAnswer<K extends string = string> {
+    type: 'classify';
+    experimental: true;
+    scores: Record<K, number>;
+    label?: K;
+    top_label?: K;
+    confidence?: number;
+    automated?: Automation;
+    labels?: K[];
+    set_confidence?: number;
+}
+export interface ClaimResult {
+    verdict: 'supported' | 'contradicted' | 'not_stated' | 'not_supported';
+    probabilities: Record<string, number>;
+    confidence: number;
+    automated: Automation;
+}
+export interface VerifyAnswer {
+    type: 'verify';
+    experimental: true;
+    claims: Record<string, ClaimResult>;
+    all_supported: boolean;
+    not_supported: string[];
+}
+/** Inclusive start/exclusive end count Unicode code points, not JavaScript UTF-16 units. */
+export interface CompressionUnit {
+    start: number;
+    end: number;
+    probability: number;
+}
+export interface CompressAnswer {
+    type: 'compress';
+    experimental: true;
+    compressed: string;
+    kept: number[];
+    units: CompressionUnit[];
+    unit: 'sentence' | 'line' | 'paragraph';
+    original_chars: number;
+    compressed_chars: number;
+    ratio: number;
+}
+export interface ExtractField {
+    value: JsonValue;
+    confidence: number;
+    source: 'choice' | 'span';
+    calibration: 'validated' | 'per decision';
+    probabilities?: Record<string, number>;
+    present_probability?: number;
+    text?: string;
+    start?: number;
+    end?: number;
+    line_probability?: number;
+    span_probability?: number;
+    error?: string;
+}
+export interface ExtractAnswer {
+    type: 'extract';
+    experimental: true;
+    data: Record<string, JsonValue>;
+    fields: Record<string, ExtractField>;
+}
+export type TaskAnswer = ClassifyAnswer | VerifyAnswer | CompressAnswer | ExtractAnswer;
+export interface ClassifyOptions {
+    multi_label?: boolean;
+    none?: boolean;
+    max_error?: number | readonly number[];
+    option_keys?: 'show' | 'hide';
+    threshold?: number;
+    min?: number;
+    max?: number;
+    objective?: MultiObjective;
+}
+export interface VerifyOptions {
+    binary?: boolean;
+    max_error?: number | readonly number[];
+}
+export interface CompressOptions {
+    unit?: 'sentence' | 'line' | 'paragraph';
+    keep_ratio?: number;
+    threshold?: number;
+    min_keep?: number;
+}
+declare abstract class TaskQuestion<A extends TaskAnswer> extends QuestionSpec<A> {
+    protected constructor(kind: A['type'], text: string, fields: Question);
+    read(response: DecisionResponse, id: string): A;
+}
+export declare class ClassifyQuestion<K extends string = string> extends TaskQuestion<ClassifyAnswer<K>> {
+    constructor(text: string, labels: Record<K, JsonValue> | readonly JsonValue[], options?: ClassifyOptions);
+}
+export declare class VerifyQuestion extends TaskQuestion<VerifyAnswer> {
+    constructor(text: string, claims: Record<string, JsonValue> | readonly JsonValue[], options?: VerifyOptions);
+}
+export declare class CompressQuestion extends TaskQuestion<CompressAnswer> {
+    constructor(text?: string, options?: CompressOptions);
+}
+export declare class ExtractQuestion extends TaskQuestion<ExtractAnswer> {
+    constructor(text: string, schema: Record<string, JsonValue>);
+}
+export declare function classify<const K extends string>(text: string, labels: Record<K, JsonValue>, options?: ClassifyOptions): ClassifyQuestion<K>;
+export declare function classify(text: string, labels: readonly JsonValue[], options?: ClassifyOptions): ClassifyQuestion;
+export declare function verify(text: string, claims: Record<string, JsonValue> | readonly JsonValue[], options?: VerifyOptions): VerifyQuestion;
+export declare function compress(text?: string, options?: CompressOptions): CompressQuestion;
+export declare function extract(text: string, schema: Record<string, JsonValue>): ExtractQuestion;
+export {};

package/dist/esm/index.d.ts

@@ -1,6 +1,8 @@
 import { type QuestionSet, type TypedDecisionResponse, type DecisionOptions } from "./questions.js";
 export * from "./questions.js";
 export * from "./media.js";
+export * from "./tasks.js";
+import type { TaskAnswer } from "./tasks.js";
 /** 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 +25,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 +37,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 +45,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 +134,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;

package/dist/esm/index.js

@@ -1,6 +1,7 @@
 import { buildRequest } from "./questions.js";
 export * from "./questions.js";
 export * from "./media.js";
+export * from "./tasks.js";
 export class BasalError extends Error {
 }
 /** Non-2xx response. Server body and Retry-After are available without logging them. */

package/dist/esm/questions.d.ts

@@ -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/esm/questions.js

@@ -30,13 +30,13 @@ function evidence(options) {
 export 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 = {
@@ -201,6 +201,11 @@ export 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/esm/tasks.d.ts

@@ -0,0 +1,108 @@
+import { QuestionSpec } from './questions.js';
+import type { DecisionResponse, JsonValue, Question, MultiObjective } from './index.js';
+/** Task automation is unknown (null) without a threshold certified for that task/error target. */
+export type Automation = Record<string, boolean | null>;
+export interface ClassifyAnswer<K extends string = string> {
+    type: 'classify';
+    experimental: true;
+    scores: Record<K, number>;
+    label?: K;
+    top_label?: K;
+    confidence?: number;
+    automated?: Automation;
+    labels?: K[];
+    set_confidence?: number;
+}
+export interface ClaimResult {
+    verdict: 'supported' | 'contradicted' | 'not_stated' | 'not_supported';
+    probabilities: Record<string, number>;
+    confidence: number;
+    automated: Automation;
+}
+export interface VerifyAnswer {
+    type: 'verify';
+    experimental: true;
+    claims: Record<string, ClaimResult>;
+    all_supported: boolean;
+    not_supported: string[];
+}
+/** Inclusive start/exclusive end count Unicode code points, not JavaScript UTF-16 units. */
+export interface CompressionUnit {
+    start: number;
+    end: number;
+    probability: number;
+}
+export interface CompressAnswer {
+    type: 'compress';
+    experimental: true;
+    compressed: string;
+    kept: number[];
+    units: CompressionUnit[];
+    unit: 'sentence' | 'line' | 'paragraph';
+    original_chars: number;
+    compressed_chars: number;
+    ratio: number;
+}
+export interface ExtractField {
+    value: JsonValue;
+    confidence: number;
+    source: 'choice' | 'span';
+    calibration: 'validated' | 'per decision';
+    probabilities?: Record<string, number>;
+    present_probability?: number;
+    text?: string;
+    start?: number;
+    end?: number;
+    line_probability?: number;
+    span_probability?: number;
+    error?: string;
+}
+export interface ExtractAnswer {
+    type: 'extract';
+    experimental: true;
+    data: Record<string, JsonValue>;
+    fields: Record<string, ExtractField>;
+}
+export type TaskAnswer = ClassifyAnswer | VerifyAnswer | CompressAnswer | ExtractAnswer;
+export interface ClassifyOptions {
+    multi_label?: boolean;
+    none?: boolean;
+    max_error?: number | readonly number[];
+    option_keys?: 'show' | 'hide';
+    threshold?: number;
+    min?: number;
+    max?: number;
+    objective?: MultiObjective;
+}
+export interface VerifyOptions {
+    binary?: boolean;
+    max_error?: number | readonly number[];
+}
+export interface CompressOptions {
+    unit?: 'sentence' | 'line' | 'paragraph';
+    keep_ratio?: number;
+    threshold?: number;
+    min_keep?: number;
+}
+declare abstract class TaskQuestion<A extends TaskAnswer> extends QuestionSpec<A> {
+    protected constructor(kind: A['type'], text: string, fields: Question);
+    read(response: DecisionResponse, id: string): A;
+}
+export declare class ClassifyQuestion<K extends string = string> extends TaskQuestion<ClassifyAnswer<K>> {
+    constructor(text: string, labels: Record<K, JsonValue> | readonly JsonValue[], options?: ClassifyOptions);
+}
+export declare class VerifyQuestion extends TaskQuestion<VerifyAnswer> {
+    constructor(text: string, claims: Record<string, JsonValue> | readonly JsonValue[], options?: VerifyOptions);
+}
+export declare class CompressQuestion extends TaskQuestion<CompressAnswer> {
+    constructor(text?: string, options?: CompressOptions);
+}
+export declare class ExtractQuestion extends TaskQuestion<ExtractAnswer> {
+    constructor(text: string, schema: Record<string, JsonValue>);
+}
+export declare function classify<const K extends string>(text: string, labels: Record<K, JsonValue>, options?: ClassifyOptions): ClassifyQuestion<K>;
+export declare function classify(text: string, labels: readonly JsonValue[], options?: ClassifyOptions): ClassifyQuestion;
+export declare function verify(text: string, claims: Record<string, JsonValue> | readonly JsonValue[], options?: VerifyOptions): VerifyQuestion;
+export declare function compress(text?: string, options?: CompressOptions): CompressQuestion;
+export declare function extract(text: string, schema: Record<string, JsonValue>): ExtractQuestion;
+export {};

package/dist/esm/tasks.js

@@ -0,0 +1,164 @@
+import { QuestionSpec } from './questions.js';
+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 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);
+    }
+}
+export 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 });
+    }
+}
+export 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 });
+    }
+}
+export 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);
+    }
+}
+export class ExtractQuestion extends TaskQuestion {
+    constructor(text, schema) { object(schema); super('extract', text, { schema }); }
+}
+export function classify(text, labels, options) { return new ClassifyQuestion(text, labels, options); }
+export function verify(text, claims, options) { return new VerifyQuestion(text, claims, options); }
+export function compress(text = '', options) { return new CompressQuestion(text, options); }
+export function extract(text, schema) { return new ExtractQuestion(text, schema); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itsoltech/basal-client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript and JavaScript client for the native Basal HTTP API",
   "type": "module",
   "main": "./dist/cjs/index.cjs",