feat(kernel-language-model-service): Add language model client

packages/kernel-language-model-service/package.json

@@ -104,6 +104,7 @@
     "node": ">=22"
   },
   "dependencies": {
+    "@endo/eventual-send": "^1.3.4",
     "@metamask/superstruct": "^3.2.1",
     "ollama": "^0.5.16",
     "ses": "^1.14.0"

packages/kernel-language-model-service/src/client.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import { makeChatClient, makeSampleClient } from './client.ts';
+import type { ChatResult, SampleResult } from './types.ts';
+
+const MODEL = 'glm-4.7-flash';
+
+vi.mock('@endo/eventual-send', () => ({
+  E: vi.fn((obj: unknown) => obj),
+}));
+
+const makeChatResult = (): ChatResult => ({
+  id: 'chat-1',
+  model: MODEL,
+  choices: [
+    {
+      message: { role: 'assistant', content: 'hello' },
+      index: 0,
+      finish_reason: 'stop',
+    },
+  ],
+  usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+});
+
+const makeSampleResult = (): SampleResult => ({ text: 'hi there' });
+
+describe('makeChatClient', () => {
+  it('calls chat on the lmsRef with merged model', async () => {
+    const chatResult = makeChatResult();
+    const lmsRef = { chat: vi.fn().mockResolvedValue(chatResult) };
+
+    const client = makeChatClient(lmsRef, MODEL);
+    const result = await client.chat.completions.create({
+      messages: [{ role: 'user', content: 'hello' }],
+    });
+
+    expect(lmsRef.chat).toHaveBeenCalledWith(
+      expect.objectContaining({
+        model: MODEL,
+        messages: [{ role: 'user', content: 'hello' }],
+      }),
+    );
+    expect(result).toStrictEqual(chatResult);
+  });
+
+  it('params.model overrides defaultModel', async () => {
+    const lmsRef = { chat: vi.fn().mockResolvedValue(makeChatResult()) };
+    const client = makeChatClient(lmsRef, 'gpt-3.5');
+
+    await client.chat.completions.create({
+      messages: [{ role: 'user', content: 'hi' }],
+      model: MODEL,
+    });
+
+    expect(lmsRef.chat).toHaveBeenCalledWith(
+      expect.objectContaining({ model: MODEL }),
+    );
+  });
+
+  it('throws when no model is available', async () => {
+    const lmsRef = { chat: vi.fn() };
+    const client = makeChatClient(lmsRef);
+
+    await expect(
+      client.chat.completions.create({
+        messages: [{ role: 'user', content: 'hi' }],
+      }),
+    ).rejects.toThrow('model is required');
+  });
+});
+
+describe('makeSampleClient', () => {
+  it('calls sample on the lmsRef with merged model', async () => {
+    const rawResult = makeSampleResult();
+    const lmsRef = { sample: vi.fn().mockResolvedValue(rawResult) };
+
+    const client = makeSampleClient(lmsRef, 'llama3');
+    const result = await client.sample({ prompt: 'Once upon' });
+
+    expect(lmsRef.sample).toHaveBeenCalledWith(
+      expect.objectContaining({ model: 'llama3', prompt: 'Once upon' }),
+    );
+    expect(result).toStrictEqual(rawResult);
+  });
+
+  it('params.model overrides defaultModel', async () => {
+    const lmsRef = {
+      sample: vi.fn().mockResolvedValue(makeSampleResult()),
+    };
+    const client = makeSampleClient(lmsRef, 'llama3');
+
+    await client.sample({ prompt: 'hi', model: 'mistral' });
+
+    expect(lmsRef.sample).toHaveBeenCalledWith(
+      expect.objectContaining({ model: 'mistral' }),
+    );
+  });
+
+  it('throws when no model is available', async () => {
+    const lmsRef = { sample: vi.fn() };
+    const client = makeSampleClient(lmsRef);
+
+    await expect(client.sample({ prompt: 'hi' })).rejects.toThrow(
+      'model is required',
+    );
+  });
+});

packages/kernel-language-model-service/src/client.ts

@@ -0,0 +1,85 @@
+import { E } from '@endo/eventual-send';
+import type { ERef } from '@endo/eventual-send';
+
+import type {
+  ChatParams,
+  ChatResult,
+  ChatService,
+  SampleParams,
+  SampleResult,
+  SampleService,
+} from './types.ts';
+
+/**
+ * Wraps a remote service reference with Open /v1-style chat completion ergonomics.
+ *
+ * Usage:
+ * ```ts
+ * const client = makeChatClient(lmsRef, 'gpt-4o');
+ * const result = await client.chat.completions.create({ messages });
+ * ```
+ *
+ * @param lmsRef - Reference to a service with a `chat` method.
+ * @param defaultModel - Default model name used when params do not specify one.
+ * @returns A client object with `chat.completions.create`.
+ */
+export const makeChatClient = (
+  lmsRef: ERef<ChatService>,
+  defaultModel?: string,
+): {
+  chat: {
+    completions: {
+      create: (
+        params: Omit<ChatParams, 'model'> & { model?: string },
+      ) => Promise<ChatResult>;
+    };
+  };
+} =>
+  harden({
+    chat: harden({
+      completions: harden({
+        async create(
+          params: Omit<ChatParams, 'model'> & { model?: string },
+        ): Promise<ChatResult> {
+          const model = params.model ?? defaultModel;
+          if (!model) {
+            throw new Error('model is required');
+          }
+          return E(lmsRef).chat(harden({ ...params, model }));
+        },
+      }),
+    }),
+  });
+
+/**
+ * Wraps a remote service reference with raw token-prediction ergonomics.
+ *
+ * Usage:
+ * ```ts
+ * const client = makeSampleClient(lmsRef, 'llama3');
+ * const result = await client.sample({ prompt: 'Once upon' });
+ * ```
+ *
+ * @param lmsRef - Reference to a service with a `sample` method.
+ * @param defaultModel - Default model name used when params do not specify one.
+ * @returns A client object with `sample`.
+ */
+export const makeSampleClient = (
+  lmsRef: ERef<SampleService>,
+  defaultModel?: string,
+): {
+  sample: (
+    params: Omit<SampleParams, 'model'> & { model?: string },
+  ) => Promise<SampleResult>;
+} =>
+  harden({
+    async sample(
+      params: Omit<SampleParams, 'model'> & { model?: string },
+    ): Promise<SampleResult> {
+      const model = params.model ?? defaultModel;
+      if (!model) {
+        throw new Error('model is required');
+      }
+      return E(lmsRef).sample(harden({ ...params, model }));
+    },
+  });

packages/kernel-language-model-service/src/index.ts

@@ -1 +1,7 @@
 export type * from './types.ts';
+export {
+  LANGUAGE_MODEL_SERVICE_NAME,
+  makeKernelLanguageModelService,
+} from './kernel-service.ts';
+export { makeOpenV1NodejsService } from './open-v1/nodejs.ts';
+export { makeChatClient, makeSampleClient } from './client.ts';

packages/kernel-language-model-service/src/kernel-service.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import {
+  LANGUAGE_MODEL_SERVICE_NAME,
+  makeKernelLanguageModelService,
+} from './kernel-service.ts';
+import type {
+  ChatParams,
+  ChatResult,
+  SampleParams,
+  SampleResult,
+} from './types.ts';
+
+const makeChatResult = (): ChatResult => ({
+  id: 'chat-1',
+  model: 'test-model',
+  choices: [
+    {
+      message: { role: 'assistant', content: 'hi' },
+      index: 0,
+      finish_reason: 'stop',
+    },
+  ],
+  usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+});
+
+const makeSampleResult = (): SampleResult => ({ text: 'hello' });
+
+describe('LANGUAGE_MODEL_SERVICE_NAME', () => {
+  it('equals languageModelService', () => {
+    expect(LANGUAGE_MODEL_SERVICE_NAME).toBe('languageModelService');
+  });
+});
+
+describe('makeKernelLanguageModelService', () => {
+  it('returns object with correct name and a service', () => {
+    const chat = vi.fn();
+    const result = makeKernelLanguageModelService(chat);
+    expect(result).toMatchObject({
+      name: LANGUAGE_MODEL_SERVICE_NAME,
+      service: expect.any(Object),
+    });
+  });
+
+  it('service has chat and sample methods', () => {
+    const chat = vi.fn();
+    const { service } = makeKernelLanguageModelService(chat);
+    expect(service).toMatchObject({
+      chat: expect.any(Function),
+      sample: expect.any(Function),
+    });
+  });
+
+  it('chat delegates to underlying function and returns hardened result', async () => {
+    const chatResult = makeChatResult();
+    const chat = vi.fn().mockResolvedValue(chatResult);
+    const { service } = makeKernelLanguageModelService(chat);
+
+    const params: ChatParams = {
+      model: 'test',
+      messages: [{ role: 'user', content: 'hi' }],
+    };
+    const result = await (
+      service as { chat: (p: ChatParams) => Promise<ChatResult> }
+    ).chat(params);
+
+    expect(chat).toHaveBeenCalledWith(params);
+    expect(result).toStrictEqual(chatResult);
+  });
+
+  it('sample delegates to provided function and returns hardened result', async () => {
+    const rawResult = makeSampleResult();
+    const chat = vi.fn();
+    const sample = vi.fn().mockResolvedValue(rawResult);
+    const { service } = makeKernelLanguageModelService(chat, sample);
+
+    const params: SampleParams = { model: 'test', prompt: 'hello' };
+    const result = await (
+      service as {
+        sample: (p: SampleParams) => Promise<SampleResult>;
+      }
+    ).sample(params);
+
+    expect(sample).toHaveBeenCalledWith(params);
+    expect(result).toStrictEqual(rawResult);
+  });
+
+  it('sample throws when no sample function provided', async () => {
+    const chat = vi.fn();
+    const { service } = makeKernelLanguageModelService(chat);
+
+    await expect(
+      (
+        service as {
+          sample: (p: SampleParams) => Promise<SampleResult>;
+        }
+      ).sample({ model: 'test', prompt: 'hello' }),
+    ).rejects.toThrow('raw sampling not supported by this backend');
+  });
+});

packages/kernel-language-model-service/src/kernel-service.ts

@@ -0,0 +1,41 @@
+import type {
+  ChatParams,
+  ChatResult,
+  SampleParams,
+  SampleResult,
+} from './types.ts';
+
+/**
+ * Canonical service name for the language model service in `ClusterConfig.services`.
+ */
+export const LANGUAGE_MODEL_SERVICE_NAME = 'languageModelService';
+
+/**
+ * Wraps `chat` and optional `sample` functions into a flat, stateless kernel service object.
+ * Use the returned `{ name, service }` with `kernel.registerKernelServiceObject(name, service)`.
+ *
+ * Return values are plain hardened data — no exos — so they are safely serializable
+ * across the kernel marshal boundary.
+ *
+ * @param chat - Function that performs a chat completion request.
+ * @param sample - Optional function that performs a raw token-prediction request.
+ *   If not provided, `service.sample()` throws "raw sampling not supported by this backend".
+ * @returns An object with `name` and `service` fields for use with the kernel.
+ */
+export const makeKernelLanguageModelService = (
+  chat: (params: ChatParams & { stream?: true & false }) => Promise<ChatResult>,
+  sample?: (params: SampleParams) => Promise<SampleResult>,
+): { name: string; service: object } => {
+  const service = harden({
+    async chat(params: ChatParams): Promise<ChatResult> {
+      return harden(await chat(params as ChatParams & { stream?: never }));
+    },
+    async sample(params: SampleParams): Promise<SampleResult> {
+      if (!sample) {
+        throw new Error('raw sampling not supported by this backend');
+      }
+      return harden(await sample(params));
+    },
+  });
+  return harden({ name: LANGUAGE_MODEL_SERVICE_NAME, service });
+};