@itsoltech/basal-client 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,39 @@
+basal-rs
+Copyright 2026 basal-rs contributors
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+This project reimplements in Rust the inference protocol of basal
+(https://github.com/rkinas/basal, Copyright 2026 Remigiusz Kinas, Apache License 2.0) and ports parts of it:
+the prompt format and letter readout (basal/prompt.py), the System One request handling and answer semantics
+including multi and act (basal/server.py), facts injection (basal/facts.py -> crates/basal-core/src/facts.rs),
+evidence spans (basal/evidence.py -> crates/basal-core/src/evidence.rs) and shared-prefix packing (basal/engine.py).
+Reference requests in tools/reference include examples from basal/examples.
+
+The basal model weights (Remek/basal-1.0-*, Remek/basal-1.5-*) are not part of this repository; they are released by
+their author under the Apache License 2.0.
+
+The NOTICE file of basal (v1.5.0) follows.
+
+--------------------------------------------------------------------------------
+
+basal
+Copyright 2026 Remigiusz Kinas
+
+This product includes models fine-tuned from the following works, licensed under the Apache License, Version 2.0:
+
+  basal-1.5-4.5B  <- speakleash/Bielik-4.5B-v3.0-Instruct  (https://huggingface.co/speakleash/Bielik-4.5B-v3.0-Instruct)
+  basal-1.5-max   <- speakleash/Bielik-PL-11B-v3.0-Instruct  (https://huggingface.co/speakleash/Bielik-PL-11B-v3.0-Instruct)
+  basal-1.5-mini  <- speakleash/Bielik-1.5B-v3.0-Instruct  (https://huggingface.co/speakleash/Bielik-1.5B-v3.0-Instruct)
+  basal-1.0-4.5B  <- speakleash/Bielik-4.5B-v3.0-Instruct  (https://huggingface.co/speakleash/Bielik-4.5B-v3.0-Instruct)
+  basal-1.0-1.5B  <- speakleash/Bielik-1.5B-v3.0-Instruct  (https://huggingface.co/speakleash/Bielik-1.5B-v3.0-Instruct)
+
+The inference engine in this repository is original work licensed under the Apache License, Version 2.0.
+
+Training data attribution (basal-1.0 models):
+  English decision items in the training data were converted from the public corpus
+  avbiswas/bev-decision-150K (https://huggingface.co/datasets/avbiswas/bev-decision-150K), which aggregates questions
+  derived from many upstream sources. Its maintainers ask users to check and attribute those upstream sources; row-level
+  source identifiers are not available, so the upstream sources of these items are not documented individually.
+
+basal-1.5 models: released under the Apache License, Version 2.0.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# @itsoltech/basal-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript/JavaScript SDK for the native Basal API (`POST /v1/basal`). ESM and CommonJS, with type declarations.
+Node.js 22+ or modern browsers with `fetch` and `AbortController`. No runtime dependencies or GPU requirement.
+
+This package is versioned independently. Release tag: `sdk-typescript-vX.Y.Z`.
+[Changelog](https://github.com/itsoltech/basal-rs/blob/main/sdk/typescript/CHANGELOG.md).
+
+```sh
+npm i @itsoltech/basal-client
+```
+
+```typescript
+import { BasalClient, choice, noul } from "@itsoltech/basal-client";
+
+const client = new BasalClient({ baseUrl: "http://127.0.0.1:8000" });
+const response = await client.decide("Klient prosi o zwrot pieniędzy za uszkodzony telefon.", {
+  department: choice("Do którego działu skierować zgłoszenie?", { returns: "Zwroty", support: "Wsparcie techniczne" }),
+  urgent: noul("Czy sprawa jest pilna?"),
+});
+console.log(response.answers.department.choice); // "returns" | "support"
+console.log(response.answers.urgent.noul);        // number
+```
+
+CommonJS: `const { BasalClient } = require("@itsoltech/basal-client")`.
+
+The transport uses the standard Web Fetch contract, in browsers and on the backend:
+
+```typescript
+import { BasalClient, type Fetch, type RequestInput } from "@itsoltech/basal-client";
+
+const transport: Fetch = async (input: RequestInput, init?: RequestInit): Promise<Response> => {
+  const request = new Request(input, init);
+  return fetch(request);
+};
+const client = new BasalClient({ baseUrl: "https://basal.example.com", fetch: transport });
+```
+
+`RequestInput = string | URL | Request`. An adapter for another HTTP client must return a Web `Response`
+with status, headers and a readable body, and honor cancellation, `redirect: "error"`, TLS verification,
+and `credentials: "omit"`. Those requirements apply to the adapter's HTTP client too. The default is
+native `fetch`; no adapter or polyfill dependency is installed by this package. A pre-aborted signal
+rejects before dispatch; the SDK deadline rejects even if an adapter fails to honor cancellation,
+but such an adapter may continue its own network I/O.
+
+`models()` reads `/v1/models`. Each method optionally takes an `AbortSignal`.
+`timeoutMs` includes response-body reading. `apiKey` optionally sends a bearer token to a reverse proxy.
+Use the server root (possibly with a proxy prefix), without `/v1`. HTTPS is required except for loopback
+HTTP (localhost, 127.0.0.1, ::1), suitable for a local server or SSH tunnel. URL credentials/query/fragment
+are rejected. Requests omit cookies and use `cache: "no-store"`.
+`maxResponseBytes` defaults to 8 MiB and limits the actual streamed body, including HTTP errors;
+oversized responses raise `BasalResponseTooLargeError`.
+
+`BasalHTTPError` provides `statusCode`, `body` and the raw `retryAfter` header. Transport failures raise
+`BasalTransportError`; malformed successful JSON raises `BasalProtocolError`. Original causes are kept
+in `cause`. `BasalHTTPError.body` remains directly accessible but is non-enumerable, so default Node
+inspection and JSON.stringify do not log it. There are no automatic retries or redirects. Types describe the native contract; successful
+responses are checked to be JSON objects without full schema validation. Unknown JSON fields are preserved.
+
+Supports `choice`, `noul`, `score`, `multi`, `act`, `facts` and `evidence`. Native choice/score accepts 2–10
+options. Criterion insertion order matters; JavaScript enumerates integer-like object keys numerically,
+so use textual keys (e.g. `low`, `high`) or an ordered score array. Evidence offsets count Unicode code
+points; use the returned text, or `Array.from(state).slice(start, end).join("")` for textual states.
+
+In browsers, the server/proxy must support your origin through CORS. Basal-rs does not enable CORS by default.
+Keep private API keys in server-side code.
+
+Factories and concrete classes cover `choice`, `noul`, `score`, `multi`, `act`. The two-argument
+`decide(state, questions, {model, facts, signal})` infers exact question IDs, answer types, choice keys
+and selected-label keys. Keep the inferred object type instead of widening it to `QuestionSet`.
+`response.answer("department")` also infers the answer from its request key. The same question
+definition can be reused under different keys; each key retains its own answer. `answer()` takes
+a key, not a question object (changed before the initial release). Required fields are
+validated before the promise resolves. Typed evidence defaults to an empty array; `response.raw`
+retains the native JSON without those defaults. The one-argument raw `decide(request, signal)` remains available.
+
+
+[Full documentation and publication setup](https://github.com/itsoltech/basal-rs/blob/main/docs/SDK.md).

package/dist/cjs/index.cjs

@@ -0,0 +1,215 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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;
+const questions_cjs_1 = require("./questions.cjs");
+__exportStar(require("./questions.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;
+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.
+ */
+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", (0, questions_cjs_1.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); }
+}
+exports.BasalClient = BasalClient;

package/dist/cjs/index.d.cts

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