@neutrome/lilsdk-ts 0.1.2 → 0.2.0

package/README.md

@@ -3,18 +3,26 @@
 High-level TypeScript SDK for transport-neutral model authoring on top of `@neutrome/lil-engine`.
 
 ```ts
-import {
-  appendSyntheticToolExchange,
-  executeWithModel,
-  observeExecutionStream,
-  writeReasoning,
-  type ModelHandler,
-} from "@neutrome/lilsdk-ts";
+import { createTwoPassExecutor, type Executor } from "@neutrome/lilsdk-ts";
+import { retry } from "@neutrome/lilsdk-ts/loops";
+import { observeExecutionStream, writeReasoning } from "@neutrome/lilsdk-ts/stream";
+import { connectTools } from "@neutrome/lilsdk-ts/tools";
 ```
 
 This package owns:
 
-- model execution interfaces
-- request/program rewriting helpers
-- stream passthrough helpers
-- multi-pass authoring primitives used by virtual models such as `enei-1`
+- executor and tool contracts
+- `@neutrome/lilsdk-ts/primitives`: structural program helpers such as `walk`, `map`, `reduce`, `has`, `find`, `indexOf`, `all`, and `any`
+- `@neutrome/lilsdk-ts/synthetic`: request/message/tool synthesis helpers such as `makeRequest`, `makeResponse`, `makeMessage`, `makeToolCall`, `makeToolResponse`, and `appendToolInteraction`
+- `@neutrome/lilsdk-ts/tools`: `connectTools` and `withTools` tool-call loops
+- `@neutrome/lilsdk-ts/stream`: stream observation and output helpers
+- `@neutrome/lilsdk-ts/loops`: `retry`, `fallback`, and `goal` executor control-flow helpers
+- `@neutrome/lilsdk-ts/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.
+
+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`.

package/package.json

@@ -1,20 +1,27 @@
 {
   "name": "@neutrome/lilsdk-ts",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    ".": "./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"
   },
   "dependencies": {
-    "@neutrome/lil-engine": "0.1.2"
+    "@neutrome/lil-engine": "0.2.0"
   },
   "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,9 +1,14 @@
-export type { ModelHandler, ModelRuntime, OutputSink } from "./types.ts";
-export type { ExecuteModelOptions, StreamModelOptions } from "./types.ts";
-export type { ObservedExecution, StreamObservationHooks } from "./observe.ts";
-export type { SyntheticToolExchange } from "./request.ts";
-
-export { appendSyntheticToolExchange } from "./request.ts";
-export { writeReasoning } from "./output.ts";
-export { executeWithModel, passthroughPrograms, pipeProgramStream, streamWithModel } from "./execution.ts";
-export { observeExecutionStream } from "./observe.ts";
+export type {
+  ExecutionTarget,
+  Executor,
+  ExecutorContext,
+  InvokeOptions,
+  OutputSink,
+  ProgramTransform,
+  SdkEvent,
+  SdkEventInput,
+  Tool,
+  TransformCapability,
+  TransformContext,
+  createSdkEvent,
+} from "./types.ts";

package/src/loops/index.ts

@@ -0,0 +1,190 @@
+import type { Program } from "@neutrome/lil-engine";
+import type { Executor, ExecutorContext } from "../types.ts";
+
+export type RetryOptions = {
+  attempts?: number;
+  shouldRetry?: (error: unknown, attempt: number) => boolean | Promise<boolean>;
+  onRetry?: (error: unknown, attempt: number) => void | Promise<void>;
+};
+
+export type FallbackOptions = {
+  shouldFallback?: (error: unknown, executorIndex: number) => boolean | Promise<boolean>;
+  onFallback?: (error: unknown, executorIndex: number) => void | Promise<void>;
+};
+
+export type GoalOptions = {
+  draft: Executor;
+  review: Executor;
+  refine: (
+    request: Program,
+    answer: Program,
+    review: Program,
+    attempt: number,
+  ) => Program | Promise<Program>;
+  satisfied: (review: Program, attempt: number) => boolean | Promise<boolean>;
+  maxIterations?: number;
+};
+
+export function retry(executor: Executor, options: RetryOptions = {}): Executor {
+  const attempts = positiveInteger(options.attempts ?? 2, "retry attempts");
+
+  return {
+    execute(request, ctx) {
+      return runRetry(
+        (attempt) => executor.execute(request, childContext(ctx, attempt)),
+        attempts,
+        options,
+      );
+    },
+
+    stream(request, ctx) {
+      return streamBuffered(() =>
+        runRetry(
+          (attempt) => collect(executor.stream(request, childContext(ctx, attempt))),
+          attempts,
+          options,
+        ),
+      );
+    },
+  };
+}
+
+export function fallback(executors: readonly Executor[], options: FallbackOptions = {}): Executor {
+  if (executors.length === 0) {
+    throw new Error("fallback requires at least one executor");
+  }
+
+  return {
+    execute(request, ctx) {
+      return runFallback(
+        (executor, index) => executor.execute(request, childContext(ctx, index + 1)),
+        executors,
+        options,
+      );
+    },
+
+    stream(request, ctx) {
+      return streamBuffered(() =>
+        runFallback(
+          (executor, index) => collect(executor.stream(request, childContext(ctx, index + 1))),
+          executors,
+          options,
+        ),
+      );
+    },
+  };
+}
+
+export function goal(options: GoalOptions): Executor {
+  const maxIterations = positiveInteger(options.maxIterations ?? 3, "goal maxIterations");
+  const executeGoal: Executor["execute"] = async (request, ctx) => {
+    let current = request;
+    let answer = request;
+
+    for (let attempt = 1; attempt <= maxIterations; attempt += 1) {
+      answer = await options.draft.execute(current, childContext(ctx, attempt));
+      const review = await options.review.execute(answer, childContext(ctx, attempt));
+      if (await options.satisfied(review, attempt)) {
+        return answer;
+      }
+      if (attempt < maxIterations) {
+        current = await options.refine(current, answer, review, attempt);
+      }
+    }
+
+    return answer;
+  };
+
+  return {
+    execute: executeGoal,
+
+    stream(request, ctx) {
+      return streamBuffered(async () => [await executeGoal(request, ctx)]);
+    },
+  };
+}
+
+async function runRetry<T>(
+  operation: (attempt: number) => Promise<T>,
+  attempts: number,
+  options: RetryOptions,
+): Promise<T> {
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      return await operation(attempt);
+    } catch (error) {
+      lastError = error;
+      const canRetry = attempt < attempts && (await shouldContinue(error, attempt, options.shouldRetry));
+      if (!canRetry) {
+        throw error;
+      }
+      await options.onRetry?.(error, attempt);
+    }
+  }
+
+  throw lastError;
+}
+
+async function runFallback<T>(
+  operation: (executor: Executor, index: number) => Promise<T>,
+  executors: readonly Executor[],
+  options: FallbackOptions,
+): Promise<T> {
+  let lastError: unknown;
+
+  for (const [index, executor] of executors.entries()) {
+    try {
+      return await operation(executor, index);
+    } catch (error) {
+      lastError = error;
+      const canFallback =
+        index < executors.length - 1 &&
+        (await shouldContinue(error, index, options.shouldFallback));
+      if (!canFallback) {
+        throw error;
+      }
+      await options.onFallback?.(error, index);
+    }
+  }
+
+  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;
+}
+
+async function collect(stream: AsyncIterable<Program>): Promise<Program[]> {
+  const chunks: Program[] = [];
+  for await (const chunk of stream) {
+    chunks.push(chunk);
+  }
+  return chunks;
+}
+
+async function* streamBuffered(load: () => Promise<Program[]>): AsyncIterable<Program> {
+  for (const chunk of await load()) {
+    yield chunk;
+  }
+}
+
+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/managed/index.ts

@@ -0,0 +1,15 @@
+export { wrap } from "./wrap.ts";
+
+export {
+  appendInternalDraft,
+  createTwoPassExecutor,
+  INTERNAL_DRAFT_CALL_ID,
+  INTERNAL_DRAFT_TOOL_NAME,
+  invokeModel,
+  streamModel,
+} from "./twoPassExecutor.ts";
+
+export type {
+  InternalDraft,
+  TwoPassExecutorOptions,
+} from "./twoPassExecutor.ts";

package/src/managed/twoPassExecutor.ts

@@ -0,0 +1,214 @@
+import {
+  callData,
+  contentText,
+  deltaText,
+  finishReason,
+  hasToolDelta,
+  insertBefore,
+  lastMessageRole,
+  messageText,
+  messages,
+  removeRange,
+  setModel,
+  type Program,
+} from "@neutrome/lil-engine";
+import { streamReasoningDelta } from "../output.ts";
+import {
+  appendToolInteraction,
+  makeMessage,
+  prependSystemPrompt,
+} from "../synthetic/index.ts";
+import type { Executor, ExecutorContext, InvokeOptions } from "../types.ts";
+
+export const INTERNAL_DRAFT_TOOL_NAME = "knowledge";
+export const INTERNAL_DRAFT_CALL_ID = "knowledge_0";
+
+export type InternalDraft =
+  | string
+  | readonly string[]
+  | readonly { text: string }[];
+
+export type TwoPassExecutorOptions = {
+  draftModel: string;
+  finalModel: string;
+  draftSystemPrompt?: string;
+  finalSystemPrompt?: string;
+  reasoningIntro?: string;
+  reasoningSeparator?: string;
+  buildFinalRequest?: (request: Program, draft: string) => Program;
+};
+
+export function invokeModel(
+  ctx: ExecutorContext,
+  request: Program,
+  model: string,
+  options?: InvokeOptions,
+): Promise<Program> {
+  return ctx.invoke(setModel(request, model), options);
+}
+
+export async function* streamModel(
+  ctx: ExecutorContext,
+  request: Program,
+  model: string,
+  options?: InvokeOptions,
+): AsyncIterable<Program> {
+  yield* ctx.invokeStream(setModel(request, model), options);
+}
+
+export function appendInternalDraft(
+  request: Program,
+  draft: InternalDraft,
+  options: { callId?: string } = {},
+): Program {
+  const callId = options.callId ?? INTERNAL_DRAFT_CALL_ID;
+  const drafts = normalizeDrafts(draft);
+  if (drafts.length === 0) {
+    return request;
+  }
+
+  return drafts.reduce(
+    (program, text, index) =>
+      appendToolInteraction(program, {
+        callId: drafts.length === 1 ? callId : `${callId}_${index}`,
+        name: INTERNAL_DRAFT_TOOL_NAME,
+        args: {},
+        result: text,
+      }),
+    request,
+  );
+}
+
+export function createTwoPassExecutor(options: TwoPassExecutorOptions): Executor {
+  const reasoningIntro = options.reasoningIntro ?? "Let me think...\n\n";
+  const reasoningSeparator = options.reasoningSeparator ?? "\n\n";
+
+  return {
+    async execute(request, ctx) {
+      const draftRequest = buildDraftRequest(options, request);
+      if (lastMessageRole(request) === "tool") {
+        return invokeModel(ctx, draftRequest, options.draftModel);
+      }
+
+      const draftResponse = await invokeModel(ctx, draftRequest, options.draftModel);
+      if (callData(draftResponse).length > 0) {
+        return draftResponse;
+      }
+
+      return invokeModel(
+        ctx,
+        buildFinalRequest(options, request, contentText(draftResponse)),
+        options.finalModel,
+      );
+    },
+
+    async *stream(request, ctx) {
+      const draftRequest = buildDraftRequest(options, request);
+      if (lastMessageRole(request) === "tool") {
+        yield* streamModel(ctx, draftRequest, options.draftModel);
+        return;
+      }
+
+      let transcript = "";
+      let emittedReasoning = false;
+      let toolMode = false;
+      const draftStream = streamModel(ctx, draftRequest, options.draftModel);
+
+      for await (const chunk of draftStream) {
+        if (ctx.signal.aborted) {
+          return;
+        }
+
+        if (toolMode) {
+          yield chunk;
+          continue;
+        }
+
+        const toolRequested = hasToolDelta(chunk) || finishReason(chunk) === "tool_calls";
+        if (toolRequested) {
+          toolMode = true;
+          yield chunk;
+          continue;
+        }
+
+        const text = deltaText(chunk);
+        if (!text) {
+          continue;
+        }
+
+        transcript += text;
+        if (!emittedReasoning) {
+          emittedReasoning = true;
+          yield streamReasoningDelta(reasoningIntro);
+        }
+        yield streamReasoningDelta(text);
+      }
+
+      if (toolMode || ctx.signal.aborted) {
+        return;
+      }
+
+      if (emittedReasoning && reasoningSeparator) {
+        yield streamReasoningDelta(reasoningSeparator);
+      }
+
+      yield* streamModel(
+        ctx,
+        buildFinalRequest(options, request, transcript),
+        options.finalModel,
+      );
+    },
+  };
+}
+
+function buildDraftRequest(options: TwoPassExecutorOptions, request: Program): Program {
+  if (!options.draftSystemPrompt) {
+    return request;
+  }
+
+  const systemSpans = messages(request).filter((span) => span.role === "system");
+  const previousSystemPrompt = systemSpans
+    .map((span) => messageText(request, span).trim())
+    .filter((text) => text.length > 0)
+    .join("\n\n");
+
+  let draft = request;
+  for (const span of systemSpans.slice().reverse()) {
+    draft = removeRange(draft, span.start, span.end);
+  }
+
+  draft = prependSystemPrompt(draft, options.draftSystemPrompt);
+
+  if (!previousSystemPrompt) {
+    return draft;
+  }
+
+  const firstNonSystem = messages(draft).find((span) => span.role !== "system");
+  return insertBefore(
+    draft,
+    firstNonSystem?.start ?? draft.code.length,
+    makeMessage("user", previousSystemPrompt).code,
+  );
+}
+
+function buildFinalRequest(
+  options: TwoPassExecutorOptions,
+  request: Program,
+  draft: string,
+): Program {
+  if (options.buildFinalRequest) {
+    return options.buildFinalRequest(request, draft);
+  }
+
+  const withDraft = appendInternalDraft(request, draft);
+  return options.finalSystemPrompt
+    ? prependSystemPrompt(withDraft, options.finalSystemPrompt)
+    : withDraft;
+}
+
+function normalizeDrafts(draft: InternalDraft): string[] {
+  const drafts = Array.isArray(draft)
+    ? draft.map((item) => typeof item === "string" ? item : item.text)
+    : [draft];
+  return drafts.map((text) => text.trim()).filter((text) => text.length > 0);
+}

package/src/managed/wrap.ts

@@ -0,0 +1,9 @@
+import { setModel } from "@neutrome/lil-engine";
+import { Executor } from "../types";
+
+export function wrap(model: string): Executor {
+  return {
+    execute: (program, ctx) => ctx.invoke(setModel(program, model)),
+    stream: (request, ctx) => ctx.invokeStream(setModel(request, model)),
+  };
+}

package/src/observe.ts

@@ -1,2 +1,94 @@
-export { observeExecutionStream } from "@neutrome/lil-engine";
-export type { ObservedExecution, StreamObservationHooks } from "@neutrome/lil-engine";
+import {
+  cloneProgram,
+  deltaText,
+  finishReason,
+  hasToolDelta,
+  type Program,
+} from "@neutrome/lil-engine";
+
+export type StreamObservationHooks = {
+  onTextStart?: () => void;
+  onTextChunk?: (text: string, chunk: Program) => void;
+};
+
+export type ObservedExecution =
+  | {
+      mode: "text";
+      transcript: string;
+      emittedText: boolean;
+    }
+  | {
+      mode: "tool";
+      transcript: string;
+      emittedText: boolean;
+      chunks: Program[];
+    };
+
+export async function observeExecutionStream(
+  source: AsyncIterable<Program>,
+  hooks: StreamObservationHooks = {},
+): Promise<ObservedExecution> {
+  const pending: Program[] = [];
+  const passthrough: Program[] = [];
+  let transcript = "";
+  let mode: "pending" | "text" | "tool" = "pending";
+  let emittedText = false;
+
+  for await (const chunk of source) {
+    const text = deltaText(chunk);
+    const toolRequested = hasToolDelta(chunk) || finishReason(chunk) === "tool_calls";
+
+    if (mode === "pending") {
+      const clone = cloneProgram(chunk);
+      pending.push(clone);
+
+      if (toolRequested) {
+        mode = "tool";
+        passthrough.push(...pending.splice(0));
+        continue;
+      }
+
+      if (!text) {
+        continue;
+      }
+
+      mode = "text";
+      emittedText = true;
+      hooks.onTextStart?.();
+      for (const pendingChunk of pending.splice(0)) {
+        const pendingText = deltaText(pendingChunk);
+        if (pendingText) {
+          transcript += pendingText;
+          hooks.onTextChunk?.(pendingText, pendingChunk);
+        }
+      }
+      continue;
+    }
+
+    if (mode === "tool") {
+      passthrough.push(cloneProgram(chunk));
+      continue;
+    }
+
+    if (toolRequested) {
+      mode = "tool";
+      passthrough.push(cloneProgram(chunk));
+      continue;
+    }
+
+    if (text) {
+      if (!emittedText) {
+        emittedText = true;
+        hooks.onTextStart?.();
+      }
+      transcript += text;
+      hooks.onTextChunk?.(text, chunk);
+    }
+  }
+
+  if (mode === "tool") {
+    return { mode: "tool", transcript, emittedText, chunks: passthrough };
+  }
+
+  return { mode: "text", transcript, emittedText };
+}

package/src/output.ts

@@ -1,10 +1,25 @@
-import { createProgram, Opcode } from "@neutrome/lil-engine";
+import {
+  createProgram,
+  Opcode,
+  streamEnd,
+  streamStart,
+  streamTextDelta,
+  type Program,
+} from "@neutrome/lil-engine";
 import type { OutputSink } from "./types.ts";
 
 export async function writeReasoning(sink: OutputSink, text: string): Promise<void> {
-  await sink.write(createProgram({
+  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 } },
     ],
-  }));
+  });
 }