@neutrome/lilsdk 0.4.6 → 0.5.0

package/test/lilsdk-ts.test.ts

@@ -1,14 +1,17 @@
 import {
-  contentText,
+  appendAssistantMessage,
+  appendToolInteraction,
   createProgram,
-  emitChatCompletionsRequest,
-  emitChatCompletionsStreamChunk,
-  parseChatCompletionsRequest,
-  parseChatCompletionsStreamChunk,
-  programAttachments,
-  viewProgram,
-  setModel,
+  delta,
+  emitProviderRequest,
+  emitProviderStreamChunk,
+  extractAttachments,
+  extractContentText,
   Opcode,
+  parseProviderRequest,
+  parseProviderStreamChunk,
+  ProgramView,
+  setModel,
   type Program,
 } from "@neutrome/lil-engine";
 import { describe, expect, it } from "vitest";
@@ -21,15 +24,7 @@ import {
   map,
   reduce,
 } from "../src/primitives/index.ts";
-import {
-  appendAssistantMessage,
-  appendToolInteraction,
-} from "../src/synthetic/index.ts";
-import {
-  observeExecutionStream,
-  streamTextResponse,
-  writeReasoning,
-} from "../src/stream/index.ts";
+import { observeExecutionStream, writeThinking } from "../src/stream/index.ts";
 import { createGoalExecutor, fallback, retry } from "../src/loops/index.ts";
 import { createAttachmentToTextExecutor } from "../src/managed/attachment-to-text.ts";
 import { createCapabilitiesExecutor } from "../src/managed/capabilities.ts";
@@ -40,7 +35,8 @@ const decoder = new TextDecoder();
 
 describe("@neutrome/lilsdk", () => {
   it("leaves capability tool prefixes directly available", async () => {
-    const request = parseChatCompletionsRequest(
+    const request = parseProviderRequest(
+      "chat-completions",
       encoder.encode(
         JSON.stringify({
           tools: [
@@ -61,14 +57,14 @@ describe("@neutrome/lilsdk", () => {
 
     await executor.execute(request, buildExecutorContext());
 
-    expect(viewProgram(innerRequest!).tools.map((tool) => tool.name)).toEqual([
-      "keep_search",
-      "learn_capability",
-    ]);
+    expect(
+      new ProgramView(innerRequest!).tools.map((tool) => tool.name),
+    ).toEqual(["keep_search", "learn_capability"]);
   });
 
   it("describes the latest attachment and removes it before the inner executor", async () => {
-    const request = parseChatCompletionsRequest(
+    const request = parseProviderRequest(
+      "chat-completions",
       encoder.encode(
         JSON.stringify({
           messages: [
@@ -113,9 +109,9 @@ describe("@neutrome/lilsdk", () => {
       ],
     );
     await executor.execute(request, buildExecutorContext());
-    expect(programAttachments(innerRequest!)).toHaveLength(0);
+    expect(extractAttachments(innerRequest!)).toHaveLength(0);
     expect(
-      viewProgram(innerRequest!).messages.at(-1)?.toolResult?.text,
+      new ProgramView(innerRequest!).messages.at(-1)?.toolResult?.text,
     ).toContain("The original binary media is not present in this context.");
   });
   it("provides clone-safe structural primitives", () => {
@@ -150,7 +146,8 @@ describe("@neutrome/lilsdk", () => {
   it("observes tool-call streams", async () => {
     const observed = await observeExecutionStream(
       (async function* () {
-        yield parseChatCompletionsStreamChunk(
+        yield parseProviderStreamChunk(
+          "chat-completions",
           encoder.encode(
             JSON.stringify({
               id: "tool-stream",
@@ -160,7 +157,8 @@ describe("@neutrome/lilsdk", () => {
             }),
           ),
         );
-        yield parseChatCompletionsStreamChunk(
+        yield parseProviderStreamChunk(
+          "chat-completions",
           encoder.encode(
             JSON.stringify({
               id: "tool-stream",
@@ -184,7 +182,8 @@ describe("@neutrome/lilsdk", () => {
             }),
           ),
         );
-        yield parseChatCompletionsStreamChunk(
+        yield parseProviderStreamChunk(
+          "chat-completions",
           encoder.encode(
             JSON.stringify({
               id: "tool-stream",
@@ -203,16 +202,18 @@ describe("@neutrome/lilsdk", () => {
     }
 
     const parsed = observed.chunks.map((chunk) =>
-      JSON.parse(decoder.decode(emitChatCompletionsStreamChunk(chunk))),
+      JSON.parse(
+        decoder.decode(emitProviderStreamChunk("chat-completions", chunk)),
+      ),
     );
     expect(parsed.some((chunk) => chunk.choices?.[0]?.delta?.tool_calls)).toBe(
       true,
     );
   });
 
-
   it("appends generic synthetic tool interactions", () => {
-    const request = parseChatCompletionsRequest(
+    const request = parseProviderRequest(
+      "chat-completions",
       encoder.encode(
         JSON.stringify({
           model: "virtual-model",
@@ -228,7 +229,7 @@ describe("@neutrome/lilsdk", () => {
       result: { status: "active" },
     });
     const emitted = JSON.parse(
-      decoder.decode(emitChatCompletionsRequest(updated)),
+      decoder.decode(emitProviderRequest("chat-completions", updated)),
     );
 
     expect(emitted.messages[1].tool_calls[0].function).toEqual({
@@ -242,19 +243,20 @@ describe("@neutrome/lilsdk", () => {
     });
   });
 
-
   it("writes reasoning helpers to a sink", async () => {
     const emitted: string[] = [];
     const sink: OutputSink = {
       write(chunk) {
-        emitted.push(decoder.decode(emitChatCompletionsStreamChunk(chunk)));
+        emitted.push(
+          decoder.decode(emitProviderStreamChunk("chat-completions", chunk)),
+        );
       },
       close() {
         emitted.push("[DONE]");
       },
     };
 
-    await writeReasoning(sink, "thinking");
+    await writeThinking(sink, "thinking");
 
     expect(JSON.parse(emitted[0]!).choices[0].delta.reasoning_content).toBe(
       "thinking",
@@ -279,7 +281,7 @@ describe("@neutrome/lilsdk", () => {
     );
 
     expect(calls).toBe(2);
-    expect(contentText(result)).toBe("ok");
+    expect(extractContentText(result)).toBe("ok");
   });
 
   it("falls back to the next executor after failure", async () => {
@@ -297,7 +299,7 @@ describe("@neutrome/lilsdk", () => {
       buildExecutorContext(),
     );
 
-    expect(contentText(result)).toBe("fallback");
+    expect(extractContentText(result)).toBe("fallback");
   });
 
   it("does not retry a stream after exposing a partial chunk", async () => {
@@ -358,7 +360,7 @@ describe("@neutrome/lilsdk", () => {
         ),
       ),
       satisfied(review) {
-        return contentText(review) === "pass";
+        return extractContentText(review) === "pass";
       },
       refine(request) {
         return request;
@@ -371,7 +373,7 @@ describe("@neutrome/lilsdk", () => {
     );
 
     expect(attempts).toBe(2);
-    expect(contentText(result)).toBe("answer 2");
+    expect(extractContentText(result)).toBe("answer 2");
   });
 
   it("streams draft and review passes through each goal iteration", async () => {
@@ -391,7 +393,7 @@ describe("@neutrome/lilsdk", () => {
         );
       }),
       satisfied(review) {
-        return contentText(review) === "pass";
+        return extractContentText(review) === "pass";
       },
       refine(request) {
         return request;
@@ -406,7 +408,7 @@ describe("@neutrome/lilsdk", () => {
       chunks.push(chunk);
     }
 
-    expect(chunks.map(contentText).filter(Boolean)).toEqual([
+    expect(chunks.map(extractContentText).filter(Boolean)).toEqual([
       "answer 1",
       "retry",
       "answer 2",
@@ -473,14 +475,14 @@ describe("@neutrome/lilsdk", () => {
     let reviewedAnswer = "";
     const executor = createGoalExecutor({
       draft: streamingExecutor(async function* () {
-        yield* streamTextResponse("answer");
+        yield* delta.textResponse("answer");
       }),
       review: streamingExecutor(async function* (request) {
-        reviewedAnswer = contentText(request);
-        yield* streamTextResponse("pass");
+        reviewedAnswer = extractContentText(request);
+        yield* delta.textResponse("pass");
       }),
       satisfied(review) {
-        return contentText(review) === "pass";
+        return extractContentText(review) === "pass";
       },
       refine(request) {
         return request;

package/test/tools.test.ts

@@ -1,13 +1,13 @@
 import { describe, expect, it } from "vitest";
 import {
-  callData,
   createProgram,
+  extractToolCalls,
   Opcode,
+  ProgramView,
   type Instruction,
   type Program,
-  viewProgram,
 } from "@neutrome/lil-engine";
-import { connectTools } from "../src/tools.ts";
+import { createToolsExecutor } from "../src/tools.ts";
 import type { ExecutorContext, Tool } from "../src/types.ts";
 
 function buildToolCallResponse(
@@ -64,7 +64,7 @@ const calculatorTool: Tool = {
   },
 };
 
-describe("connectTools", () => {
+describe("createToolsExecutor", () => {
   it("passes the executor cache to connected tools", async () => {
     let callCount = 0;
     const cache = {
@@ -83,7 +83,7 @@ describe("connectTools", () => {
         return (await ctx.cache.get("tool-key")) ?? "missing";
       },
     };
-    const executor = connectTools([tool], "test-model");
+    const executor = createToolsExecutor("test-model", [tool]);
     const ctx = buildCtx({
       async invoke() {
         callCount += 1;
@@ -105,7 +105,7 @@ describe("connectTools", () => {
   });
 
   it("passes through when LLM returns no tool calls", async () => {
-    const executor = connectTools([calculatorTool], "test-model");
+    const executor = createToolsExecutor("test-model", [calculatorTool]);
 
     const request = createProgram({
       code: [
@@ -136,7 +136,7 @@ describe("connectTools", () => {
   });
 
   it("executes connected tool and loops until text response", async () => {
-    const executor = connectTools([calculatorTool], "test-model");
+    const executor = createToolsExecutor("test-model", [calculatorTool]);
 
     let callCount = 0;
     const request = createProgram({
@@ -175,7 +175,7 @@ describe("connectTools", () => {
   });
 
   it("returns malformed connected-tool arguments to the model", async () => {
-    const executor = connectTools([calculatorTool], "test-model");
+    const executor = createToolsExecutor("test-model", [calculatorTool]);
     let retryRequest: Program | undefined;
     let invocations = 0;
     const ctx = buildCtx({
@@ -198,9 +198,11 @@ describe("connectTools", () => {
 
     expect(invocations).toBe(2);
     expect(
-      viewProgram(retryRequest!).messages.at(-1)?.toolResult?.text,
-    ).toBe('Tool "calculator" failed: Tool "calculator" received invalid JSON object arguments');
-    expect(callData(result)).toHaveLength(0);
+      new ProgramView(retryRequest!).messages.at(-1)?.toolResult?.text,
+    ).toBe(
+      'Tool "calculator" failed: Tool "calculator" received invalid JSON object arguments',
+    );
+    expect(extractToolCalls(result)).toHaveLength(0);
   });
 
   it("returns thrown connected-tool errors to the model", async () => {
@@ -210,7 +212,7 @@ describe("connectTools", () => {
         throw new Error("Calculator service is unavailable");
       },
     };
-    const executor = connectTools([failingTool], "test-model");
+    const executor = createToolsExecutor("test-model", [failingTool]);
     let retryRequest: Program | undefined;
     let invocations = 0;
     const ctx = buildCtx({
@@ -233,7 +235,7 @@ describe("connectTools", () => {
 
     expect(invocations).toBe(2);
     expect(
-      viewProgram(retryRequest!).messages.at(-1)?.toolResult?.text,
+      new ProgramView(retryRequest!).messages.at(-1)?.toolResult?.text,
     ).toBe('Tool "calculator" failed: Calculator service is unavailable');
   });
 
@@ -249,7 +251,7 @@ describe("connectTools", () => {
         return `value_of_${key}`;
       },
     };
-    const executor = connectTools([multiTool], "test-model");
+    const executor = createToolsExecutor("test-model", [multiTool]);
 
     let callCount = 0;
     const request = createProgram();
@@ -276,7 +278,7 @@ describe("connectTools", () => {
   });
 
   it("returns immediately when outer (non-connected) tool calls are present", async () => {
-    const executor = connectTools([calculatorTool], "test-model");
+    const executor = createToolsExecutor("test-model", [calculatorTool]);
 
     const request = createProgram();
     const ctx = buildCtx({
@@ -298,17 +300,17 @@ describe("connectTools", () => {
         return calculatorTool.execute(args, ctx);
       },
     };
-    const guardedExecutor = connectTools([tool], "test-model");
+    const guardedExecutor = createToolsExecutor("test-model", [tool]);
     const result = await guardedExecutor.execute(request, ctx);
 
-    const calls = callData(result);
+    const calls = extractToolCalls(result);
     expect(calls).toHaveLength(2);
     expect(calls.some((c) => c.name === "external_tool")).toBe(true);
     expect(executions).toBe(0);
   });
 
   it("respects maxIterations", async () => {
-    const executor = connectTools([calculatorTool], "test-model", {
+    const executor = createToolsExecutor("test-model", [calculatorTool], {
       maxIterations: 2,
     });
 
@@ -336,7 +338,7 @@ describe("connectTools", () => {
   });
 
   it("streams final response after tool loop completes", async () => {
-    const executor = connectTools([calculatorTool], "test-model");
+    const executor = createToolsExecutor("test-model", [calculatorTool]);
 
     let callCount = 0;
     const request = createProgram();
@@ -395,7 +397,7 @@ describe("connectTools", () => {
         return "4";
       },
     };
-    const executor = connectTools([tool], "test-model");
+    const executor = createToolsExecutor("test-model", [tool]);
     let invocation = 0;
     const ctx = buildCtx({
       async invoke() {

package/etc/api/synthetic.api.md

@@ -1,46 +0,0 @@
-## 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/types.api.md

@@ -1,103 +0,0 @@
-## 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)
-
-```

package/src/synthetic/index.ts

@@ -1,134 +0,0 @@
-import {
-  addTool,
-  appendInstructions,
-  createProgram,
-  insertBefore,
-  messages,
-  Opcode,
-  setModel,
-  type Instruction,
-  type Opcode as OpcodeValue,
-  type Program,
-} from "@neutrome/lil-engine";
-
-const encoder = new TextEncoder();
-
-export type TextMessageRole = "system" | "user" | "assistant";
-
-export type ToolInteraction = {
-  callId: string;
-  name: string;
-  args?: unknown;
-  result: unknown;
-};
-
-export function createModelProgram(model: string): Program {
-  return setModel(createProgram(), model);
-}
-
-export function makeMessage(role: TextMessageRole, text: string): Program {
-  return createProgram({ code: buildMessage(role, text) });
-}
-
-export function prependSystemPrompt(program: Program, text: string): Program {
-  const systemMessage = buildMessage("system", text);
-  const spans = messages(program);
-  if (spans.length === 0) {
-    return appendInstructions(program, systemMessage);
-  }
-  const firstSpan = spans[0];
-  if (!firstSpan) return appendInstructions(program, systemMessage);
-  return insertBefore(program, firstSpan.start, systemMessage);
-}
-
-export function appendUserMessage(program: Program, text: string): Program {
-  return appendInstructions(program, buildMessage("user", text));
-}
-
-export function appendAssistantMessage(
-  program: Program,
-  text: string,
-): Program {
-  return appendInstructions(program, buildMessage("assistant", text));
-}
-
-export function makeToolCall(
-  name: string,
-  args: unknown = {},
-  callId: string = crypto.randomUUID(),
-): Program {
-  return createProgram({
-    code: [
-      { opcode: Opcode.MSG_START, value: { kind: "none" } },
-      { opcode: Opcode.ROLE_AST, value: { kind: "none" } },
-      { opcode: Opcode.CALL_START, value: { kind: "string", value: callId } },
-      { opcode: Opcode.CALL_NAME, value: { kind: "string", value: name } },
-      {
-        opcode: Opcode.CALL_ARGS,
-        value: { kind: "json", value: encodeJson(args) },
-      },
-      { opcode: Opcode.CALL_END, value: { kind: "none" } },
-      { opcode: Opcode.MSG_END, value: { kind: "none" } },
-    ],
-  });
-}
-
-export function makeToolResponse(callId: string, result: unknown): Program {
-  return createProgram({ code: buildToolResponse(callId, result) });
-}
-
-export function appendToolInteraction(
-  program: Program,
-  interaction: ToolInteraction,
-): Program {
-  return appendInstructions(program, [
-    ...makeToolCall(
-      interaction.name,
-      interaction.args ?? {},
-      interaction.callId,
-    ).code,
-    ...buildToolResponse(interaction.callId, interaction.result),
-  ]);
-}
-
-function buildMessage(role: TextMessageRole, text: string): Instruction[] {
-  return [
-    { opcode: Opcode.MSG_START, value: { kind: "none" } },
-    { opcode: roleOpcode(role), value: { kind: "none" } },
-    { opcode: Opcode.TXT_CHUNK, value: { kind: "string", value: text } },
-    { opcode: Opcode.MSG_END, value: { kind: "none" } },
-  ];
-}
-
-function buildToolResponse(callId: string, result: unknown): Instruction[] {
-  return [
-    { opcode: Opcode.MSG_START, value: { kind: "none" } },
-    { opcode: Opcode.ROLE_TOOL, value: { kind: "none" } },
-    { opcode: Opcode.RESULT_START, value: { kind: "string", value: callId } },
-    {
-      opcode: Opcode.RESULT_DATA,
-      value: { kind: "string", value: stringifyResult(result) },
-    },
-    { opcode: Opcode.RESULT_END, value: { kind: "none" } },
-    { opcode: Opcode.MSG_END, value: { kind: "none" } },
-  ];
-}
-
-function roleOpcode(role: TextMessageRole): OpcodeValue {
-  switch (role) {
-    case "system":
-      return Opcode.ROLE_SYS;
-    case "user":
-      return Opcode.ROLE_USR;
-    case "assistant":
-      return Opcode.ROLE_AST;
-  }
-}
-
-function encodeJson(value: unknown): Uint8Array {
-  return encoder.encode(JSON.stringify(value));
-}
-
-function stringifyResult(result: unknown): string {
-  return typeof result === "string" ? result : JSON.stringify(result);
-}