@fgv/ts-extras-ollama 5.1.0-34

package/src/test/unit/chatStructured.test.ts

@@ -0,0 +1,330 @@
+import '@fgv/ts-utils-jest';
+import { succeed } from '@fgv/ts-utils';
+import { JsonSchema, type JsonObject } from '@fgv/ts-json-base';
+import { type IOllamaChatMessage, type IOllamaClient, chatStructured, createOllamaClient } from '../../index';
+
+const personSchema = JsonSchema.object({
+  name: JsonSchema.string(),
+  age: JsonSchema.integer()
+});
+type Person = JsonSchema.Static<typeof personSchema>;
+
+/** A streaming `/api/chat` chunk in the upstream `ChatResponse` shape (the fields we consume). */
+interface IChatChunk {
+  model: string;
+  message: { role: string; content: string };
+  done: boolean;
+  done_reason?: string;
+}
+
+/**
+ * Builds a structural mock of the upstream `AbortableAsyncIterator<ChatResponse>` returned by
+ * `client.chat({ stream: true })`. `abort()` flips a flag the generator checks before each chunk.
+ */
+function makeChatIterator(
+  chunks: ReadonlyArray<IChatChunk>
+): { abort: jest.Mock } & AsyncIterable<IChatChunk> {
+  let aborted = false;
+  return {
+    abort: jest.fn(() => {
+      aborted = true;
+    }),
+    async *[Symbol.asyncIterator](): AsyncGenerator<IChatChunk> {
+      for (const chunk of chunks) {
+        if (aborted) {
+          throw new Error('The operation was aborted');
+        }
+        yield chunk;
+      }
+    }
+  };
+}
+
+/**
+ * Like {@link makeChatIterator}, but yields control (a real timer) after each chunk so a signal
+ * aborted *after* the listener is attached lands mid-stream — exercising the abort-listener path
+ * (vs. the already-aborted branch).
+ */
+function makeDelayedChatIterator(
+  chunks: ReadonlyArray<IChatChunk>
+): { abort: jest.Mock } & AsyncIterable<IChatChunk> {
+  let aborted = false;
+  return {
+    abort: jest.fn(() => {
+      aborted = true;
+    }),
+    async *[Symbol.asyncIterator](): AsyncGenerator<IChatChunk> {
+      for (const chunk of chunks) {
+        if (aborted) {
+          throw new Error('The operation was aborted');
+        }
+        yield chunk;
+        await new Promise<void>((resolve) => setTimeout(resolve, 30));
+      }
+    }
+  };
+}
+
+function mockChatClient(chat: unknown): IOllamaClient {
+  return { chat } as unknown as IOllamaClient;
+}
+
+/** Chunks whose assembled `message.content` is `{"name":"ada","age":42}`. */
+function validPersonChunks(model: string = 'llama3.1:8b'): IChatChunk[] {
+  return [
+    { model, message: { role: 'assistant', content: '{"name":"ada",' }, done: false },
+    { model, message: { role: 'assistant', content: '"age":42}' }, done: false },
+    { model, message: { role: 'assistant', content: '' }, done: true, done_reason: 'stop' }
+  ];
+}
+
+const userTurn: ReadonlyArray<IOllamaChatMessage> = [{ role: 'user', content: 'Describe Ada.' }];
+
+describe('chatStructured (layer 1 — structural client mock)', () => {
+  test('validates the assembled document against the same schema sent on the wire', async () => {
+    const chat = jest.fn().mockResolvedValue(makeChatIterator(validPersonChunks()));
+    const client = mockChatClient(chat);
+
+    expect(
+      await chatStructured(client, { model: 'llama3.1:8b', messages: userTurn, schema: personSchema })
+    ).toSucceedAndSatisfy((result) => {
+      const value: Person = result.value;
+      expect(value).toEqual({ name: 'ada', age: 42 });
+      expect(result.raw).toBe('{"name":"ada","age":42}');
+      expect(result.model).toBe('llama3.1:8b');
+      expect(result.doneReason).toBe('stop');
+    });
+
+    // The wire request: streaming, messages mapped, and the sanitized schema as `format`.
+    const request = chat.mock.calls[0][0] as JsonObject;
+    expect(request.stream).toBe(true);
+    expect(request.messages).toEqual([{ role: 'user', content: 'Describe Ada.' }]);
+    const format = request.format as JsonObject;
+    expect(format.type).toBe('object');
+    expect(format.properties).toEqual({ name: { type: 'string' }, age: { type: 'integer' } });
+    expect(format.required).toEqual(['name', 'age']);
+    // Draft-07-only keywords are stripped before hitting Ollama's `format`.
+    expect(format).not.toHaveProperty('additionalProperties');
+    expect(format).not.toHaveProperty('$schema');
+    // No options / keep_alive were supplied.
+    expect(request).not.toHaveProperty('options');
+    expect(request).not.toHaveProperty('keep_alive');
+  });
+
+  test('forwards options, keep_alive, and base64 images verbatim', async () => {
+    const chat = jest.fn().mockResolvedValue(makeChatIterator(validPersonChunks()));
+    const client = mockChatClient(chat);
+    const messages: ReadonlyArray<IOllamaChatMessage> = [
+      { role: 'system', content: 'Be terse.' },
+      { role: 'user', content: 'Look', images: ['aGVsbG8='] }
+    ];
+
+    expect(
+      await chatStructured(client, {
+        model: 'llama3.1:8b',
+        messages,
+        schema: personSchema,
+        options: { temperature: 0, seed: 7 },
+        keepAlive: '5m'
+      })
+    ).toSucceed();
+
+    const request = chat.mock.calls[0][0] as JsonObject;
+    expect(request.options).toEqual({ temperature: 0, seed: 7 });
+    expect(request.keep_alive).toBe('5m');
+    expect(request.messages).toEqual([
+      { role: 'system', content: 'Be terse.' },
+      { role: 'user', content: 'Look', images: ['aGVsbG8='] }
+    ]);
+  });
+
+  test('fails with context when the response parses but violates the schema', async () => {
+    const chunks: IChatChunk[] = [
+      {
+        model: 'llama3.1:8b',
+        message: { role: 'assistant', content: '{"name":"ada","age":"old"}' },
+        done: true
+      }
+    ];
+    const client = mockChatClient(jest.fn().mockResolvedValue(makeChatIterator(chunks)));
+
+    expect(
+      await chatStructured(client, { model: 'llama3.1:8b', messages: userTurn, schema: personSchema })
+    ).toFailWith(/chatStructured\(llama3\.1:8b\): response failed schema validation/i);
+  });
+
+  test('fails with context when the response is not valid JSON', async () => {
+    const chunks: IChatChunk[] = [
+      { model: 'llama3.1:8b', message: { role: 'assistant', content: 'not json at all' }, done: true }
+    ];
+    const client = mockChatClient(jest.fn().mockResolvedValue(makeChatIterator(chunks)));
+
+    expect(
+      await chatStructured(client, { model: 'llama3.1:8b', messages: userTurn, schema: personSchema })
+    ).toFailWith(/chatStructured\(llama3\.1:8b\): response was not valid JSON/i);
+  });
+
+  test('an already-aborted signal cancels the generation', async () => {
+    const iterator = makeChatIterator(validPersonChunks());
+    const client = mockChatClient(jest.fn().mockResolvedValue(iterator));
+    const controller = new AbortController();
+    controller.abort();
+
+    expect(
+      await chatStructured(client, {
+        model: 'llama3.1:8b',
+        messages: userTurn,
+        schema: personSchema,
+        signal: controller.signal
+      })
+    ).toFailWith(/abort/i);
+    expect(iterator.abort).toHaveBeenCalledTimes(1);
+  });
+
+  test('a mid-stream abort cancels the generation and removes the listener', async () => {
+    const iterator = makeDelayedChatIterator(validPersonChunks());
+    const client = mockChatClient(jest.fn().mockResolvedValue(iterator));
+    const controller = new AbortController();
+    const removeSpy = jest.spyOn(controller.signal, 'removeEventListener');
+
+    const promise = chatStructured(client, {
+      model: 'llama3.1:8b',
+      messages: userTurn,
+      schema: personSchema,
+      signal: controller.signal
+    });
+    // Let the request settle and the listener attach + first chunk land, then abort mid-stream so
+    // the abort fires through the listener (not the already-aborted branch).
+    await new Promise<void>((resolve) => setTimeout(resolve, 5));
+    controller.abort();
+
+    expect(await promise).toFailWith(/abort/i);
+    expect(iterator.abort).toHaveBeenCalled();
+    expect(removeSpy).toHaveBeenCalledWith('abort', expect.any(Function));
+  });
+
+  test('removes the abort listener after a successful completion', async () => {
+    const client = mockChatClient(jest.fn().mockResolvedValue(makeChatIterator(validPersonChunks())));
+    const controller = new AbortController();
+    const removeSpy = jest.spyOn(controller.signal, 'removeEventListener');
+
+    expect(
+      await chatStructured(client, {
+        model: 'llama3.1:8b',
+        messages: userTurn,
+        schema: personSchema,
+        signal: controller.signal
+      })
+    ).toSucceed();
+    expect(removeSpy).toHaveBeenCalledWith('abort', expect.any(Function));
+  });
+});
+
+describe('chatStructured — draft-07 format sanitizer', () => {
+  test('recursively strips $schema and additionalProperties while preserving property names and arrays', async () => {
+    // A schema double whose toJson() carries $schema, nested additionalProperties, an array, and a
+    // property *named* additionalProperties (which must survive — it is a name, not a keyword).
+    const rawSchema: JsonObject = {
+      $schema: 'http://json-schema.org/draft-07/schema#',
+      type: 'object',
+      properties: {
+        nested: {
+          type: 'object',
+          properties: { x: { type: 'string' } },
+          additionalProperties: false
+        },
+        additionalProperties: { type: 'string' }
+      },
+      required: ['nested'],
+      additionalProperties: false
+    };
+    const schemaDouble = {
+      _type: 'object',
+      toJson: () => rawSchema,
+      validate: (value: unknown) => succeed(value)
+    } as unknown as JsonSchema.ISchemaValidator<unknown>;
+
+    const chat = jest
+      .fn()
+      .mockResolvedValue(
+        makeChatIterator([
+          { model: 'm', message: { role: 'assistant', content: '{"nested":{"x":"y"}}' }, done: true }
+        ])
+      );
+    const client = mockChatClient(chat);
+
+    expect(
+      await chatStructured(client, { model: 'm', messages: userTurn, schema: schemaDouble })
+    ).toSucceed();
+
+    const format = (chat.mock.calls[0][0] as JsonObject).format as JsonObject;
+    expect(format).not.toHaveProperty('$schema');
+    expect(format).not.toHaveProperty('additionalProperties');
+    expect(format.required).toEqual(['nested']);
+    const properties = format.properties as JsonObject;
+    // The nested object's additionalProperties is stripped too.
+    expect(properties.nested).toEqual({ type: 'object', properties: { x: { type: 'string' } } });
+    // A property literally named `additionalProperties` is preserved (name, not keyword).
+    expect(properties.additionalProperties).toEqual({ type: 'string' });
+  });
+});
+
+/**
+ * Layer 2 — a real client over a mock `fetch` that streams a newline-delimited `/api/chat`
+ * response. Proves the no-drift claim end-to-end: the request body that actually goes on the wire
+ * carries `format` = the sanitized `schema.toJson()`, and the assembled reply validates.
+ */
+function ndjsonResponse(lines: ReadonlyArray<string>): Response {
+  const bytes = new TextEncoder().encode(lines.join('\n') + '\n');
+  const mid = Math.floor(bytes.length / 2);
+  const parts = [bytes.slice(0, mid), bytes.slice(mid)];
+  let i = 0;
+  const stream = new ReadableStream<Uint8Array>({
+    pull(controller: ReadableStreamDefaultController<Uint8Array>): void {
+      if (i < parts.length) {
+        controller.enqueue(parts[i++]);
+      } else {
+        controller.close();
+      }
+    }
+  });
+  return new Response(stream, { status: 200 });
+}
+
+describe('chatStructured (layer 2 — fetch-level wire-format integration)', () => {
+  test('sends the sanitized schema as the wire format and validates the assembled reply', async () => {
+    const lines = [
+      JSON.stringify({
+        model: 'llama3.1:8b',
+        message: { role: 'assistant', content: '{"name":"ada",' },
+        done: false
+      }),
+      JSON.stringify({
+        model: 'llama3.1:8b',
+        message: { role: 'assistant', content: '"age":42}' },
+        done: true,
+        done_reason: 'stop'
+      })
+    ];
+    const fetchMock = jest.fn().mockResolvedValue(ndjsonResponse(lines));
+    const client = createOllamaClient({ fetch: fetchMock as unknown as typeof fetch }).orThrow();
+
+    expect(
+      await chatStructured(client, { model: 'llama3.1:8b', messages: userTurn, schema: personSchema })
+    ).toSucceedAndSatisfy((result) => {
+      expect(result.value).toEqual({ name: 'ada', age: 42 });
+      expect(result.raw).toBe('{"name":"ada","age":42}');
+      expect(result.doneReason).toBe('stop');
+    });
+
+    // The actual wire body carries the sanitized schema as `format` — no-drift proven end-to-end.
+    const requestInit = fetchMock.mock.calls[0][1] as { body: string };
+    const body = JSON.parse(requestInit.body) as JsonObject;
+    expect(body.stream).toBe(true);
+    const format = body.format as JsonObject;
+    expect(format.type).toBe('object');
+    expect(format.properties).toEqual({ name: { type: 'string' }, age: { type: 'integer' } });
+    expect(format).not.toHaveProperty('additionalProperties');
+    expect(format).not.toHaveProperty('$schema');
+  });
+});

package/src/test/unit/fixtures/wireFixtures.ts

@@ -0,0 +1,95 @@
+import { type ListResponse, type ShowResponse } from 'ollama';
+
+/**
+ * Canned wire-shape fixtures for the layer-1 structural-client-mock tests.
+ *
+ * These mirror the actual JSON the Ollama daemon returns — snake_case keys and **string**
+ * timestamps. The upstream `ollama` types annotate `modified_at` / `expires_at` as `Date`, but the
+ * library returns `response.json()` verbatim so the wire delivers RFC3339 strings; each fixture is
+ * cast once (`as unknown as <Response>`) to reconcile the inaccurate upstream annotation with the
+ * real shape, so the normalization layer is exercised against the data it actually sees.
+ */
+
+/** `GET /api/tags` — one fully-detailed model plus one with sparse `details` (missing fields). */
+export const tagsResponse: ListResponse = {
+  models: [
+    {
+      name: 'llama3.1:8b',
+      model: 'llama3.1:8b',
+      modified_at: '2024-08-01T12:34:56.789Z',
+      size: 4661226402,
+      digest: 'sha256:abc123',
+      details: {
+        parent_model: '',
+        format: 'gguf',
+        family: 'llama',
+        families: ['llama'],
+        parameter_size: '8.0B',
+        quantization_level: 'Q4_0'
+      }
+    },
+    {
+      name: 'custom:latest',
+      model: 'custom:latest',
+      modified_at: '2024-09-15T08:00:00.000Z',
+      size: 1234567,
+      digest: 'sha256:def456',
+      // Sparse details — Ollama omits fields it cannot determine; exercises the optional-field path.
+      details: {
+        format: 'gguf',
+        family: 'llama'
+      }
+    }
+  ]
+} as unknown as ListResponse;
+
+/** `GET /api/ps` — a running model with `expires_at` + `size_vram` (no `modified_at`). */
+export const psResponse: ListResponse = {
+  models: [
+    {
+      name: 'llama3.1:8b',
+      model: 'llama3.1:8b',
+      size: 4661226402,
+      digest: 'sha256:abc123',
+      details: {
+        parent_model: '',
+        format: 'gguf',
+        family: 'llama',
+        families: ['llama'],
+        parameter_size: '8.0B',
+        quantization_level: 'Q4_0'
+      },
+      expires_at: '2024-08-01T13:00:00.000Z',
+      size_vram: 4661226402
+    }
+  ]
+} as unknown as ListResponse;
+
+/** `POST /api/show` — full response including the low-level `model_info` metadata bag. */
+export const showResponse: ShowResponse = {
+  modelfile: 'FROM llama3.1:8b',
+  parameters: 'stop "<|eot_id|>"',
+  template: '{{ .Prompt }}',
+  details: {
+    parent_model: '',
+    format: 'gguf',
+    family: 'llama',
+    families: ['llama'],
+    parameter_size: '8.0B',
+    quantization_level: 'Q4_0'
+  },
+  model_info: {
+    'general.architecture': 'llama',
+    'llama.context_length': 131072,
+    'llama.embedding_length': 4096
+  },
+  capabilities: ['completion', 'tools']
+} as unknown as ShowResponse;
+
+/** `POST /api/show` — a minimal response with `model_info` and `capabilities` omitted. */
+export const showResponseMinimal: ShowResponse = {
+  details: {
+    format: 'gguf',
+    family: 'llama'
+  }
+} as unknown as ShowResponse;

package/src/test/unit/modelManagement.test.ts

@@ -0,0 +1,128 @@
+import '@fgv/ts-utils-jest';
+import { type IOllamaClient, listModels, listRunning, showModel, deleteModel } from '../../index';
+import { psResponse, showResponse, showResponseMinimal, tagsResponse } from './fixtures/wireFixtures';
+
+/**
+ * Builds a structural client mock exposing only the methods under test, typed back to
+ * {@link IOllamaClient}. This is the layer-1 seam from the design (§7) — it verifies the wire→fgv
+ * mapping and Result success/failure paths without HTTP or the `ollama` lib internals.
+ */
+function mockClient(methods: Partial<Record<'list' | 'ps' | 'show' | 'delete', unknown>>): IOllamaClient {
+  return methods as unknown as IOllamaClient;
+}
+
+describe('listModels', () => {
+  test('normalizes /api/tags entries to camelCase with a parsed modifiedAt Date', async () => {
+    const client = mockClient({ list: jest.fn().mockResolvedValue(tagsResponse) });
+    expect(await listModels(client)).toSucceedAndSatisfy((models) => {
+      expect(models).toHaveLength(2);
+      const [full, sparse] = models;
+      expect(full.name).toBe('llama3.1:8b');
+      expect(full.size).toBe(4661226402);
+      expect(full.digest).toBe('sha256:abc123');
+      expect(full.modifiedAt).toBeInstanceOf(Date);
+      expect(full.modifiedAt.toISOString()).toBe('2024-08-01T12:34:56.789Z');
+      expect(full.details).toEqual({
+        parentModel: '',
+        format: 'gguf',
+        family: 'llama',
+        families: ['llama'],
+        parameterSize: '8.0B',
+        quantizationLevel: 'Q4_0'
+      });
+      // An empty `parent_model` is preserved as '' (present-and-empty, distinct from undefined).
+      expect(full.details.parentModel).toBe('');
+      // Sparse details: omitted wire fields normalize to undefined.
+      expect(sparse.details.format).toBe('gguf');
+      expect(sparse.details.parameterSize).toBeUndefined();
+      expect(sparse.details.quantizationLevel).toBeUndefined();
+      expect(sparse.details.parentModel).toBeUndefined();
+      expect(sparse.details.families).toBeUndefined();
+    });
+  });
+
+  test('fails when the client throws', async () => {
+    const client = mockClient({ list: jest.fn().mockRejectedValue(new Error('connection refused')) });
+    expect(await listModels(client)).toFailWith(/connection refused/);
+  });
+});
+
+describe('listRunning', () => {
+  test('normalizes /api/ps entries with expiresAt Date and sizeVram', async () => {
+    const client = mockClient({ ps: jest.fn().mockResolvedValue(psResponse) });
+    expect(await listRunning(client)).toSucceedAndSatisfy((running) => {
+      expect(running).toHaveLength(1);
+      const [model] = running;
+      expect(model.name).toBe('llama3.1:8b');
+      expect(model.sizeVram).toBe(4661226402);
+      expect(model.expiresAt).toBeInstanceOf(Date);
+      expect(model.expiresAt.toISOString()).toBe('2024-08-01T13:00:00.000Z');
+      expect(model.details.family).toBe('llama');
+    });
+  });
+
+  test('fails when the client throws', async () => {
+    const client = mockClient({ ps: jest.fn().mockRejectedValue(new Error('daemon down')) });
+    expect(await listRunning(client)).toFailWith(/daemon down/);
+  });
+});
+
+describe('showModel', () => {
+  test('normalizes /api/show including the model_info metadata bag', async () => {
+    const show = jest.fn().mockResolvedValue(showResponse);
+    const client = mockClient({ show });
+    expect(await showModel(client, 'llama3.1:8b')).toSucceedAndSatisfy((info) => {
+      expect(info.modelfile).toBe('FROM llama3.1:8b');
+      expect(info.parameters).toBe('stop "<|eot_id|>"');
+      expect(info.template).toBe('{{ .Prompt }}');
+      expect(info.capabilities).toEqual(['completion', 'tools']);
+      expect(info.modelInfo).toEqual({
+        'general.architecture': 'llama',
+        'llama.context_length': 131072,
+        'llama.embedding_length': 4096
+      });
+      expect(info.details.parameterSize).toBe('8.0B');
+    });
+    // No verbose flag was requested, so only `model` is on the request body.
+    expect(show).toHaveBeenCalledWith({ model: 'llama3.1:8b' });
+  });
+
+  test('maps an absent model_info to undefined', async () => {
+    const client = mockClient({ show: jest.fn().mockResolvedValue(showResponseMinimal) });
+    expect(await showModel(client, 'custom:latest')).toSucceedAndSatisfy((info) => {
+      expect(info.modelInfo).toBeUndefined();
+      expect(info.capabilities).toBeUndefined();
+      expect(info.modelfile).toBeUndefined();
+      expect(info.details.family).toBe('llama');
+    });
+  });
+
+  test('forwards verbose: true on the /api/show request body', async () => {
+    const show = jest.fn().mockResolvedValue(showResponse);
+    const client = mockClient({ show });
+    expect(await showModel(client, 'llama3.1:8b', { verbose: true })).toSucceed();
+    expect(show).toHaveBeenCalledWith({ model: 'llama3.1:8b', verbose: true });
+  });
+
+  test('fails when the client throws (unknown model)', async () => {
+    const client = mockClient({ show: jest.fn().mockRejectedValue(new Error('model not found')) });
+    expect(await showModel(client, 'nope:latest')).toFailWith(/model not found/);
+  });
+});
+
+describe('deleteModel', () => {
+  test('succeeds with a meaningful result and forwards the model name', async () => {
+    const del = jest.fn().mockResolvedValue({ status: 'success' });
+    const client = mockClient({ delete: del });
+    expect(await deleteModel(client, 'llama3.1:8b')).toSucceedWith({
+      model: 'llama3.1:8b',
+      deleted: true
+    });
+    expect(del).toHaveBeenCalledWith({ model: 'llama3.1:8b' });
+  });
+
+  test('fails when the client throws (missing model)', async () => {
+    const client = mockClient({ delete: jest.fn().mockRejectedValue(new Error('model not found')) });
+    expect(await deleteModel(client, 'nope:latest')).toFailWith(/model not found/);
+  });
+});

package/src/test/unit/ollamaClient.test.ts

@@ -0,0 +1,44 @@
+import '@fgv/ts-utils-jest';
+import { Ollama } from 'ollama';
+import { createOllamaClient } from '../../index';
+
+/**
+ * Reads the upstream client's (protected) resolved host for assertion. The `Ollama` instance
+ * keeps its config on a protected field; tests reach it through a narrow cast rather than widening
+ * the production surface.
+ */
+function resolvedHost(client: unknown): string {
+  return (client as { config: { host: string } }).config.host;
+}
+
+describe('createOllamaClient', () => {
+  test('succeeds with default host when no params are supplied', () => {
+    expect(createOllamaClient()).toSucceedAndSatisfy((client) => {
+      expect(client).toBeInstanceOf(Ollama);
+      expect(resolvedHost(client)).toBe('http://127.0.0.1:11434');
+    });
+  });
+
+  test('applies a custom host', () => {
+    expect(createOllamaClient({ host: 'http://10.0.0.5:11434' })).toSucceedAndSatisfy((client) => {
+      expect(resolvedHost(client)).toBe('http://10.0.0.5:11434');
+    });
+  });
+
+  test('accepts a custom fetch and headers', () => {
+    const customFetch = jest.fn() as unknown as typeof fetch;
+    expect(
+      createOllamaClient({
+        host: 'http://localhost:11434',
+        fetch: customFetch,
+        headers: { Authorization: 'Bearer token' }
+      })
+    ).toSucceedAndSatisfy((client) => {
+      expect(client).toBeInstanceOf(Ollama);
+    });
+  });
+
+  test('fails when the host is malformed (upstream constructor throws)', () => {
+    expect(createOllamaClient({ host: 'not a url' })).toFailWith(/invalid url/i);
+  });
+});