@tangleai/models 0.21.1 → 0.25.0

package/src/retry.js

@@ -1,4 +1,3 @@
-//@ts-check
 /**
  * The transport policy every client in this package shares: which
  * failures are transient, how long to wait before trying again, what a
@@ -12,58 +11,26 @@
  * Everything here is internal to the package; the public surface is
  * the `retry` option each client documents.
  */
-
-import { AiError } from './errors.js';
+import { AiError } from "./errors.js";
 import { backoffDelay, parseRetryAfter, sleep as defaultSleep, abortError } from '@jarenjs/core/retry';
 export { abortError };
-
+/** The `retry` option of every client. */
+/** The option with its defaults filled in. */
 /**
- * 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) {
-  return {
-    attempts: Math.max(1, retry?.attempts ?? 3),
-    baseMs: retry?.baseMs ?? 500,
-    maxMs: retry?.maxMs ?? 8000,
-    random: retry?.random ?? Math.random,
-    sleep: retry?.sleep ?? defaultSleep,
-  };
+    return {
+        attempts: Math.max(1, retry?.attempts ?? 3),
+        baseMs: retry?.baseMs ?? 500,
+        maxMs: retry?.maxMs ?? 8000,
+        random: retry?.random ?? Math.random,
+        sleep: retry?.sleep ?? defaultSleep,
+    };
 }
-
 /** Statuses worth a retry: timeout, rate limit, server-side failure. */
 function isRetryableStatus(status) {
-  return status === 0 || status === 408 || status === 429 || status >= 500;
+    return status === 0 || status === 408 || status === 429 || status >= 500;
 }
-
 /**
  * Whether a failure is the transient kind. A transport error with a
  * retryable status is (a network failure before any response counts
@@ -72,28 +39,24 @@ function isRetryableStatus(status) {
  * 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) {
-  if (!(err instanceof AiError)) return false;
-  return err.code === 'AI0003'
-    || (err.code === 'AI0002' && isRetryableStatus(err.status ?? -1));
+    if (!(err instanceof AiError))
+        return false;
+    return err.code === 'AI0003'
+        || (err.code === 'AI0002' && isRetryableStatus(err.status ?? -1));
 }
-
 /**
  * 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
+ * @param attempt - the try that just failed, counted from 1
+ * @param retryAfter - the provider's ask, in ms
+ * @returns milliseconds
  */
 export function retryDelay(policy, attempt, retryAfter) {
-  return backoffDelay({ ...policy, policy: 'ai-compat' }, attempt, retryAfter);
+    return backoffDelay({ ...policy, policy: 'ai-compat' }, attempt, retryAfter);
 }
-
 /**
  * Run `once` until it settles. A failure `retryable` accepts backs off
  * and tries again while tries remain; anything else is thrown as it
@@ -102,81 +65,63 @@ export function retryDelay(policy, attempt, retryAfter) {
  * 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
+ * @param once - one request/response cycle
  *   - `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 async function withRetry(policy, once, options) {
-  for (let attempt = 1; ; attempt++) {
-    try {
-      return await once();
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await once();
+        }
+        catch (err) {
+            if (options.signal?.aborted)
+                throw abortError(options.signal);
+            const failure = err;
+            const coded = failure instanceof AiError;
+            if (!(coded && options.retryable(failure) && attempt < policy.attempts)) {
+                if (coded && (failure.code === 'AI0002' || failure.code === 'AI0003'))
+                    failure.attempts = attempt;
+                throw err;
+            }
+            await policy.sleep(retryDelay(policy, attempt, failure.retryAfterMs), options.signal);
+        }
     }
-    catch (err) {
-      if (options.signal?.aborted) throw abortError(options.signal);
-      const failure = /** @type {any} */ (err);
-      const coded = failure instanceof AiError;
-      if (!(coded && options.retryable(failure) && attempt < policy.attempts)) {
-        if (coded && (failure.code === 'AI0002' || failure.code === 'AI0003'))
-          failure.attempts = attempt;
-        throw err;
-      }
-      await policy.sleep(retryDelay(policy, attempt, failure.retryAfterMs), options.signal);
-    }
-  }
 }
-
 /**
  * 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 async function httpFailure(response, url) {
-  const excerpt = await readErrorExcerpt(response);
-  return new AiError('AI0002',
-    `HTTP ${response.status} from ${url}${excerpt === '' ? '' : `: ${excerpt}`}`,
-    { status: response.status, retryAfterMs: retryAfterMs(response) });
+    const excerpt = await readErrorExcerpt(response);
+    return new AiError('AI0002', `HTTP ${response.status} from ${url}${excerpt === '' ? '' : `: ${excerpt}`}`, { status: response.status, retryAfterMs: retryAfterMs(response) });
 }
-
 /**
  * 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, url) {
-  if (err?.name === 'AbortError') return err;
-  return new AiError('AI0002',
-    `network error calling ${url}: ${err?.message ?? err}`,
-    { status: 0, cause: err });
+    if (err?.name === 'AbortError')
+        return err;
+    return new AiError('AI0002', `network error calling ${url}: ${err?.message ?? err}`, { status: 0, cause: err });
 }
-
 /**
  * Parse a `Retry-After` header (delta-seconds or HTTP-date) into ms.
- * @param {any} response
- * @returns {number | undefined}
  */
 export function retryAfterMs(response) {
-  return parseRetryAfter(response?.headers?.get?.('retry-after'));
+    return parseRetryAfter(response?.headers?.get?.('retry-after'));
 }
-
 /**
- * @param {any} response
- * @returns {Promise<string>} a short excerpt of the error body
+ * @returns a short excerpt of the error body
  */
 async function readErrorExcerpt(response) {
-  try {
-    const text = await response.text();
-    return text.length > 300 ? `${text.slice(0, 300)}…` : text;
-  }
-  catch {
-    return '';
-  }
+    try {
+        const text = await response.text();
+        return text.length > 300 ? `${text.slice(0, 300)}…` : text;
+    }
+    catch {
+        return '';
+    }
 }

package/src/routing.d.ts

@@ -1,13 +1,11 @@
-/** @typedef {{ deadlineMs?: number, outputTokens?: number, reasoningTokens?: number }} ModelLimits */
-/** @typedef {{ purpose: 'author'|'subcall'|'embedding'|'stylesheet', grammar?: string, depth?: number, limits?: ModelLimits }} ModelContext */
+/** Optional host routing for model-only calls. No tools execute inside this boundary. */
+export declare const MODEL_PURPOSES: readonly string[];
 /** A selector returns a route or ordered fallback routes: `{client, identity}`.
  * A route identity is host data; it never controls provider policy. Embedding callers
  * use their embedding API directly: this chat wrapper refuses that purpose so a
  * fallback cannot silently change an index's embedding identity.
- * @param {{ client: any, selectModel?: (context: ModelContext) => any,
- *   limits?: ModelLimits, onRoute?: (event: any) => void, account?: any }} options
- * @param {ModelContext} context */
-export function createRoutedClient(options: {
+ * @param context */
+export declare function createRoutedClient(options: {
     client: any;
     selectModel?: (context: ModelContext) => any;
     limits?: ModelLimits;
@@ -17,15 +15,13 @@ export function createRoutedClient(options: {
     endpoint: any;
     complete(request: any): Promise<any>;
 };
-/** Optional host routing for model-only calls. No tools execute inside this boundary. */
-export const MODEL_PURPOSES: readonly string[];
 export type ModelLimits = {
     deadlineMs?: number;
     outputTokens?: number;
     reasoningTokens?: number;
 };
 export type ModelContext = {
-    purpose: "author" | "subcall" | "embedding" | "stylesheet";
+    purpose: 'author' | 'subcall' | 'embedding' | 'stylesheet';
     grammar?: string;
     depth?: number;
     limits?: ModelLimits;

package/src/routing.js

@@ -1,87 +1,99 @@
-//@ts-check
 /** Optional host routing for model-only calls. No tools execute inside this boundary. */
 export const MODEL_PURPOSES = Object.freeze(['author', 'subcall', 'embedding', 'stylesheet']);
-
-/** @typedef {{ deadlineMs?: number, outputTokens?: number, reasoningTokens?: number }} ModelLimits */
-/** @typedef {{ purpose: 'author'|'subcall'|'embedding'|'stylesheet', grammar?: string, depth?: number, limits?: ModelLimits }} ModelContext */
-
 /** A selector returns a route or ordered fallback routes: `{client, identity}`.
  * A route identity is host data; it never controls provider policy. Embedding callers
  * use their embedding API directly: this chat wrapper refuses that purpose so a
  * fallback cannot silently change an index's embedding identity.
- * @param {{ client: any, selectModel?: (context: ModelContext) => any,
- *   limits?: ModelLimits, onRoute?: (event: any) => void, account?: any }} options
- * @param {ModelContext} context */
+ * @param context */
 export function createRoutedClient(options, context) {
-  if (!MODEL_PURPOSES.includes(context.purpose) || context.purpose === 'embedding')
-    throw new TypeError('chat routing requires author, stylesheet or subcall purpose');
-  const limits = { ...options.limits, ...context.limits };
-  for (const [name, value] of Object.entries(limits)) {
-    if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${name} must be a positive integer`);
-  }
-  return {
-    endpoint: options.client.endpoint,
-    async complete(request) {
-      if (request.tools?.length || request.toolChoice !== undefined)
-        throw new TypeError('model routing does not retry tool-bearing requests');
-      const choice = options.selectModel ? await options.selectModel({ ...context, limits }) : null;
-      const routes = choice === null ? [{ client: options.client, identity: 'default' }]
-        : Array.isArray(choice) ? choice : [choice];
-      if (routes.length === 0) throw new TypeError('selectModel returned no routes');
-      let last;
-      for (const [index, route] of routes.entries()) {
-        if (!route?.client?.complete || typeof route.identity !== 'string' || !route.identity)
-          throw new TypeError('a model route needs client and identity');
-        request.signal?.throwIfAborted();
-        const stopped = options.account?.stop();
-        if (stopped) throw new Error(stopped);
-        const controller = new AbortController();
-        const remaining = options.account?.remaining?.().ms;
-        const deadline = Math.min(limits.deadlineMs ?? Infinity, remaining ?? Infinity);
-        const signal = request.signal
-          ? Number.isFinite(deadline) ? AbortSignal.any([request.signal, controller.signal]) : request.signal
-          : controller.signal;
-        let timer;
-        const started = performance.now();
-        const event = { ...context, identity: route.identity, fallback: index, limits, outcome: 'provider', ms: 0, usage: null,
-          schemaBytes: request.responseFormat?.schema ? new TextEncoder().encode(JSON.stringify(request.responseFormat.schema)).length : 0,
-          finishReason: null, errorCode: null };
-        try {
-          options.account?.reserve();
-          const bounded = { ...request, signal,
-            ...(limits.outputTokens ? { maxTokens: Math.min(request.maxTokens ?? Infinity, limits.outputTokens) } : {}),
-            ...(limits.reasoningTokens ? { reasoning: { ...request.reasoning,
-              max_tokens: Math.min(request.reasoning?.max_tokens ?? Infinity, limits.reasoningTokens) } } : {}),
-          };
-          const pending = Promise.resolve().then(() => route.client.complete(bounded));
-          const reply = await Promise.race([pending, new Promise((_, reject) => {
-            const abort = () => reject(signal.reason ?? new Error('aborted'));
-            signal.addEventListener('abort', abort, { once: true });
-            // Remove the listener when even an abort-ignoring client eventually settles.
-            pending.then(() => signal.removeEventListener('abort', abort), () => signal.removeEventListener('abort', abort));
-            if (Number.isFinite(deadline)) timer = setTimeout(() => controller.abort(new Error('model deadline')), deadline);
-          })]);
-          event.usage = reply.usage ?? null;
-          event.finishReason = reply.finishReason ?? null;
-          options.account?.settle(reply.usage, JSON.stringify(request.messages) + String(reply.message?.content ?? ''));
-          const usage = reply.usage;
-          if ((limits.outputTokens && usage?.completion_tokens > limits.outputTokens)
-            || (limits.reasoningTokens && usage?.completion_tokens_details?.reasoning_tokens > limits.reasoningTokens)) {
-            event.outcome = 'token-limit';
-            throw new Error('provider exceeded model token ceiling');
-          }
-          event.outcome = 'complete';
-          return reply;
-        }
-        catch (error) {
-          last = error;
-          event.errorCode = error?.code ?? error?.name ?? 'Error';
-          if (controller.signal.aborted) event.outcome = 'timeout';
-          if (request.signal?.aborted) { event.outcome = 'aborted'; throw error; }
-        }
-        finally { clearTimeout(timer); event.ms = performance.now() - started; options.onRoute?.(event); }
-      }
-      throw last;
-    },
-  };
+    if (!MODEL_PURPOSES.includes(context.purpose) || context.purpose === 'embedding')
+        throw new TypeError('chat routing requires author, stylesheet or subcall purpose');
+    const limits = { ...options.limits, ...context.limits };
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new TypeError(`${name} must be a positive integer`);
+    }
+    return {
+        endpoint: options.client.endpoint,
+        async complete(request) {
+            if (request.tools?.length || request.toolChoice !== undefined)
+                throw new TypeError('model routing does not retry tool-bearing requests');
+            const choice = options.selectModel ? await options.selectModel({ ...context, limits }) : null;
+            const routes = choice === null ? [{ client: options.client, identity: 'default' }]
+                : Array.isArray(choice) ? choice : [choice];
+            if (routes.length === 0)
+                throw new TypeError('selectModel returned no routes');
+            let last;
+            for (const [index, route] of routes.entries()) {
+                if (!route?.client?.complete || typeof route.identity !== 'string' || !route.identity)
+                    throw new TypeError('a model route needs client and identity');
+                request.signal?.throwIfAborted();
+                const stopped = options.account?.stop();
+                if (stopped)
+                    throw new Error(stopped);
+                const controller = new AbortController();
+                const remaining = options.account?.remaining?.().ms;
+                const deadline = Math.min(limits.deadlineMs ?? Infinity, remaining ?? Infinity);
+                const signal = request.signal
+                    ? Number.isFinite(deadline) ? AbortSignal.any([request.signal, controller.signal]) : request.signal
+                    : controller.signal;
+                let timer;
+                const started = performance.now();
+                const event = {
+                    ...context, identity: route.identity, fallback: index, limits, outcome: 'provider', ms: 0, usage: null,
+                    schemaBytes: request.responseFormat?.schema ? new TextEncoder().encode(JSON.stringify(request.responseFormat.schema)).length : 0,
+                    finishReason: null, errorCode: null
+                };
+                try {
+                    options.account?.reserve();
+                    const bounded = {
+                        ...request, signal,
+                        ...(limits.outputTokens ? { maxTokens: Math.min(request.maxTokens ?? Infinity, limits.outputTokens) } : {}),
+                        ...(limits.reasoningTokens ? {
+                            reasoning: {
+                                ...request.reasoning,
+                                max_tokens: Math.min(request.reasoning?.max_tokens ?? Infinity, limits.reasoningTokens)
+                            }
+                        } : {}),
+                    };
+                    const pending = Promise.resolve().then(() => route.client.complete(bounded));
+                    const reply = await Promise.race([pending, new Promise((_, reject) => {
+                            const abort = () => reject(signal.reason ?? new Error('aborted'));
+                            signal.addEventListener('abort', abort, { once: true });
+                            // Remove the listener when even an abort-ignoring client eventually settles.
+                            pending.then(() => signal.removeEventListener('abort', abort), () => signal.removeEventListener('abort', abort));
+                            if (Number.isFinite(deadline))
+                                timer = setTimeout(() => controller.abort(new Error('model deadline')), deadline);
+                        })]);
+                    event.usage = reply.usage ?? null;
+                    event.finishReason = reply.finishReason ?? null;
+                    options.account?.settle(reply.usage, JSON.stringify(request.messages) + String(reply.message?.content ?? ''));
+                    const usage = reply.usage;
+                    if ((limits.outputTokens && usage?.completion_tokens > limits.outputTokens)
+                        || (limits.reasoningTokens && usage?.completion_tokens_details?.reasoning_tokens > limits.reasoningTokens)) {
+                        event.outcome = 'token-limit';
+                        throw new Error('provider exceeded model token ceiling');
+                    }
+                    event.outcome = 'complete';
+                    return reply;
+                }
+                catch (error) {
+                    last = error;
+                    event.errorCode = error?.code ?? error?.name ?? 'Error';
+                    if (controller.signal.aborted)
+                        event.outcome = 'timeout';
+                    if (request.signal?.aborted) {
+                        event.outcome = 'aborted';
+                        throw error;
+                    }
+                }
+                finally {
+                    clearTimeout(timer);
+                    event.ms = performance.now() - started;
+                    options.onRoute?.(event);
+                }
+            }
+            throw last;
+        },
+    };
 }

package/src/sse.d.ts

@@ -1 +1,10 @@
-export { createSseDecoder } from "@jarenjs/core/text/sse";
+/**
+ * @file The `@tangleai/models/sse` subpath: the data-only Server-Sent-
+ * Events decoder the streaming client consumes — the one SSE codec of
+ * the suite, which lives in `@jarenjs/core/text/sse` and is re-exported
+ * here so this package's public surface is unchanged. Feed it network
+ * chunks in any split (mid-line, mid-event, CR/LF/CRLF); it yields the
+ * complete `data:` payloads in order; non-data fields and comments are
+ * ignored, multi-line data joins with a newline per the specification.
+ */
+export { createSseDecoder } from '@jarenjs/core/text/sse';

package/src/sse.js

@@ -1,4 +1,3 @@
-//@ts-check
 /**
  * @file The `@tangleai/models/sse` subpath: the data-only Server-Sent-
  * Events decoder the streaming client consumes — the one SSE codec of
@@ -8,5 +7,4 @@
  * complete `data:` payloads in order; non-data fields and comments are
  * ignored, multi-line data joins with a newline per the specification.
  */
-
 export { createSseDecoder } from '@jarenjs/core/text/sse';

package/src/structured.d.ts

@@ -1,27 +1,30 @@
+/**
+ * Structured output: schema in, validated JSON value out — on every
+ * provider tier.
+ *
+ * The helper sends one (non-streaming) chat request constrained by a
+ * JSON Schema, using the strongest mechanism the provider speaks
+ * (`response_format: json_schema` → JSON mode → schema embedded in a
+ * system instruction), parses the reply, and validates it locally with
+ * `@jarenjs/validate` — the same validator that guards the toolbox.
+ * Local validation is never optional: provider structured-output
+ * implementations enforce varying schema subsets, so the server is an
+ * accelerator, not an authority. On failure the instancePath'd errors
+ * go back to the model for a bounded number of repair rounds.
+ */
 /**
  * Strip an accidental markdown fence from a reply ("```json … ```") —
  * the classic prompt-embedded-schema failure mode.
  *
  * Exported because every place this package parses a model's JSON has to
  * make the same allowance, and two copies of "how forgiving are we about
- * fences" is two answers to one question: `program.js`'s sub-calls parse
+ * fences" is two answers to one question: `program.ts`'s sub-calls parse
  * replies the same way structured generation does.
- * @param {string} text
  */
-export function unfence(text: string): string;
+export declare function unfence(text: string): string;
 /**
  * Create a structured-output generator over a chat client.
  *
- * @param {{ client: { endpoint: { provider: string }, complete: (request: any) => Promise<any> },
- *   schema: any,
- *   name?: string,
- *   strict?: boolean,
- *   validator?: (value: any) => any,
- *   refs?: any[],
- *   gate?: ((value: any) => any) | Array<(value: any) => any>,
- *   stream?: boolean,
- *   onAttempt?: (event: { attempt: number, outcome: string, errors: any[] }) => void,
- *   maxRepairs?: number }} options
  *   - `validator` overrides the internally compiled check (any
  *     function returning a boolean or `{ valid, errors }`).
  *   - `refs` are other JSON Schemas the `schema` references by `$id`,
@@ -50,11 +53,8 @@ export function unfence(text: string): string;
  *     callers who never asked for one.
  *   - `maxRepairs` is how many failed rounds may go back to the model
  *     with the validation errors (default 1).
- * @returns {{ generate: (messages: any[], hooks?: { signal?: AbortSignal }) => Promise<
- *   { value: any, raw: string, attempts: number } |
- *   { errors: any[], raw: string, attempts: number }> }}
  */
-export function createStructuredOutput(options: {
+export declare function createStructuredOutput(options: {
     client: {
         endpoint: {
             provider: string;
@@ -79,10 +79,12 @@ export function createStructuredOutput(options: {
         signal?: AbortSignal;
     }) => Promise<{
         value: any;
+        errors?: undefined;
         raw: string;
         attempts: number;
     } | {
         errors: any[];
+        value?: undefined;
         raw: string;
         attempts: number;
     }>;