@neutrome/lilsdk-ts 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# `@neutrome/lilsdk-ts`
+
+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";
+```
+
+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`

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@neutrome/lilsdk-ts",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@neutrome/lil-engine": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  }
+}

package/src/execution.ts

@@ -0,0 +1,64 @@
+import { setModel, setStreaming, type Program } from "@neutrome/lil-engine";
+import type { ExecuteModelOptions, ModelRuntime, OutputSink, StreamModelOptions } from "./types.ts";
+
+export async function executeWithModel(
+  request: Program,
+  runtime: ModelRuntime,
+  model: string,
+  options?: ExecuteModelOptions,
+): Promise<Program> {
+  return runtime.execute(setStreaming(setModel(request, model), false), options);
+}
+
+export async function pipeProgramStream(
+  source: AsyncIterable<Program>,
+  sink: OutputSink,
+): Promise<void> {
+  for await (const chunk of source) {
+    await sink.write(chunk);
+  }
+}
+
+export async function streamWithModel(
+  request: Program,
+  runtime: ModelRuntime,
+  sink: OutputSink,
+  model: string,
+  options: StreamModelOptions = {},
+): Promise<void> {
+  const { close = true, ...invokeOptions } = options;
+  await pipeProgramStream(
+    runtime.stream(setStreaming(setModel(request, model), true), invokeOptions),
+    sink,
+  );
+  if (options?.close !== false) {
+    await sink.close();
+  }
+}
+
+export function passthroughPrograms(
+  programs: Iterable<Program> | AsyncIterable<Program>,
+  sink: OutputSink,
+  options: { close?: boolean } = {},
+): Promise<void> {
+  return passthroughProgramsInternal(programs, sink, options);
+}
+
+async function passthroughProgramsInternal(
+  programs: Iterable<Program> | AsyncIterable<Program>,
+  sink: OutputSink,
+  options: { close?: boolean },
+): Promise<void> {
+  if (Symbol.asyncIterator in Object(programs)) {
+    for await (const chunk of programs as AsyncIterable<Program>) {
+      await sink.write(chunk);
+    }
+  } else {
+    for (const chunk of programs as Iterable<Program>) {
+      await sink.write(chunk);
+    }
+  }
+  if (options?.close !== false) {
+    await sink.close();
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+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";

package/src/observe.ts

@@ -0,0 +1,2 @@
+export { observeExecutionStream } from "@neutrome/lil-engine";
+export type { ObservedExecution, StreamObservationHooks } from "@neutrome/lil-engine";

package/src/output.ts

@@ -0,0 +1,10 @@
+import { createProgram, Opcode } from "@neutrome/lil-engine";
+import type { OutputSink } from "./types.ts";
+
+export async function writeReasoning(sink: OutputSink, text: string): Promise<void> {
+  await sink.write(createProgram({
+    code: [
+      { opcode: Opcode.STREAM_THINK_DELTA, value: { kind: "string", value: text } },
+    ],
+  }));
+}

package/src/request.ts

@@ -0,0 +1,21 @@
+import { appendToolExchange, type Program } from "@neutrome/lil-engine";
+
+export type SyntheticToolExchange = {
+  callId: string;
+  name: string;
+  args: string;
+  result: string;
+};
+
+export function appendSyntheticToolExchange(
+  request: Program,
+  exchange: SyntheticToolExchange,
+): Program {
+  return appendToolExchange(
+    request,
+    exchange.callId,
+    exchange.name,
+    exchange.args,
+    exchange.result,
+  );
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+import type { Program } from "@neutrome/lil-engine";
+import type { ExecutionRuntime, InvokeOptions } from "@neutrome/lil-engine";
+
+export type ModelRuntime = Pick<ExecutionRuntime, "execute" | "stream">;
+
+export type OutputSink = {
+  write(chunk: Program): void | Promise<void>;
+  close(): void | Promise<void>;
+};
+
+export type ExecuteModelOptions = InvokeOptions;
+
+export type StreamModelOptions = InvokeOptions & {
+  close?: boolean;
+};
+
+export type ModelHandler = {
+  execute(
+    request: Program,
+    runtime: ModelRuntime,
+    options?: ExecuteModelOptions,
+  ): Promise<Program>;
+  stream(
+    request: Program,
+    runtime: ModelRuntime,
+    sink: OutputSink,
+    options?: StreamModelOptions,
+  ): Promise<void>;
+};

package/test/lilsdk-ts.test.ts

@@ -0,0 +1,185 @@
+import {
+  appendAssistantMessage,
+  contentText,
+  emitChatCompletionsRequest,
+  emitChatCompletionsStreamChunk,
+  getModel,
+  isStreaming,
+  parseChatCompletionsRequest,
+  parseChatCompletionsStreamChunk,
+  prependSystemPrompt,
+  type Program,
+} from "@neutrome/lil-engine";
+import { describe, expect, it } from "vitest";
+import {
+  appendSyntheticToolExchange,
+  executeWithModel,
+  observeExecutionStream,
+  passthroughPrograms,
+  streamWithModel,
+  writeReasoning,
+  type ModelRuntime,
+  type OutputSink,
+} from "../src/index.ts";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+describe("@neutrome/lilsdk-ts", () => {
+  it("observes tool-call streams and supports passthrough", async () => {
+    const observed = await observeExecutionStream((async function* () {
+      yield parseChatCompletionsStreamChunk(encoder.encode(JSON.stringify({
+        id: "tool-stream",
+        object: "chat.completion.chunk",
+        model: "smart",
+        choices: [{ index: 0, delta: { role: "assistant" } }],
+      })));
+      yield parseChatCompletionsStreamChunk(encoder.encode(JSON.stringify({
+        id: "tool-stream",
+        object: "chat.completion.chunk",
+        model: "smart",
+        choices: [{
+          index: 0,
+          delta: {
+            tool_calls: [{
+              index: 0,
+              id: "call_lookup",
+              type: "function",
+              function: { name: "lookup", arguments: "{\"q\":\"kyiv\"}" },
+            }],
+          },
+        }],
+      })));
+      yield parseChatCompletionsStreamChunk(encoder.encode(JSON.stringify({
+        id: "tool-stream",
+        object: "chat.completion.chunk",
+        model: "smart",
+        choices: [{ index: 0, delta: {}, finish_reason: "tool_calls" }],
+      })));
+    })());
+
+    expect(observed.mode).toBe("tool");
+    if (observed.mode !== "tool") {
+      throw new Error("expected tool mode");
+    }
+
+    const emitted: string[] = [];
+    const sink: OutputSink = {
+      write(chunk) {
+        emitted.push(decoder.decode(emitChatCompletionsStreamChunk(chunk)));
+      },
+      close() {
+        emitted.push("[DONE]");
+      },
+    };
+
+    await passthroughPrograms(observed.chunks, sink);
+
+    expect(emitted.at(-1)).toBe("[DONE]");
+    const parsed = emitted.slice(0, -1).map((chunk) => JSON.parse(chunk));
+    expect(parsed.some((chunk) => chunk.choices?.[0]?.delta?.tool_calls)).toBe(true);
+  });
+
+  it("appends synthetic tool exchanges to a request program", () => {
+    const request = parseChatCompletionsRequest(encoder.encode(JSON.stringify({
+      model: "virtual-model",
+      messages: [{ role: "user", content: "hello" }],
+    })));
+
+    const updated = appendSyntheticToolExchange(request, {
+      callId: "knowledge_0",
+      name: "knowledge",
+      args: "{\"question\":\"thinking\"}",
+      result: "draft answer",
+    });
+
+    const emitted = JSON.parse(decoder.decode(emitChatCompletionsRequest(updated)));
+    expect(emitted.messages).toHaveLength(3);
+    expect(emitted.messages[1].tool_calls[0].function.name).toBe("knowledge");
+    expect(emitted.messages[2].tool_call_id).toBe("knowledge_0");
+    expect(JSON.parse(decoder.decode(emitChatCompletionsRequest(request))).messages).toHaveLength(1);
+  });
+
+  it("supports chained model execution across multiple passes", async () => {
+    const calls: Array<{ model: string; streaming: boolean }> = [];
+    const runtime: ModelRuntime = {
+      async execute(request) {
+        calls.push({ model: getModel(request) ?? "", streaming: isStreaming(request) });
+        if (calls.length === 1) {
+          return appendAssistantMessage({ code: [], buffers: [] }, "draft answer");
+        }
+        return appendAssistantMessage({ code: [], buffers: [] }, "final answer");
+      },
+      async *stream(): AsyncIterable<Program> {
+        throw new Error("streaming path is not used in this test");
+      },
+    };
+
+    const request = parseChatCompletionsRequest(encoder.encode(JSON.stringify({
+      model: "virtual-model",
+      messages: [{ role: "user", content: "hello" }],
+    })));
+    const first = await executeWithModel(request, runtime, "smart-model");
+    const draft = contentText(first);
+
+    let secondRequest = appendSyntheticToolExchange(request, {
+      callId: "knowledge_0",
+      name: "knowledge",
+      args: "{\"question\":\"thinking\"}",
+      result: draft,
+    });
+    secondRequest = prependSystemPrompt(secondRequest, "system prompt");
+
+    const second = await executeWithModel(secondRequest, runtime, "base-model");
+
+    expect(calls).toEqual([
+      { model: "smart-model", streaming: false },
+      { model: "base-model", streaming: false },
+    ]);
+    expect(contentText(second)).toBe("final answer");
+    expect(getModel(request)).toBe("virtual-model");
+  });
+
+  it("streams model output through a sink and writes reasoning helpers", async () => {
+    const request = parseChatCompletionsRequest(encoder.encode(JSON.stringify({
+      model: "virtual-model",
+      messages: [{ role: "user", content: "hello" }],
+    })));
+    const emitted: string[] = [];
+    const sink: OutputSink = {
+      write(chunk) {
+        emitted.push(decoder.decode(emitChatCompletionsStreamChunk(chunk)));
+      },
+      close() {
+        emitted.push("[DONE]");
+      },
+    };
+
+    const runtime: ModelRuntime = {
+      async execute() {
+        throw new Error("non-streaming path is not used in this test");
+      },
+      async *stream(program) {
+        expect(getModel(program)).toBe("base-model");
+        expect(isStreaming(program)).toBe(true);
+        yield parseChatCompletionsStreamChunk(encoder.encode(JSON.stringify({
+          id: "stream-response",
+          model: "base-model",
+          choices: [{ index: 0, delta: { content: "hello" } }],
+        })));
+        yield parseChatCompletionsStreamChunk(encoder.encode(JSON.stringify({
+          id: "stream-response",
+          model: "base-model",
+          choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
+        })));
+      },
+    };
+
+    await writeReasoning(sink, "thinking");
+    await streamWithModel(request, runtime, sink, "base-model");
+
+    expect(emitted.at(-1)).toBe("[DONE]");
+    expect(JSON.parse(emitted[0]!).choices[0].delta.reasoning_content).toBe("thinking");
+    expect(JSON.parse(emitted[1]!).choices[0].delta.content).toBe("hello");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["node", "vitest/globals"],
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/vitest.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({});