@tangleai/models 0.21.1

package/src/providers.js

@@ -0,0 +1,156 @@
+//@ts-check
+/**
+ * Provider endpoint resolution for OpenAI-compatible chat APIs.
+ *
+ * The bring-your-own-key reality of browser-side AI is three shapes:
+ * a cloud aggregator key (OpenRouter) or a local runtime URL (Ollama,
+ * LM Studio). All of them — and every other OpenAI-compatible server —
+ * speak the same `/chat/completions` wire format, so one small client
+ * covers the lot; the only per-provider knowledge needed is the base
+ * URL convention, which lives here.
+ *
+ * No key ever leaves the caller's hands: resolution just turns
+ * `{ provider, baseUrl, apiKey, model }` into a base, the chat URL and
+ * headers. The base is resolved ONCE and returned, so every sibling
+ * endpoint of the family (`/models`, and whatever else hangs off the
+ * same base) is composed from it — never re-derived from the chat URL
+ * by string surgery.
+ */
+
+import { AiError } from './errors.js';
+
+/**
+ * The built-in providers. `custom` accepts any OpenAI-compatible base
+ * URL (the caller must supply one). The local runtimes get `/v1`
+ * appended automatically when the URL carries no path — pasting
+ * `http://localhost:11434` just works.
+ *
+ * `structured` names the strongest structured-output tier the provider
+ * reliably speaks on this wire: `'json_schema'` (schema-constrained
+ * decoding), `'json'` (JSON mode without a schema), or `null` (assume
+ * nothing — the schema travels in the prompt). Either way the caller
+ * validates locally; the tier only decides how much the server helps.
+ * @type {Record<string, { label: string, baseUrl: string | null,
+ *   local: boolean, structured: 'json_schema' | 'json' | null }>}
+ */
+export const PROVIDERS = {
+  openrouter: { label: 'OpenRouter', baseUrl: 'https://openrouter.ai/api/v1', local: false, structured: 'json_schema' },
+  ollama: { label: 'Ollama', baseUrl: 'http://localhost:11434/v1', local: true, structured: 'json' },
+  lmstudio: { label: 'LM Studio', baseUrl: 'http://localhost:1234/v1', local: true, structured: 'json_schema' },
+  custom: { label: 'OpenAI-compatible', baseUrl: null, local: false, structured: null },
+};
+
+/**
+ * Resolve a provider configuration into a concrete chat endpoint.
+ * @param {{ provider?: string, baseUrl?: string, apiKey?: string,
+ *   model?: string, headers?: Record<string, string> }} [options]
+ * @returns {{ provider: string, base: string, url: string,
+ *   headers: Record<string, string>, model: string }} `base` is the
+ *   normalized base URL every endpoint of this wire family hangs off;
+ *   `url` is `${base}/chat/completions`
+ */
+export function resolveEndpoint(options = {}) {
+  const provider = options.provider
+    ?? (typeof options.baseUrl === 'string' && options.baseUrl.trim() !== '' ? 'custom' : 'openrouter');
+  const preset = PROVIDERS[provider];
+  if (preset === undefined)
+    throw new AiError('AI0001', `unknown provider '${provider}' (${Object.keys(PROVIDERS).join(', ')})`);
+
+  const configured = (options.baseUrl ?? '').trim();
+  const raw = configured === '' ? preset.baseUrl : configured;
+  if (raw === null || raw === '')
+    throw new AiError('AI0001', `provider '${provider}' needs a baseUrl`);
+
+  const base = normalizeBaseUrl(raw, preset.local);
+  /** @type {Record<string, string>} */
+  const headers = { 'content-type': 'application/json' };
+  const apiKey = (options.apiKey ?? '').trim();
+  if (apiKey !== '') headers.authorization = `Bearer ${apiKey}`;
+  Object.assign(headers, options.headers);
+
+  return { provider, base, url: `${base}/chat/completions`, headers, model: options.model ?? '' };
+}
+
+/**
+ * Probe a provider before the first turn: can this key/URL answer, and
+ * which models does it offer? GETs the OpenAI-compatible `/models`
+ * listing (OpenRouter, Ollama and LM Studio all serve it) with the
+ * same resolved auth the chat call would use. Never throws — the
+ * result object is the settings-UI contract.
+ * @param {{ provider?: string, baseUrl?: string, apiKey?: string,
+ *   headers?: Record<string, string>, fetch?: typeof fetch,
+ *   timeoutMs?: number }} [options]
+ * @returns {Promise<{ ok: true, models: string[] } |
+ *   { ok: false, status?: number, error: string }>}
+ */
+export async function probeProvider(options = {}) {
+  /** @type {ReturnType<typeof resolveEndpoint>} */
+  let endpoint;
+  try {
+    endpoint = resolveEndpoint(options);
+  }
+  catch (err) {
+    return { ok: false, error: /** @type {Error} */ (err).message };
+  }
+  const url = `${endpoint.base}/models`;
+  const fetchFn = options.fetch ?? ((u, init) => globalThis.fetch(u, init));
+  const timeoutMs = options.timeoutMs ?? 5000;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchFn(url, {
+      method: 'GET',
+      headers: endpoint.headers,
+      signal: controller.signal,
+    });
+    if (response.ok !== true)
+      return { ok: false, status: response.status, error: `HTTP ${response.status} from ${url}` };
+    const payload = await response.json();
+    const models = Array.isArray(payload?.data)
+      ? payload.data.map((m) => m?.id).filter((id) => typeof id === 'string')
+      : [];
+    return { ok: true, models };
+  }
+  catch (err) {
+    return {
+      ok: false,
+      error: controller.signal.aborted
+        ? `no answer from ${url} within ${timeoutMs} ms`
+        : /** @type {any} */ (err)?.message ?? String(err),
+    };
+  }
+  finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Forgiving base-URL normalization, on the parts of ONE parse: trailing
+ * slashes and a pasted `/chat/completions` suffix (in any case) are
+ * stripped from the path; local runtimes with a bare origin get their
+ * `/v1` prefix. A query string or fragment is refused rather than
+ * carried: this wire family composes endpoints by appending a path, and
+ * `…?api-version=x/chat/completions` is a URL nobody meant.
+ * @param {string} raw
+ * @param {boolean} local
+ * @returns {string}
+ */
+function normalizeBaseUrl(raw, local) {
+  /** @type {URL} */
+  let url;
+  try {
+    url = new URL(raw);
+  }
+  catch {
+    throw new AiError('AI0001', `invalid baseUrl '${raw}'`);
+  }
+  if (url.search !== '' || url.hash !== '')
+    throw new AiError('AI0001', `baseUrl '${raw}' must not carry a query string or fragment`);
+  let path = url.pathname.replace(/\/+$/, '');
+  if (/\/chat\/completions$/i.test(path))
+    path = path.slice(0, -'/chat/completions'.length).replace(/\/+$/, '');
+  if (local && path === '') path = '/v1';
+  // with no search and no hash, `href` is everything before the path —
+  // origin, plus any credentials the caller pasted — followed by the path
+  return url.href.slice(0, url.href.length - url.pathname.length) + path;
+}

package/src/replay.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The replay cache seam a host implements.
+ * @typedef {Object} ReplayCache
+ * @property {(key: string) => any} get - the stored value, or `undefined`
+ *   for a miss; may answer a promise
+ * @property {(key: string, value: any) => any} set - remember a value
+ *   under a key; may answer a promise. The value is JSON-only.
+ */
+/**
+ * The `cache` option, checked once at client construction: absent means
+ * no cache; present means both members are functions, or `AI0001`.
+ * @param {unknown} cache
+ * @returns {ReplayCache | null}
+ */
+export function normalizeCache(cache: unknown): ReplayCache | null;
+/**
+ * The key one request has under one endpoint: the canonical
+ * serialization of the wire, the credential-free endpoint identity and
+ * the effective request. The same request keys the same string on
+ * every host.
+ * @param {'chat' | 'embeddings'} wire
+ * @param {{ provider: string, base: string }} endpoint
+ * @param {any} request - the body the client would POST, `stream` removed
+ * @returns {string}
+ * @throws {AiError} `AI0001` when the request cannot be keyed injectively
+ */
+export function replayKey(wire: "chat" | "embeddings", endpoint: {
+    provider: string;
+    base: string;
+}, request: any): string;
+/**
+ * A stored chat entry, verified: `{ value, ms }` with `value` a
+ * normalized result carrying a `message` object and `ms` a finite
+ * number — or `AI0003`.
+ * @param {any} entry
+ * @returns {{ value: any, ms: number }}
+ */
+export function verifyChatEntry(entry: any): {
+    value: any;
+    ms: number;
+};
+/**
+ * A stored embedding entry, verified into a fresh vector: `{ vector,
+ * ms }` with `vector` a non-empty array of finite numbers at the settled
+ * width (any positive width when none is settled yet — the first replay
+ * settles it exactly as a first wire reply would) — or `AI0003`.
+ * @param {any} entry
+ * @param {number | undefined} dims - the settled width, if any
+ * @returns {Float32Array}
+ */
+export function verifyEmbeddingEntry(entry: any, dims: number | undefined): Float32Array;
+/**
+ * A JSON-only copy: what is stored, and what a replay answers, so that a
+ * caller mutating its result never mutates the adapter's entry.
+ * @template T
+ * @param {T} value
+ * @returns {T}
+ */
+export function cloneJson<T>(value: T): T;
+/** Milliseconds now, for the wall time of a purchase. */
+export function now(): number;
+/**
+ * The replay cache seam a host implements.
+ */
+export type ReplayCache = {
+    /**
+     * - the stored value, or `undefined`
+     * for a miss; may answer a promise
+     */
+    get: (key: string) => any;
+    /**
+     * - remember a value
+     * under a key; may answer a promise. The value is JSON-only.
+     */
+    set: (key: string, value: any) => any;
+};

package/src/replay.js

@@ -0,0 +1,141 @@
+//@ts-check
+/**
+ * The replay seam behind both wire clients: what a remembered reply is
+ * keyed by, and what a remembered entry must look like before it is
+ * served. This module owns the two decisions a host must not be left
+ * to make twice —
+ *
+ *  - **the key is the effective wire request, canonicalized.** It is
+ *    built by the client after endpoint resolution and default
+ *    application, from `{ wire, provider, base, request }` where
+ *    `request` is the body the client would POST (minus `stream`, which
+ *    does not change an answer). Never the headers (they carry the
+ *    credential), never the signal, never a callback. Because the key
+ *    is the body rather than an allow-list of request members, an
+ *    option added to the body later enters the key by construction — it
+ *    cannot alias an older key. The serialization is `semanticKey`:
+ *    injective over plain data, so two requests share a key exactly when
+ *    they are the same request, and a request that cannot be keyed
+ *    injectively (a function inside `tools`, a cycle) is refused up
+ *    front rather than folded onto someone else's entry;
+ *
+ *  - **a stored entry is verified, not trusted.** A chat entry must carry
+ *    a normalized result and the wall time of the purchase; an embedding
+ *    entry must carry a vector of finite numbers at the settled width.
+ *    Anything else is `AI0003`, never served — a cache that answers
+ *    garbage is worse than a cache that is down.
+ *
+ * The client hands the adapter the complete canonical string. It is
+ * long (a whole conversation is in it) and that is the point: it is
+ * collision-free. An adapter that needs a fixed-width storage id hashes
+ * it — with a cryptographic hash, because a 32-bit hash over prompts
+ * that differ by one token would sooner or later serve one prompt's
+ * answer for another's.
+ *
+ * The adapter contract is two members, each sync or async:
+ * `get(key) → value | undefined` and `set(key, value)`. The seam FAILS
+ * CLOSED: an adapter that throws fails the call. An adapter that wants
+ * to fail open — keep buying while its storage is broken — catches its
+ * own errors and answers `undefined`; the client will not guess which
+ * it wanted.
+ */
+
+import { semanticKey } from '@jarenjs/core/object';
+
+import { AiError } from './errors.js';
+import { verifyEmbeddingComponents } from './embedding-vector.js';
+
+/**
+ * The replay cache seam a host implements.
+ * @typedef {Object} ReplayCache
+ * @property {(key: string) => any} get - the stored value, or `undefined`
+ *   for a miss; may answer a promise
+ * @property {(key: string, value: any) => any} set - remember a value
+ *   under a key; may answer a promise. The value is JSON-only.
+ */
+
+/**
+ * The `cache` option, checked once at client construction: absent means
+ * no cache; present means both members are functions, or `AI0001`.
+ * @param {unknown} cache
+ * @returns {ReplayCache | null}
+ */
+export function normalizeCache(cache) {
+  if (cache === undefined || cache === null) return null;
+  const candidate = /** @type {any} */ (cache);
+  if (typeof candidate.get !== 'function' || typeof candidate.set !== 'function')
+    throw new AiError('AI0001', 'cache needs { get(key), set(key, value) } — both functions, sync or async');
+  return candidate;
+}
+
+/**
+ * The key one request has under one endpoint: the canonical
+ * serialization of the wire, the credential-free endpoint identity and
+ * the effective request. The same request keys the same string on
+ * every host.
+ * @param {'chat' | 'embeddings'} wire
+ * @param {{ provider: string, base: string }} endpoint
+ * @param {any} request - the body the client would POST, `stream` removed
+ * @returns {string}
+ * @throws {AiError} `AI0001` when the request cannot be keyed injectively
+ */
+export function replayKey(wire, endpoint, request) {
+  try {
+    return semanticKey({ wire, provider: endpoint.provider, base: endpoint.base, request });
+  }
+  catch (err) {
+    throw new AiError('AI0001',
+      `the ${wire} request is not cacheable: ${/** @type {Error} */ (err).message}`);
+  }
+}
+
+/** @param {any} value */
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * A stored chat entry, verified: `{ value, ms }` with `value` a
+ * normalized result carrying a `message` object and `ms` a finite
+ * number — or `AI0003`.
+ * @param {any} entry
+ * @returns {{ value: any, ms: number }}
+ */
+export function verifyChatEntry(entry) {
+  if (!isRecord(entry) || !isRecord(entry.value) || !isRecord(entry.value.message)
+    || typeof entry.ms !== 'number' || !Number.isFinite(entry.ms))
+    throw new AiError('AI0003', 'malformed replay entry for the chat wire: expected { value: { message, … }, ms }');
+  return entry;
+}
+
+/**
+ * A stored embedding entry, verified into a fresh vector: `{ vector,
+ * ms }` with `vector` a non-empty array of finite numbers at the settled
+ * width (any positive width when none is settled yet — the first replay
+ * settles it exactly as a first wire reply would) — or `AI0003`.
+ * @param {any} entry
+ * @param {number | undefined} dims - the settled width, if any
+ * @returns {Float32Array}
+ */
+export function verifyEmbeddingEntry(entry, dims) {
+  const vector = isRecord(entry) ? entry.vector : undefined;
+  if (!Array.isArray(vector) || vector.length === 0)
+    throw new AiError('AI0003', 'malformed replay entry for the embeddings wire: expected { vector: number[], ms }');
+  if (dims !== undefined && vector.length !== dims)
+    throw new AiError('AI0003', `replay entry carries ${vector.length} dimensions, expected ${dims}`);
+  return verifyEmbeddingComponents(vector, 'replay entry carries');
+}
+
+/**
+ * A JSON-only copy: what is stored, and what a replay answers, so that a
+ * caller mutating its result never mutates the adapter's entry.
+ * @template T
+ * @param {T} value
+ * @returns {T}
+ */
+export function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+/** Milliseconds now, for the wall time of a purchase. */
+export function now() {
+  return globalThis.performance.now();
+}

package/src/retry.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The `retry` option of every client.
+ * @typedef {Object} RetryOptions
+ * @property {number} [attempts] - the TOTAL number of tries (default 3;
+ *   1 disables retrying)
+ * @property {number} [baseMs] - the first backoff (default 500); each
+ *   later one doubles, with full jitter
+ * @property {number} [maxMs] - the ceiling on any single wait (default
+ *   8 000) — a provider `Retry-After` included: a provider asking for a
+ *   minute gets the cap, and the value it asked for rides the final
+ *   error as `retryAfterMs` for the caller to honour
+ * @property {() => number} [random] - the jitter source, for
+ *   deterministic tests
+ * @property {(ms: number, signal?: AbortSignal) => Promise<void>} [sleep]
+ *   - the wait itself, for deterministic tests; the default is a timer
+ *   that rejects with the abort reason the moment `signal` aborts
+ */
+/**
+ * The option with its defaults filled in.
+ * @typedef {Object} RetryPolicy
+ * @property {number} attempts
+ * @property {number} baseMs
+ * @property {number} maxMs
+ * @property {() => number} random
+ * @property {(ms: number, signal?: AbortSignal) => Promise<void>} sleep
+ */
+/**
+ * @param {RetryOptions | undefined} retry
+ * @returns {RetryPolicy}
+ */
+export function normalizeRetry(retry: RetryOptions | undefined): RetryPolicy;
+/**
+ * Whether a failure is the transient kind. A transport error with a
+ * retryable status is (a network failure before any response counts
+ * as status 0); so is a malformed 200 — a reply that carried none of
+ * what the wire promised is a provider hiccup, common on busy cheap
+ * tiers, and safe to retry precisely because nothing was delivered.
+ * Anything else — a caller error, a 401, a 404 — is final on the first
+ * try.
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isTransientFailure(err: unknown): boolean;
+/**
+ * The wait before the next try: exponential backoff with full jitter,
+ * capped at `maxMs` — unless the provider named a `Retry-After`, which
+ * wins up to the same cap.
+ * @param {RetryPolicy} policy
+ * @param {number} attempt - the try that just failed, counted from 1
+ * @param {number | undefined} retryAfter - the provider's ask, in ms
+ * @returns {number} milliseconds
+ */
+export function retryDelay(policy: RetryPolicy, attempt: number, retryAfter: number | undefined): number;
+/**
+ * Run `once` until it settles. A failure `retryable` accepts backs off
+ * and tries again while tries remain; anything else is thrown as it
+ * came, and a coded transport failure (`AI0002`, `AI0003`) carries the
+ * number of tries as `attempts`. The wait honours `signal`: an abort
+ * during backoff rejects with the abort reason, exactly like an abort
+ * during the request — nothing is ever retried past an abort.
+ * @template T
+ * @param {RetryPolicy} policy
+ * @param {() => Promise<T>} once - one request/response cycle
+ * @param {{ signal?: AbortSignal, retryable: (failure: AiError) => boolean }} options
+ *   - `retryable` is the wire's own judgment over a coded failure (the
+ *   chat client, for one, stops retrying once a streamed delta has
+ *   reached the caller); it is never asked about an uncoded error
+ * @returns {Promise<T>}
+ */
+export function withRetry<T>(policy: RetryPolicy, once: () => Promise<T>, options: {
+    signal?: AbortSignal;
+    retryable: (failure: AiError) => boolean;
+}): Promise<T>;
+/**
+ * The `AI0002` for a response that is not ok: the status, a short
+ * excerpt of the body, and the provider's `Retry-After` in ms.
+ * @param {any} response
+ * @param {string} url
+ * @returns {Promise<AiError>}
+ */
+export function httpFailure(response: any, url: string): Promise<AiError>;
+/**
+ * What to throw when `fetch` itself threw: an abort exactly as it came
+ * (the caller's own signal, never retried, never rewrapped); anything
+ * else the `AI0002` of a failure before any response, status 0.
+ * @param {any} err
+ * @param {string} url
+ * @returns {any}
+ */
+export function transportFailure(err: any, url: string): any;
+/**
+ * Parse a `Retry-After` header (delta-seconds or HTTP-date) into ms.
+ * @param {any} response
+ * @returns {number | undefined}
+ */
+export function retryAfterMs(response: any): number | undefined;
+export { abortError };
+/**
+ * The `retry` option of every client.
+ */
+export type RetryOptions = {
+    /**
+     * - the TOTAL number of tries (default 3;
+     * 1 disables retrying)
+     */
+    attempts?: number;
+    /**
+     * - the first backoff (default 500); each
+     * later one doubles, with full jitter
+     */
+    baseMs?: number;
+    /**
+     * - the ceiling on any single wait (default
+     * 8 000) — a provider `Retry-After` included: a provider asking for a
+     * minute gets the cap, and the value it asked for rides the final
+     * error as `retryAfterMs` for the caller to honour
+     */
+    maxMs?: number;
+    /**
+     * - the jitter source, for
+     * deterministic tests
+     */
+    random?: () => number;
+    /**
+     * - the wait itself, for deterministic tests; the default is a timer
+     * that rejects with the abort reason the moment `signal` aborts
+     */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+};
+/**
+ * The option with its defaults filled in.
+ */
+export type RetryPolicy = {
+    attempts: number;
+    baseMs: number;
+    maxMs: number;
+    random: () => number;
+    sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+};
+import { AiError } from './errors.js';
+import { abortError } from '@jarenjs/core/retry';