@demlik/tea 0.13.0 → 0.14.0

package/dist/llm-call/index.d.ts

@@ -1,311 +0,0 @@
-import { C as Cmd } from '../core-Co0LWkIA.js';
-import { RunCmd, SucceedMsg, FailMsg, ResilientState } from '../resilient-call/index.js';
-import { RetryPolicy } from '../retry-backoff/index.js';
-import { DeadlineExceeded, DeadlineSub } from '../deadline/index.js';
-export { deadlineSub, subscribeDeadline } from '../deadline/index.js';
-import 'zod';
-import '../cache/index.js';
-import '../types-XS_miRnB.js';
-import '../circuit-breaker/index.js';
-import '../protocol-B5YmJr0d.js';
-import '../rate-limit/index.js';
-
-/**
- * @packageDocumentation
- * @demlik/tea/llm-call — `resilient-call` + structured-output parse + a typed
- * failure variant, around a purpose-discriminated LLM invocation.
- *
- * This is the ~60-line `call_llm` handler from the audit-agent seed
- * (`interpret.ts` / `effects.ts`) collapsed into the uniform L2 knob: a config
- * object, the resilient-call slice it inherits, and one interpret handler that
- * assembles messages, binds the structured-output schema for the call's
- * `purpose`, invokes the model (retry composed from `../resilient-call`, NOT
- * reinvented), parses the output, and RETURNS the enriched resilient settle Msg
- * (`resilient_ok` / `resilient_err`) so it re-enters the host reducer and drives
- * the inherited succeed/fail → backoff → onTimer loop.
- *
- * ## What it adds over `../resilient-call`
- *
- *   - **Two DI ports** (the seed's two seams):
- *       1. `model: (modelId) => LLM` — the model factory. Tests pass a fake so
- *          the handler runs end-to-end without touching a real provider; the
- *          production worker wires `createChatModel(env, …)`.
- *       2. `loadMessages: Loader` — the SDK / message loader. The seed lazy-
- *          imports `@langchain/core/messages` (a top-level `import type` blows
- *          up the workers test runner); the loader keeps that import lazy and
- *          stubbable. It produces the `BaseMessage[]` for a given call.
- *   - **Structured-output parse** — each `purpose` maps to a `Schema` in
- *     `config.schemas`. The handler binds `model.withStructuredOutput(schema)`
- *     so the invoke resolves to a typed object; a `Schema.parse` that throws
- *     becomes a `resilient_err` carrying an `LlmErr` (a parse failure is a
- *     failure, not a stall — "errors are data"). `withStructuredOutput` is the
- *     seed's brain-only path; the fake model in tests returns the typed object
- *     directly.
- *   - **A typed failure variant** — every failure (model throw, timeout-via-
- *     retry-exhaustion, schema parse) is surfaced as the `LlmErr` carried on the
- *     enriched `resilient_err` settle Msg, tagged with the `purpose` so the
- *     consumer's reducer routes per-stage. The seed dispatched
- *     `llm_failed{purpose}`; the consumer rebuilds that shape in its reducer arm
- *     from `m.error: LlmErr`.
- *
- * ## Inheriting resilient-call by composition (not reinvention)
- *
- * The retry / backoff lives in `../resilient-call`: `createLlmCall` builds a
- * `createResilientCall` knob over the model-invoke port and DELEGATES `init`,
- * `attempt`, `succeed`, `fail`, `onTimer`, `subs` to it verbatim — the slice is
- * literally resilient-call's slice (the spec's "retry lives here"). There is no
- * second backoff implementation here. The handler runs the invoke through the
- * resilient-call handler so a transient model failure backs off exactly as a
- * resilient HTTP call would; the `purpose`-branch + structured parse wrap the
- * port the resilient handler drives.
- *
- * ## The two non-negotiables (canon, inherited)
- *
- *   - **Durable** — the slice is resilient-call's plain-data slice (a Model
- *     field). Input carried on the `resilient_run` Cmd is the plain
- *     `LlmCall` request (purpose + modelId + payload) — no closures.
- *   - **Replayable** — every transition is a resilient-call verb; the handler
- *     is the only impurity, and the one clock read is `Date.now()` at the
- *     effect boundary (inside the handler), exactly as the seed stamped its
- *     `llm_responded` / `llm_failed` Msgs.
- *
- * ## Typical wiring
- *
- *   const llm = createLlmCall<MyPurpose, MyOutputs>({
- *     model: (id) => createChatModel(env, id),
- *     schemas: { plan: planSchema, report: reportSchema },
- *     retry: defaultRetryPolicy,
- *     loadMessages: defaultMessagesLoader,
- *   });
- *
- *   // in the machine:
- *   init: () => [{ resilience: llm.init() }, []],
- *   update: {
- *     call_llm:  (s, m) => lift(s, llm.attempt(s.resilience, m.input, m.at)),
- *     // `resilient_ok` / `resilient_err` RE-ENTER from `handlers` (the settle
- *     // Msg the interpret handler returns). Run the inherited verb FIRST so the
- *     // succeed/fail → backoff → onTimer loop advances, THEN fold the enriched
- *     // payload (`m.result: LlmOk` / `m.error: LlmErr`) into the host's own
- *     // state — the enrichment lives in the reducer arm, not the handler.
- *     resilient_ok:  (s, m) => {
- *       const [slice, cmds] = llm.succeed(s.resilience, m.key, m);
- *       return [{ ...s, resilience: slice, output: m.result.output }, cmds];
- *     },
- *     resilient_err: (s, m) => {
- *       const [slice, cmds] = llm.fail(s.resilience, m.key, m);
- *       return [{ ...s, resilience: slice, failure: m.error }, cmds];
- *     },
- *     deadline_exceeded: (s, m) => lift(s, llm.onTimer(s.resilience, m)),
- *   },
- *   subscriptions: (s) => llm.subs(s.resilience),
- *   subscribe: { deadline: subscribeDeadline },
- *   interpret: llm.handlers(),
- */
-
-/**
- * The minimal structured-output schema contract: `parse(unknown) => T`, the
- * zod-style call the handler uses to validate the model's output before it
- * settles `resilient_ok`. A throwing `parse` (the zod contract on invalid
- * input) propagates out of `invokeOne` and is caught by the resilient handler,
- * which settles `resilient_err` (enriched to `LlmErr`) — a parse failure is a
- * failure, never a silent pass. Structural so a real `z.ZodType<T>` satisfies
- * it without an import.
- */
-interface Schema<T> {
-    /** Validate + narrow `value` to `T`, or throw on mismatch (the zod contract). */
-    parse(value: unknown): T;
-}
-/**
- * The minimal chat-model contract every model the handler talks to must
- * satisfy — the seed's `InjectableChatModel`, trimmed to the one operation
- * llm-call drives for brain-only stages:
- *
- *   `withStructuredOutput(schema)` → a runnable whose `invoke(messages)`
- *   resolves to a typed object matching `schema`.
- *
- * `BaseChatModel` from `@langchain/core` is the runtime type; this surface
- * names only what llm-call calls so a test fake can ignore the rest. Generic
- * over the message shape `Msg` so a consumer's loader and model agree on it
- * without llm-call inspecting messages.
- */
-interface Llm<Msg> {
-    withStructuredOutput<T>(schema: Schema<T>): {
-        invoke(messages: readonly Msg[]): Promise<T>;
-    };
-}
-/**
- * Build the `Msg[]` the handler hands to the bound model for a given call. The
- * SDK / message-assembly seam — the seed's `buildBaseMessages` + the lazy
- * `loadMessages` loader rolled into one injected port. Async because the seed
- * lazy-imports the SDK (a top-level `import type` of the langchain messages
- * package explodes the workers test runner). Receives the full `LlmCall` so it
- * can branch on `purpose` exactly as the seed's `buildBaseMessages` did.
- */
-type MessageLoader<P extends string, Msg> = (call: LlmCall<P>) => Promise<readonly Msg[]>;
-/**
- * The model factory — the first DI port. `(modelId) => Llm`. Tests pass a fake
- * builder; production wires `createChatModel(env, getModelConfig(id))`. `null`
- * means "the host's default model" (the seed's `string | null`).
- */
-type ModelFactory<Msg> = (modelId: string | null) => Llm<Msg>;
-/**
- * The llm-call knob. `model` and `schemas` are the load-bearing pair — the
- * model factory DI port and the per-purpose structured-output targets; the
- * rest is optional, exactly the resilient-call "omit a brick → omit its gate"
- * story for `retry`:
- *
- *   - `model`        — DI port 1: the model factory.
- *   - `schemas`      — one `Schema` per `Purpose`. The handler binds
- *                      `schemas[call.purpose]` as the structured-output target.
- *   - `retry`        — backoff policy, composed straight into `../resilient-
- *                      call`. Omit it and a model failure is terminal (no
- *                      backoff), exactly as resilient-call with no retry brick.
- *   - `loadMessages` — DI port 2: the SDK / message loader. Omit it and the
- *                      handler invokes the bound model with `[]` (a degenerate
- *                      but valid call) — provide it to assemble real messages.
- *
- * `P` is the purpose union (e.g. `"plan" | "report"`); `O` maps each purpose to
- * its parsed output type; `Msg` is the model's message shape (threaded through
- * the loader + model so llm-call never inspects a message).
- */
-interface LlmCallConfig<P extends string, O extends Record<P, unknown>, Msg = unknown> {
-    /** DI port 1 — the model factory. `(modelId) => Llm`. */
-    readonly model: ModelFactory<Msg>;
-    /** One structured-output schema per purpose; the parse target the handler binds. */
-    readonly schemas: {
-        readonly [K in P]: Schema<O[K]>;
-    };
-    /** Backoff policy, composed into `../resilient-call`. Omit → no backoff. */
-    readonly retry?: RetryPolicy;
-    /** DI port 2 — the SDK / message loader. Omit → the handler invokes with `[]`. */
-    readonly loadMessages?: MessageLoader<P, Msg>;
-}
-/**
- * One LLM call request — the resilient-call `input` for this knob, carried on
- * the `resilient_run` Cmd as plain data (no closures, invariant 3). Mirrors the
- * seed's purpose-discriminated `CallLlmCmd`: a `purpose` selecting the schema +
- * prompt assembly, the `model` id, and the opaque per-purpose `payload` the
- * loader consumes.
- *
- * `key` defaults to `purpose` when the consumer calls `attempt(s, purpose, …)`,
- * so one in-flight call per purpose is tracked under the resilient-call slice —
- * the common single-call-per-stage shape. A consumer that fans out many calls
- * of one purpose passes a distinct `key`.
- */
-interface LlmCall<P extends string> {
-    /** The stage / schema selector — drives both `schemas[purpose]` and message assembly. */
-    readonly purpose: P;
-    /** The model id to invoke; `null` = the host's default model. */
-    readonly model: string | null;
-    /** The per-purpose prompt payload the `MessageLoader` consumes. Opaque to the knob. */
-    readonly payload: unknown;
-}
-/** The parsed, typed success carried on the `resilient_ok` settle Msg, tagged with its purpose. */
-interface LlmOk<P extends string, O extends Record<P, unknown>> {
-    readonly key: string;
-    readonly purpose: P;
-    readonly output: O[P];
-}
-/** The typed failure variant — every failure path surfaces this, tagged by purpose. */
-interface LlmErr<P extends string> {
-    readonly key: string;
-    readonly purpose: P;
-    /** A human-readable cause (model throw, retry-exhaustion, or schema parse). */
-    readonly reason: string;
-    /** The original error, carried untouched for the consumer to inspect. */
-    readonly error: unknown;
-}
-/**
- * The settle Msgs llm-call's handler RETURNS from `interpret` so the substrate
- * enqueues them as follow-up Msgs (re-entry) into the host reducer — exactly as
- * `../resilient-call` does. They are the resilient-call settle Msgs with the
- * payloads ENRICHED to llm-call's typed variants: `result` is the parsed,
- * purpose-tagged `LlmOk`; `error` is the typed `LlmErr` (purpose + reason +
- * raw). The host wires `resilient_ok` → `succeed` and `resilient_err` → `fail`
- * reducer arms (the doc-comment wiring), and folds the enriched payload into its
- * own state there — llm-call never forces a Msg vocabulary on the host, and the
- * settle Msg drives the inherited succeed/fail → backoff → onTimer loop instead
- * of bypassing it.
- */
-type LlmSucceedMsg<P extends string, O extends Record<P, unknown>> = SucceedMsg<LlmOk<P, O>>;
-type LlmFailMsg<P extends string> = Omit<FailMsg, "error"> & {
-    readonly error: LlmErr<P>;
-};
-/** The retry / deadline timer Msg — `DeadlineExceeded`, inherited from resilient-call. */
-type LlmTimerMsg = DeadlineExceeded;
-/**
- * The ports the LEGACY detached `handlers(ports)` form takes. Two outbound Msg
- * builders the handler hands the typed Ok / Err; the consumer returns its own
- * Msg (or `undefined`). KEPT only for `../agent`, which still inherits the
- * detached shape; that path does NOT drive the retry loop (it dispatches the
- * consumer's Msg directly and never re-enters the resilient settle Msg). New
- * consumers use the no-arg `handlers()` form, which RETURNS the settle Msg for
- * re-entry and drives the inherited succeed/fail → backoff → onTimer loop.
- * `../agent` carries the same retry-loop gap and is fixed separately.
- *
- * The builders return `M | undefined` — `undefined` is the "dispatch nothing"
- * sentinel the detached form checks (`!== undefined`), spelled as `undefined`
- * rather than `void` so the union is unambiguous (a `void` member of a union is
- * confusing and reads as "may return anything").
- */
-interface LlmCallPorts<P extends string, O extends Record<P, unknown>, M> {
-    /** Build the Msg dispatched on a parsed success. Return `undefined` to dispatch nothing. */
-    readonly onOk: (ok: LlmOk<P, O>) => M | undefined;
-    /** Build the Msg dispatched on any failure (throw / retry-exhausted / parse). */
-    readonly onErr: (err: LlmErr<P>) => M | undefined;
-}
-/**
- * The effect Cmd the knob emits: run the LLM call for `key` with `input`. The
- * `input` is the plain `LlmCall` request — the handler reads `purpose` /
- * `model` / `payload` off it (invariant 3: Cmds are data).
- *
- * It is `../resilient-call`'s `RunCmd` specialized to the `LlmCall` input — NOT a
- * re-declared shape — so the resilient verbs' return tuples (`[State, RunCmd[]]`)
- * are this exact type and thread through `attempt` / `succeed` / `fail` /
- * `onTimer` with no cast.
- */
-type LlmRunCmd<P extends string> = RunCmd<LlmCall<P>>;
-/**
- * Build an llm-call knob from `config`. `rng` is injected for the inherited
- * retry jitter (pass a fixed `() => 0.5` in tests to pin backoff; defaults to
- * `Math.random`, read only at the resilient-call verb boundary).
- *
- * Returns the uniform L2 knob contract. The slice + verbs (`init`, `attempt`,
- * `succeed`, `fail`, `onTimer`, `subs`) are DELEGATED to a `../resilient-call`
- * knob built over the structured-output model-invoke port — no second backoff
- * here. `handlers` is the one new piece: the purpose-branching, schema-parsing
- * wrapper that returns the enriched resilient settle Msg for re-entry.
- *
- * `P` is the purpose union, `O` the purpose→output map, `Msg` the model's
- * message shape.
- */
-declare function createLlmCall<P extends string, O extends Record<P, unknown>, Msg = unknown>(config: LlmCallConfig<P, O, Msg>, rng?: () => number): {
-    init: () => ResilientState<LlmCall<P>, LlmOk<P, O>>;
-    attempt: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>, input: LlmCall<P>, at: number, key?: string) => readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly LlmRunCmd<P>[]];
-    succeed: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>, key: string, msg: LlmSucceedMsg<P, O>) => readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly LlmRunCmd<P>[]];
-    fail: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>, key: string, msg: LlmFailMsg<P>) => readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly LlmRunCmd<P>[]];
-    onTimer: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>, msg: LlmTimerMsg) => readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly LlmRunCmd<P>[]];
-    subs: (s: ResilientState<LlmCall<P>, LlmOk<P, O>>) => readonly DeadlineSub[];
-    handlers: {
-        (): {
-            resilient_run: (cmd: LlmRunCmd<P>) => Promise<LlmSucceedMsg<P, O> | LlmFailMsg<P>>;
-        };
-        <M>(ports: LlmCallPorts<P, O, M>): {
-            resilient_run: (cmd: LlmRunCmd<P>, ctx: {
-                waitUntil(p: Promise<unknown>): void;
-                dispatch(msg: M): unknown;
-            }) => void;
-        };
-    };
-    invokeOne: (input: LlmCall<P>) => Promise<LlmOk<P, O>>;
-};
-/**
- * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the
- * slice lives at `state.resilience` — the same convenience `../resilient-call`
- * ships, re-typed for the llm-call slice so consumers wire one import. Pure.
- */
-declare function liftLlmCall<S extends {
-    resilience: ResilientState<LlmCall<P>, LlmOk<P, O>>;
-}, P extends string, O extends Record<P, unknown>, C extends Cmd>(state: S, result: readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly C[]]): readonly [S, readonly C[]];
-
-export { DeadlineExceeded, DeadlineSub, type Llm, type LlmCall, type LlmCallConfig, type LlmCallPorts, type LlmErr, type LlmFailMsg, type LlmOk, type LlmRunCmd, type LlmSucceedMsg, type LlmTimerMsg, type MessageLoader, type ModelFactory, ResilientState, type Schema, createLlmCall, liftLlmCall };

package/dist/llm-call/index.js

@@ -1,16 +0,0 @@
-export { createLlmCall, liftLlmCall } from '../chunk-COS5MSTO.js';
-import '../chunk-4KLG43GY.js';
-import '../chunk-JELSZN25.js';
-import '../chunk-RH5EFRVJ.js';
-export { deadlineSub, subscribeDeadline } from '../chunk-DGE4PV4A.js';
-import '../chunk-Q2UM7BXU.js';
-import '../chunk-S2EGRPCM.js';
-import '../chunk-UF4MZSLT.js';
-import '../chunk-G5E74IJB.js';
-import '../chunk-VYFAZN3F.js';
-import '../chunk-2YFLOCWX.js';
-import '../chunk-ZJ5AOYBH.js';
-import '../chunk-ZSUUOEPL.js';
-import '../chunk-OOYD44JI.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/llm-call/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}