@neutrome/lilsdk 0.3.5 → 0.4.0

package/src/types.ts

@@ -8,20 +8,6 @@ export type TransformCapability =
   | "drop_content"
   | "provider_extension";
 
-export type ExecutionTarget =
-  | {
-      kind: "provider";
-      provider?: string;
-      model: string;
-      transforms?: string[];
-    }
-  | {
-      kind: "executor";
-      executorId: string;
-      alias: string;
-      transforms?: string[];
-    };
-
 export type ExecutionEvent = {
   kind: string;
   requestId: string;
@@ -37,40 +23,40 @@ export type ExecutionEventInput = Omit<ExecutionEvent, "timestamp"> & {
   timestamp?: string;
 };
 
-export type InvokeOptions = {
-  target?: ExecutionTarget;
-  requestId?: string;
-  executionId?: string;
-  parentExecutionId?: string;
+export type CachePutOptions = {
+  expiration?: number;
+  expirationTtl?: number;
+};
+
+export type Cache = {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: CachePutOptions): Promise<void>;
+  delete(key: string): Promise<void>;
 };
 
-export type TransformContext = {
-  invoke(request: Program, options?: InvokeOptions): Promise<Program>;
+type RuntimeContext = {
+  cache: Cache;
+  invoke(executor: ExecutorInput, request: Program): Promise<Program>;
   invokeStream(
+    executor: ExecutorInput,
     request: Program,
-    options?: InvokeOptions,
   ): AsyncIterable<Program>;
   observe(event: ExecutionEvent): void;
   signal: AbortSignal;
 };
 
+export type TransformContext = RuntimeContext;
+
 export type ProgramTransform = {
   name: string;
   capabilities: TransformCapability[];
   apply(program: Program, ctx: TransformContext): Program | Promise<Program>;
 };
 
-export type ExecutorContext = {
+export type ExecutorContext = RuntimeContext & {
   requestId: string;
   executionId: string;
   parentExecutionId?: string;
-  invoke(request: Program, options?: InvokeOptions): Promise<Program>;
-  invokeStream(
-    request: Program,
-    options?: InvokeOptions,
-  ): AsyncIterable<Program>;
-  observe(event: ExecutionEvent): void;
-  signal: AbortSignal;
 };
 
 export type Executor = {
@@ -78,6 +64,8 @@ export type Executor = {
   stream(request: Program, ctx: ExecutorContext): AsyncIterable<Program>;
 };
 
+export type ExecutorInput = string | Executor;
+
 export type Tool = {
   name: string;
   description: string;

package/test/lilsdk-ts.test.ts

@@ -1,10 +1,13 @@
 import {
   contentText,
+  createProgram,
+  deltaText,
   emitChatCompletionsRequest,
   emitChatCompletionsStreamChunk,
   getModel,
   parseChatCompletionsRequest,
   parseChatCompletionsStreamChunk,
+  setModel,
   Opcode,
   type Program,
 } from "@neutrome/lil-engine";
@@ -31,10 +34,8 @@ import { createGoalExecutor, fallback, retry } from "../src/loops/index.ts";
 import {
   appendInternalDraft,
   createTwoPassExecutor,
-  invokeExecutor,
   INTERNAL_DRAFT_TOOL_NAME,
-  streamExecutor,
-} from "../src/managed/twoPassExecutor.ts";
+} from "../src/managed/two-pass.ts";
 import type { Executor, ExecutorContext, OutputSink } from "../src/types.ts";
 
 const encoder = new TextEncoder();
@@ -197,7 +198,7 @@ describe("@neutrome/lilsdk", () => {
     );
     const seen: Program[] = [];
     const ctx = buildExecutorContext({
-      async invoke(program) {
+      async invoke(_executor, program) {
         seen.push(program);
         if (seen.length === 1) {
           return appendAssistantMessage(
@@ -216,8 +217,8 @@ describe("@neutrome/lilsdk", () => {
     });
 
     const executor = createTwoPassExecutor({
-      draftModel: "smart-model",
-      finalModel: "base-model",
+      draft: "smart-model",
+      final: "base-model",
       resolveFinalSettings: () => ({
         reasoningLevel: "high",
         systemPrompt: "system prompt",
@@ -265,7 +266,7 @@ describe("@neutrome/lilsdk", () => {
     );
     const seen: Program[] = [];
     const ctx = buildExecutorContext({
-      async invoke(program) {
+      async invoke(_executor, program) {
         seen.push(program);
         return appendAssistantMessage(
           { code: [], buffers: [] },
@@ -278,8 +279,8 @@ describe("@neutrome/lilsdk", () => {
     });
 
     const executor = createTwoPassExecutor({
-      draftModel: "smart-model",
-      finalModel: "base-model",
+      draft: "smart-model",
+      final: "base-model",
       resolveDraftSettings: () => ({ systemPrompt: "draft system" }),
     });
 
@@ -295,17 +296,17 @@ describe("@neutrome/lilsdk", () => {
     ]);
   });
 
-  it("invokes and streams string or custom executors", async () => {
+  it("composes model strings and custom executors", async () => {
     const calls: Array<{ model: string; streaming: boolean }> = [];
     const ctx = buildExecutorContext({
-      async invoke(program) {
+      async invoke(_executor, program) {
         calls.push({ model: getModel(program) ?? "", streaming: false });
         return appendAssistantMessage(
           { code: [], buffers: [] },
           "model answer",
         );
       },
-      async *invokeStream(program) {
+      async *invokeStream(_executor, program) {
         calls.push({ model: getModel(program) ?? "", streaming: true });
         yield parseChatCompletionsStreamChunk(
           encoder.encode(
@@ -327,9 +328,9 @@ describe("@neutrome/lilsdk", () => {
         }),
       ),
     );
-    const first = await invokeExecutor(ctx, request, "smart-model");
+    const first = await ctx.invoke("smart-model", request);
     const chunks: Program[] = [];
-    for await (const chunk of streamExecutor(ctx, request, "base-model")) {
+    for await (const chunk of ctx.invokeStream("base-model", request)) {
       chunks.push(chunk);
     }
 
@@ -346,12 +347,12 @@ describe("@neutrome/lilsdk", () => {
     const customExecutor = executorFromExecute(async () =>
       appendAssistantMessage({ code: [], buffers: [] }, "custom answer"),
     );
-    const custom = await invokeExecutor(ctx, request, customExecutor);
+    const custom = await ctx.invoke(customExecutor, request);
     expect(contentText(custom)).toBe("custom answer");
 
     const twoPass = createTwoPassExecutor({
-      draftModel: customExecutor,
-      finalModel: customExecutor,
+      draft: customExecutor,
+      final: customExecutor,
     });
     expect(contentText(await twoPass.execute(request, ctx))).toBe(
       "custom answer",
@@ -369,7 +370,7 @@ describe("@neutrome/lilsdk", () => {
     );
     const seen: Program[] = [];
     const ctx = buildExecutorContext({
-      async invoke(program) {
+      async invoke(_executor, program) {
         seen.push(program);
         return appendAssistantMessage(
           { code: [], buffers: [] },
@@ -382,8 +383,8 @@ describe("@neutrome/lilsdk", () => {
     });
 
     const executor = createTwoPassExecutor({
-      draftModel: "smart-model",
-      finalModel: "base-model",
+      draft: "smart-model",
+      final: "base-model",
       maxTotalContextLength: 10,
       resolveDraftSettings: () => ({ systemPrompt: "draft" }),
     });
@@ -397,8 +398,8 @@ describe("@neutrome/lilsdk", () => {
     let receivedRequest: Program | undefined;
     let receivedContext: ExecutorContext | undefined;
     const directFinal = createTwoPassExecutor({
-      draftModel: "unused",
-      finalModel: "base-model",
+      draft: "unused",
+      final: "base-model",
       resolveDraftSettings: (incomingRequest, incomingContext) => {
         receivedRequest = incomingRequest;
         receivedContext = incomingContext;
@@ -411,14 +412,55 @@ describe("@neutrome/lilsdk", () => {
     expect(receivedContext).toBe(ctx);
 
     const draftOnly = createTwoPassExecutor({
-      draftModel: "smart-model",
-      finalModel: "unused",
+      draft: "smart-model",
+      final: "unused",
       resolveFinalSettings: () => null,
     });
     await draftOnly.execute(request, ctx);
     expect(getModel(seen.at(-1)!)).toBe("smart-model");
   });
 
+  it("keeps two-pass drafts inside the final stream", async () => {
+    const executor = createTwoPassExecutor({
+      draft: "draft",
+      final: "final",
+    });
+    const ctx = buildExecutorContext({
+      async invoke() {
+        throw new Error("non-streaming path is not used in this test");
+      },
+      async *invokeStream(executor) {
+        const text = executor === "draft" ? "draft" : "final";
+        yield createProgram({
+          code: [
+            {
+              opcode: Opcode.STREAM_DELTA,
+              value: { kind: "string", value: text },
+            },
+            {
+              opcode: Opcode.RESP_DONE,
+              value: { kind: "string", value: "stop" },
+            },
+            { opcode: Opcode.STREAM_END, value: { kind: "none" } },
+          ],
+        });
+      },
+    });
+
+    const chunks: Program[] = [];
+    for await (const chunk of executor.stream({ code: [], buffers: [] }, ctx)) {
+      chunks.push(chunk);
+    }
+    const opcodes = chunks.flatMap((chunk) =>
+      chunk.code.map((instruction) => instruction.opcode),
+    );
+
+    expect(
+      opcodes.filter((opcode) => opcode === Opcode.STREAM_END),
+    ).toHaveLength(1);
+    expect(chunks.map(deltaText).filter(Boolean)).toContain("final");
+  });
+
   it("writes reasoning helpers to a sink", async () => {
     const emitted: string[] = [];
     const sink: OutputSink = {
@@ -582,7 +624,7 @@ describe("@neutrome/lilsdk", () => {
       chunks.push(chunk);
     }
 
-    expect(chunks.map(contentText)).toEqual([
+    expect(chunks.map(contentText).filter(Boolean)).toEqual([
       "answer 1",
       "retry",
       "answer 2",
@@ -590,6 +632,61 @@ describe("@neutrome/lilsdk", () => {
     ]);
   });
 
+  it("keeps goal stage completions inside one stream", async () => {
+    let attempt = 0;
+    const stage = (text: string) =>
+      streamingExecutor(async function* () {
+        yield createProgram({
+          code: [
+            {
+              opcode: Opcode.STREAM_DELTA,
+              value: { kind: "string", value: text },
+            },
+            {
+              opcode: Opcode.RESP_DONE,
+              value: { kind: "string", value: "stop" },
+            },
+            { opcode: Opcode.STREAM_END, value: { kind: "none" } },
+          ],
+        });
+      });
+    const executor = createGoalExecutor({
+      draft: streamingExecutor(async function* () {
+        attempt += 1;
+        yield* stage(`answer ${attempt}`).stream(
+          { code: [], buffers: [] },
+          buildExecutorContext(),
+        );
+      }),
+      review: streamingExecutor(async function* () {
+        yield* stage("review").stream(
+          { code: [], buffers: [] },
+          buildExecutorContext(),
+        );
+      }),
+      satisfied: () => attempt === 2,
+      refine: (request) => request,
+    });
+
+    const chunks: Program[] = [];
+    for await (const chunk of executor.stream(
+      { code: [], buffers: [] },
+      buildExecutorContext(),
+    )) {
+      chunks.push(chunk);
+    }
+
+    const opcodes = chunks.flatMap((chunk) =>
+      chunk.code.map((instruction) => instruction.opcode),
+    );
+    expect(
+      opcodes.filter((opcode) => opcode === Opcode.RESP_DONE),
+    ).toHaveLength(1);
+    expect(
+      opcodes.filter((opcode) => opcode === Opcode.STREAM_END),
+    ).toHaveLength(1);
+  });
+
   it("uses streamed text as the next goal stage's response", async () => {
     let reviewedAnswer = "";
     const executor = createGoalExecutor({
@@ -621,24 +718,44 @@ describe("@neutrome/lilsdk", () => {
 
 function buildExecutorContext(
   impl: Pick<ExecutorContext, "invoke" | "invokeStream"> = {
-    async invoke(program) {
-      return program;
+    async invoke(_executor, request) {
+      return request;
     },
-    async *invokeStream(program) {
-      yield program;
+    async *invokeStream(_executor, request) {
+      yield request;
     },
   },
 ): ExecutorContext {
-  return {
+  const context: ExecutorContext = {
+    cache: testCache,
     requestId: "req_test",
     executionId: "exec_test",
-    invoke: impl.invoke,
-    invokeStream: impl.invokeStream,
+    invoke(executor, request) {
+      return typeof executor === "string"
+        ? impl.invoke(executor, setModel(request, executor))
+        : executor.execute(request, context);
+    },
+    async *invokeStream(executor, request) {
+      if (typeof executor === "string") {
+        yield* impl.invokeStream(executor, setModel(request, executor));
+        return;
+      }
+      yield* executor.stream(request, context);
+    },
     observe: () => {},
     signal: new AbortController().signal,
   };
+  return context;
 }
 
+const testCache: ExecutorContext["cache"] = {
+  async get() {
+    return null;
+  },
+  async put() {},
+  async delete() {},
+};
+
 function executorFromExecute(execute: Executor["execute"]): Executor {
   return {
     execute,