@neutrome/lilsdk 0.4.4 → 0.4.6

package/README.md

@@ -3,7 +3,7 @@
 High-level TypeScript SDK for transport-neutral model authoring on top of `@neutrome/lil-engine`.
 
 ```ts
-import { createTwoPassExecutor, type Executor } from "@neutrome/lilsdk";
+import type { Executor } from "@neutrome/lilsdk";
 import { retry } from "@neutrome/lilsdk/loops";
 import {
   observeExecutionStream,
@@ -20,11 +20,7 @@ This package owns:
 - `@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
-
-The root export is intentionally small: SDK contracts plus the most common
-high-level two-pass executor helper.
+The root export is intentionally small: SDK contracts.
 
 It intentionally does not own HTTP routing, provider credentials, target
 resolution, or provider JSON conversion. Those live in `@neutrome/open-ai-router`

package/etc/api/index.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 (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)
+
+```

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 (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)
+
+```

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 (undocumented)
+export type AttachmentReaderRule = {
+    mimeTypes: readonly string[];
+    executor: ExecutorInput;
+};
+
+// @public (undocumented)
+export type AttachmentToTextOptions = {
+    systemPrompt?: string;
+    cacheKey?: (attachment: ProgramAttachment, ctx: ExecutorContext) => string;
+};
+
+// @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;
+};
+
+// @public (undocumented)
+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 (undocumented)
+export function createAttachmentToTextExecutor(inner: ExecutorInput, rules: readonly AttachmentReaderRule[], options?: AttachmentToTextOptions): Executor;
+
+// @public (undocumented)
+export function createCapabilitiesExecutor(inner: ExecutorInput, options?: CapabilitiesExecutorOptions): 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;
+
+// @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/managed/attachment-to-text.d.ts:5: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:9: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: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
+
+// (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 (undocumented)
+export function all(program: Program, callback: (instruction: Instruction, index: number, program: Program) => boolean): boolean;
+
+// @public (undocumented)
+export function any(program: Program, callback: (instruction: Instruction, index: number, program: Program) => boolean): boolean;
+
+// @public (undocumented)
+export function filter(program: Program, callback: (instruction: Instruction, index: number, program: Program) => boolean): Program;
+
+// @public (undocumented)
+export function find(program: Program, needle: Instruction): Instruction | undefined;
+
+// @public (undocumented)
+export function has(program: Program, needle: Instruction): boolean;
+
+// @public (undocumented)
+export function indexOf(program: Program, needle: Instruction): number;
+
+// @public (undocumented)
+export function map(program: Program, callback: (instruction: Instruction, index: number, program: Program) => Instruction): Program;
+
+// @public (undocumented)
+export function reduce<T>(program: Program, callback: (accumulator: T, instruction: Instruction, index: number, program: Program) => T, initialValue: T): T;
+
+// @public (undocumented)
+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,55 @@
+## 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)
+export function completeStream(reason?: string): Program;
+
+// @public (undocumented)
+export type ObservedExecution = {
+    mode: "text";
+    transcript: string;
+    emittedText: boolean;
+} | {
+    mode: "tool";
+    transcript: string;
+    emittedText: boolean;
+    chunks: Program[];
+};
+
+// @public (undocumented)
+export function observeExecutionStream(source: AsyncIterable<Program>, hooks?: StreamObservationHooks): Promise<ObservedExecution>;
+
+// @public (undocumented)
+type OutputSink = {
+    write(chunk: Program): void | Promise<void>;
+    close(): void | Promise<void>;
+};
+
+// @public (undocumented)
+export type StreamObservationHooks = {
+    onTextStart?: () => void;
+    onTextChunk?: (text: string, chunk: Program) => void;
+};
+
+// @public (undocumented)
+export function streamReasoningDelta(text: string): Program;
+
+// @public
+export function streamStage(source: AsyncIterable<Program>): AsyncGenerator<Program>;
+
+// @public (undocumented)
+export function streamTextResponse(text: string): Program[];
+
+// Warning: (ae-forgotten-export) The symbol "OutputSink" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+export function writeReasoning(sink: OutputSink, text: string): Promise<void>;
+
+// (No @packageDocumentation comment for this package)
+
+```

package/etc/api/synthetic.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 (undocumented)
+export function appendAssistantMessage(program: Program, text: string): Program;
+
+// @public (undocumented)
+export function appendToolInteraction(program: Program, interaction: ToolInteraction): Program;
+
+// @public (undocumented)
+export function appendUserMessage(program: Program, text: string): Program;
+
+// @public (undocumented)
+export function createModelProgram(model: string): Program;
+
+// @public (undocumented)
+export function makeMessage(role: TextMessageRole, text: string): Program;
+
+// @public (undocumented)
+export function makeToolCall(name: string, args?: unknown, callId?: string): Program;
+
+// @public (undocumented)
+export function makeToolResponse(callId: string, result: unknown): Program;
+
+// @public (undocumented)
+export function prependSystemPrompt(program: Program, text: string): Program;
+
+// @public (undocumented)
+export type TextMessageRole = "system" | "user" | "assistant";
+
+// @public (undocumented)
+export type ToolInteraction = {
+    callId: string;
+    name: string;
+    args?: unknown;
+    result: unknown;
+};
+
+// (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 (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 "Tool" needs to be exported by the entry point tools.d.ts
+// Warning: (ae-forgotten-export) The symbol "ExecutorInput" 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 (undocumented)
+export function connectTools(tools: Tool[], inner: ExecutorInput, options?: WithToolsOptions): 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 tools.d.ts
+//
+// @public (undocumented)
+type ExecutorContext = RuntimeContext & {
+    requestId: string;
+    executionId: string;
+    parentExecutionId?: string;
+};
+
+// @public (undocumented)
+type ExecutorInput = string | Executor;
+
+// @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)
+type Tool = {
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+    systemPromptFragment?: string;
+    execute(args: Record<string, unknown>, ctx: ExecutorContext): Promise<string>;
+};
+
+// @public (undocumented)
+export class ToolArgumentsError extends Error {
+    constructor(toolName: string, argumentsText: string);
+    // (undocumented)
+    readonly argumentsText: string;
+    // (undocumented)
+    readonly toolName: string;
+}
+
+// @public (undocumented)
+export type WithToolsOptions = {
+    maxIterations?: number;
+};
+
+// 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 tools.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 tools.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 tools.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 tools.d.ts
+
+// (No @packageDocumentation comment for this package)
+
+```

package/etc/api/types.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 (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 types.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)
+
+```