@neutrome/lilsdk 0.4.5 → 0.5.0

package/README.md

@@ -3,29 +3,32 @@
 High-level TypeScript SDK for transport-neutral model authoring on top of `@neutrome/lil-engine`.
 
 ```ts
-import { createTwoPassExecutor, type Executor } from "@neutrome/lilsdk";
-import { retry } from "@neutrome/lilsdk/loops";
-import {
-  observeExecutionStream,
-  writeReasoning,
-} from "@neutrome/lilsdk/stream";
-import { connectTools } from "@neutrome/lilsdk/tools";
+import type { Executor } from "@neutrome/lilsdk";
+import { fallback, retry } from "@neutrome/lilsdk/loops";
+import { createToolsExecutor } from "@neutrome/lilsdk/tools";
+import { observeExecutionStream, writeThinking } from "@neutrome/lilsdk/stream";
+import { prependSystemPrompt } from "@neutrome/lil-engine";
 ```
 
-This package owns:
+Every symbol has exactly one import path. The root export is intentionally
+small — SDK contracts only — and each subpath owns one concern:
 
-- executor and tool contracts
-- `@neutrome/lilsdk/primitives`: structural program helpers such as `walk`, `map`, `reduce`, `has`, `find`, `indexOf`, `all`, and `any`
-- `@neutrome/lilsdk/synthetic`: request/message synthesis helpers such as `createModelProgram`, `makeMessage`, `makeToolCall`, `makeToolResponse`, and `appendToolInteraction`
-- `@neutrome/lilsdk/tools`: `connectTools` tool-call loop
-- `@neutrome/lilsdk/stream`: stream observation and output helpers
-- `@neutrome/lilsdk/loops`: `retry`, `fallback`, and `createGoalExecutor` control-flow helpers
-- `@neutrome/lilsdk/managed/twoPassExecutor`: `createTwoPassExecutor` and model invocation helpers
-- multi-pass authoring primitives used by virtual models
+- root: `Executor`, `ExecutorContext`, `ExecutorInput`, `Tool`,
+  `ProgramTransform`, `RuntimeContext`, `Cache`, `ExecutionEvent`,
+  `OutputSink`, and `createExecutionEvent`
+- `@neutrome/lilsdk/loops`: `retry`, `fallback`, and `createGoalExecutor`
+- `@neutrome/lilsdk/tools`: `createToolsExecutor` tool-call loop
+- `@neutrome/lilsdk/managed`: `createCapabilitiesExecutor` and
+  `createAttachmentToTextExecutor`
+- `@neutrome/lilsdk/stream`: `observeExecutionStream`, `streamStage`, and
+  `writeThinking`
+- `@neutrome/lilsdk/primitives`: structural program helpers — `walk`, `map`,
+  `filter`, `reduce`, `has`, `find`, `indexOf`, `all`, and `any`
 
-The root export is intentionally small: SDK contracts plus the most common
-high-level two-pass executor helper.
+Executor factories are named `create*Executor`, except `retry` and `fallback`,
+which read better as bare verbs.
 
-It intentionally does not own HTTP routing, provider credentials, target
-resolution, or provider JSON conversion. Those live in `@neutrome/open-ai-router`
-and `@neutrome/lil-engine`.
+Building programs — messages, tool calls, attachments, streaming chunks — is
+`@neutrome/lil-engine`'s job, so `prependSystemPrompt` and friends are imported
+from there. HTTP routing, provider credentials, target resolution and provider
+JSON conversion live in `@neutrome/open-ai-router` and `@neutrome/lil-engine`.

package/etc/api/index.api.md

@@ -0,0 +1,96 @@
+## API Report File for "neutrome"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import type { Program } from '@neutrome/lil-engine';
+
+// @public
+type Cache_2 = {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: CachePutOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+};
+export { Cache_2 as Cache }
+
+// @public
+export type CachePutOptions = {
+    expiration?: number;
+    expirationTtl?: number;
+};
+
+// @public
+export function createExecutionEvent(input: ExecutionEventInput): ExecutionEvent;
+
+// @public
+export type ExecutionEvent = {
+    kind: string;
+    requestId: string;
+    executionId: string;
+    timestamp: string;
+    parentExecutionId?: string;
+    target?: {
+        kind: "provider" | "executor";
+        id: string;
+    };
+    errorKind?: string;
+    data?: Record<string, unknown>;
+};
+
+// @public
+export type ExecutionEventInput = Omit<ExecutionEvent, "timestamp"> & {
+    timestamp?: string;
+};
+
+// @public
+export type Executor = {
+    execute(request: Program, ctx: ExecutorContext): Promise<Program>;
+    stream(request: Program, ctx: ExecutorContext): AsyncIterable<Program>;
+};
+
+// @public
+export type ExecutorContext = RuntimeContext & {
+    requestId: string;
+    executionId: string;
+    parentExecutionId?: string;
+};
+
+// @public
+export type ExecutorInput = string | Executor;
+
+// @public
+export type OutputSink = {
+    write(chunk: Program): void | Promise<void>;
+    close(): void | Promise<void>;
+};
+
+// @public
+export type ProgramTransform = {
+    name: string;
+    capabilities: TransformCapability[];
+    apply(program: Program, ctx: RuntimeContext): Program | Promise<Program>;
+};
+
+// @public
+export type RuntimeContext = {
+    cache: Cache_2;
+    invoke(executor: ExecutorInput, request: Program): Promise<Program>;
+    invokeStream(executor: ExecutorInput, request: Program): AsyncIterable<Program>;
+    observe(event: ExecutionEvent): void;
+    signal: AbortSignal;
+};
+
+// @public
+export type Tool = {
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+    systemPromptFragment?: string;
+    execute(args: Record<string, unknown>, ctx: ExecutorContext): Promise<string>;
+};
+
+// @public
+export type TransformCapability = "read_messages" | "write_messages" | "write_config" | "write_tools" | "drop_content" | "provider_extension";
+
+```

package/etc/api/loops.api.md

@@ -0,0 +1,108 @@
+## API Report File for "neutrome"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { Program } from '@neutrome/lil-engine';
+
+// @public
+type Cache_2 = {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: CachePutOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+};
+
+// @public
+type CachePutOptions = {
+    expiration?: number;
+    expirationTtl?: number;
+};
+
+// Warning: (ae-forgotten-export) The symbol "Executor" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function createGoalExecutor(options: GoalExecutorOptions): Executor;
+
+// @public
+type ExecutionEvent = {
+    kind: string;
+    requestId: string;
+    executionId: string;
+    timestamp: string;
+    parentExecutionId?: string;
+    target?: {
+        kind: "provider" | "executor";
+        id: string;
+    };
+    errorKind?: string;
+    data?: Record<string, unknown>;
+};
+
+// @public
+type Executor = {
+    execute(request: Program, ctx: ExecutorContext): Promise<Program>;
+    stream(request: Program, ctx: ExecutorContext): AsyncIterable<Program>;
+};
+
+// Warning: (ae-forgotten-export) The symbol "RuntimeContext" needs to be exported by the entry point index.d.ts
+//
+// @public
+type ExecutorContext = RuntimeContext & {
+    requestId: string;
+    executionId: string;
+    parentExecutionId?: string;
+};
+
+// @public
+type ExecutorInput = string | Executor;
+
+// Warning: (ae-forgotten-export) The symbol "ExecutorInput" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function fallback(executors: readonly ExecutorInput[], options?: FallbackOptions): Executor;
+
+// @public
+export type FallbackOptions = {
+    shouldFallback?: (error: unknown, executorIndex: number) => boolean | Promise<boolean>;
+    onFallback?: (error: unknown, executorIndex: number) => void | Promise<void>;
+};
+
+// @public
+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;
+};
+
+// @public
+export function retry(executor: ExecutorInput, options?: RetryOptions): Executor;
+
+// @public
+export type RetryOptions = {
+    attempts?: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean | Promise<boolean>;
+    onRetry?: (error: unknown, attempt: number) => void | Promise<void>;
+};
+
+// @public
+type RuntimeContext = {
+    cache: Cache_2;
+    invoke(executor: ExecutorInput, request: Program): Promise<Program>;
+    invokeStream(executor: ExecutorInput, request: Program): AsyncIterable<Program>;
+    observe(event: ExecutionEvent): void;
+    signal: AbortSignal;
+};
+
+// Warnings were encountered during analysis:
+//
+// .reference-build/types/neutrome-lilsdk/src/types.d.ts:42:5 - (ae-forgotten-export) The symbol "CachePutOptions" needs to be exported by the entry point index.d.ts
+// .reference-build/types/neutrome-lilsdk/src/types.d.ts:55:5 - (ae-forgotten-export) The symbol "Cache_2" needs to be exported by the entry point index.d.ts
+// .reference-build/types/neutrome-lilsdk/src/types.d.ts:77:5 - (ae-forgotten-export) The symbol "ExecutionEvent" needs to be exported by the entry point index.d.ts
+// .reference-build/types/neutrome-lilsdk/src/types.d.ts:131:5 - (ae-forgotten-export) The symbol "ExecutorContext" needs to be exported by the entry point index.d.ts
+
+// (No @packageDocumentation comment for this package)
+
+```

package/etc/api/managed.api.md

@@ -0,0 +1,102 @@
+## API Report File for "neutrome"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import type { Program } from '@neutrome/lil-engine';
+import { ProgramAttachment } from '@neutrome/lil-engine';
+
+// @public
+export type AttachmentReaderRule = {
+    mimeTypes: readonly string[];
+    executor: ExecutorInput;
+};
+
+// @public
+export type AttachmentToTextOptions = {
+    systemPrompt?: string;
+    cacheKey?: (attachment: ProgramAttachment, ctx: ExecutorContext) => string;
+};
+
+// @public
+type Cache_2 = {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: CachePutOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+};
+
+// @public
+type CachePutOptions = {
+    expiration?: number;
+    expirationTtl?: number;
+};
+
+// @public
+export type CapabilitiesExecutorOptions = {
+    enabledIterations?: number;
+    cacheKey?: (ctx: ExecutorContext) => string;
+    skipPrefixes?: readonly string[];
+};
+
+// Warning: (ae-forgotten-export) The symbol "Executor" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function createAttachmentToTextExecutor(inner: ExecutorInput, rules: readonly AttachmentReaderRule[], options?: AttachmentToTextOptions): Executor;
+
+// @public
+export function createCapabilitiesExecutor(inner: ExecutorInput, options?: CapabilitiesExecutorOptions): Executor;
+
+// @public
+type ExecutionEvent = {
+    kind: string;
+    requestId: string;
+    executionId: string;
+    timestamp: string;
+    parentExecutionId?: string;
+    target?: {
+        kind: "provider" | "executor";
+        id: string;
+    };
+    errorKind?: string;
+    data?: Record<string, unknown>;
+};
+
+// @public
+type Executor = {
+    execute(request: Program, ctx: ExecutorContext): Promise<Program>;
+    stream(request: Program, ctx: ExecutorContext): AsyncIterable<Program>;
+};
+
+// Warning: (ae-forgotten-export) The symbol "RuntimeContext" needs to be exported by the entry point index.d.ts
+//
+// @public
+type ExecutorContext = RuntimeContext & {
+    requestId: string;
+    executionId: string;
+    parentExecutionId?: string;
+};
+
+// @public
+type ExecutorInput = string | Executor;
+
+// @public
+type RuntimeContext = {
+    cache: Cache_2;
+    invoke(executor: ExecutorInput, request: Program): Promise<Program>;
+    invokeStream(executor: ExecutorInput, request: Program): AsyncIterable<Program>;
+    observe(event: ExecutionEvent): void;
+    signal: AbortSignal;
+};
+
+// Warnings were encountered during analysis:
+//
+// .reference-build/types/neutrome-lilsdk/src/managed/attachment-to-text.d.ts:8:5 - (ae-forgotten-export) The symbol "ExecutorInput" needs to be exported by the entry point index.d.ts
+// .reference-build/types/neutrome-lilsdk/src/managed/attachment-to-text.d.ts:15:5 - (ae-forgotten-export) The symbol "ExecutorContext" needs to be exported by the entry point index.d.ts
+// .reference-build/types/neutrome-lilsdk/src/types.d.ts:42:5 - (ae-forgotten-export) The symbol "CachePutOptions" needs to be exported by the entry point index.d.ts
+// .reference-build/types/neutrome-lilsdk/src/types.d.ts:55:5 - (ae-forgotten-export) The symbol "Cache_2" needs to be exported by the entry point index.d.ts
+// .reference-build/types/neutrome-lilsdk/src/types.d.ts:77:5 - (ae-forgotten-export) The symbol "ExecutionEvent" needs to be exported by the entry point index.d.ts
+
+// (No @packageDocumentation comment for this package)
+
+```

package/etc/api/primitives.api.md

@@ -0,0 +1,39 @@
+## API Report File for "neutrome"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { Instruction } from '@neutrome/lil-engine';
+import { Program } from '@neutrome/lil-engine';
+
+// @public
+export function all(program: Program, callback: (instruction: Instruction, index: number, program: Program) => boolean): boolean;
+
+// @public
+export function any(program: Program, callback: (instruction: Instruction, index: number, program: Program) => boolean): boolean;
+
+// @public
+export function filter(program: Program, callback: (instruction: Instruction, index: number, program: Program) => boolean): Program;
+
+// @public
+export function find(program: Program, needle: Instruction): Instruction | undefined;
+
+// @public
+export function has(program: Program, needle: Instruction): boolean;
+
+// @public
+export function indexOf(program: Program, needle: Instruction): number;
+
+// @public
+export function map(program: Program, callback: (instruction: Instruction, index: number, program: Program) => Instruction): Program;
+
+// @public
+export function reduce<T>(program: Program, callback: (accumulator: T, instruction: Instruction, index: number, program: Program) => T, initialValue: T): T;
+
+// @public
+export function walk(program: Program, callback: (instruction: Instruction, index: number, program: Program) => void): void;
+
+// (No @packageDocumentation comment for this package)
+
+```

package/etc/api/stream.api.md

@@ -0,0 +1,46 @@
+## API Report File for "neutrome"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { Program } from '@neutrome/lil-engine';
+
+// @public
+export type ObservedExecution = {
+    mode: "text";
+    transcript: string;
+    emittedText: boolean;
+} | {
+    mode: "tool";
+    transcript: string;
+    emittedText: boolean;
+    chunks: Program[];
+};
+
+// @public
+export function observeExecutionStream(source: AsyncIterable<Program>, hooks?: StreamObservationHooks): Promise<ObservedExecution>;
+
+// @public
+type OutputSink = {
+    write(chunk: Program): void | Promise<void>;
+    close(): void | Promise<void>;
+};
+
+// @public
+export type StreamObservationHooks = {
+    onTextStart?: () => void;
+    onTextChunk?: (text: string, chunk: Program) => void;
+};
+
+// @public
+export function streamStage(source: AsyncIterable<Program>): AsyncGenerator<Program>;
+
+// Warning: (ae-forgotten-export) The symbol "OutputSink" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function writeThinking(sink: OutputSink, text: string): Promise<void>;
+
+// (No @packageDocumentation comment for this package)
+
+```

package/etc/api/tools.api.md

@@ -0,0 +1,103 @@
+## API Report File for "neutrome"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import type { Program } from '@neutrome/lil-engine';
+
+// @public
+type Cache_2 = {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: CachePutOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+};
+
+// @public
+type CachePutOptions = {
+    expiration?: number;
+    expirationTtl?: number;
+};
+
+// Warning: (ae-forgotten-export) The symbol "ExecutorInput" needs to be exported by the entry point tools.d.ts
+// Warning: (ae-forgotten-export) The symbol "Tool" needs to be exported by the entry point tools.d.ts
+// Warning: (ae-forgotten-export) The symbol "Executor" needs to be exported by the entry point tools.d.ts
+//
+// @public
+export function createToolsExecutor(inner: ExecutorInput, tools: Tool[], options?: ToolsExecutorOptions): Executor;
+
+// @public
+type ExecutionEvent = {
+    kind: string;
+    requestId: string;
+    executionId: string;
+    timestamp: string;
+    parentExecutionId?: string;
+    target?: {
+        kind: "provider" | "executor";
+        id: string;
+    };
+    errorKind?: string;
+    data?: Record<string, unknown>;
+};
+
+// @public
+type Executor = {
+    execute(request: Program, ctx: ExecutorContext): Promise<Program>;
+    stream(request: Program, ctx: ExecutorContext): AsyncIterable<Program>;
+};
+
+// Warning: (ae-forgotten-export) The symbol "RuntimeContext" needs to be exported by the entry point tools.d.ts
+//
+// @public
+type ExecutorContext = RuntimeContext & {
+    requestId: string;
+    executionId: string;
+    parentExecutionId?: string;
+};
+
+// @public
+type ExecutorInput = string | Executor;
+
+// @public
+type RuntimeContext = {
+    cache: Cache_2;
+    invoke(executor: ExecutorInput, request: Program): Promise<Program>;
+    invokeStream(executor: ExecutorInput, request: Program): AsyncIterable<Program>;
+    observe(event: ExecutionEvent): void;
+    signal: AbortSignal;
+};
+
+// @public
+type Tool = {
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+    systemPromptFragment?: string;
+    execute(args: Record<string, unknown>, ctx: ExecutorContext): Promise<string>;
+};
+
+// @public
+export class ToolArgumentsError extends Error {
+    constructor(toolName: string, argumentsText: string);
+    // (undocumented)
+    readonly argumentsText: string;
+    // (undocumented)
+    readonly toolName: string;
+}
+
+// @public
+export type ToolsExecutorOptions = {
+    maxIterations?: number;
+};
+
+// Warnings were encountered during analysis:
+//
+// .reference-build/types/neutrome-lilsdk/src/types.d.ts:42:5 - (ae-forgotten-export) The symbol "CachePutOptions" needs to be exported by the entry point tools.d.ts
+// .reference-build/types/neutrome-lilsdk/src/types.d.ts:55:5 - (ae-forgotten-export) The symbol "Cache_2" needs to be exported by the entry point tools.d.ts
+// .reference-build/types/neutrome-lilsdk/src/types.d.ts:77:5 - (ae-forgotten-export) The symbol "ExecutionEvent" needs to be exported by the entry point tools.d.ts
+// .reference-build/types/neutrome-lilsdk/src/types.d.ts:131:5 - (ae-forgotten-export) The symbol "ExecutorContext" needs to be exported by the entry point tools.d.ts
+
+// (No @packageDocumentation comment for this package)
+
+```

package/package.json

@@ -1,27 +1,26 @@
 {
   "name": "@neutrome/lilsdk",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./types": "./src/types.ts",
     "./primitives": "./src/primitives/index.ts",
-    "./synthetic": "./src/synthetic/index.ts",
     "./stream": "./src/stream/index.ts",
     "./tools": "./src/tools.ts",
     "./loops": "./src/loops/index.ts",
     "./managed": "./src/managed/index.ts"
   },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "npm:publish": "pnpm publish --no-git-checks"
+  },
   "dependencies": {
-    "@neutrome/lil-engine": "0.4.5"
+    "@neutrome/lil-engine": "workspace:*"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",
     "typescript": "^6.0.3",
     "vitest": "^4.1.6"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
   }
-}
+}

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";