@tangleai/models 0.21.1 → 0.25.0

package/src/structured.js

@@ -1,4 +1,3 @@
-//@ts-check
 /**
  * Structured output: schema in, validated JSON value out — on every
  * provider tier.
@@ -13,14 +12,11 @@
  * accelerator, not an authority. On failure the instancePath'd errors
  * go back to the model for a bounded number of repair rounds.
  */
-
 import { JarenValidator } from '@jarenjs/validate';
 import { checkOutcome, composeChecks } from '@jarenjs/core/check';
-import { PROVIDERS } from './providers.js';
-
+import { PROVIDERS } from "./providers.js";
 /** Validation errors reported per failed generation: enough to repair. */
 const MAX_ERRORS = 8;
-
 /**
  * Normalize an injected check's errors into the compact records a
  * repair prompt carries. The default `JarenValidator` check reports
@@ -35,81 +31,64 @@ const MAX_ERRORS = 8;
  * `message` so the record never carries the code and the path twice —
  * the composed `message` already contains both, and the fields beside
  * it are the structured copies.
- * @param {any[]} raw
  */
 function normalizeErrors(raw) {
-  return raw.slice(0, MAX_ERRORS).map((e) => {
-    /** @type {any} */
-    const out = {
-      instancePath: e.docPath ?? e.instancePath ?? '',
-      keyword: e.code ?? e.keyword ?? '',
-      message: e.reason ?? e.message ?? 'invalid',
-    };
-    if (e.code !== undefined) out.code = e.code;
-    if (e.docPath !== undefined) out.docPath = e.docPath;
-    return out;
-  });
+    return raw.slice(0, MAX_ERRORS).map((e) => {
+        const out = {
+            instancePath: e.docPath ?? e.instancePath ?? '',
+            keyword: e.code ?? e.keyword ?? '',
+            message: e.reason ?? e.message ?? 'invalid',
+        };
+        if (e.code !== undefined)
+            out.code = e.code;
+        if (e.docPath !== undefined)
+            out.docPath = e.docPath;
+        return out;
+    });
 }
-
 /**
  * The system instruction for providers that cannot (fully) constrain
  * decoding: the schema travels in the prompt and the reply must be the
  * bare JSON value.
- * @param {any} schema
  */
 function schemaInstruction(schema) {
-  return [
-    'Reply with a single JSON value that validates against this JSON Schema.',
-    'Output ONLY the JSON — no prose, no code fences.',
-    '',
-    JSON.stringify(schema),
-  ].join('\n');
+    return [
+        'Reply with a single JSON value that validates against this JSON Schema.',
+        'Output ONLY the JSON — no prose, no code fences.',
+        '',
+        JSON.stringify(schema),
+    ].join('\n');
 }
-
 /**
  * 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) {
-  const trimmed = text.trim();
-  const match = /^```(?:json)?\s*([\s\S]*?)\s*```$/.exec(trimmed);
-  return match === null ? trimmed : match[1];
+    const trimmed = text.trim();
+    const match = /^```(?:json)?\s*([\s\S]*?)\s*```$/.exec(trimmed);
+    return match === null ? trimmed : match[1];
 }
-
 /**
  * Compile a schema that may reference others by `$id`, registering the
  * referenced schemas first. Every Jaren engine-document grammar
  * (fsm/dag/app/JSLT) composes the query grammar by `$ref`, so a plain
  * `.compile(schema)` on one of them throws "Can not resolve schema".
- * @param {any} schema
- * @param {any[]} [refs]
- * @returns {(value: any) => any}
+ * @param [refs]
  */
 function compileWithRefs(schema, refs) {
-  const v = new JarenValidator({ skipErrors: false, collectErrors: true });
-  for (const ref of refs ?? []) v.addSchema(ref);
-  return v.compile(schema);
+    const v = new JarenValidator({ skipErrors: false, collectErrors: true });
+    for (const ref of refs ?? [])
+        v.addSchema(ref);
+    return v.compile(schema);
 }
-
 /**
  * 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`,
@@ -138,82 +117,74 @@ function compileWithRefs(schema, refs) {
  *     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) {
-  const { client, schema } = options;
-  if (schema === null || typeof schema !== 'object')
-    throw new TypeError('createStructuredOutput needs a JSON Schema object');
-  const name = options.name ?? 'result';
-  const maxRepairs = options.maxRepairs ?? 1;
-  // Non-streaming stays the DEFAULT, and the reason is a behaviour change
-  // rather than a preference: a caller reading `raw` or counting attempts
-  // gets the same answer either way, but a caller that passed a client
-  // with `onDelta` wired sees deltas start arriving where none did
-  // before. The measurement that made this an option: the campaign's
-  // authoring timeouts were on STREAMED calls, so streaming is not the
-  // cure for a slow authoring turn — but it is how a long turn stays
-  // observable, and a caller who wants that should not have to wrap the
-  // client to get it.
-  const stream = options.stream ?? false;
-  const base = options.validator ?? compileWithRefs(schema, options.refs);
-  const gates = options.gate === undefined ? [] : [].concat(options.gate);
-  const check = composeChecks(...gates);
-  const tier = PROVIDERS[client.endpoint.provider]?.structured ?? null;
-
-  /**
-   * @param {any[]} messages - wire-shape conversation to answer
-   * @param {{ signal?: AbortSignal }} [hooks]
-   */
-  async function generate(messages, hooks = {}) {
-    /** @type {any} */
-    const request = { stream, signal: hooks.signal };
-    let turn = [...messages];
-    if (tier === 'json_schema') {
-      request.responseFormat = { name, schema, strict: options.strict ?? true };
+    const { client, schema } = options;
+    if (schema === null || typeof schema !== 'object')
+        throw new TypeError('createStructuredOutput needs a JSON Schema object');
+    const name = options.name ?? 'result';
+    const maxRepairs = options.maxRepairs ?? 1;
+    // Non-streaming stays the DEFAULT, and the reason is a behaviour change
+    // rather than a preference: a caller reading `raw` or counting attempts
+    // gets the same answer either way, but a caller that passed a client
+    // with `onDelta` wired sees deltas start arriving where none did
+    // before. The measurement that made this an option: the campaign's
+    // authoring timeouts were on STREAMED calls, so streaming is not the
+    // cure for a slow authoring turn — but it is how a long turn stays
+    // observable, and a caller who wants that should not have to wrap the
+    // client to get it.
+    const stream = options.stream ?? false;
+    const base = options.validator ?? compileWithRefs(schema, options.refs);
+    const gates = options.gate === undefined ? [] : [].concat(options.gate);
+    const check = composeChecks(...gates);
+    const tier = PROVIDERS[client.endpoint.provider]?.structured ?? null;
+    /**
+     * @param messages - wire-shape conversation to answer
+     * @param [hooks]
+     */
+    async function generate(messages, hooks = {}) {
+        const request = { stream, signal: hooks.signal };
+        let turn = [...messages];
+        if (tier === 'json_schema') {
+            request.responseFormat = { name, schema, strict: options.strict ?? true };
+        }
+        else {
+            // JSON mode (or nothing): the schema travels in the prompt;
+            // local validation makes the weaker tiers safe
+            if (tier === 'json')
+                request.responseFormat = { type: 'json' };
+            turn = [{ role: 'system', content: schemaInstruction(schema) }, ...turn];
+        }
+        let raw = '';
+        let errors = [];
+        for (let attempt = 1; attempt <= 1 + maxRepairs; attempt++) {
+            const result = await client.complete({ ...request, messages: turn });
+            raw = result.message.content;
+            let value;
+            try {
+                value = JSON.parse(unfence(raw));
+            }
+            catch (err) {
+                errors = [{ instancePath: '', keyword: 'parse', message: `the reply is not JSON: ${err.message}` }];
+                options.onAttempt?.({ attempt, outcome: 'schema', errors });
+                turn = [...turn,
+                    { role: 'assistant', content: raw },
+                    { role: 'user', content: 'That reply was not parseable JSON. Reply again with ONLY the JSON value.' }];
+                continue;
+            }
+            const shape = checkOutcome(base(value));
+            const outcome = shape.valid ? checkOutcome(check(value)) : shape;
+            if (outcome.valid) {
+                options.onAttempt?.({ attempt, outcome: 'valid', errors: [] });
+                return { value, raw, attempts: attempt };
+            }
+            errors = normalizeErrors(outcome.errors);
+            options.onAttempt?.({ attempt, outcome: shape.valid ? 'gate' : 'schema', errors });
+            turn = [...turn,
+                { role: 'assistant', content: raw },
+                { role: 'user', content: `That JSON does not validate against the schema. Fix exactly these and reply with ONLY the corrected JSON value:\n${JSON.stringify(errors)}` }];
+        }
+        return { errors, raw, attempts: 1 + maxRepairs };
     }
-    else {
-      // JSON mode (or nothing): the schema travels in the prompt;
-      // local validation makes the weaker tiers safe
-      if (tier === 'json') request.responseFormat = { type: 'json' };
-      turn = [{ role: 'system', content: schemaInstruction(schema) }, ...turn];
-    }
-
-    let raw = '';
-    /** @type {any[]} */
-    let errors = [];
-    for (let attempt = 1; attempt <= 1 + maxRepairs; attempt++) {
-      const result = await client.complete({ ...request, messages: turn });
-      raw = result.message.content;
-      /** @type {any} */
-      let value;
-      try {
-        value = JSON.parse(unfence(raw));
-      }
-      catch (err) {
-        errors = [{ instancePath: '', keyword: 'parse', message: `the reply is not JSON: ${/** @type {Error} */ (err).message}` }];
-        options.onAttempt?.({ attempt, outcome: 'schema', errors });
-        turn = [...turn,
-          { role: 'assistant', content: raw },
-          { role: 'user', content: 'That reply was not parseable JSON. Reply again with ONLY the JSON value.' }];
-        continue;
-      }
-      const shape = checkOutcome(base(value));
-      const outcome = shape.valid ? checkOutcome(check(value)) : shape;
-      if (outcome.valid) {
-        options.onAttempt?.({ attempt, outcome: 'valid', errors: [] });
-        return { value, raw, attempts: attempt };
-      }
-      errors = normalizeErrors(outcome.errors);
-      options.onAttempt?.({ attempt, outcome: shape.valid ? 'gate' : 'schema', errors });
-      turn = [...turn,
-        { role: 'assistant', content: raw },
-        { role: 'user', content: `That JSON does not validate against the schema. Fix exactly these and reply with ONLY the corrected JSON value:\n${JSON.stringify(errors)}` }];
-    }
-    return { errors, raw, attempts: 1 + maxRepairs };
-  }
-
-  return { generate };
+    return { generate };
 }