@neutrome/lilsdk 0.3.5

package/README.md

@@ -0,0 +1,31 @@
+# `@neutrome/lilsdk`
+
+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";
+```
+
+This package owns:
+
+- 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
+
+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

@@ -0,0 +1,27 @@
+{
+  "name": "@neutrome/lilsdk",
+  "version": "0.3.5",
+  "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"
+  },
+  "dependencies": {
+    "@neutrome/lil-engine": "0.3.4"
+  },
+  "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

@@ -0,0 +1,14 @@
+export type {
+  ExecutionTarget,
+  Executor,
+  ExecutorContext,
+  InvokeOptions,
+  OutputSink,
+  ProgramTransform,
+  ExecutionEvent,
+  ExecutionEventInput,
+  Tool,
+  TransformCapability,
+  TransformContext,
+} from "./types.ts";
+export { createExecutionEvent } from "./types.ts";

package/src/loops/index.ts

@@ -0,0 +1,266 @@
+import { createProgram, deltaText, type Program } from "@neutrome/lil-engine";
+import type { Executor, ExecutorContext } from "../types.ts";
+import { appendAssistantMessage } from "../synthetic/index.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 GoalExecutorOptions = {
+  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,
+      );
+    },
+
+    async *stream(request, ctx) {
+      let lastError: unknown;
+
+      for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        let emitted = false;
+        try {
+          for await (const chunk of executor.stream(
+            request,
+            childContext(ctx, attempt),
+          )) {
+            emitted = true;
+            yield chunk;
+          }
+          return;
+        } catch (error) {
+          lastError = error;
+          if (emitted) throw error;
+          const canRetry =
+            attempt < attempts &&
+            (await shouldContinue(error, attempt, options.shouldRetry));
+          if (!canRetry) {
+            throw error;
+          }
+          await options.onRetry?.(error, attempt);
+        }
+      }
+
+      throw lastError;
+    },
+  };
+}
+
+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,
+      );
+    },
+
+    async *stream(request, ctx) {
+      let lastError: unknown;
+
+      for (const [index, executor] of executors.entries()) {
+        let emitted = false;
+        try {
+          for await (const chunk of executor.stream(
+            request,
+            childContext(ctx, index + 1),
+          )) {
+            emitted = true;
+            yield chunk;
+          }
+          return;
+        } catch (error) {
+          lastError = error;
+          if (emitted) throw error;
+          const canFallback =
+            index < executors.length - 1 &&
+            (await shouldContinue(error, index, options.shouldFallback));
+          if (!canFallback) {
+            throw error;
+          }
+          await options.onFallback?.(error, index);
+        }
+      }
+
+      throw lastError;
+    },
+  };
+}
+
+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 options.draft.execute(current, attemptContext);
+        const review = await options.review.execute(answer, attemptContext);
+        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(
+          options.draft.stream(current, attemptContext),
+          current,
+        );
+        const review = yield* streamGoalStage(
+          options.review.stream(answer, attemptContext),
+          answer,
+        );
+
+        if (await options.satisfied(review, attempt)) return;
+        if (attempt < maxIterations) {
+          current = await options.refine(current, answer, review, attempt);
+        }
+      }
+    },
+  };
+}
+
+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,
+  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;
+}
+
+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,18 @@
+export { createTargetExecutor } from "./target-executor.ts";
+
+export {
+  appendInternalDraft,
+  createTwoPassExecutor,
+  INTERNAL_DRAFT_CALL_ID,
+  INTERNAL_DRAFT_TOOL_NAME,
+  invokeExecutor,
+  streamExecutor,
+} from "./twoPassExecutor.ts";
+
+export type {
+  InternalDraft,
+  ModelExecutor,
+  TwoPassExecutorOptions,
+  TwoPassSettings,
+  TwoPassSettingsResolver,
+} from "./twoPassExecutor.ts";

package/src/managed/target-executor.ts

@@ -0,0 +1,12 @@
+import type { ExecutionTarget, Executor } from "../types.ts";
+
+export function createTargetExecutor(target: ExecutionTarget): Executor {
+  return {
+    execute(request, context) {
+      return context.invoke(request, { target });
+    },
+    stream(request, context) {
+      return context.invokeStream(request, { target });
+    },
+  };
+}

package/src/managed/two-pass-request.ts

@@ -0,0 +1,164 @@
+import {
+  appendInstructions,
+  contentText,
+  insertBefore,
+  messageText,
+  messages,
+  removeRange,
+  type Program,
+} from "@neutrome/lil-engine";
+import { Opcode } from "@neutrome/lil-engine";
+import {
+  appendToolInteraction,
+  makeMessage,
+  prependSystemPrompt,
+} from "../synthetic/index.ts";
+import type { ExecutorContext } 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 TwoPassSettings = {
+  reasoningLevel?: string;
+  systemPrompt?: string;
+};
+
+export type TwoPassSettingsResolver = (
+  request: Program,
+  ctx: ExecutorContext,
+) => TwoPassSettings | null | Promise<TwoPassSettings | null>;
+
+export type TwoPassRequestOptions = {
+  maxTotalContextLength?: number;
+  buildFinalRequest?: (request: Program, draft: string) => Program;
+};
+
+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 buildDraftRequest(
+  request: Program,
+  settings: TwoPassSettings,
+): Program {
+  const withPrompt = settings.systemPrompt
+    ? replaceSystemPrompt(request, settings.systemPrompt)
+    : request;
+  return applySettings(withPrompt, settings);
+}
+
+export function buildFinalRequest(
+  options: TwoPassRequestOptions,
+  request: Program,
+  settings: TwoPassSettings,
+  draft: string,
+): Program {
+  const limitedDraft = limitDraft(options, request, settings, draft);
+  const withDraft = options.buildFinalRequest
+    ? options.buildFinalRequest(request, limitedDraft)
+    : appendInternalDraft(request, limitedDraft);
+  const withPrompt = settings.systemPrompt
+    ? prependSystemPrompt(withDraft, settings.systemPrompt)
+    : withDraft;
+  return applySettings(withPrompt, settings);
+}
+
+export function validateMaxContextLength(value: number | undefined): void {
+  if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+    throw new Error("maxTotalContextLength must be a non-negative integer");
+  }
+}
+
+function replaceSystemPrompt(request: Program, systemPrompt: string): Program {
+  const systemSpans = messages(request).filter(
+    (span) => span.role === "system",
+  );
+  const previousSystemPrompt = systemSpans
+    .map((span) => messageText(request, span).trim())
+    .filter(Boolean)
+    .join("\n\n");
+  let draft = request;
+  for (const span of systemSpans.slice().reverse()) {
+    draft = removeRange(draft, span.start, span.end);
+  }
+  draft = prependSystemPrompt(draft, systemPrompt);
+  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 applySettings(request: Program, settings: TwoPassSettings): Program {
+  if (!settings.reasoningLevel) return request;
+  return appendInstructions(
+    {
+      ...request,
+      code: request.code.filter(
+        (instruction) => instruction.opcode !== Opcode.SET_REASON_EFFORT,
+      ),
+    },
+    [
+      {
+        opcode: Opcode.SET_REASON_EFFORT,
+        value: { kind: "string", value: settings.reasoningLevel },
+      },
+    ],
+  );
+}
+
+function limitDraft(
+  options: TwoPassRequestOptions,
+  request: Program,
+  settings: TwoPassSettings,
+  draft: string,
+): string {
+  if (options.maxTotalContextLength === undefined) return draft;
+  const base = buildFinalRequestWithoutDraft(options, request, settings);
+  const available = options.maxTotalContextLength - contentText(base).length;
+  return available > 0 ? draft.slice(0, available) : "";
+}
+
+function buildFinalRequestWithoutDraft(
+  options: TwoPassRequestOptions,
+  request: Program,
+  settings: TwoPassSettings,
+): Program {
+  const withDraft = options.buildFinalRequest
+    ? options.buildFinalRequest(request, "")
+    : request;
+  const withPrompt = settings.systemPrompt
+    ? prependSystemPrompt(withDraft, settings.systemPrompt)
+    : withDraft;
+  return applySettings(withPrompt, settings);
+}
+
+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);
+}