@fgv/ts-extras-ollama 5.1.0-34

package/dist/test/unit/pullModel.test.js

@@ -0,0 +1,202 @@
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+import '@fgv/ts-utils-jest';
+import { createOllamaClient, pullModel } from '../../index';
+/**
+ * Builds a structural mock of the upstream `AbortableAsyncIterator` returned by `client.pull`.
+ * `abort()` flips an internal flag that the generator checks before each chunk — so an abort
+ * triggered mid-stream surfaces as a throw on the next iteration, matching the real lib.
+ */
+function makePullIterator(chunks, opts) {
+    let aborted = false;
+    return {
+        abort: jest.fn(() => {
+            aborted = true;
+        }),
+        [Symbol.asyncIterator]() {
+            return __asyncGenerator(this, arguments, function* _a() {
+                for (const chunk of chunks) {
+                    if (aborted) {
+                        throw new Error('The operation was aborted');
+                    }
+                    yield yield __await(chunk);
+                    if (opts === null || opts === void 0 ? void 0 : opts.throwMidStream) {
+                        throw new Error('stream broke mid-pull');
+                    }
+                }
+            });
+        }
+    };
+}
+function mockPullClient(pull) {
+    return { pull };
+}
+const happyChunks = [
+    { status: 'pulling manifest' },
+    { status: 'pulling sha256:abc', digest: 'sha256:abc', total: 1000, completed: 1000 },
+    { status: 'success' }
+];
+describe('pullModel (layer 1 — structural client mock)', () => {
+    test('drives the stream, maps each chunk, and resolves with finalStatus + chunkCount', async () => {
+        const pull = jest.fn().mockResolvedValue(makePullIterator(happyChunks));
+        const client = mockPullClient(pull);
+        const seen = [];
+        expect(await pullModel(client, { model: 'llama3.1:8b', onProgress: (p) => seen.push(p) })).toSucceedWith({
+            model: 'llama3.1:8b',
+            finalStatus: 'success',
+            chunkCount: 3
+        });
+        expect(pull).toHaveBeenCalledWith({ model: 'llama3.1:8b', stream: true });
+        expect(seen).toHaveLength(3);
+        // Manifest phase: no layer fields.
+        expect(seen[0]).toEqual({
+            status: 'pulling manifest',
+            digest: undefined,
+            total: undefined,
+            completed: undefined
+        });
+        // Transfer phase: layer fields present and mapped 1:1.
+        expect(seen[1]).toEqual({
+            status: 'pulling sha256:abc',
+            digest: 'sha256:abc',
+            total: 1000,
+            completed: 1000
+        });
+        expect(seen[2].status).toBe('success');
+    });
+    test('forwards insecure and works without an onProgress callback', async () => {
+        const pull = jest.fn().mockResolvedValue(makePullIterator(happyChunks));
+        const client = mockPullClient(pull);
+        expect(await pullModel(client, { model: 'llama3.1:8b', insecure: true })).toSucceedWith({
+            model: 'llama3.1:8b',
+            finalStatus: 'success',
+            chunkCount: 3
+        });
+        expect(pull).toHaveBeenCalledWith({ model: 'llama3.1:8b', stream: true, insecure: true });
+    });
+    test('fails when the stream errors mid-pull', async () => {
+        const pull = jest.fn().mockResolvedValue(makePullIterator(happyChunks, { throwMidStream: true }));
+        const client = mockPullClient(pull);
+        expect(await pullModel(client, { model: 'llama3.1:8b' })).toFailWith(/stream broke mid-pull/);
+    });
+    test('fails when onProgress throws', async () => {
+        const pull = jest.fn().mockResolvedValue(makePullIterator(happyChunks));
+        const client = mockPullClient(pull);
+        expect(await pullModel(client, {
+            model: 'llama3.1:8b',
+            onProgress: () => {
+                throw new Error('consumer blew up');
+            }
+        })).toFailWith(/consumer blew up/);
+    });
+    test('an already-aborted signal cancels the pull on the first iteration', async () => {
+        // The signal is aborted before the loop begins, so the iterator's abort fires up front; the
+        // throw surfaces on the first iteration attempt (the mock checks the flag before the first yield).
+        const iterator = makePullIterator(happyChunks);
+        const pull = jest.fn().mockResolvedValue(iterator);
+        const client = mockPullClient(pull);
+        const controller = new AbortController();
+        controller.abort();
+        expect(await pullModel(client, { model: 'llama3.1:8b', signal: controller.signal })).toFailWith(/abort/i);
+        expect(iterator.abort).toHaveBeenCalledTimes(1);
+    });
+    test('a mid-stream abort cancels the pull, removes the listener, and surfaces as failure', async () => {
+        const iterator = makePullIterator(happyChunks);
+        const pull = jest.fn().mockResolvedValue(iterator);
+        const client = mockPullClient(pull);
+        const controller = new AbortController();
+        const removeSpy = jest.spyOn(controller.signal, 'removeEventListener');
+        const seen = [];
+        const result = await pullModel(client, {
+            model: 'llama3.1:8b',
+            signal: controller.signal,
+            onProgress: (p) => {
+                seen.push(p);
+                if (seen.length === 1) {
+                    controller.abort();
+                }
+            }
+        });
+        expect(result).toFailWith(/abort/i);
+        expect(iterator.abort).toHaveBeenCalled();
+        expect(seen).toHaveLength(1);
+        // The `finally` cleanup runs on the failure path too — no listener leak after an abort.
+        expect(removeSpy).toHaveBeenCalledWith('abort', expect.any(Function));
+    });
+    test('removes the abort listener after a normal completion', async () => {
+        const pull = jest.fn().mockResolvedValue(makePullIterator(happyChunks));
+        const client = mockPullClient(pull);
+        const controller = new AbortController();
+        const removeSpy = jest.spyOn(controller.signal, 'removeEventListener');
+        expect(await pullModel(client, { model: 'llama3.1:8b', signal: controller.signal })).toSucceed();
+        expect(removeSpy).toHaveBeenCalledWith('abort', expect.any(Function));
+    });
+});
+/**
+ * Layer 2 — a real client built with a mock `fetch` whose body is a `ReadableStream` of
+ * newline-delimited JSON. This exercises the `ollama` lib's actual JSON-lines stream parsing
+ * flowing through `pullModel`'s loop — the framing that layer 1 stubs over.
+ */
+function ndjsonResponse(lines) {
+    const bytes = new TextEncoder().encode(lines.join('\n') + '\n');
+    // Split the payload mid-stream (likely mid-line) into two reads to exercise buffer reassembly.
+    const mid = Math.floor(bytes.length / 2);
+    const parts = [bytes.slice(0, mid), bytes.slice(mid)];
+    let i = 0;
+    const stream = new ReadableStream({
+        pull(controller) {
+            if (i < parts.length) {
+                controller.enqueue(parts[i++]);
+            }
+            else {
+                controller.close();
+            }
+        }
+    });
+    return new Response(stream, { status: 200 });
+}
+describe('pullModel (layer 2 — fetch-level JSON-lines integration)', () => {
+    test('parses a real newline-delimited /api/pull stream through the ollama lib', async () => {
+        const lines = [
+            JSON.stringify({ status: 'pulling manifest' }),
+            JSON.stringify({ status: 'pulling sha256:abc', digest: 'sha256:abc', total: 1000, completed: 1000 }),
+            JSON.stringify({ status: 'verifying sha256 digest' }),
+            JSON.stringify({ status: 'writing manifest' }),
+            JSON.stringify({ status: 'success' })
+        ];
+        const fetchMock = jest.fn().mockResolvedValue(ndjsonResponse(lines));
+        const client = createOllamaClient({ fetch: fetchMock }).orThrow();
+        const seen = [];
+        expect(await pullModel(client, { model: 'llama3.1:8b', onProgress: (p) => seen.push(p) })).toSucceedAndSatisfy((r) => {
+            expect(r.finalStatus).toBe('success');
+            expect(r.chunkCount).toBe(5);
+        });
+        expect(seen.map((s) => s.status)).toEqual([
+            'pulling manifest',
+            'pulling sha256:abc',
+            'verifying sha256 digest',
+            'writing manifest',
+            'success'
+        ]);
+        expect(seen[1]).toEqual({
+            status: 'pulling sha256:abc',
+            digest: 'sha256:abc',
+            total: 1000,
+            completed: 1000
+        });
+        expect(seen[0].digest).toBeUndefined();
+        expect(fetchMock.mock.calls[0][0]).toEqual(expect.stringContaining('/api/pull'));
+    });
+});
+//# sourceMappingURL=pullModel.test.js.map

package/dist/test/unit/pullModel.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pullModel.test.js","sourceRoot":"","sources":["../../../src/test/unit/pullModel.test.ts"],"names":[],"mappings":"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","sourcesContent":["import '@fgv/ts-utils-jest';\nimport { type IOllamaClient, type IOllamaPullProgress, createOllamaClient, pullModel } from '../../index';\n\n/** The actual `/api/pull` wire chunk shape — layer fields absent on non-transfer phases. */\ninterface IPullChunk {\n  status: string;\n  digest?: string;\n  total?: number;\n  completed?: number;\n}\n\n/**\n * Builds a structural mock of the upstream `AbortableAsyncIterator` returned by `client.pull`.\n * `abort()` flips an internal flag that the generator checks before each chunk — so an abort\n * triggered mid-stream surfaces as a throw on the next iteration, matching the real lib.\n */\nfunction makePullIterator(\n  chunks: ReadonlyArray<IPullChunk>,\n  opts?: { readonly throwMidStream?: boolean }\n): { abort: jest.Mock } & AsyncIterable<IPullChunk> {\n  let aborted = false;\n  return {\n    abort: jest.fn(() => {\n      aborted = true;\n    }),\n    async *[Symbol.asyncIterator](): AsyncGenerator<IPullChunk> {\n      for (const chunk of chunks) {\n        if (aborted) {\n          throw new Error('The operation was aborted');\n        }\n        yield chunk;\n        if (opts?.throwMidStream) {\n          throw new Error('stream broke mid-pull');\n        }\n      }\n    }\n  };\n}\n\nfunction mockPullClient(pull: unknown): IOllamaClient {\n  return { pull } as unknown as IOllamaClient;\n}\n\nconst happyChunks: ReadonlyArray<IPullChunk> = [\n  { status: 'pulling manifest' },\n  { status: 'pulling sha256:abc', digest: 'sha256:abc', total: 1000, completed: 1000 },\n  { status: 'success' }\n];\n\ndescribe('pullModel (layer 1 — structural client mock)', () => {\n  test('drives the stream, maps each chunk, and resolves with finalStatus + chunkCount', async () => {\n    const pull = jest.fn().mockResolvedValue(makePullIterator(happyChunks));\n    const client = mockPullClient(pull);\n    const seen: IOllamaPullProgress[] = [];\n\n    expect(await pullModel(client, { model: 'llama3.1:8b', onProgress: (p) => seen.push(p) })).toSucceedWith({\n      model: 'llama3.1:8b',\n      finalStatus: 'success',\n      chunkCount: 3\n    });\n    expect(pull).toHaveBeenCalledWith({ model: 'llama3.1:8b', stream: true });\n    expect(seen).toHaveLength(3);\n    // Manifest phase: no layer fields.\n    expect(seen[0]).toEqual({\n      status: 'pulling manifest',\n      digest: undefined,\n      total: undefined,\n      completed: undefined\n    });\n    // Transfer phase: layer fields present and mapped 1:1.\n    expect(seen[1]).toEqual({\n      status: 'pulling sha256:abc',\n      digest: 'sha256:abc',\n      total: 1000,\n      completed: 1000\n    });\n    expect(seen[2].status).toBe('success');\n  });\n\n  test('forwards insecure and works without an onProgress callback', async () => {\n    const pull = jest.fn().mockResolvedValue(makePullIterator(happyChunks));\n    const client = mockPullClient(pull);\n\n    expect(await pullModel(client, { model: 'llama3.1:8b', insecure: true })).toSucceedWith({\n      model: 'llama3.1:8b',\n      finalStatus: 'success',\n      chunkCount: 3\n    });\n    expect(pull).toHaveBeenCalledWith({ model: 'llama3.1:8b', stream: true, insecure: true });\n  });\n\n  test('fails when the stream errors mid-pull', async () => {\n    const pull = jest.fn().mockResolvedValue(makePullIterator(happyChunks, { throwMidStream: true }));\n    const client = mockPullClient(pull);\n\n    expect(await pullModel(client, { model: 'llama3.1:8b' })).toFailWith(/stream broke mid-pull/);\n  });\n\n  test('fails when onProgress throws', async () => {\n    const pull = jest.fn().mockResolvedValue(makePullIterator(happyChunks));\n    const client = mockPullClient(pull);\n\n    expect(\n      await pullModel(client, {\n        model: 'llama3.1:8b',\n        onProgress: () => {\n          throw new Error('consumer blew up');\n        }\n      })\n    ).toFailWith(/consumer blew up/);\n  });\n\n  test('an already-aborted signal cancels the pull on the first iteration', async () => {\n    // The signal is aborted before the loop begins, so the iterator's abort fires up front; the\n    // throw surfaces on the first iteration attempt (the mock checks the flag before the first yield).\n    const iterator = makePullIterator(happyChunks);\n    const pull = jest.fn().mockResolvedValue(iterator);\n    const client = mockPullClient(pull);\n    const controller = new AbortController();\n    controller.abort();\n\n    expect(await pullModel(client, { model: 'llama3.1:8b', signal: controller.signal })).toFailWith(/abort/i);\n    expect(iterator.abort).toHaveBeenCalledTimes(1);\n  });\n\n  test('a mid-stream abort cancels the pull, removes the listener, and surfaces as failure', async () => {\n    const iterator = makePullIterator(happyChunks);\n    const pull = jest.fn().mockResolvedValue(iterator);\n    const client = mockPullClient(pull);\n    const controller = new AbortController();\n    const removeSpy = jest.spyOn(controller.signal, 'removeEventListener');\n    const seen: IOllamaPullProgress[] = [];\n\n    const result = await pullModel(client, {\n      model: 'llama3.1:8b',\n      signal: controller.signal,\n      onProgress: (p) => {\n        seen.push(p);\n        if (seen.length === 1) {\n          controller.abort();\n        }\n      }\n    });\n    expect(result).toFailWith(/abort/i);\n    expect(iterator.abort).toHaveBeenCalled();\n    expect(seen).toHaveLength(1);\n    // The `finally` cleanup runs on the failure path too — no listener leak after an abort.\n    expect(removeSpy).toHaveBeenCalledWith('abort', expect.any(Function));\n  });\n\n  test('removes the abort listener after a normal completion', async () => {\n    const pull = jest.fn().mockResolvedValue(makePullIterator(happyChunks));\n    const client = mockPullClient(pull);\n    const controller = new AbortController();\n    const removeSpy = jest.spyOn(controller.signal, 'removeEventListener');\n\n    expect(await pullModel(client, { model: 'llama3.1:8b', signal: controller.signal })).toSucceed();\n    expect(removeSpy).toHaveBeenCalledWith('abort', expect.any(Function));\n  });\n});\n\n/**\n * Layer 2 — a real client built with a mock `fetch` whose body is a `ReadableStream` of\n * newline-delimited JSON. This exercises the `ollama` lib's actual JSON-lines stream parsing\n * flowing through `pullModel`'s loop — the framing that layer 1 stubs over.\n */\nfunction ndjsonResponse(lines: ReadonlyArray<string>): Response {\n  const bytes = new TextEncoder().encode(lines.join('\\n') + '\\n');\n  // Split the payload mid-stream (likely mid-line) into two reads to exercise buffer reassembly.\n  const mid = Math.floor(bytes.length / 2);\n  const parts = [bytes.slice(0, mid), bytes.slice(mid)];\n  let i = 0;\n  const stream = new ReadableStream<Uint8Array>({\n    pull(controller: ReadableStreamDefaultController<Uint8Array>): void {\n      if (i < parts.length) {\n        controller.enqueue(parts[i++]);\n      } else {\n        controller.close();\n      }\n    }\n  });\n  return new Response(stream, { status: 200 });\n}\n\ndescribe('pullModel (layer 2 — fetch-level JSON-lines integration)', () => {\n  test('parses a real newline-delimited /api/pull stream through the ollama lib', async () => {\n    const lines = [\n      JSON.stringify({ status: 'pulling manifest' }),\n      JSON.stringify({ status: 'pulling sha256:abc', digest: 'sha256:abc', total: 1000, completed: 1000 }),\n      JSON.stringify({ status: 'verifying sha256 digest' }),\n      JSON.stringify({ status: 'writing manifest' }),\n      JSON.stringify({ status: 'success' })\n    ];\n    const fetchMock = jest.fn().mockResolvedValue(ndjsonResponse(lines));\n    const client = createOllamaClient({ fetch: fetchMock as unknown as typeof fetch }).orThrow();\n    const seen: IOllamaPullProgress[] = [];\n\n    expect(\n      await pullModel(client, { model: 'llama3.1:8b', onProgress: (p) => seen.push(p) })\n    ).toSucceedAndSatisfy((r) => {\n      expect(r.finalStatus).toBe('success');\n      expect(r.chunkCount).toBe(5);\n    });\n    expect(seen.map((s) => s.status)).toEqual([\n      'pulling manifest',\n      'pulling sha256:abc',\n      'verifying sha256 digest',\n      'writing manifest',\n      'success'\n    ]);\n    expect(seen[1]).toEqual({\n      status: 'pulling sha256:abc',\n      digest: 'sha256:abc',\n      total: 1000,\n      completed: 1000\n    });\n    expect(seen[0].digest).toBeUndefined();\n    expect(fetchMock.mock.calls[0][0]).toEqual(expect.stringContaining('/api/pull'));\n  });\n});\n"]}

package/dist/ts-extras-ollama.d.ts

@@ -0,0 +1,365 @@
+/**
+ * `@fgv/ts-extras-ollama` — Result-integration boundary over the official `ollama` JS library
+ * (Node-side).
+ *
+ * A thin facade that wraps the `ollama` client's native-API calls in `Result<T>` from
+ * `@fgv/ts-utils`, mirroring the discipline established by `@fgv/ts-extras-webauthn` and
+ * `@fgv/ts-extras-transformers`: one-line `captureResult` / `captureAsyncResult` wrappers around
+ * upstream primitives with **no opinionated orchestration** above the boundary.
+ *
+ * This package owns **exactly and only** the native-Ollama surface that the OpenAI-compatible
+ * `/v1` endpoint cannot express: model management (`/api/tags`, `/api/show`, `/api/ps`,
+ * `/api/delete`), streamed model pulls (`/api/pull`), and grammar-constrained structured output
+ * (`/api/chat` with a full-JSON-schema `format`). The text-completion / streaming / tool-use path
+ * is **not** duplicated here — `@fgv/ts-extras/ai-assist` owns it via the `/v1` compat layer
+ * (point a provider descriptor's `endpoint` at `http://localhost:11434/v1`).
+ *
+ * **Explicitly NOT in scope:**
+ * - Text completion / free-text chat / streaming chat (ai-assist owns it via `/v1`).
+ * - Browser / CORS path (Node-only at v0.1; a future `@fgv/ts-web-extras-ollama` is its home).
+ * - Model authoring / publishing (`push`, `create`, `copy`) — use the `ollama` lib directly.
+ * - `keep_alive` / model-lifecycle policy — pass-through only, no policy applied.
+ * - Pull-progress UI / rendering — `onProgress` hands raw chunks to the consumer.
+ * - Multi-host orchestration / connection pooling / retries / backoff — one client = one host.
+ *
+ * For any of the above, use the `ollama` library directly (with `captureAsyncResult` for your own
+ * Result wrapping); the opaque client handle returned by {@link createOllamaClient} is the
+ * upstream instance, so nothing this boundary omits is hidden from you.
+ *
+ * @packageDocumentation
+ */
+
+import { JsonSchema } from '@fgv/ts-json-base';
+import { JsonValue } from '@fgv/ts-json-base';
+import { Ollama } from 'ollama';
+import { Result } from '@fgv/ts-utils';
+
+/**
+ * Single-turn grammar-constrained structured chat (`POST /api/chat` with `format` = full JSON
+ * schema). The fidelity win over ai-assist's prompt-and-parse path is **grammar-constrained
+ * sampling**: Ollama restricts the token sampler to the supplied schema, so the response is
+ * structurally guaranteed to match.
+ *
+ * The schema is the single source of truth: `schema.toJson()` (draft-07-sanitized) is sent as the
+ * wire `format`, and the same `schema.validate()` checks the reply — they cannot drift. `T` flows
+ * end-to-end from `JsonSchema.Static<typeof schema>`; no caller-supplied `T`, no cast.
+ *
+ * Runs over the streaming chat path internally, assembling the full document from the stream
+ * chunks and validating it whole — partial JSON has no validation value. (The design §4 sketch
+ * said `stream: false`, but the locked OQ-3 amendment requires an `AbortSignal`, and the `ollama`
+ * lib only threads a signal on the streaming path — its non-streaming request has no signal
+ * plumbing. The streaming `AbortableAsyncIterator.abort()` is "the mechanism that already exists
+ * for `pullModel`".) Any upstream error, abort, parse failure, or validation failure surfaces as a
+ * single `Failure` with context.
+ *
+ * @param client - A client from {@link createOllamaClient}.
+ * @param params - {@link IChatStructuredParams} — model, messages, the `JsonSchema` schema, and
+ *   optional `options` / `keepAlive` / `signal`.
+ * @returns `Promise<Result<IOllamaChatStructuredResult<T>>>`.
+ * @public
+ */
+export declare function chatStructured<T>(client: IOllamaClient, params: IChatStructuredParams<T>): Promise<Result<IOllamaChatStructuredResult<T>>>;
+
+/**
+ * Constructs an Ollama client. Synchronous (the constructor performs no I/O), so returns
+ * `Result<IOllamaClient>` rather than a promise. A malformed `host` (which the upstream
+ * constructor rejects) surfaces as `Result.fail`.
+ *
+ * @param params - Optional {@link ICreateOllamaClientParams}. Omitted fields fall back to the
+ *   `ollama` library defaults.
+ * @returns `Result<IOllamaClient>` wrapping the upstream `Ollama` instance.
+ * @public
+ */
+export declare function createOllamaClient(params?: ICreateOllamaClientParams): Result<IOllamaClient>;
+
+/**
+ * Deletes a model from the local store (`DELETE /api/delete`). Returns a meaningful
+ * {@link IOllamaDeleteResult} rather than `Result<void>`.
+ *
+ * @param client - A client from {@link createOllamaClient}.
+ * @param model - The model name to delete.
+ * @returns `Promise<Result<IOllamaDeleteResult>>`; a missing model or transport error surfaces as
+ *   `Failure`.
+ * @public
+ */
+export declare function deleteModel(client: IOllamaClient, model: string): Promise<Result<IOllamaDeleteResult>>;
+
+/**
+ * Parameters for {@link chatStructured}.
+ * @public
+ */
+export declare interface IChatStructuredParams<T> {
+    /** The model to chat with, e.g. `'llama3.1:8b'`. */
+    readonly model: string;
+    /** The conversation so far. */
+    readonly messages: ReadonlyArray<IOllamaChatMessage>;
+    /**
+     * The single source of truth for both the wire schema (`schema.toJson()`, sent as the native
+     * `format` field) and the result validator (`schema.validate()`). Author with
+     * `JsonSchema.object(...)` from `@fgv/ts-json-base`; `T` is derived via
+     * `JsonSchema.Static<typeof schema>`. A runtime-discovered (MCP) schema parsed via
+     * `JsonSchema.fromJson(raw)` also works — its `T` is `JsonValue`.
+     */
+    readonly schema: JsonSchema.ISchemaValidator<T>;
+    /** Native Ollama `options` (temperature, num_ctx, seed, …). Passed verbatim. */
+    readonly options?: Readonly<Record<string, JsonValue>>;
+    /** Native `keep_alive` (duration string or seconds). Passed verbatim — no policy applied. */
+    readonly keepAlive?: string | number;
+    /**
+     * Abort signal. Cancels the in-flight generation; the upstream stream throws an `AbortError`,
+     * which surfaces as `Result.fail`. An already-aborted signal cancels immediately.
+     */
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * Construction parameters for an Ollama client. All optional; defaults match the `ollama` JS
+ * library (host `http://127.0.0.1:11434`).
+ * @public
+ */
+export declare interface ICreateOllamaClientParams {
+    /** Server address. Defaults to `http://127.0.0.1:11434`. */
+    readonly host?: string;
+    /**
+     * Custom `fetch` implementation. Injecting a fetch is the primary unit-test seam and the hook
+     * for a future proxy / browser path.
+     */
+    readonly fetch?: typeof fetch;
+    /** Custom headers included on every request (e.g. an auth token for a guarded sidecar). */
+    readonly headers?: Record<string, string>;
+}
+
+/**
+ * A chat message in Ollama native shape.
+ * @public
+ */
+export declare interface IOllamaChatMessage {
+    /** The message role. */
+    readonly role: 'system' | 'user' | 'assistant' | 'tool';
+    /** The message text. */
+    readonly content: string;
+    /** Base64 image data for vision models (no `data:` prefix). */
+    readonly images?: ReadonlyArray<string>;
+}
+
+/**
+ * Result of a grammar-constrained structured chat. Carries both the validated typed value and the
+ * raw JSON text the model emitted, for diagnostics.
+ * @public
+ */
+export declare interface IOllamaChatStructuredResult<T> {
+    /** The parsed-and-validated value (validated by the same schema sent on the wire). */
+    readonly value: T;
+    /** The raw `message.content` JSON string the model emitted (assembled across stream chunks). */
+    readonly raw: string;
+    /** The model that produced the response. */
+    readonly model: string;
+    /** Provider-reported finish reason, when present. */
+    readonly doneReason?: string;
+}
+
+/**
+ * Opaque client handle. Re-export of the upstream `ollama` `Ollama` instance type — consumers
+ * retain full access to the upstream API for anything this boundary does not wrap.
+ * @public
+ */
+export declare type IOllamaClient = Ollama;
+
+/**
+ * Result of a delete. Returns a meaningful value rather than `Result<void>` (per repo standards —
+ * `Result<void>` is an anti-pattern).
+ * @public
+ */
+export declare interface IOllamaDeleteResult {
+    /** The model that was deleted. */
+    readonly model: string;
+    /** Always `true` — a failed delete surfaces as `Result.fail`, never `deleted: false`. */
+    readonly deleted: true;
+}
+
+/**
+ * A model present in the local store (`/api/tags`).
+ * @public
+ */
+export declare interface IOllamaModel extends IOllamaModelBase {
+    /** Last-modified timestamp, parsed from the RFC3339 wire value. */
+    readonly modifiedAt: Date;
+}
+
+/**
+ * Fields common to a locally-stored model and a running model.
+ * @public
+ */
+export declare interface IOllamaModelBase {
+    /** Tagged name, e.g. `'llama3.1:8b'`. */
+    readonly name: string;
+    /** Underlying model id (often equal to `name`). */
+    readonly model: string;
+    /** On-disk size in bytes. */
+    readonly size: number;
+    /** SHA-256 manifest digest. */
+    readonly digest: string;
+    /** GGUF / architecture detail. */
+    readonly details: IOllamaModelDetail;
+}
+
+/**
+ * GGUF / model detail block, common to `/api/tags`, `/api/ps`, and `/api/show`. All fields
+ * optional — Ollama omits any it cannot determine.
+ * @public
+ */
+export declare interface IOllamaModelDetail {
+    /** Storage format, e.g. `'gguf'`. */
+    readonly format?: string;
+    /** Primary architecture family, e.g. `'llama'`. */
+    readonly family?: string;
+    /** All architecture families this model belongs to. */
+    readonly families?: ReadonlyArray<string>;
+    /** Human-readable parameter count, e.g. `'8.0B'`. */
+    readonly parameterSize?: string;
+    /** Quantization level, e.g. `'Q4_0'`. */
+    readonly quantizationLevel?: string;
+    /** Parent model for fine-tunes / derived models. */
+    readonly parentModel?: string;
+}
+
+/**
+ * Full model detail, capabilities, parameters, and template (`POST /api/show`).
+ * @public
+ */
+export declare interface IOllamaModelInfo {
+    /** The Modelfile source, when returned. */
+    readonly modelfile?: string;
+    /** Default parameters string. */
+    readonly parameters?: string;
+    /** The prompt template. */
+    readonly template?: string;
+    /** GGUF / architecture detail. */
+    readonly details: IOllamaModelDetail;
+    /** Low-level model metadata key-value map (`model_info`). */
+    readonly modelInfo?: Readonly<Record<string, JsonValue>>;
+    /** Declared capabilities, e.g. `['completion', 'tools', 'vision', 'thinking']`. */
+    readonly capabilities?: ReadonlyArray<string>;
+}
+
+/**
+ * A single progress chunk from a streamed pull (`/api/pull`). Ollama emits a JSON-lines stream;
+ * each line is one of these. Fields map 1:1 from the upstream `ProgressResponse`; the layer fields
+ * (`digest`/`total`/`completed`) are `undefined` on the manifest / verify / write phases.
+ * @public
+ */
+export declare interface IOllamaPullProgress {
+    /**
+     * Phase string, e.g. `'pulling manifest'`, `'pulling <digest>'`, `'verifying sha256 digest'`,
+     * `'writing manifest'`, `'success'`.
+     */
+    readonly status: string;
+    /** Layer digest being transferred (present during `'pulling <digest>'` phases). */
+    readonly digest?: string;
+    /** Total bytes for the current layer, when known. */
+    readonly total?: number;
+    /** Bytes transferred so far for the current layer, when known. */
+    readonly completed?: number;
+}
+
+/**
+ * Terminal result of a completed pull. Returns a meaningful value (not `Result<void>`): the final
+ * status plus a count of progress chunks observed.
+ * @public
+ */
+export declare interface IOllamaPullResult {
+    /** The model that was pulled. */
+    readonly model: string;
+    /** The `status` of the final chunk, normally `'success'`. */
+    readonly finalStatus: string;
+    /** Number of progress chunks observed (useful for tests and diagnostics). */
+    readonly chunkCount: number;
+}
+
+/**
+ * A model currently loaded into memory (`/api/ps`). Note `/api/ps` does NOT return
+ * `modified_at`, so this does not extend {@link IOllamaModel}.
+ * @public
+ */
+export declare interface IOllamaRunningModel extends IOllamaModelBase {
+    /** When the model will be unloaded, parsed from the RFC3339 wire value. */
+    readonly expiresAt: Date;
+    /** Bytes resident in VRAM (0 when fully on CPU). */
+    readonly sizeVram: number;
+}
+
+/**
+ * Parameters for {@link pullModel}.
+ * @public
+ */
+export declare interface IPullModelParams {
+    /** Model to pull, e.g. `'llama3.1:8b'`. */
+    readonly model: string;
+    /** Allow pulling from insecure (non-TLS) registries. */
+    readonly insecure?: boolean;
+    /**
+     * Progress callback, invoked once per JSON-lines chunk as it arrives. The `Result` returned by
+     * {@link pullModel} resolves only after the stream terminates; progress is surfaced here in the
+     * interim. A throw from this callback fails the whole pull (it runs inside the captured loop).
+     */
+    readonly onProgress?: (progress: IOllamaPullProgress) => void;
+    /**
+     * Abort signal. Cancels the in-flight pull; the upstream stream throws an `AbortError`, which
+     * surfaces as `Result.fail`. An already-aborted signal cancels immediately.
+     */
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * Lists models in the local store (`GET /api/tags`). Each entry is normalized to
+ * {@link IOllamaModel} (camelCase, `modifiedAt` as a `Date`).
+ *
+ * @param client - A client from {@link createOllamaClient}.
+ * @returns `Promise<Result<ReadonlyArray<IOllamaModel>>>`; upstream / transport errors are captured
+ *   as `Failure`.
+ * @public
+ */
+export declare function listModels(client: IOllamaClient): Promise<Result<ReadonlyArray<IOllamaModel>>>;
+
+/**
+ * Lists models currently loaded into memory (`GET /api/ps`). Each entry is normalized to
+ * {@link IOllamaRunningModel} (camelCase, `expiresAt` as a `Date`, `sizeVram` in bytes).
+ *
+ * @param client - A client from {@link createOllamaClient}.
+ * @returns `Promise<Result<ReadonlyArray<IOllamaRunningModel>>>`; upstream / transport errors are
+ *   captured as `Failure`.
+ * @public
+ */
+export declare function listRunning(client: IOllamaClient): Promise<Result<ReadonlyArray<IOllamaRunningModel>>>;
+
+/**
+ * Pulls a model with streamed progress (`POST /api/pull`). Drives the upstream JSON-lines stream
+ * internally, invoking `params.onProgress` once per chunk, and resolves the `Result` once the
+ * stream terminates. Any upstream error — connection drop, registry 404, abort, or a throwing
+ * `onProgress` — becomes a single `Failure`; success returns a meaningful {@link IOllamaPullResult}
+ * rather than `Result<void>`.
+ *
+ * @param client - A client from {@link createOllamaClient}.
+ * @param params - {@link IPullModelParams} — the model, optional `insecure` flag, optional
+ *   `onProgress` callback, and optional `AbortSignal`.
+ * @returns `Promise<Result<IOllamaPullResult>>`.
+ * @public
+ */
+export declare function pullModel(client: IOllamaClient, params: IPullModelParams): Promise<Result<IOllamaPullResult>>;
+
+/**
+ * Full model detail, capabilities, parameters, and template (`POST /api/show`), normalized to
+ * {@link IOllamaModelInfo}.
+ *
+ * @param client - A client from {@link createOllamaClient}.
+ * @param model - The model name to inspect, e.g. `'llama3.1:8b'`.
+ * @param options - Optional flags. `verbose: true` requests the full low-level `model_info` block.
+ * @returns `Promise<Result<IOllamaModelInfo>>`; upstream / transport errors (e.g. unknown model)
+ *   are captured as `Failure`.
+ * @public
+ */
+export declare function showModel(client: IOllamaClient, model: string, options?: {
+    readonly verbose?: boolean;
+}): Promise<Result<IOllamaModelInfo>>;
+
+export { }

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.7"
+    }
+  ]
+}

package/eslint.config.js

@@ -0,0 +1,15 @@
+// ESLint 9 flat config
+const nodeProfile = require('@rushstack/eslint-config/flat/profile/node');
+const packletsPlugin = require('@rushstack/eslint-config/flat/mixins/packlets');
+const tsdocPlugin = require('@rushstack/eslint-config/flat/mixins/tsdoc');
+
+module.exports = [
+  ...nodeProfile,
+  packletsPlugin,
+  ...tsdocPlugin,
+  {
+    rules: {
+      '@rushstack/packlets/mechanics': 'warn'
+    }
+  }
+];