@neutrome/lilsdk 0.4.6 → 0.5.0

package/src/index.ts

@@ -1,15 +1,41 @@
-export type {
-  Cache,
-  CachePutOptions,
-  Executor,
-  ExecutorInput,
-  ExecutorContext,
-  OutputSink,
-  ProgramTransform,
-  ExecutionEvent,
-  ExecutionEventInput,
-  Tool,
-  TransformCapability,
-  TransformContext,
-} from "./types.ts";
-export { createExecutionEvent } from "./types.ts";
+/**
+ * Runtime contracts and combinators for building executors.
+ *
+ * The root entry point carries only contracts — {@link Executor},
+ * {@link Tool}, {@link ProgramTransform}, {@link ExecutorContext} and friends.
+ * Everything that does work lives on a subpath, and each symbol has exactly one
+ * import path:
+ *
+ * - `@neutrome/lilsdk/loops` — `retry`, `fallback`, goal loops
+ * - `@neutrome/lilsdk/tools` — tool loops
+ * - `@neutrome/lilsdk/managed` — capability and attachment executors
+ * - `@neutrome/lilsdk/stream` — stream observation and output helpers
+ * - `@neutrome/lilsdk/primitives` — functional helpers over instruction lists
+ *
+ * Programs themselves are built with `@neutrome/lil-engine`, which owns the
+ * protocol; this package owns everything that runs.
+ *
+ * Executor factories are named `create*Executor`, except `retry` and `fallback`,
+ * which read better as bare verbs.
+ *
+ * @example
+ * ```ts
+ * import type { Executor } from "@neutrome/lilsdk";
+ * import { fallback, retry } from "@neutrome/lilsdk/loops";
+ * import { prependSystemPrompt } from "@neutrome/lil-engine";
+ *
+ * const upstream = fallback([retry("default/glm-5.2", { attempts: 3 }), "fast/gemma-4-31b"]);
+ *
+ * const executor: Executor = {
+ *   async execute(request, ctx) {
+ *     return ctx.invoke(upstream, prependSystemPrompt(request, "Be concise."));
+ *   },
+ *   async *stream(request, ctx) {
+ *     yield* ctx.invokeStream(upstream, prependSystemPrompt(request, "Be concise."));
+ *   },
+ * };
+ * ```
+ *
+ * @packageDocumentation
+ */
+export * from "./types.ts";

package/src/loops/goal.ts

@@ -0,0 +1,111 @@
+import {
+  appendAssistantMessage,
+  createProgram,
+  delta,
+  type Program,
+} from "@neutrome/lil-engine";
+import type { Executor, ExecutorInput } from "../types.ts";
+import { streamStage } from "../stream/index.ts";
+import { childContext, positiveInteger } from "./shared.ts";
+
+/**
+ * Options accepted by {@link createGoalExecutor}.
+ */
+export type GoalExecutorOptions = {
+  draft: ExecutorInput;
+  review: ExecutorInput;
+  refine: (
+    request: Program,
+    answer: Program,
+    review: Program,
+    attempt: number,
+  ) => Program | Promise<Program>;
+  satisfied: (review: Program, attempt: number) => boolean | Promise<boolean>;
+  maxIterations?: number;
+};
+
+/**
+ * Builds an executor that drafts, reviews and refines until a goal is met.
+ *
+ * @param options - Draft and review executors, plus the refine and satisfied predicates.
+ * @returns An executor that iterates up to `maxIterations` times.
+ * @example
+ * ```ts
+ * export default createGoalExecutor({
+ *   draft: "core/turn-1",
+ *   review: "core/critic-1",
+ *   satisfied: (review) => extractContentText(review).includes("APPROVED"),
+ *   refine: (request, answer, review) => appendUserMessage(request, extractContentText(review)),
+ * });
+ * ```
+ */
+export function createGoalExecutor(options: GoalExecutorOptions): Executor {
+  const maxIterations = positiveInteger(
+    options.maxIterations ?? 3,
+    "goal maxIterations",
+  );
+
+  return {
+    async execute(request, ctx) {
+      let current = request;
+      let answer = request;
+
+      for (let attempt = 1; attempt <= maxIterations; attempt += 1) {
+        const attemptContext = childContext(ctx, attempt);
+        answer = await attemptContext.invoke(options.draft, current);
+        const review = await attemptContext.invoke(options.review, answer);
+        if (await options.satisfied(review, attempt)) return answer;
+        if (attempt < maxIterations) {
+          current = await options.refine(current, answer, review, attempt);
+        }
+      }
+
+      return answer;
+    },
+
+    async *stream(request, ctx) {
+      let current = request;
+      let answer = request;
+
+      for (let attempt = 1; attempt <= maxIterations; attempt += 1) {
+        const attemptContext = childContext(ctx, attempt);
+        answer = yield* streamGoalStage(
+          streamStage(attemptContext.invokeStream(options.draft, current)),
+          current,
+        );
+        const review = yield* streamGoalStage(
+          streamStage(attemptContext.invokeStream(options.review, answer)),
+          answer,
+        );
+
+        if (await options.satisfied(review, attempt)) {
+          yield delta.end();
+          return;
+        }
+        if (attempt < maxIterations) {
+          current = await options.refine(current, answer, review, attempt);
+        }
+      }
+
+      yield delta.end();
+    },
+  };
+}
+
+async function* streamGoalStage(
+  source: AsyncIterable<Program>,
+  fallback: Program,
+): AsyncGenerator<Program, Program> {
+  let final = fallback;
+  let transcript = "";
+
+  for await (const chunk of source) {
+    final = chunk;
+    transcript += delta.extractContentText(chunk);
+    yield chunk;
+  }
+
+  return transcript
+    ? appendAssistantMessage(createProgram(), transcript)
+    : final;
+}

package/src/loops/index.ts

@@ -1,14 +1,21 @@
-import { createProgram, deltaText, type Program } from "@neutrome/lil-engine";
 import type { Executor, ExecutorContext, ExecutorInput } from "../types.ts";
-import { completeStream, streamStage } from "../stream/stages.ts";
-import { appendAssistantMessage } from "../synthetic/index.ts";
+import { childContext, positiveInteger, shouldContinue } from "./shared.ts";
 
+export { createGoalExecutor } from "./goal.ts";
+export type { GoalExecutorOptions } from "./goal.ts";
+
+/**
+ * Options accepted by {@link retry}.
+ */
 export type RetryOptions = {
   attempts?: number;
   shouldRetry?: (error: unknown, attempt: number) => boolean | Promise<boolean>;
   onRetry?: (error: unknown, attempt: number) => void | Promise<void>;
 };
 
+/**
+ * Options accepted by {@link fallback}.
+ */
 export type FallbackOptions = {
   shouldFallback?: (
     error: unknown,
@@ -17,19 +24,20 @@ export type FallbackOptions = {
   onFallback?: (error: unknown, executorIndex: number) => void | Promise<void>;
 };
 
-export type GoalExecutorOptions = {
-  draft: ExecutorInput;
-  review: ExecutorInput;
-  refine: (
-    request: Program,
-    answer: Program,
-    review: Program,
-    attempt: number,
-  ) => Program | Promise<Program>;
-  satisfied: (review: Program, attempt: number) => boolean | Promise<boolean>;
-  maxIterations?: number;
-};
-
+/**
+ * Retries an executor until it succeeds or runs out of attempts.
+ *
+ * A streaming attempt that has already emitted a chunk is never retried, so a
+ * client never sees the same text twice.
+ *
+ * @param executor - Executor or model id to run.
+ * @param options - Attempt count and retry predicates.
+ * @returns An executor that retries on failure.
+ * @example
+ * ```ts
+ * const upstream = retry("default/glm-5.2", { attempts: 3 });
+ * ```
+ */
 export function retry(
   executor: ExecutorInput,
   options: RetryOptions = {},
@@ -77,6 +85,23 @@ export function retry(
   };
 }
 
+/**
+ * Tries executors in order until one succeeds.
+ *
+ * A streaming attempt that has already emitted a chunk is never abandoned.
+ *
+ * @param executors - Executors or model ids to try, best first.
+ * @param options - Fallback predicates and hooks.
+ * @returns An executor that fails over.
+ * @throws Error when `executors` is empty.
+ * @example
+ * ```ts
+ * const upstream = fallback([
+ *   retry("default/glm-5.2", { attempts: 3 }),
+ *   "fast/gemma-4-31b",
+ * ]);
+ * ```
+ */
 export function fallback(
   executors: readonly ExecutorInput[],
   options: FallbackOptions = {},
@@ -127,77 +152,6 @@ export function fallback(
   };
 }
 
-export function createGoalExecutor(options: GoalExecutorOptions): Executor {
-  const maxIterations = positiveInteger(
-    options.maxIterations ?? 3,
-    "goal maxIterations",
-  );
-
-  return {
-    async execute(request, ctx) {
-      let current = request;
-      let answer = request;
-
-      for (let attempt = 1; attempt <= maxIterations; attempt += 1) {
-        const attemptContext = childContext(ctx, attempt);
-        answer = await attemptContext.invoke(options.draft, current);
-        const review = await attemptContext.invoke(options.review, answer);
-        if (await options.satisfied(review, attempt)) return answer;
-        if (attempt < maxIterations) {
-          current = await options.refine(current, answer, review, attempt);
-        }
-      }
-
-      return answer;
-    },
-
-    async *stream(request, ctx) {
-      let current = request;
-      let answer = request;
-
-      for (let attempt = 1; attempt <= maxIterations; attempt += 1) {
-        const attemptContext = childContext(ctx, attempt);
-        answer = yield* streamGoalStage(
-          streamStage(attemptContext.invokeStream(options.draft, current)),
-          current,
-        );
-        const review = yield* streamGoalStage(
-          streamStage(attemptContext.invokeStream(options.review, answer)),
-          answer,
-        );
-
-        if (await options.satisfied(review, attempt)) {
-          yield completeStream();
-          return;
-        }
-        if (attempt < maxIterations) {
-          current = await options.refine(current, answer, review, attempt);
-        }
-      }
-
-      yield completeStream();
-    },
-  };
-}
-
-async function* streamGoalStage(
-  source: AsyncIterable<Program>,
-  fallback: Program,
-): AsyncGenerator<Program, Program> {
-  let final = fallback;
-  let transcript = "";
-
-  for await (const chunk of source) {
-    final = chunk;
-    transcript += deltaText(chunk);
-    yield chunk;
-  }
-
-  return transcript
-    ? appendAssistantMessage(createProgram(), transcript)
-    : final;
-}
-
 async function runRetry<T>(
   operation: (attempt: number) => Promise<T>,
   attempts: number,
@@ -247,26 +201,3 @@ async function runFallback<T>(
 
   throw lastError;
 }
-
-async function shouldContinue(
-  error: unknown,
-  attempt: number,
-  predicate?: (error: unknown, attempt: number) => boolean | Promise<boolean>,
-): Promise<boolean> {
-  return predicate ? predicate(error, attempt) : true;
-}
-
-function childContext(ctx: ExecutorContext, attempt: number): ExecutorContext {
-  return {
-    ...ctx,
-    executionId: `${ctx.executionId}:${attempt}`,
-    parentExecutionId: ctx.executionId,
-  };
-}
-
-function positiveInteger(value: number, label: string): number {
-  if (!Number.isInteger(value) || value < 1) {
-    throw new Error(`${label} must be a positive integer`);
-  }
-  return value;
-}

package/src/loops/shared.ts

@@ -0,0 +1,27 @@
+import type { ExecutorContext } from "../types.ts";
+
+export async function shouldContinue(
+  error: unknown,
+  attempt: number,
+  predicate?: (error: unknown, attempt: number) => boolean | Promise<boolean>,
+): Promise<boolean> {
+  return predicate ? predicate(error, attempt) : true;
+}
+
+export function childContext(
+  ctx: ExecutorContext,
+  attempt: number,
+): ExecutorContext {
+  return {
+    ...ctx,
+    executionId: `${ctx.executionId}:${attempt}`,
+    parentExecutionId: ctx.executionId,
+  };
+}
+
+export function positiveInteger(value: number, label: string): number {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return value;
+}

package/src/managed/attachment-to-text.ts

@@ -1,32 +1,54 @@
 import {
-  contentText,
+  appendToolInteraction,
+  extractAttachments,
+  extractContentText,
+  findMessages,
   insertAfter,
   isAttachmentOpcode,
-  messages,
-  programAttachments,
+  prependSystemPrompt,
   type Program,
   type ProgramAttachment,
 } from "@neutrome/lil-engine";
-import {
-  appendToolInteraction,
-  prependSystemPrompt,
-} from "../synthetic/index.ts";
 import type { Executor, ExecutorContext, ExecutorInput } from "../types.ts";
 
 const toolName = "attachment_to_text";
 const defaultPrompt =
   "Read the attached file carefully. Return a detailed factual description of its content for another assistant to use. Include all relevant visible text, structure, and details. Do not discuss this instruction.";
 
+/**
+ * Maps a set of MIME types to the executor that can read them.
+ */
 export type AttachmentReaderRule = {
   mimeTypes: readonly string[];
   executor: ExecutorInput;
 };
 
+/**
+ * Options accepted by {@link createAttachmentToTextExecutor}.
+ */
 export type AttachmentToTextOptions = {
   systemPrompt?: string;
   cacheKey?: (attachment: ProgramAttachment, ctx: ExecutorContext) => string;
 };
 
+/**
+ * Wraps a text-only executor so it can answer requests carrying attachments.
+ *
+ * Each attachment is handed to the first rule matching its MIME type, and the
+ * description that comes back replaces the attachment in the request.
+ *
+ * @param inner - Text-only executor or model id.
+ * @param rules - Reader executors, in priority order. `"*"` matches any type.
+ * @param options - Reader prompt and cache key.
+ * @returns An executor that accepts attachments.
+ * @throws Error when `rules` is empty.
+ * @example
+ * ```ts
+ * export default createAttachmentToTextExecutor("default/glm-5.2", [
+ *   { mimeTypes: ["*"], executor: "default/gemma-4-31b" },
+ * ]);
+ * ```
+ */
 export function createAttachmentToTextExecutor(
   inner: ExecutorInput,
   rules: readonly AttachmentReaderRule[],
@@ -59,13 +81,13 @@ async function prepareRequest(
   prompt: string,
   options: AttachmentToTextOptions,
 ): Promise<Program> {
-  const attachments = programAttachments(request);
+  const attachments = extractAttachments(request);
   if (attachments.length === 0) return request;
   const latestUserStart = [...attachments]
     .filter((attachment) => attachment.message.role === "user")
     .at(-1)?.message.start;
   let result = stripAttachments(request);
-  const sourceMessages = messages(request);
+  const sourceMessages = findMessages(request);
 
   for (const attachment of [...attachments].reverse()) {
     const rule = rules.find((candidate) =>
@@ -90,7 +112,9 @@ async function prepareRequest(
         );
       }
       const readerRequest = readerProgram(request, attachment, prompt);
-      description = contentText(await ctx.invoke(rule.executor, readerRequest));
+      description = extractContentText(
+        await ctx.invoke(rule.executor, readerRequest),
+      );
       if (!description.trim())
         throw new Error(
           `Attachment reader returned no text for ${attachment.mimeType}`,
@@ -111,7 +135,7 @@ async function prepareRequest(
     const messageIndex = sourceMessages.findIndex(
       (message) => message.start === attachment.message.start,
     );
-    const targetMessage = messages(result)[messageIndex];
+    const targetMessage = findMessages(result)[messageIndex];
     if (!targetMessage)
       throw new Error("Attachment message was removed from context");
     const synthetic = appendToolInteraction(

package/src/managed/capabilities.ts

@@ -1,12 +1,12 @@
 import {
-  addTool,
-  clearIndices,
-  toolDefinitions,
-  viewProgram,
+  appendTool,
+  findToolDefinitions,
+  ProgramView,
+  removeInstructions,
   type Program,
   type ProgramTool,
 } from "@neutrome/lil-engine";
-import { connectTools } from "../tools.ts";
+import { createToolsExecutor } from "../tools.ts";
 import type {
   Executor,
   ExecutorContext,
@@ -17,6 +17,9 @@ import type {
 const capabilityToolName = "learn_capability";
 const encoder = new TextEncoder();
 
+/**
+ * Options accepted by {@link createCapabilitiesExecutor}.
+ */
 export type CapabilitiesExecutorOptions = {
   enabledIterations?: number;
   cacheKey?: (ctx: ExecutorContext) => string;
@@ -25,6 +28,20 @@ export type CapabilitiesExecutorOptions = {
 
 type CapabilitySelection = { toolName: string; remaining: number };
 
+/**
+ * Wraps an executor so the model can look up its own capabilities on demand.
+ *
+ * A `learn_capability` tool is offered for the first few iterations; what the
+ * model learns is cached per request, so repeated lookups are free.
+ *
+ * @param inner - Executor or model id that does the generating.
+ * @param options - Iteration budget, cache key and prompt prefixes to skip.
+ * @returns An executor that can answer questions about itself.
+ * @example
+ * ```ts
+ * export default createCapabilitiesExecutor("core/voice-1");
+ * ```
+ */
 export function createCapabilitiesExecutor(
   inner: ExecutorInput,
   options: CapabilitiesExecutorOptions = {},
@@ -35,7 +52,7 @@ export function createCapabilitiesExecutor(
 
   return {
     async execute(request, ctx) {
-      const tools = viewProgram(request).tools;
+      const tools = new ProgramView(request).tools;
       if (tools.length === 0) return ctx.invoke(inner, request);
 
       const managedTools = tools.filter(
@@ -45,14 +62,16 @@ export function createCapabilitiesExecutor(
 
       const key = selectionKey(cacheKey(ctx));
       await discardMissingSelection(ctx, key, managedTools);
-      return connectCapabilities(inner, managedTools, key, enabledIterations).execute(
-        withoutManagedTools(request, managedTools),
-        ctx,
-      );
+      return connectCapabilities(
+        inner,
+        managedTools,
+        key,
+        enabledIterations,
+      ).execute(withoutManagedTools(request, managedTools), ctx);
     },
 
     async *stream(request, ctx) {
-      const tools = viewProgram(request).tools;
+      const tools = new ProgramView(request).tools;
       if (tools.length === 0) {
         yield* ctx.invokeStream(inner, request);
         return;
@@ -68,10 +87,12 @@ export function createCapabilitiesExecutor(
 
       const key = selectionKey(cacheKey(ctx));
       await discardMissingSelection(ctx, key, managedTools);
-      yield* connectCapabilities(inner, managedTools, key, enabledIterations).stream(
-        withoutManagedTools(request, managedTools),
-        ctx,
-      );
+      yield* connectCapabilities(
+        inner,
+        managedTools,
+        key,
+        enabledIterations,
+      ).stream(withoutManagedTools(request, managedTools), ctx);
     },
   };
 }
@@ -97,10 +118,9 @@ function connectCapabilities(
     },
   };
 
-  return connectTools(
-    [learnCapabilityTool(tools, key, enabledIterations)],
-    selectedInner,
-  );
+  return createToolsExecutor(selectedInner, [
+    learnCapabilityTool(tools, key, enabledIterations),
+  ]);
 }
 
 function learnCapabilityTool(
@@ -174,17 +194,17 @@ function withoutManagedTools(
 ): Program {
   const managedNames = new Set(managedTools.map((tool) => tool.name));
   const indices: number[] = [];
-  for (const definition of toolDefinitions(request)) {
+  for (const definition of findToolDefinitions(request)) {
     if (!definition.name || !managedNames.has(definition.name)) continue;
     for (let index = definition.start; index <= definition.end; index += 1) {
       indices.push(index);
     }
   }
-  return clearIndices(request, indices);
+  return removeInstructions(request, indices);
 }
 
 function addProgramTool(request: Program, tool: ProgramTool): Program {
-  return addTool(
+  return appendTool(
     request,
     tool.name,
     tool.description,

package/src/observe.ts

@@ -1,16 +1,21 @@
 import {
   cloneProgram,
-  deltaText,
-  finishReason,
-  hasToolDelta,
+  delta,
+  getFinishReason,
   type Program,
 } from "@neutrome/lil-engine";
 
+/**
+ * Callbacks fired while {@link observeExecutionStream} consumes a stream.
+ */
 export type StreamObservationHooks = {
   onTextStart?: () => void;
   onTextChunk?: (text: string, chunk: Program) => void;
 };
 
+/**
+ * What a stream turned out to be: plain text, or a tool request.
+ */
 export type ObservedExecution =
   | {
       mode: "text";
@@ -24,6 +29,16 @@ export type ObservedExecution =
       chunks: Program[];
     };
 
+/**
+ * Consumes a stream and reports whether it answered with text or tool calls.
+ *
+ * Chunks are buffered until the answer's shape is known, so a caller can decide
+ * what to forward. Tool-mode results carry every chunk for replay.
+ *
+ * @param source - Chunks to consume.
+ * @param hooks - Callbacks fired as text arrives.
+ * @returns What the stream turned out to be.
+ */
 export async function observeExecutionStream(
   source: AsyncIterable<Program>,
   hooks: StreamObservationHooks = {},
@@ -35,9 +50,9 @@ export async function observeExecutionStream(
   let emittedText = false;
 
   for await (const chunk of source) {
-    const text = deltaText(chunk);
+    const text = delta.extractContentText(chunk);
     const toolRequested =
-      hasToolDelta(chunk) || finishReason(chunk) === "tool_calls";
+      delta.hasToolCall(chunk) || getFinishReason(chunk) === "tool_calls";
 
     if (mode === "pending") {
       const clone = cloneProgram(chunk);
@@ -57,7 +72,7 @@ export async function observeExecutionStream(
       emittedText = true;
       hooks.onTextStart?.();
       for (const pendingChunk of pending.splice(0)) {
-        const pendingText = deltaText(pendingChunk);
+        const pendingText = delta.extractContentText(pendingChunk);
         if (pendingText) {
           transcript += pendingText;
           hooks.onTextChunk?.(pendingText, pendingChunk);