@tangleai/agents 0.21.1

package/src/program.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Compile a program document.
+ *
+ * Two stages, like every compiler in the suite: this one resolves names
+ * and compiles the embedded queries once, and the runner executes the
+ * result. Nothing here reads a slot's content and nothing here calls a
+ * model, so a compile is cheap enough to run on every authored candidate
+ * — which is exactly what makes it usable as a decoding gate.
+ *
+ * @param {any} doc - the program document
+ * @param {{ compileQuery?: ((document: any) => (data: any) => any) | null,
+ *   known?: Iterable<string>, recursive?: boolean, analyzeQuery?: any, annotateTypes?: any }} [options]
+ *   - `compileQuery` is the D3 seam. Absent, a program using `select` or
+ *     `reduce` is refused with AI0206 rather than half-compiled.
+ *   - `known` is what the environment already holds. Given, a `from`
+ *     that is neither a binding nor a known slot is AI0201 — the
+ *     "transition to an undeclared state" check, which is the whole
+ *     reason a compile gate catches what a schema cannot. Absent, only
+ *     bindings are resolved: nothing else can be checked without an
+ *     environment, and inventing an error would be worse than saying so.
+ * @returns {{ steps: any[], answer: { from: string, chars: number },
+ *   bindings: string[], chars: number }}
+ * @throws {ProgramError}
+ */
+export function compileProgram(doc: any, options?: {
+    compileQuery?: ((document: any) => (data: any) => any) | null;
+    known?: Iterable<string>;
+    recursive?: boolean;
+    analyzeQuery?: any;
+    annotateTypes?: any;
+}): {
+    steps: any[];
+    answer: {
+        from: string;
+        chars: number;
+    };
+    bindings: string[];
+    chars: number;
+};
+/**
+ * The compile gate, ready for `createStructuredOutput({ gate })`.
+ *
+ * One implementation of "does this program compile", used by the
+ * authoring path and by the runner, so a program that authored cleanly
+ * cannot fail differently when it runs.
+ * @param {{ compileQuery?: any, known?: Iterable<string>, recursive?: boolean, analyzeQuery?: any, annotateTypes?: any }} [options]
+ * @returns {(doc: any) => true | { valid: false, errors: any[] }}
+ */
+export function programGate(options?: {
+    compileQuery?: any;
+    known?: Iterable<string>;
+    recursive?: boolean;
+    analyzeQuery?: any;
+    annotateTypes?: any;
+}): (doc: any) => true | {
+    valid: false;
+    errors: any[];
+};
+/**
+ * Create a runner over an environment.
+ *
+ * @param {{ environment: any,
+ *   client?: { complete: (request: any) => Promise<any> },
+ *   compileQuery?: any,
+ *   recursive?: boolean, analyzeQuery?: any, annotateTypes?: any,
+ *   selectModel?: any, limits?: any, onRoute?: any, depth?: number,
+ *   model?: string,
+ *   maxSubcalls?: number, maxConcurrentSubcalls?: number,
+ *   subcallChars?: number, maxReduceChars?: number,
+ *   sequential?: boolean,
+ *   subcall?: (name: string, prompt: string, signal?: AbortSignal, index?: number) => Promise<any>,
+ *   account?: { reserve: Function, settle: Function, stop: () => string | null } }} options
+ *   - `client` is only needed by `map`; a program without one is a
+ *     perfectly good program (chunk / grep / select / stat / answer are
+ *     model-free), and running a `map` without a client is a stated
+ *     refusal rather than a crash.
+ *   - `sequential` runs sub-calls one at a time. It exists so the
+ *     benchmark can publish parallel against sequential wall-clock with
+ *     the same code path on both sides.
+ *   - `subcall` REPLACES what one piece of a map is worth. The default
+ *     asks the model about it; a recursive run passes a function that
+ *     spawns a child agent over that piece instead. This is a seam
+ *     rather than a second runner because the bound, the ordering, the
+ *     abort and the error capture must be identical at every depth —
+ *     one fan-out implementation, two things to fan out over.
+ *   - `account` is a budget shared with everything else in the run,
+ *     including other depths. Checked before each sub-call and charged
+ *     by it, so a tree cannot outspend the sum of its branches.
+ * @returns {{ run: (doc: any, hooks?: { signal?: AbortSignal }) => Promise<ProgramRunResult> }}
+ */
+export function createProgramRunner(options: {
+    environment: any;
+    client?: {
+        complete: (request: any) => Promise<any>;
+    };
+    compileQuery?: any;
+    recursive?: boolean;
+    analyzeQuery?: any;
+    annotateTypes?: any;
+    selectModel?: any;
+    limits?: any;
+    onRoute?: any;
+    depth?: number;
+    model?: string;
+    maxSubcalls?: number;
+    maxConcurrentSubcalls?: number;
+    subcallChars?: number;
+    maxReduceChars?: number;
+    sequential?: boolean;
+    subcall?: (name: string, prompt: string, signal?: AbortSignal, index?: number) => Promise<any>;
+    account?: {
+        reserve: Function;
+        settle: Function;
+        stop: () => string | null;
+    };
+}): {
+    run: (doc: any, hooks?: {
+        signal?: AbortSignal;
+    }) => Promise<ProgramRunResult>;
+};
+/**
+ * Author a program with a model, gated on the compiler.
+ *
+ * The root sees the environment's DIGEST and the question — never a
+ * slot's content (D2) — so the authoring request is the same size for a
+ * ten-kilobyte corpus and a ten-megabyte one. The schema constrains
+ * decoding, the compile gate constrains meaning, and a rejected
+ * candidate goes back with its code and its pointer.
+ *
+ * @param {{ client: any, environment: any, compileQuery?: any,
+ *   recursive?: boolean, analyzeQuery?: any, annotateTypes?: any,
+ *   selectModel?: any, limits?: any, onRoute?: any, depth?: number, account?: any,
+ *   createStructuredOutput: (options: any) => { generate: Function },
+ *   querySchema?: any, maxRepairs?: number, system?: string }} options
+ *   - `createStructuredOutput` is injected rather than imported so a
+ *     caller can wrap it (a probe counting attempts, a cache); the
+ *     package's own is the obvious argument.
+ *   - `querySchema` is the published query grammar. Given, `select` and
+ *     `reduce` are shape-constrained too and it is registered as a
+ *     `$ref`; absent, the compile gate carries it alone (D3).
+ * @returns {{ author: (question: string, hooks?: { signal?: AbortSignal }) => Promise<any> }}
+ */
+export function createProgramAuthor(options: {
+    client: any;
+    environment: any;
+    compileQuery?: any;
+    recursive?: boolean;
+    analyzeQuery?: any;
+    annotateTypes?: any;
+    selectModel?: any;
+    limits?: any;
+    onRoute?: any;
+    depth?: number;
+    account?: any;
+    createStructuredOutput: (options: any) => {
+        generate: Function;
+    };
+    querySchema?: any;
+    maxRepairs?: number;
+    system?: string;
+}): {
+    author: (question: string, hooks?: {
+        signal?: AbortSignal;
+    }) => Promise<any>;
+};
+export { readProgramAnswer } from "./program-result.js";
+/**
+ * A program that will not compile.
+ *
+ * Thrown, unlike `refine.js`'s AI01xx records, because this is a
+ * COMPILER and the suite's compilers throw coded errors with a
+ * `docPath` — which is what makes the documented two-line gate adapter
+ * (`try { compile(doc) } catch (e) { … }`) work here exactly as it does
+ * for a query, a stylesheet or a flow machine. {@link programGate} is
+ * that adapter, so a caller never writes it.
+ *
+ * The codes:
+ *
+ *   AI0200 — the document is not a program
+ *   AI0201 — a step reads a name nothing produced
+ *   AI0202 — a name is bound twice
+ *   AI0203 — the last step is not `answer`, or there is more than one
+ *   AI0204 — a `reduce` reads something that is not a `map`
+ *   AI0205 — the program is longer than its cap
+ *   AI0206 — a step needs the query seam and none is wired
+ *   AI0207 — a step reading ONE slot was given a family of pieces
+ *   AI0208 — a recursive result has an incompatible or unknown envelope
+ *   AI0209 — a runtime result violates its declared recursive shape
+ *
+ * A query that does not compile keeps the QUERY engine's own code
+ * (`JQ0002`, …) and its pointer is rebased onto the program document,
+ * so the model is told which step and which member — the same posture
+ * `refine.js` takes with the patch engine's codes.
+ */
+export class ProgramError extends CodedError {
+    /**
+     * @param {string} code - 'AI0200' … 'AI0209'
+     * @param {string} reason - the bare reason
+     * @param {string} [docPath] - JSON Pointer into the program document
+     */
+    constructor(code: string, reason: string, docPath?: string);
+}
+export namespace PROGRAM_EXAMPLE {
+    let steps: ({
+        op: string;
+        from: string;
+        as: string;
+        strategy: string;
+        size: number;
+        prompt?: undefined;
+        query?: undefined;
+    } | {
+        op: string;
+        from: string;
+        as: string;
+        prompt: string;
+        strategy?: undefined;
+        size?: undefined;
+        query?: undefined;
+    } | {
+        op: string;
+        from: string;
+        as: string;
+        query: {
+            $for: {
+                r: string;
+            };
+            $return: string;
+        };
+        strategy?: undefined;
+        size?: undefined;
+        prompt?: undefined;
+    } | {
+        op: string;
+        from: string;
+        as?: undefined;
+        strategy?: undefined;
+        size?: undefined;
+        prompt?: undefined;
+        query?: undefined;
+    })[];
+}
+export type ProgramRunResult = import("./program-result.js").ProgramRunResult;
+import { CodedError } from '@jarenjs/core/errors';