@neutrome/lilsdk 0.4.6 → 0.5.1

package/src/output.ts

@@ -1,31 +1,19 @@
-import {
-  createProgram,
-  Opcode,
-  streamEnd,
-  streamStart,
-  streamTextDelta,
-  type Program,
-} from "@neutrome/lil-engine";
+import { delta } from "@neutrome/lil-engine";
 import type { OutputSink } from "./types.ts";
 
-export async function writeReasoning(
+/**
+ * Writes a model-reasoning chunk to a sink.
+ *
+ * @param sink - Sink to write to.
+ * @param text - Reasoning text to emit.
+ * @example
+ * ```ts
+ * await writeThinking(sink, "Checking the attachment first.");
+ * ```
+ */
+export async function writeThinking(
   sink: OutputSink,
   text: string,
 ): Promise<void> {
-  await sink.write(streamReasoningDelta(text));
-}
-
-export function streamTextResponse(text: string): Program[] {
-  return [streamStart(), streamTextDelta(text), streamEnd()];
-}
-
-export function streamReasoningDelta(text: string): Program {
-  return createProgram({
-    code: [
-      {
-        opcode: Opcode.STREAM_THINK_DELTA,
-        value: { kind: "string", value: text },
-      },
-    ],
-  });
+  await sink.write(delta.thinking(text));
 }

package/src/primitives/index.ts

@@ -4,16 +4,37 @@ import {
   type Program,
 } from "@neutrome/lil-engine";
 
+/**
+ * Finds the position of an instruction by value.
+ *
+ * @param program - Program to search.
+ * @param needle - Instruction to match, compared by opcode and payload.
+ * @returns The index, or `-1` when absent.
+ */
 export function indexOf(program: Program, needle: Instruction): number {
   return program.code.findIndex((instruction) =>
     instructionEquals(instruction, needle),
   );
 }
 
+/**
+ * Reports whether a program contains an instruction by value.
+ *
+ * @param program - Program to search.
+ * @param needle - Instruction to match.
+ * @returns `true` when a matching instruction exists.
+ */
 export function has(program: Program, needle: Instruction): boolean {
   return indexOf(program, needle) >= 0;
 }
 
+/**
+ * Reads the first instruction matching a value.
+ *
+ * @param program - Program to search.
+ * @param needle - Instruction to match.
+ * @returns A copy of the match, or `undefined` when absent.
+ */
 export function find(
   program: Program,
   needle: Instruction,
@@ -22,6 +43,12 @@ export function find(
   return i >= 0 ? cloneInstruction(program.code[i]!) : undefined;
 }
 
+/**
+ * Visits every instruction in order.
+ *
+ * @param program - Program to walk.
+ * @param callback - Called with each instruction, its index and the program.
+ */
 export function walk(
   program: Program,
   callback: (instruction: Instruction, index: number, program: Program) => void,
@@ -31,6 +58,19 @@ export function walk(
   );
 }
 
+/**
+ * Rewrites every instruction.
+ *
+ * @param program - Program to map.
+ * @param callback - Returns the replacement for each instruction.
+ * @returns A new program; the input is left untouched.
+ * @example
+ * ```ts
+ * const redacted = map(program, (instruction) =>
+ *   instruction.opcode === Opcode.TXT_CHUNK ? redact(instruction) : instruction,
+ * );
+ * ```
+ */
 export function map(
   program: Program,
   callback: (
@@ -47,6 +87,13 @@ export function map(
   };
 }
 
+/**
+ * Keeps only the instructions a predicate accepts.
+ *
+ * @param program - Program to filter.
+ * @param callback - Returns `true` for instructions to keep.
+ * @returns A new program; the input is left untouched.
+ */
 export function filter(
   program: Program,
   callback: (
@@ -63,6 +110,14 @@ export function filter(
   };
 }
 
+/**
+ * Folds the instruction list into a single value.
+ *
+ * @param program - Program to fold.
+ * @param callback - Combines the accumulator with each instruction.
+ * @param initialValue - Starting accumulator.
+ * @returns The final accumulator.
+ */
 export function reduce<T>(
   program: Program,
   callback: (
@@ -80,6 +135,13 @@ export function reduce<T>(
   return accumulator;
 }
 
+/**
+ * Reports whether every instruction satisfies a predicate.
+ *
+ * @param program - Program to test.
+ * @param callback - Predicate applied to each instruction.
+ * @returns `true` when all instructions pass, including for empty programs.
+ */
 export function all(
   program: Program,
   callback: (
@@ -94,6 +156,13 @@ export function all(
   return true;
 }
 
+/**
+ * Reports whether any instruction satisfies a predicate.
+ *
+ * @param program - Program to test.
+ * @param callback - Predicate applied to each instruction.
+ * @returns `true` when at least one instruction passes.
+ */
 export function any(
   program: Program,
   callback: (

package/src/stream/index.ts

@@ -1,9 +1,5 @@
 export type { ObservedExecution, StreamObservationHooks } from "../observe.ts";
 
 export { observeExecutionStream } from "../observe.ts";
-export { completeStream, streamStage } from "./stages.ts";
-export {
-  streamReasoningDelta,
-  streamTextResponse,
-  writeReasoning,
-} from "../output.ts";
+export { streamStage } from "./stages.ts";
+export { writeThinking } from "../output.ts";

package/src/stream/stages.ts

@@ -1,6 +1,19 @@
-import { createProgram, Opcode, type Program } from "@neutrome/lil-engine";
+import { Opcode, type Program } from "@neutrome/lil-engine";
 
-/** Streams one stage without allowing it to complete the enclosing stream. */
+/**
+ * Forwards one stage of a stream without letting it close the outer stream.
+ *
+ * Drops the `RESP_DONE` and `STREAM_END` instructions, so several executors can
+ * stream into one response and only the last one finishes it.
+ *
+ * @param source - Chunks to forward.
+ * @returns The chunks, minus any terminal instructions.
+ * @example
+ * ```ts
+ * for await (const chunk of streamStage(ctx.invokeStream(draft, request))) yield chunk;
+ * yield delta.end();
+ * ```
+ */
 export async function* streamStage(
   source: AsyncIterable<Program>,
 ): AsyncGenerator<Program> {
@@ -14,12 +27,3 @@ export async function* streamStage(
     yield code.length === chunk.code.length ? chunk : { ...chunk, code };
   }
 }
-
-export function completeStream(reason = "stop"): Program {
-  return createProgram({
-    code: [
-      { opcode: Opcode.RESP_DONE, value: { kind: "string", value: reason } },
-      { opcode: Opcode.STREAM_END, value: { kind: "none" } },
-    ],
-  });
-}

package/src/tools-support.ts

@@ -1,5 +1,8 @@
-import { addTool, type Program } from "@neutrome/lil-engine";
-import { prependSystemPrompt } from "./synthetic/index.ts";
+import {
+  appendTool,
+  prependSystemPrompt,
+  type Program,
+} from "@neutrome/lil-engine";
 import {
   createExecutionEvent,
   type ExecutorContext,
@@ -14,6 +17,9 @@ export type ToolExecution = {
   result: string;
 };
 
+/**
+ * Thrown when a model calls a tool with arguments that are not valid JSON.
+ */
 export class ToolArgumentsError extends Error {
   constructor(
     readonly toolName: string,
@@ -36,7 +42,7 @@ export function buildToolAugmenter(tools: readonly Tool[]) {
       augmented = prependSystemPrompt(augmented, fragments.join("\n\n"));
     }
     for (const tool of tools) {
-      augmented = addTool(
+      augmented = appendTool(
         augmented,
         tool.name,
         tool.description,

package/src/tools.ts

@@ -1,15 +1,14 @@
 import {
-  callData,
+  appendToolInteraction,
   createProgram,
-  decodeStreamToolDelta,
+  delta,
+  extractToolCalls,
   isStreaming,
   Opcode,
   setStreaming,
   type Instruction,
   type Program,
-  type StreamToolDelta,
 } from "@neutrome/lil-engine";
-import { appendToolInteraction } from "./synthetic/index.ts";
 import {
   type Executor,
   type ExecutorContext,
@@ -26,14 +25,16 @@ import {
 
 export { ToolArgumentsError } from "./tools-support.ts";
 
-export type WithToolsOptions = {
+/** Options accepted by {@link createToolsExecutor}. */
+export type ToolsExecutorOptions = {
+  /** Maximum tool round trips before the loop gives up. Defaults to 10. */
   maxIterations?: number;
 };
 
 const DEFAULT_MAX_ITERATIONS = 10;
 
 type ToolDeltaAcc = { index: number; id: string; name: string; args: string };
-type DecodedToolDelta = { instruction: Instruction; delta: StreamToolDelta };
+type DecodedToolDelta = { instruction: Instruction; delta: delta.ToolCall };
 
 function collectToolDeltasFromChunk(
   chunk: Program,
@@ -41,19 +42,19 @@ function collectToolDeltasFromChunk(
 ): DecodedToolDelta[] {
   const deltas: DecodedToolDelta[] = [];
   for (const instr of chunk.code) {
-    const delta = decodeStreamToolDelta(instr);
-    if (!delta) continue;
-    deltas.push({ instruction: instr, delta });
-    const current = acc.get(delta.index) ?? {
-      index: delta.index,
+    const toolCall = delta.decodeToolCall(instr);
+    if (!toolCall) continue;
+    deltas.push({ instruction: instr, delta: toolCall });
+    const current = acc.get(toolCall.index) ?? {
+      index: toolCall.index,
       id: "",
       name: "",
       args: "",
     };
-    if (delta.id) current.id = delta.id;
-    if (delta.name) current.name = delta.name;
-    if (delta.arguments) current.args += delta.arguments;
-    acc.set(delta.index, current);
+    if (toolCall.id) current.id = toolCall.id;
+    if (toolCall.name) current.name = toolCall.name;
+    if (toolCall.arguments) current.args += toolCall.arguments;
+    acc.set(toolCall.index, current);
   }
   return deltas;
 }
@@ -179,10 +180,26 @@ async function* streamToolLoop(
   });
 }
 
-export function connectTools(
-  tools: Tool[],
+/**
+ * Wraps an executor in a tool loop.
+ *
+ * The returned executor declares `tools` to the model, runs any it owns, feeds
+ * the results back and repeats. Calls to tools it does not own are passed
+ * through to the caller untouched, so an outer loop can handle them.
+ *
+ * @param inner - Executor or model id that does the generating.
+ * @param tools - Tools this loop owns and executes.
+ * @param options - Loop limits.
+ * @returns An executor that resolves tool calls before answering.
+ * @example
+ * ```ts
+ * export default createToolsExecutor("core/turn-1", [searchTool, calculatorTool]);
+ * ```
+ */
+export function createToolsExecutor(
   inner: ExecutorInput,
-  options: WithToolsOptions = {},
+  tools: Tool[],
+  options: ToolsExecutorOptions = {},
 ): Executor {
   const maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS;
   const toolMap = new Map(tools.map((t) => [t.name, t]));
@@ -198,7 +215,7 @@ export function connectTools(
 
       while (canRunToolLoop(state, maxIterations)) {
         const response = await ctx.invoke(inner, state.request);
-        const calls = callData(response);
+        const calls = extractToolCalls(response);
         const decision = decideToolLoop(calls, toolMap);
         if (decision.kind !== "continue") return response;
 

package/src/types.ts

@@ -1,5 +1,6 @@
 import type { Program } from "@neutrome/lil-engine";
 
+/** A capability a {@link ProgramTransform} declares before it may be applied. */
 export type TransformCapability =
   | "read_messages"
   | "write_messages"
@@ -8,77 +9,201 @@ export type TransformCapability =
   | "drop_content"
   | "provider_extension";
 
+/** One audit record emitted while a request is being served. */
 export type ExecutionEvent = {
+  /** Event name, such as `"executor.start"`. */
   kind: string;
+  /** Id shared by every event of one inbound request. */
   requestId: string;
+  /** Id of the execution that emitted the event. */
   executionId: string;
+  /** ISO timestamp of the event. */
   timestamp: string;
+  /** Id of the enclosing execution, when nested. */
   parentExecutionId?: string;
+  /** What the execution was talking to. */
   target?: { kind: "provider" | "executor"; id: string };
+  /** Error class, for failure events. */
   errorKind?: string;
+  /** Free-form payload. */
   data?: Record<string, unknown>;
 };
 
+/** {@link ExecutionEvent} before a timestamp is stamped on it. */
 export type ExecutionEventInput = Omit<ExecutionEvent, "timestamp"> & {
   timestamp?: string;
 };
 
+/** Expiry options accepted by {@link Cache.put}. */
 export type CachePutOptions = {
+  /** Absolute expiry, as a Unix timestamp in seconds. */
   expiration?: number;
+  /** Relative expiry, in seconds from now. */
   expirationTtl?: number;
 };
 
+/** Key-value store handed to executors through {@link RuntimeContext.cache}. */
 export type Cache = {
+  /** Reads a value, or `null` when the key is unset. */
   get(key: string): Promise<string | null>;
+  /** Writes a value, optionally with an expiry. */
   put(key: string, value: string, options?: CachePutOptions): Promise<void>;
+  /** Removes a key. */
   delete(key: string): Promise<void>;
 };
 
-type RuntimeContext = {
+/**
+ * The runtime services available while a request is being served.
+ *
+ * Executors and transforms never talk to providers directly: they call
+ * {@link RuntimeContext.invoke}, which lets the runtime handle routing,
+ * auditing and cancellation.
+ */
+export type RuntimeContext = {
+  /** Request-scoped cache. */
   cache: Cache;
+  /**
+   * Runs another executor, or a model id, to completion.
+   *
+   * @param executor - Executor value or model id to run.
+   * @param request - Program to send.
+   * @returns The response program.
+   */
   invoke(executor: ExecutorInput, request: Program): Promise<Program>;
+  /**
+   * Runs another executor, or a model id, and streams its chunks.
+   *
+   * @param executor - Executor value or model id to run.
+   * @param request - Program to send.
+   * @returns The response chunks.
+   */
   invokeStream(
     executor: ExecutorInput,
     request: Program,
   ): AsyncIterable<Program>;
+  /**
+   * Records an audit event.
+   *
+   * @param event - Event to record.
+   */
   observe(event: ExecutionEvent): void;
+  /** Aborts when the client goes away or the request times out. */
   signal: AbortSignal;
 };
 
-export type TransformContext = RuntimeContext;
-
+/** A named, capability-scoped edit applied to every program passing through. */
 export type ProgramTransform = {
+  /** Transform name, used in audit events. */
   name: string;
+  /** Everything this transform is allowed to do. */
   capabilities: TransformCapability[];
-  apply(program: Program, ctx: TransformContext): Program | Promise<Program>;
+  /**
+   * Applies the transform.
+   *
+   * @param program - Program to edit.
+   * @param ctx - Runtime services.
+   * @returns The edited program.
+   */
+  apply(program: Program, ctx: RuntimeContext): Program | Promise<Program>;
 };
 
+/** {@link RuntimeContext} plus the identity of the running execution. */
 export type ExecutorContext = RuntimeContext & {
+  /** Id shared by every execution of one inbound request. */
   requestId: string;
+  /** Id of this execution. */
   executionId: string;
+  /** Id of the enclosing execution, when nested. */
   parentExecutionId?: string;
 };
 
+/**
+ * The unit of composition: something that answers a program.
+ *
+ * Both methods must be implemented, so an executor can be used in a streaming
+ * and a non-streaming request alike.
+ *
+ * @example
+ * ```ts
+ * const executor: Executor = {
+ *   async execute(request, ctx) {
+ *     return ctx.invoke(upstream, prependSystemPrompt(request, system()));
+ *   },
+ *   async *stream(request, ctx) {
+ *     yield* ctx.invokeStream(upstream, prependSystemPrompt(request, system()));
+ *   },
+ * };
+ * ```
+ */
 export type Executor = {
+  /**
+   * Answers a request in one shot.
+   *
+   * @param request - Program to answer.
+   * @param ctx - Runtime services and execution identity.
+   * @returns The response program.
+   */
   execute(request: Program, ctx: ExecutorContext): Promise<Program>;
+  /**
+   * Answers a request as a chunk stream.
+   *
+   * @param request - Program to answer.
+   * @param ctx - Runtime services and execution identity.
+   * @returns The response chunks.
+   */
   stream(request: Program, ctx: ExecutorContext): AsyncIterable<Program>;
 };
 
+/**
+ * An executor, or the id of a model to run.
+ *
+ * Every combinator in this package accepts either, so `retry("fast/gemma-4-31b")`
+ * and `retry(myExecutor)` are both valid.
+ */
 export type ExecutorInput = string | Executor;
 
+/** A tool the model may call during a tool loop. */
 export type Tool = {
+  /** Tool name the model must use when calling it. */
   name: string;
+  /** Natural-language description shown to the model. */
   description: string;
+  /** JSON Schema describing the arguments. */
   schema: Record<string, unknown>;
+  /** Extra instructions appended to the system prompt when this tool is enabled. */
   systemPromptFragment?: string;
+  /**
+   * Runs the tool.
+   *
+   * @param args - Arguments the model supplied, already parsed.
+   * @param ctx - Runtime services and execution identity.
+   * @returns The result, rendered as text for the model.
+   */
   execute(args: Record<string, unknown>, ctx: ExecutorContext): Promise<string>;
 };
 
+/** Where streamed chunks are written. */
 export type OutputSink = {
+  /** Writes one chunk. */
   write(chunk: Program): void | Promise<void>;
+  /** Closes the stream. */
   close(): void | Promise<void>;
 };
 
+/**
+ * Stamps an audit event with the current time.
+ *
+ * @param input - Event details, without a timestamp.
+ * @returns A complete event, ready to pass to {@link RuntimeContext.observe}.
+ * @example
+ * ```ts
+ * ctx.observe(createExecutionEvent({
+ *   kind: "executor.start",
+ *   requestId: ctx.requestId,
+ *   executionId: ctx.executionId,
+ * }));
+ * ```
+ */
 export function createExecutionEvent(
   input: ExecutionEventInput,
 ): ExecutionEvent {