@neutrome/lilsdk 0.4.6 → 0.5.0

package/README.md

@@ -4,24 +4,31 @@ High-level TypeScript SDK for transport-neutral model authoring on top of `@neut
 
 ```ts
 import 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 { 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
-The root export is intentionally small: SDK contracts.
+- 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`
 
-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`.
+Executor factories are named `create*Executor`, except `retry` and `fallback`,
+which read better as bare verbs.
+
+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

@@ -1,103 +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 (undocumented)
-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 (undocumented)
-export type CachePutOptions = {
-    expiration?: number;
-    expirationTtl?: number;
-};
-
-// @public (undocumented)
-export function createExecutionEvent(input: ExecutionEventInput): ExecutionEvent;
-
-// @public (undocumented)
-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 (undocumented)
-export type ExecutionEventInput = Omit<ExecutionEvent, "timestamp"> & {
-    timestamp?: string;
-};
-
-// @public (undocumented)
-export 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 (undocumented)
-export type ExecutorContext = RuntimeContext & {
-    requestId: string;
-    executionId: string;
-    parentExecutionId?: string;
-};
-
-// @public (undocumented)
-export type ExecutorInput = string | Executor;
-
-// @public (undocumented)
-export type OutputSink = {
-    write(chunk: Program): void | Promise<void>;
-    close(): void | Promise<void>;
-};
-
-// @public (undocumented)
-export type ProgramTransform = {
-    name: string;
-    capabilities: TransformCapability[];
-    apply(program: Program, ctx: TransformContext): Program | Promise<Program>;
-};
-
-// @public (undocumented)
-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 (undocumented)
-export type Tool = {
-    name: string;
-    description: string;
-    schema: Record<string, unknown>;
-    systemPromptFragment?: string;
-    execute(args: Record<string, unknown>, ctx: ExecutorContext): Promise<string>;
-};
-
-// @public (undocumented)
-export type TransformCapability = "read_messages" | "write_messages" | "write_config" | "write_tools" | "drop_content" | "provider_extension";
-
-// @public (undocumented)
-export type TransformContext = RuntimeContext;
-
-// (No @packageDocumentation comment for this package)
-
-```
+## 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

@@ -1,108 +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 (undocumented)
-type Cache_2 = {
-    get(key: string): Promise<string | null>;
-    put(key: string, value: string, options?: CachePutOptions): Promise<void>;
-    delete(key: string): Promise<void>;
-};
-
-// @public (undocumented)
-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 (undocumented)
-export function createGoalExecutor(options: GoalExecutorOptions): Executor;
-
-// @public (undocumented)
-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 (undocumented)
-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 (undocumented)
-type ExecutorContext = RuntimeContext & {
-    requestId: string;
-    executionId: string;
-    parentExecutionId?: string;
-};
-
-// @public (undocumented)
-type ExecutorInput = string | Executor;
-
-// Warning: (ae-forgotten-export) The symbol "ExecutorInput" needs to be exported by the entry point index.d.ts
-//
-// @public (undocumented)
-export function fallback(executors: readonly ExecutorInput[], options?: FallbackOptions): Executor;
-
-// @public (undocumented)
-export type FallbackOptions = {
-    shouldFallback?: (error: unknown, executorIndex: number) => boolean | Promise<boolean>;
-    onFallback?: (error: unknown, executorIndex: number) => void | Promise<void>;
-};
-
-// @public (undocumented)
-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 (undocumented)
-export function retry(executor: ExecutorInput, options?: RetryOptions): Executor;
-
-// @public (undocumented)
-export type RetryOptions = {
-    attempts?: number;
-    shouldRetry?: (error: unknown, attempt: number) => boolean | Promise<boolean>;
-    onRetry?: (error: unknown, attempt: number) => void | Promise<void>;
-};
-
-// @public (undocumented)
-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:25: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:29: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:32: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:47:5 - (ae-forgotten-export) The symbol "ExecutorContext" needs to be exported by the entry point index.d.ts
-
-// (No @packageDocumentation comment for this package)
-
-```
+## 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)
+
+```