@itsoltech/basal-client 0.0.0-stage → 0.2.0

package/dist/esm/index.d.ts

@@ -0,0 +1,196 @@
+import { type QuestionSet, type TypedDecisionResponse, type DecisionOptions } from "./questions.js";
+export * from "./questions.js";
+export * from "./media.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 type Calibration = "validated" | "unvalidated" | "text";
+export type MultiObjective = "threshold" | "exact" | "iou" | "f1";
+export interface MediaInput {
+    type: "image" | "audio";
+    data: string;
+}
+export interface MediaUsage {
+    images: number;
+    audio: number;
+    media_tokens: number;
+    detail: "default" | "high";
+}
+export interface ToolRanking {
+    tool: string;
+    probability: number;
+}
+export type ToolDefinition = Record<string, JsonValue>;
+export interface Question {
+    type?: "choice" | "noul" | "score" | "multi" | "act" | "tool";
+    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;
+    objective?: MultiObjective;
+    exclusive?: readonly string[];
+    fallback?: string;
+    fallback_threshold?: number;
+    tools?: readonly ToolDefinition[];
+    extra?: readonly ("answer_directly" | "ask_user" | "none")[];
+    rank?: number;
+    multi?: boolean;
+}
+export interface DecisionRequest {
+    state: JsonValue;
+    questions: Record<string, Question>;
+    model?: string;
+    facts?: "off" | "auto";
+    lang?: "pl" | "en";
+    media?: readonly MediaInput[];
+    detail?: "default" | "high";
+}
+export interface EvidenceSpan {
+    text: string;
+    start: number;
+    end: number;
+    probability: number;
+}
+interface BaseAnswer<K extends string = string> {
+    probabilities: Record<K, number>;
+    evidence?: EvidenceSpan[];
+    calibration?: Calibration;
+}
+export interface ChoiceAnswer<K extends string = string> extends BaseAnswer<K> {
+    type: "choice";
+    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 SelectionResult<K extends string = string> {
+    threshold?: number;
+    objective?: MultiObjective;
+    expected_score?: number | null;
+    constraints_applied?: JsonValue;
+    set_confidence: number;
+}
+export interface MultiAnswer<K extends string = string> extends BaseAnswer<K>, SelectionResult<K> {
+    type: "multi";
+    selected: K[];
+}
+export interface SingleToolAnswer extends BaseAnswer {
+    type: "tool";
+    multi?: false;
+    tool: string | null;
+    call: boolean;
+    confidence: number;
+    ranking?: ToolRanking[];
+    deferred?: boolean;
+    refused?: string;
+    max_error?: string;
+}
+export interface MultiToolAnswer extends BaseAnswer, SelectionResult {
+    type: "tool";
+    multi: true;
+    tools: string[];
+    call: boolean;
+    ranking?: ToolRanking[];
+}
+export type ToolAnswer = SingleToolAnswer | MultiToolAnswer;
+export interface ActAnswer<K extends string = string, A extends string = string> extends BaseAnswer<K> {
+    type: "act";
+    action: A;
+    answer: K;
+    expected_costs: Record<A, number>;
+    confidence: number;
+    calibration: Calibration;
+    refused?: string;
+    max_error?: string;
+    deferred?: boolean;
+}
+export type Answer = ChoiceAnswer | NoulAnswer | ScoreAnswer | MultiAnswer | ActAnswer | ToolAnswer;
+export interface Usage {
+    input_tokens: number;
+    output_tokens: number;
+    questions?: number;
+    branches?: number;
+    latency_ms?: number;
+    longest_prompt_tokens?: number;
+    second_order_branches?: number;
+    media?: MediaUsage;
+}
+export interface DecisionResponse {
+    model: string;
+    answers: Record<string, Answer>;
+    usage: Usage;
+}
+export interface ModelMetadata {
+    name: string;
+    description?: string;
+    release_date?: string;
+    mode?: string;
+    early_exit?: JsonValue[];
+    prompt_format?: number;
+    orders?: JsonValue;
+    temperature_per_prim?: Record<string, number>;
+    media?: ("image" | "audio")[];
+}
+export interface ModelsResponse {
+    models: ModelMetadata[];
+}
+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,193 @@
+import { buildRequest } from "./questions.js";
+export * from "./questions.js";
+export * from "./media.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/media.d.ts

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

package/dist/esm/media.js

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

package/dist/esm/questions.d.ts

@@ -0,0 +1,85 @@
+import type { ActAnswer, Answer, ChoiceAnswer, DecisionResponse, EvidenceSpan, JsonValue, MultiAnswer, NoulAnswer, Question, ScoreAnswer, ToolAnswer, ToolDefinition, MultiObjective, DecisionRequest } 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<K extends string = string> {
+    threshold?: number;
+    min?: number;
+    max?: number;
+    objective?: MultiObjective;
+    exclusive?: readonly K[];
+    fallback?: K;
+    fallback_threshold?: number;
+}
+export interface ToolOptions extends MultiOptions {
+    extra?: readonly ("answer_directly" | "ask_user" | "none")[];
+    rank?: number;
+    multi?: boolean;
+    max_error?: number;
+}
+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 extends Pick<DecisionRequest, 'model' | 'facts' | 'lang' | 'media' | 'detail'> {
+    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<K>);
+}
+export declare class ToolQuestion extends QuestionSpec<ToolAnswer> {
+    constructor(instructions: string, tools: readonly ToolDefinition[], options?: ToolOptions);
+}
+export declare class ActQuestion<K extends string = 'true' | 'false', A extends string = string> extends QuestionSpec<TypedActAnswer<K, A>> {
+    constructor(instructions: string, costs: Record<A, Record<NoInfer<K>, number>>, options?: ActOptions<K, NoInfer<A>>);
+}
+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<K>): MultiQuestion<K>;
+export declare function act<const K extends string = 'true' | 'false', const A extends string = string>(instructions: string, costs: Record<A, Record<NoInfer<K>, number>>, options?: ActOptions<K, NoInfer<A>>): ActQuestion<K, A>;
+export declare function tool(instructions: string, tools: readonly ToolDefinition[], options?: ToolOptions): ToolQuestion;
+export type QuestionSet = Record<string, QuestionSpec>;
+export type TypedDecisionResponse<Q extends QuestionSet> = Omit<DecisionResponse, 'answers'> & {
+    answers: {
+        [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): DecisionRequest;