@tangleai/models 0.21.1 → 0.25.0

package/src/errors.js

@@ -1,4 +1,3 @@
-//@ts-check
 /**
  * The model transport error type. Every failure the package itself raises
  * carries a stable code, like the rest of the suite:
@@ -12,34 +11,33 @@
  * those come back as `{ error }` results the model can read and
  * recover from. AiError is reserved for the transport and for misuse.
  *
- * Refinement (`refine.js`) rejects with its own `AI01xx` codes, enumerated
+ * Refinement (`refine.ts`) rejects with its own `AI01xx` codes, enumerated
  * there. They are the same idea one step further out: never thrown, they
  * travel as records with a pointer, because their reader is a model
  * repairing its own proposal.
  */
-
 import { CodedError } from '@jarenjs/core/errors';
-
 export class AiError extends CodedError {
-  /**
-   * @param {string} code - stable error code ('AI0001' | 'AI0002' | 'AI0003')
-   * @param {string} reason - The bare reason; `message` is composed as
-   *   `${code}: ${reason}` per the coded contract (transport errors
-   *   have no document, so there is never a location).
-   * @param {{ status?: number, attempts?: number, retryAfterMs?: number,
-   *   cause?: unknown }} [meta] - transport metadata: the HTTP status
-   *   (`0` for a network failure before any response), how many tries
-   *   the client made, and the provider's `Retry-After` in ms
-   */
-  constructor(code, reason, meta) {
-    super('AiError', code, reason, undefined,
-      meta !== undefined && meta.cause !== undefined
-        ? { cause: meta.cause }
-        : undefined);
-    if (meta !== undefined) {
-      if (meta.status !== undefined) this.status = meta.status;
-      if (meta.attempts !== undefined) this.attempts = meta.attempts;
-      if (meta.retryAfterMs !== undefined) this.retryAfterMs = meta.retryAfterMs;
+    /**
+     * @param code - stable error code ('AI0001' | 'AI0002' | 'AI0003')
+     * @param reason - The bare reason; `message` is composed as
+     *   `${code}: ${reason}` per the coded contract (transport errors
+     *   have no document, so there is never a location).
+     * @param [meta] - transport metadata: the HTTP status
+     *   (`0` for a network failure before any response), how many tries
+     *   the client made, and the provider's `Retry-After` in ms
+     */
+    constructor(code, reason, meta) {
+        super('AiError', code, reason, undefined, meta !== undefined && meta.cause !== undefined
+            ? { cause: meta.cause }
+            : undefined);
+        if (meta !== undefined) {
+            if (meta.status !== undefined)
+                this.status = meta.status;
+            if (meta.attempts !== undefined)
+                this.attempts = meta.attempts;
+            if (meta.retryAfterMs !== undefined)
+                this.retryAfterMs = meta.retryAfterMs;
+        }
     }
-  }
 }

package/src/grammar.d.ts

@@ -1,10 +1,7 @@
-/** @param {{ client: any, grammar: 'query'|'jslt'|'app'|'fsm'|'dag'|'statechart'|'workflow'|'model', profile: any,
- *   schema: any, refs?: any[], compile: (document: any) => any, gate?: any,
- *   maxRepairs?: number, stream?: boolean, onAttempt?: any,
- *   selectModel?: any, limits?: any, onRoute?: any }} options */
-export function createGrammarAuthor(options: {
+/** @param options */
+export declare function createGrammarAuthor(options: {
     client: any;
-    grammar: "query" | "jslt" | "app" | "fsm" | "dag" | "statechart" | "workflow" | "model";
+    grammar: 'query' | 'jslt' | 'app' | 'fsm' | 'dag' | 'statechart' | 'workflow' | 'model';
     profile: any;
     schema: any;
     refs?: any[];
@@ -17,12 +14,14 @@ export function createGrammarAuthor(options: {
     limits?: any;
     onRoute?: any;
 }): {
-    author: (question: any, hooks?: {}) => Promise<{
+    author: (question: any, hooks?: Record<string, any>) => Promise<{
         value: any;
+        errors?: undefined;
         raw: string;
         attempts: number;
     } | {
         errors: any[];
+        value?: undefined;
         raw: string;
         attempts: number;
     }>;

package/src/grammar.js

@@ -1,35 +1,44 @@
-//@ts-check
 /** One profile decoder and mandatory full-grammar gate for any injected compiler. */
 import { JarenValidator } from '@jarenjs/validate';
-import { createStructuredOutput } from './structured.js';
+import { createStructuredOutput } from "./structured.js";
 import { checkOutcome } from '@jarenjs/core/check';
-import { createRoutedClient } from './routing.js';
-
-/** @param {{ client: any, grammar: 'query'|'jslt'|'app'|'fsm'|'dag'|'statechart'|'workflow'|'model', profile: any,
- *   schema: any, refs?: any[], compile: (document: any) => any, gate?: any,
- *   maxRepairs?: number, stream?: boolean, onAttempt?: any,
- *   selectModel?: any, limits?: any, onRoute?: any }} options */
+import { createRoutedClient } from "./routing.js";
+/** @param options */
 export function createGrammarAuthor(options) {
-  if (!['query', 'jslt', 'app', 'fsm', 'dag', 'statechart', 'workflow', 'model'].includes(options.grammar))
-    throw new TypeError('unknown authored grammar');
-  if (!options.profile || !options.schema || typeof options.compile !== 'function')
-    throw new TypeError('grammar author needs a derived profile, full schema and compiler');
-  const validator = new JarenValidator({ skipErrors: false, collectErrors: true });
-  for (const ref of options.refs ?? []) validator.addSchema(ref);
-  const full = validator.compile(options.schema);
-  const generate = createStructuredOutput({ client: createRoutedClient(options, { purpose: 'author', grammar: options.grammar }), schema: options.profile,
-    name: `jaren_${options.grammar}`, strict: false, refs: options.refs,
-    maxRepairs: options.maxRepairs, stream: options.stream ?? true, onAttempt: options.onAttempt,
-    gate: [(document) => {
-      const shape = checkOutcome(full(document));
-      if (!shape.valid) return shape;
-      try { options.compile(document); return true; }
-      catch (error) { return { valid: false, errors: [{ code: error.code ?? 'AI0200',
-        docPath: error.docPath ?? '', message: error.reason ?? error.message }] }; }
-    }, ...[].concat(options.gate ?? [])],
-  });
-  return { author: (question, hooks = {}) => generate.generate([
-    { role: 'system', content: `Author a ${options.grammar} document. Return only JSON. The full grammar and compiler validate every response.` },
-    { role: 'user', content: question },
-  ], hooks) };
+    if (!['query', 'jslt', 'app', 'fsm', 'dag', 'statechart', 'workflow', 'model'].includes(options.grammar))
+        throw new TypeError('unknown authored grammar');
+    if (!options.profile || !options.schema || typeof options.compile !== 'function')
+        throw new TypeError('grammar author needs a derived profile, full schema and compiler');
+    const validator = new JarenValidator({ skipErrors: false, collectErrors: true });
+    for (const ref of options.refs ?? [])
+        validator.addSchema(ref);
+    const full = validator.compile(options.schema);
+    const generate = createStructuredOutput({
+        client: createRoutedClient(options, { purpose: 'author', grammar: options.grammar }), schema: options.profile,
+        name: `jaren_${options.grammar}`, strict: false, refs: options.refs,
+        maxRepairs: options.maxRepairs, stream: options.stream ?? true, onAttempt: options.onAttempt,
+        gate: [(document) => {
+                const shape = checkOutcome(full(document));
+                if (!shape.valid)
+                    return shape;
+                try {
+                    options.compile(document);
+                    return true;
+                }
+                catch (error) {
+                    return {
+                        valid: false, errors: [{
+                                code: error.code ?? 'AI0200',
+                                docPath: error.docPath ?? '', message: error.reason ?? error.message
+                            }]
+                    };
+                }
+            }, ...[].concat(options.gate ?? [])],
+    });
+    return {
+        author: (question, hooks = {}) => generate.generate([
+            { role: 'system', content: `Author a ${options.grammar} document. Return only JSON. The full grammar and compiler validate every response.` },
+            { role: 'user', content: question },
+        ], hooks)
+    };
 }

package/src/index.d.ts

@@ -1,9 +1,10 @@
-export { AiError } from "./errors.js";
-export { createSseDecoder } from "./sse.js";
-export { createStructuredOutput } from "./structured.js";
-export { createGrammarAuthor } from "./grammar.js";
-export { invalidInput } from "./check.js";
-export { PROVIDERS, resolveEndpoint, probeProvider } from "./providers.js";
-export { createChatClient, createStreamAccumulator } from "./client.js";
-export { createEmbeddingClient, probeEmbeddings, createHashEmbedder } from "./embed.js";
-export { createRoutedClient, MODEL_PURPOSES } from "./routing.js";
+/** models: public AI mechanisms over injected Jaren foundations. */
+export { AiError } from './errors.ts';
+export { PROVIDERS, resolveEndpoint, probeProvider } from './providers.ts';
+export { createSseDecoder } from './sse.ts';
+export { createChatClient, createStreamAccumulator } from './client.ts';
+export { createEmbeddingClient, probeEmbeddings, createHashEmbedder } from './embed.ts';
+export { createStructuredOutput } from './structured.ts';
+export { createGrammarAuthor } from './grammar.ts';
+export { createRoutedClient, MODEL_PURPOSES } from './routing.ts';
+export { invalidInput } from './check.ts';

package/src/index.js

@@ -1,11 +1,10 @@
-//@ts-check
 /** models: public AI mechanisms over injected Jaren foundations. */
-export { AiError } from './errors.js';
-export { PROVIDERS, resolveEndpoint, probeProvider } from './providers.js';
-export { createSseDecoder } from './sse.js';
-export { createChatClient, createStreamAccumulator } from './client.js';
-export { createEmbeddingClient, probeEmbeddings, createHashEmbedder } from './embed.js';
-export { createStructuredOutput } from './structured.js';
-export { createGrammarAuthor } from './grammar.js';
-export { createRoutedClient, MODEL_PURPOSES } from './routing.js';
-export { invalidInput } from './check.js';
+export { AiError } from "./errors.js";
+export { PROVIDERS, resolveEndpoint, probeProvider } from "./providers.js";
+export { createSseDecoder } from "./sse.js";
+export { createChatClient, createStreamAccumulator } from "./client.js";
+export { createEmbeddingClient, probeEmbeddings, createHashEmbedder } from "./embed.js";
+export { createStructuredOutput } from "./structured.js";
+export { createGrammarAuthor } from "./grammar.js";
+export { createRoutedClient, MODEL_PURPOSES } from "./routing.js";
+export { invalidInput } from "./check.js";

package/src/providers.d.ts

@@ -1,13 +1,47 @@
+/**
+ * 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.
+ */
+/**
+ * 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
+ */
+export declare const PROVIDERS: Record<string, {
+    label: string;
+    baseUrl: string | null;
+    local: boolean;
+    structured: 'json_schema' | 'json' | 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
+ * @param [options]
+ * @returns `base` is the
  *   normalized base URL every endpoint of this wire family hangs off;
  *   `url` is `${base}/chat/completions`
  */
-export function resolveEndpoint(options?: {
+export declare function resolveEndpoint(options?: {
     provider?: string;
     baseUrl?: string;
     apiKey?: string;
@@ -26,13 +60,9 @@ export function resolveEndpoint(options?: {
  * 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 }>}
+ * @param [options]
  */
-export function probeProvider(options?: {
+export declare function probeProvider(options?: {
     provider?: string;
     baseUrl?: string;
     apiKey?: string;
@@ -47,23 +77,3 @@ export function probeProvider(options?: {
     status?: number;
     error: string;
 }>;
-/**
- * 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: Record<string, {
-    label: string;
-    baseUrl: string | null;
-    local: boolean;
-    structured: "json_schema" | "json" | null;
-}>;

package/src/providers.js

@@ -1,4 +1,3 @@
-//@ts-check
 /**
  * Provider endpoint resolution for OpenAI-compatible chat APIs.
  *
@@ -16,9 +15,7 @@
  * same base) is composed from it — never re-derived from the chat URL
  * by string surgery.
  */
-
-import { AiError } from './errors.js';
-
+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`
@@ -30,100 +27,86 @@ import { AiError } from './errors.js';
  * 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 }>}
+ * @type
  */
 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 },
+    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
+ * @param [options]
+ * @returns `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 ?? '' };
+    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);
+    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 }>}
+ * @param [options]
  */
 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);
-  }
+    let endpoint;
+    try {
+        endpoint = resolveEndpoint(options);
+    }
+    catch (err) {
+        return { ok: false, 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`
+                : 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
@@ -131,26 +114,23 @@ export async function probeProvider(options = {}) {
  * `/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;
+    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;
 }