@fgv/ts-extras-ollama 5.1.0-34

package/CHANGELOG.json

@@ -0,0 +1,4 @@
+{
+  "name": "@fgv/ts-extras-ollama",
+  "entries": []
+}

package/README.md

@@ -0,0 +1,105 @@
+# @fgv/ts-extras-ollama
+
+Result-integration boundary over the official [`ollama`](https://github.com/ollama/ollama-js) JS
+library for Node-side consumers. Owns **exactly and only** the native-Ollama surface that the
+OpenAI-compatible `/v1` endpoint cannot express.
+
+**Status:** v0.1 surface complete (the `ollama-native` stream, phases O-1…O-4). Native `embed` is
+held pending the cross-provider `ai-assist-embeddings` design.
+
+---
+
+## What this is
+
+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`](../ts-extras-webauthn) and
+[`@fgv/ts-extras-transformers`](../ts-extras-transformers): one-line `captureAsyncResult` /
+`captureResult` wrappers around upstream primitives with **no opinionated orchestration** above the
+boundary. Consumers compose the primitives themselves.
+
+The text-completion / streaming / tool-use path is **not** here — `@fgv/ts-extras/ai-assist` owns it
+via the `/v1` compat layer (point a provider descriptor's `endpoint` at `http://localhost:11434/v1`
+and call `callProviderCompletion` / `callProviderCompletionStream` / `executeClientToolTurn`).
+
+## The native-only surface
+
+| Function | Wraps | Status |
+|---|---|---|
+| `createOllamaClient(params?)` | `new Ollama(...)` | O-1 |
+| `listModels(client)` | `client.list()` (`/api/tags`) | O-2 |
+| `showModel(client, model)` | `client.show(...)` (`/api/show`) | O-2 |
+| `listRunning(client)` | `client.ps()` (`/api/ps`) | O-2 |
+| `deleteModel(client, model)` | `client.delete(...)` (`/api/delete`) | O-2 |
+| `pullModel(client, params)` | `client.pull({ stream: true })` (`/api/pull`) | O-3 |
+| `chatStructured(client, params)` | `client.chat({ format })` (`/api/chat`) | O-4 |
+
+## Quick start
+
+```typescript
+import { createOllamaClient, listModels, pullModel, chatStructured } from '@fgv/ts-extras-ollama';
+import { JsonSchema } from '@fgv/ts-json-base';
+
+// Construct a client (defaults to http://127.0.0.1:11434). Returns Result<IOllamaClient>.
+const client = createOllamaClient().orThrow();
+
+// Enumerate locally-pulled models with GGUF metadata the /v1 layer can't surface.
+const models = await listModels(client);
+if (models.isSuccess()) {
+  for (const m of models.value) {
+    console.log(`${m.name} — ${m.details.parameterSize} ${m.details.quantizationLevel}, ${m.size} bytes`);
+  }
+}
+
+// Pull a model with streamed progress; the Result resolves when the stream terminates.
+const pulled = await pullModel(client, {
+  model: 'llama3.1:8b',
+  onProgress: (p) => console.log(p.status, p.completed, '/', p.total)
+});
+
+// Grammar-constrained structured output — one schema is BOTH the wire `format` and the validator.
+const personSchema = JsonSchema.object({
+  name: JsonSchema.string(),
+  age: JsonSchema.integer()
+});
+
+const structured = await chatStructured(client, {
+  model: 'llama3.1:8b',
+  messages: [{ role: 'user', content: 'Invent a person as JSON.' }],
+  schema: personSchema // T is derived via JsonSchema.Static<typeof personSchema> — no cast
+});
+if (structured.isSuccess()) {
+  // structured.value.value is { name: string; age: number }, validated by the same schema.
+  console.log(structured.value.value.name, structured.value.value.age);
+}
+```
+
+For **text completion / streaming / tool-use** against the same daemon, use
+`@fgv/ts-extras/ai-assist` (`callProviderCompletion` / `callProviderCompletionStream` /
+`executeClientToolTurn`) with a provider `endpoint` of `http://localhost:11434/v1` — that path is
+not duplicated here.
+
+## 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.
+- Native embeddings (`embed`) → HELD pending the cross-provider `ai-assist-embeddings` design.
+
+For anything not wrapped here, use the `ollama` library directly (with `captureAsyncResult` for your
+own Result wrapping) — the client handle returned by `createOllamaClient` is the upstream instance.
+
+---
+
+## Runtime requirements
+
+- **Node.js:** v20 LTS or later.
+- **`ollama`:** ^0.6.0 (peer dependency; bring your own).
+- **`@fgv/ts-utils`:** workspace:* (peer dependency).
+
+## License
+
+MIT — same as the parent fgv monorepo.

package/config/api-extractor.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "projectFolder": "..",
+  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
+  "bundledPackages": [],
+  "compiler": {},
+  "apiReport": {
+    "enabled": true
+  },
+  "docModel": {
+    "enabled": true
+  },
+  "dtsRollup": {
+    "enabled": true
+  },
+  "tsdocMetadata": {},
+  "messages": {
+    "compilerMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+    "extractorMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      },
+      "ae-unresolved-link": {
+        "logLevel": "none",
+        "addToApiReportFile": true
+      }
+    },
+    "tsdocMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    }
+  }
+}

package/config/jest.config.json

@@ -0,0 +1,13 @@
+{
+  "extends": "@rushstack/heft-node-rig/profiles/default/config/jest.config.json",
+  "coverageThreshold": {
+    "global": {
+      "branches": 100,
+      "functions": 100,
+      "lines": 100,
+      "statements": 100
+    }
+  },
+  "collectCoverage": true,
+  "coverageReporters": ["text", "lcov", "html"]
+}

package/config/rig.json

@@ -0,0 +1,6 @@
+// The "rig.json" file directs tools to look for their config files in an external package.
+// Documentation for this system: https://www.npmjs.com/package/@rushstack/rig-package
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@fgv/heft-dual-rig"
+}

package/dist/index.js

@@ -0,0 +1,388 @@
+/**
+ * `@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
+ */
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+import { Ollama } from 'ollama';
+import { captureAsyncResult, captureResult, succeed } from '@fgv/ts-utils';
+/**
+ * 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 function createOllamaClient(params) {
+    // The upstream `Ollama` constructor reads each config field with `?? <default>`, so omitted or
+    // `undefined` fields fall back to the library defaults — no per-field guarding needed.
+    return captureResult(() => new Ollama(params !== null && params !== void 0 ? params : {}));
+}
+// ─── Wire → fgv normalization (§6.3, Appendix) ──────────────────────────────────
+/**
+ * Maps the upstream snake_case `ModelDetails` to the normalized camelCase {@link IOllamaModelDetail}.
+ * Upstream types every field as a required `string`, but Ollama omits fields it cannot determine,
+ * so individual values may be `undefined` at runtime — the normalized type reflects that by making
+ * every field optional.
+ */
+function normalizeModelDetail(d) {
+    return {
+        format: d.format,
+        family: d.family,
+        families: d.families,
+        parameterSize: d.parameter_size,
+        quantizationLevel: d.quantization_level,
+        parentModel: d.parent_model
+    };
+}
+/**
+ * Maps a `/api/tags` `ModelResponse` to {@link IOllamaModel}. `modified_at` is normalized to a
+ * `Date` via the `Date` constructor, which accepts both the RFC3339 string the wire actually
+ * delivers and the `Date` the upstream type (inaccurately) claims.
+ */
+function normalizeModel(m) {
+    return {
+        name: m.name,
+        model: m.model,
+        size: m.size,
+        digest: m.digest,
+        details: normalizeModelDetail(m.details),
+        modifiedAt: new Date(m.modified_at)
+    };
+}
+/**
+ * Maps a `/api/ps` `ModelResponse` to {@link IOllamaRunningModel}. `/api/ps` returns `expires_at`
+ * and `size_vram` in place of `modified_at`.
+ */
+function normalizeRunningModel(m) {
+    return {
+        name: m.name,
+        model: m.model,
+        size: m.size,
+        digest: m.digest,
+        details: normalizeModelDetail(m.details),
+        expiresAt: new Date(m.expires_at),
+        sizeVram: m.size_vram
+    };
+}
+/**
+ * Normalizes the `model_info` metadata bag. The upstream type annotates it as `Map<string, any>`,
+ * but the lib returns `response.json()` verbatim, so the wire delivers a plain JSON object (or
+ * omits the field). The single `as unknown as` bridge reconciles the inaccurate upstream annotation
+ * with the actual JSON shape — there is no untyped input to validate here.
+ */
+function normalizeModelInfo(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    return raw;
+}
+/**
+ * Maps a `/api/show` `ShowResponse` to {@link IOllamaModelInfo}. The remaining `ShowResponse`
+ * fields (`license`, `system`, `messages`, `modified_at`, `projector_info`) are intentionally not
+ * carried through — they are out of scope for the v0.1 surface.
+ */
+function normalizeShowResponse(r) {
+    return {
+        modelfile: r.modelfile,
+        parameters: r.parameters,
+        template: r.template,
+        details: normalizeModelDetail(r.details),
+        modelInfo: normalizeModelInfo(r.model_info),
+        capabilities: r.capabilities
+    };
+}
+// ─── Model management primitives (§3.3) ─────────────────────────────────────────
+/**
+ * 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 async function listModels(client) {
+    return captureAsyncResult(async () => {
+        const response = await client.list();
+        return response.models.map(normalizeModel);
+    });
+}
+/**
+ * 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 async function listRunning(client) {
+    return captureAsyncResult(async () => {
+        const response = await client.ps();
+        return response.models.map(normalizeRunningModel);
+    });
+}
+/**
+ * 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 async function showModel(client, model, options) {
+    return captureAsyncResult(async () => {
+        // `verbose` is a valid `/api/show` body field that the lib forwards verbatim, but the upstream
+        // `ShowRequest` type omits it; building it as a non-literal object passes it through without a
+        // cast (and omits the key entirely when no flag was supplied).
+        const request = Object.assign({ model }, ((options === null || options === void 0 ? void 0 : options.verbose) !== undefined && { verbose: options.verbose }));
+        const response = await client.show(request);
+        return normalizeShowResponse(response);
+    });
+}
+/**
+ * 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 async function deleteModel(client, model) {
+    return captureAsyncResult(async () => {
+        await client.delete({ model });
+        return { model, deleted: true };
+    });
+}
+/**
+ * Maps an upstream `ProgressResponse` chunk to {@link IOllamaPullProgress}. The upstream type marks
+ * every field required, but the layer fields are omitted (and thus `undefined` at runtime) on the
+ * non-transfer phases — a direct structural copy preserves that, matching the optional fields.
+ */
+function normalizePullProgress(c) {
+    return {
+        status: c.status,
+        digest: c.digest,
+        total: c.total,
+        completed: c.completed
+    };
+}
+/**
+ * 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 async function pullModel(client, params) {
+    return captureAsyncResult(async () => {
+        var _a, e_1, _b, _c;
+        var _d, _e;
+        const request = Object.assign({ model: params.model, stream: true }, (params.insecure !== undefined && { insecure: params.insecure }));
+        const iterator = await client.pull(request);
+        // Wire the abort signal to the upstream iterator's abort path. An already-aborted signal
+        // cancels immediately; otherwise abort on first fire (and clean the listener up in `finally`).
+        const abortListener = () => iterator.abort();
+        if (params.signal !== undefined) {
+            if (params.signal.aborted) {
+                iterator.abort();
+            }
+            else {
+                params.signal.addEventListener('abort', abortListener, { once: true });
+            }
+        }
+        let chunkCount = 0;
+        let finalStatus = '';
+        try {
+            try {
+                for (var _f = true, iterator_1 = __asyncValues(iterator), iterator_1_1; iterator_1_1 = await iterator_1.next(), _a = iterator_1_1.done, !_a; _f = true) {
+                    _c = iterator_1_1.value;
+                    _f = false;
+                    const chunk = _c;
+                    (_d = params.onProgress) === null || _d === void 0 ? void 0 : _d.call(params, normalizePullProgress(chunk));
+                    chunkCount += 1;
+                    finalStatus = chunk.status;
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_f && !_a && (_b = iterator_1.return)) await _b.call(iterator_1);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
+        finally {
+            (_e = params.signal) === null || _e === void 0 ? void 0 : _e.removeEventListener('abort', abortListener);
+        }
+        return { model: params.model, finalStatus, chunkCount };
+    });
+}
+/**
+ * Recursively removes the JSON-Schema keywords (`$schema`, `additionalProperties`) — *if present*
+ * — that Ollama's `format` does not need. `JsonSchema.object(...).toJson()` emits
+ * `additionalProperties: false` on object nodes; `$schema` is not added by default but may appear
+ * on a runtime-discovered schema (`JsonSchema.fromJson(raw)`). Mirrors the ai-assist Gemini
+ * precedent (`toGeminiParameterSchema`): the keywords are removed only where they appear as schema
+ * *keywords* (siblings of `type`/`properties`/…). Inside a `properties` map the keys are
+ * user-defined property names, not keywords, so they are preserved verbatim while each property's
+ * subschema value is still recursively sanitized. Stripping is infallible, so it returns a plain
+ * value rather than a `Result`.
+ */
+function sanitizeFormatSchema(schema) {
+    if (Array.isArray(schema)) {
+        return schema.map(sanitizeFormatSchema);
+    }
+    if (schema !== null && typeof schema === 'object') {
+        const out = {};
+        for (const [key, value] of Object.entries(schema)) {
+            if (key === '$schema' || key === 'additionalProperties') {
+                continue;
+            }
+            if (key === 'properties' && value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                const properties = {};
+                for (const [name, propSchema] of Object.entries(value)) {
+                    properties[name] = sanitizeFormatSchema(propSchema);
+                }
+                out[key] = properties;
+            }
+            else {
+                out[key] = sanitizeFormatSchema(value);
+            }
+        }
+        return out;
+    }
+    return schema;
+}
+/**
+ * Maps an {@link IOllamaChatMessage} to the upstream `Message` wire shape, copying the optional
+ * base64 `images` array only when present.
+ */
+function toWireMessage(message) {
+    return Object.assign({ role: message.role, content: message.content }, (message.images !== undefined && { images: [...message.images] }));
+}
+/**
+ * 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 async function chatStructured(client, params) {
+    const accumulated = await captureAsyncResult(async () => {
+        var _a, e_2, _b, _c;
+        var _d;
+        const wireFormat = sanitizeFormatSchema(params.schema.toJson());
+        const request = Object.assign(Object.assign({ model: params.model, messages: params.messages.map(toWireMessage), 
+            // The wire schema accepts a plain object; the lib types `format` as `string | object`.
+            format: wireFormat, stream: true }, (params.options !== undefined && { options: params.options })), (params.keepAlive !== undefined && { keep_alive: params.keepAlive }));
+        const iterator = await client.chat(request);
+        const abortListener = () => iterator.abort();
+        if (params.signal !== undefined) {
+            if (params.signal.aborted) {
+                iterator.abort();
+            }
+            else {
+                params.signal.addEventListener('abort', abortListener, { once: true });
+            }
+        }
+        let raw = '';
+        let model = params.model;
+        let doneReason;
+        try {
+            try {
+                for (var _e = true, iterator_2 = __asyncValues(iterator), iterator_2_1; iterator_2_1 = await iterator_2.next(), _a = iterator_2_1.done, !_a; _e = true) {
+                    _c = iterator_2_1.value;
+                    _e = false;
+                    const chunk = _c;
+                    raw += chunk.message.content;
+                    model = chunk.model;
+                    if (chunk.done) {
+                        doneReason = chunk.done_reason;
+                    }
+                }
+            }
+            catch (e_2_1) { e_2 = { error: e_2_1 }; }
+            finally {
+                try {
+                    if (!_e && !_a && (_b = iterator_2.return)) await _b.call(iterator_2);
+                }
+                finally { if (e_2) throw e_2.error; }
+            }
+        }
+        finally {
+            (_d = params.signal) === null || _d === void 0 ? void 0 : _d.removeEventListener('abort', abortListener);
+        }
+        return { raw, model, doneReason };
+    });
+    return accumulated.onSuccess(({ raw, model, doneReason }) => captureResult(() => JSON.parse(raw))
+        .withErrorFormat((message) => `chatStructured(${params.model}): response was not valid JSON: ${message}`)
+        .onSuccess((parsed) => params.schema
+        .validate(parsed)
+        .withErrorFormat((message) => `chatStructured(${params.model}): response failed schema validation: ${message}`)
+        .onSuccess((value) => succeed({ value, raw, model, doneReason }))));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;;;;;;AAEH,OAAO,EACL,MAAM,EASP,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,OAAO,EAAe,MAAM,eAAe,CAAC;AA2BxF;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAkC;IACnE,+FAA+F;IAC/F,uFAAuF;IACvF,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,MAAM,CAAC,MAAM,aAAN,MAAM,cAAN,MAAM,GAAI,EAAE,CAAC,CAAC,CAAC;AACvD,CAAC;AA6FD,mFAAmF;AAEnF;;;;;GAKG;AACH,SAAS,oBAAoB,CAAC,CAAe;IAC3C,OAAO;QACL,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,aAAa,EAAE,CAAC,CAAC,cAAc;QAC/B,iBAAiB,EAAE,CAAC,CAAC,kBAAkB;QACvC,WAAW,EAAE,CAAC,CAAC,YAAY;KAC5B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,CAAgB;IACtC,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,OAAO,CAAC;QACxC,UAAU,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC;KACpC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,qBAAqB,CAAC,CAAgB;IAC7C,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,OAAO,CAAC;QACxC,SAAS,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC;QACjC,QAAQ,EAAE,CAAC,CAAC,SAAS;KACtB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,kBAAkB,CACzB,GAA+B;IAE/B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,GAAqD,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAAC,CAAe;IAC5C,OAAO;QACL,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,OAAO,CAAC;QACxC,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAC,UAAU,CAAC;QAC3C,YAAY,EAAE,CAAC,CAAC,YAAY;KAC7B,CAAC;AACJ,CAAC;AAED,mFAAmF;AAEnF;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAqB;IACpD,OAAO,kBAAkB,CAAC,KAAK,IAAI,EAAE;QACnC,MAAM,QAAQ,GAAiB,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACnD,OAAO,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAqB;IAErB,OAAO,kBAAkB,CAAC,KAAK,IAAI,EAAE;QACnC,MAAM,QAAQ,GAAiB,MAAM,MAAM,CAAC,EAAE,EAAE,CAAC;QACjD,OAAO,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAAqB,EACrB,KAAa,EACb,OAAwC;IAExC,OAAO,kBAAkB,CAAC,KAAK,IAAI,EAAE;QACnC,+FAA+F;QAC/F,+FAA+F;QAC/F,+DAA+D;QAC/D,MAAM,OAAO,mBAAK,KAAK,IAAK,CAAC,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,MAAK,SAAS,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAE,CAAC;QAC/F,MAAM,QAAQ,GAAiB,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1D,OAAO,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAqB,EACrB,KAAa;IAEb,OAAO,kBAAkB,CAAC,KAAK,IAAI,EAAE;QACnC,MAAM,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/B,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAClC,CAAC,CAAC,CAAC;AACL,CAAC;AA4DD;;;;GAIG;AACH,SAAS,qBAAqB,CAAC,CAAmB;IAChD,OAAO;QACL,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,SAAS,EAAE,CAAC,CAAC,SAAS;KACvB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAAqB,EACrB,MAAwB;IAExB,OAAO,kBAAkB,CAAC,KAAK,IAAI,EAAE;;;QACnC,MAAM,OAAO,mBACX,KAAK,EAAE,MAAM,CAAC,KAAK,EACnB,MAAM,EAAE,IAAa,IAClB,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CACpE,CAAC;QACF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAE5C,yFAAyF;QACzF,+FAA+F;QAC/F,MAAM,aAAa,GAAG,GAAS,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC;YACnB,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;QAED,IAAI,UAAU,GAAG,CAAC,CAAC;QACnB,IAAI,WAAW,GAAG,EAAE,CAAC;QACrB,IAAI,CAAC;;gBACH,KAA0B,eAAA,aAAA,cAAA,QAAQ,CAAA,cAAA,kFAAE,CAAC;oBAAX,wBAAQ;oBAAR,WAAQ;oBAAvB,MAAM,KAAK,KAAA,CAAA;oBACpB,MAAA,MAAM,CAAC,UAAU,uDAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC;oBAClD,UAAU,IAAI,CAAC,CAAC;oBAChB,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC;gBAC7B,CAAC;;;;;;;;;QACH,CAAC;gBAAS,CAAC;YACT,MAAA,MAAM,CAAC,MAAM,0CAAE,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAC7D,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1D,CAAC,CAAC,CAAC;AACL,CAAC;AA6DD;;;;;;;;;;GAUG;AACH,SAAS,oBAAoB,CAAC,MAAiB;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,GAAG,GAAe,EAAE,CAAC;QAC3B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,sBAAsB,EAAE,CAAC;gBACxD,SAAS;YACX,CAAC;YACD,IAAI,GAAG,KAAK,YAAY,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjG,MAAM,UAAU,GAAe,EAAE,CAAC;gBAClC,KAAK,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBACvD,UAAU,CAAC,IAAI,CAAC,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC;gBACtD,CAAC;gBACD,GAAG,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC;YACxB,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CAAC,OAA2B;IAChD,uBACE,IAAI,EAAE,OAAO,CAAC,IAAI,EAClB,OAAO,EAAE,OAAO,CAAC,OAAO,IACrB,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,EACpE;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAqB,EACrB,MAAgC;IAEhC,MAAM,WAAW,GAAG,MAAM,kBAAkB,CAAC,KAAK,IAAI,EAAE;;;QACtD,MAAM,UAAU,GAAG,oBAAoB,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAChE,MAAM,OAAO,iCACX,KAAK,EAAE,MAAM,CAAC,KAAK,EACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC;YAC5C,uFAAuF;YACvF,MAAM,EAAE,UAAoB,EAC5B,MAAM,EAAE,IAAI,IAGT,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,OAAsC,EAAE,CAAC,GAC5F,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CACxE,CAAC;QACF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAE5C,MAAM,aAAa,GAAG,GAAS,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC;YACnB,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;QAED,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,IAAI,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QACzB,IAAI,UAA8B,CAAC;QACnC,IAAI,CAAC;;gBACH,KAA0B,eAAA,aAAA,cAAA,QAAQ,CAAA,cAAA,kFAAE,CAAC;oBAAX,wBAAQ;oBAAR,WAAQ;oBAAvB,MAAM,KAAK,KAAA,CAAA;oBACpB,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;oBAC7B,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;oBACpB,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;wBACf,UAAU,GAAG,KAAK,CAAC,WAAW,CAAC;oBACjC,CAAC;gBACH,CAAC;;;;;;;;;QACH,CAAC;gBAAS,CAAC;YACT,MAAA,MAAM,CAAC,MAAM,0CAAE,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,OAAO,WAAW,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,CAC1D,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;SAC5C,eAAe,CACd,CAAC,OAAO,EAAE,EAAE,CAAC,kBAAkB,MAAM,CAAC,KAAK,mCAAmC,OAAO,EAAE,CACxF;SACA,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE,CACpB,MAAM,CAAC,MAAM;SACV,QAAQ,CAAC,MAAM,CAAC;SAChB,eAAe,CACd,CAAC,OAAO,EAAE,EAAE,CAAC,kBAAkB,MAAM,CAAC,KAAK,yCAAyC,OAAO,EAAE,CAC9F;SACA,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC,CACpE,CACJ,CAAC;AACJ,CAAC","sourcesContent":["/**\n * `@fgv/ts-extras-ollama` — Result-integration boundary over the official `ollama` JS library\n * (Node-side).\n *\n * A thin facade that wraps the `ollama` client's native-API calls in `Result<T>` from\n * `@fgv/ts-utils`, mirroring the discipline established by `@fgv/ts-extras-webauthn` and\n * `@fgv/ts-extras-transformers`: one-line `captureResult` / `captureAsyncResult` wrappers around\n * upstream primitives with **no opinionated orchestration** above the boundary.\n *\n * This package owns **exactly and only** the native-Ollama surface that the OpenAI-compatible\n * `/v1` endpoint cannot express: model management (`/api/tags`, `/api/show`, `/api/ps`,\n * `/api/delete`), streamed model pulls (`/api/pull`), and grammar-constrained structured output\n * (`/api/chat` with a full-JSON-schema `format`). The text-completion / streaming / tool-use path\n * is **not** duplicated here — `@fgv/ts-extras/ai-assist` owns it via the `/v1` compat layer\n * (point a provider descriptor's `endpoint` at `http://localhost:11434/v1`).\n *\n * **Explicitly NOT in scope:**\n * - Text completion / free-text chat / streaming chat (ai-assist owns it via `/v1`).\n * - Browser / CORS path (Node-only at v0.1; a future `@fgv/ts-web-extras-ollama` is its home).\n * - Model authoring / publishing (`push`, `create`, `copy`) — use the `ollama` lib directly.\n * - `keep_alive` / model-lifecycle policy — pass-through only, no policy applied.\n * - Pull-progress UI / rendering — `onProgress` hands raw chunks to the consumer.\n * - Multi-host orchestration / connection pooling / retries / backoff — one client = one host.\n *\n * For any of the above, use the `ollama` library directly (with `captureAsyncResult` for your own\n * Result wrapping); the opaque client handle returned by {@link createOllamaClient} is the\n * upstream instance, so nothing this boundary omits is hidden from you.\n *\n * @packageDocumentation\n */\n\nimport {\n  Ollama,\n  type ChatRequest,\n  type ListResponse,\n  type Message,\n  type ModelResponse,\n  type ModelDetails,\n  type Options,\n  type ProgressResponse,\n  type ShowResponse\n} from 'ollama';\nimport { captureAsyncResult, captureResult, succeed, type Result } from '@fgv/ts-utils';\nimport { type JsonObject, type JsonValue, type JsonSchema } from '@fgv/ts-json-base';\n\n/**\n * Construction parameters for an Ollama client. All optional; defaults match the `ollama` JS\n * library (host `http://127.0.0.1:11434`).\n * @public\n */\nexport interface ICreateOllamaClientParams {\n  /** Server address. Defaults to `http://127.0.0.1:11434`. */\n  readonly host?: string;\n  /**\n   * Custom `fetch` implementation. Injecting a fetch is the primary unit-test seam and the hook\n   * for a future proxy / browser path.\n   */\n  readonly fetch?: typeof fetch;\n  /** Custom headers included on every request (e.g. an auth token for a guarded sidecar). */\n  readonly headers?: Record<string, string>;\n}\n\n/**\n * Opaque client handle. Re-export of the upstream `ollama` `Ollama` instance type — consumers\n * retain full access to the upstream API for anything this boundary does not wrap.\n * @public\n */\nexport type IOllamaClient = Ollama;\n\n/**\n * Constructs an Ollama client. Synchronous (the constructor performs no I/O), so returns\n * `Result<IOllamaClient>` rather than a promise. A malformed `host` (which the upstream\n * constructor rejects) surfaces as `Result.fail`.\n *\n * @param params - Optional {@link ICreateOllamaClientParams}. Omitted fields fall back to the\n *   `ollama` library defaults.\n * @returns `Result<IOllamaClient>` wrapping the upstream `Ollama` instance.\n * @public\n */\nexport function createOllamaClient(params?: ICreateOllamaClientParams): Result<IOllamaClient> {\n  // The upstream `Ollama` constructor reads each config field with `?? <default>`, so omitted or\n  // `undefined` fields fall back to the library defaults — no per-field guarding needed.\n  return captureResult(() => new Ollama(params ?? {}));\n}\n\n// ─── Shared normalized model types (§3.2) ───────────────────────────────────────\n\n/**\n * GGUF / model detail block, common to `/api/tags`, `/api/ps`, and `/api/show`. All fields\n * optional — Ollama omits any it cannot determine.\n * @public\n */\nexport interface IOllamaModelDetail {\n  /** Storage format, e.g. `'gguf'`. */\n  readonly format?: string;\n  /** Primary architecture family, e.g. `'llama'`. */\n  readonly family?: string;\n  /** All architecture families this model belongs to. */\n  readonly families?: ReadonlyArray<string>;\n  /** Human-readable parameter count, e.g. `'8.0B'`. */\n  readonly parameterSize?: string;\n  /** Quantization level, e.g. `'Q4_0'`. */\n  readonly quantizationLevel?: string;\n  /** Parent model for fine-tunes / derived models. */\n  readonly parentModel?: string;\n}\n\n/**\n * Fields common to a locally-stored model and a running model.\n * @public\n */\nexport interface IOllamaModelBase {\n  /** Tagged name, e.g. `'llama3.1:8b'`. */\n  readonly name: string;\n  /** Underlying model id (often equal to `name`). */\n  readonly model: string;\n  /** On-disk size in bytes. */\n  readonly size: number;\n  /** SHA-256 manifest digest. */\n  readonly digest: string;\n  /** GGUF / architecture detail. */\n  readonly details: IOllamaModelDetail;\n}\n\n/**\n * A model present in the local store (`/api/tags`).\n * @public\n */\nexport interface IOllamaModel extends IOllamaModelBase {\n  /** Last-modified timestamp, parsed from the RFC3339 wire value. */\n  readonly modifiedAt: Date;\n}\n\n/**\n * A model currently loaded into memory (`/api/ps`). Note `/api/ps` does NOT return\n * `modified_at`, so this does not extend {@link IOllamaModel}.\n * @public\n */\nexport interface IOllamaRunningModel extends IOllamaModelBase {\n  /** When the model will be unloaded, parsed from the RFC3339 wire value. */\n  readonly expiresAt: Date;\n  /** Bytes resident in VRAM (0 when fully on CPU). */\n  readonly sizeVram: number;\n}\n\n/**\n * Full model detail, capabilities, parameters, and template (`POST /api/show`).\n * @public\n */\nexport interface IOllamaModelInfo {\n  /** The Modelfile source, when returned. */\n  readonly modelfile?: string;\n  /** Default parameters string. */\n  readonly parameters?: string;\n  /** The prompt template. */\n  readonly template?: string;\n  /** GGUF / architecture detail. */\n  readonly details: IOllamaModelDetail;\n  /** Low-level model metadata key-value map (`model_info`). */\n  readonly modelInfo?: Readonly<Record<string, JsonValue>>;\n  /** Declared capabilities, e.g. `['completion', 'tools', 'vision', 'thinking']`. */\n  readonly capabilities?: ReadonlyArray<string>;\n}\n\n/**\n * Result of a delete. Returns a meaningful value rather than `Result<void>` (per repo standards —\n * `Result<void>` is an anti-pattern).\n * @public\n */\nexport interface IOllamaDeleteResult {\n  /** The model that was deleted. */\n  readonly model: string;\n  /** Always `true` — a failed delete surfaces as `Result.fail`, never `deleted: false`. */\n  readonly deleted: true;\n}\n\n// ─── Wire → fgv normalization (§6.3, Appendix) ──────────────────────────────────\n\n/**\n * Maps the upstream snake_case `ModelDetails` to the normalized camelCase {@link IOllamaModelDetail}.\n * Upstream types every field as a required `string`, but Ollama omits fields it cannot determine,\n * so individual values may be `undefined` at runtime — the normalized type reflects that by making\n * every field optional.\n */\nfunction normalizeModelDetail(d: ModelDetails): IOllamaModelDetail {\n  return {\n    format: d.format,\n    family: d.family,\n    families: d.families,\n    parameterSize: d.parameter_size,\n    quantizationLevel: d.quantization_level,\n    parentModel: d.parent_model\n  };\n}\n\n/**\n * Maps a `/api/tags` `ModelResponse` to {@link IOllamaModel}. `modified_at` is normalized to a\n * `Date` via the `Date` constructor, which accepts both the RFC3339 string the wire actually\n * delivers and the `Date` the upstream type (inaccurately) claims.\n */\nfunction normalizeModel(m: ModelResponse): IOllamaModel {\n  return {\n    name: m.name,\n    model: m.model,\n    size: m.size,\n    digest: m.digest,\n    details: normalizeModelDetail(m.details),\n    modifiedAt: new Date(m.modified_at)\n  };\n}\n\n/**\n * Maps a `/api/ps` `ModelResponse` to {@link IOllamaRunningModel}. `/api/ps` returns `expires_at`\n * and `size_vram` in place of `modified_at`.\n */\nfunction normalizeRunningModel(m: ModelResponse): IOllamaRunningModel {\n  return {\n    name: m.name,\n    model: m.model,\n    size: m.size,\n    digest: m.digest,\n    details: normalizeModelDetail(m.details),\n    expiresAt: new Date(m.expires_at),\n    sizeVram: m.size_vram\n  };\n}\n\n/**\n * Normalizes the `model_info` metadata bag. The upstream type annotates it as `Map<string, any>`,\n * but the lib returns `response.json()` verbatim, so the wire delivers a plain JSON object (or\n * omits the field). The single `as unknown as` bridge reconciles the inaccurate upstream annotation\n * with the actual JSON shape — there is no untyped input to validate here.\n */\nfunction normalizeModelInfo(\n  raw: ShowResponse['model_info']\n): Readonly<Record<string, JsonValue>> | undefined {\n  if (raw === undefined) {\n    return undefined;\n  }\n  return raw as unknown as Readonly<Record<string, JsonValue>>;\n}\n\n/**\n * Maps a `/api/show` `ShowResponse` to {@link IOllamaModelInfo}. The remaining `ShowResponse`\n * fields (`license`, `system`, `messages`, `modified_at`, `projector_info`) are intentionally not\n * carried through — they are out of scope for the v0.1 surface.\n */\nfunction normalizeShowResponse(r: ShowResponse): IOllamaModelInfo {\n  return {\n    modelfile: r.modelfile,\n    parameters: r.parameters,\n    template: r.template,\n    details: normalizeModelDetail(r.details),\n    modelInfo: normalizeModelInfo(r.model_info),\n    capabilities: r.capabilities\n  };\n}\n\n// ─── Model management primitives (§3.3) ─────────────────────────────────────────\n\n/**\n * Lists models in the local store (`GET /api/tags`). Each entry is normalized to\n * {@link IOllamaModel} (camelCase, `modifiedAt` as a `Date`).\n *\n * @param client - A client from {@link createOllamaClient}.\n * @returns `Promise<Result<ReadonlyArray<IOllamaModel>>>`; upstream / transport errors are captured\n *   as `Failure`.\n * @public\n */\nexport async function listModels(client: IOllamaClient): Promise<Result<ReadonlyArray<IOllamaModel>>> {\n  return captureAsyncResult(async () => {\n    const response: ListResponse = await client.list();\n    return response.models.map(normalizeModel);\n  });\n}\n\n/**\n * Lists models currently loaded into memory (`GET /api/ps`). Each entry is normalized to\n * {@link IOllamaRunningModel} (camelCase, `expiresAt` as a `Date`, `sizeVram` in bytes).\n *\n * @param client - A client from {@link createOllamaClient}.\n * @returns `Promise<Result<ReadonlyArray<IOllamaRunningModel>>>`; upstream / transport errors are\n *   captured as `Failure`.\n * @public\n */\nexport async function listRunning(\n  client: IOllamaClient\n): Promise<Result<ReadonlyArray<IOllamaRunningModel>>> {\n  return captureAsyncResult(async () => {\n    const response: ListResponse = await client.ps();\n    return response.models.map(normalizeRunningModel);\n  });\n}\n\n/**\n * Full model detail, capabilities, parameters, and template (`POST /api/show`), normalized to\n * {@link IOllamaModelInfo}.\n *\n * @param client - A client from {@link createOllamaClient}.\n * @param model - The model name to inspect, e.g. `'llama3.1:8b'`.\n * @param options - Optional flags. `verbose: true` requests the full low-level `model_info` block.\n * @returns `Promise<Result<IOllamaModelInfo>>`; upstream / transport errors (e.g. unknown model)\n *   are captured as `Failure`.\n * @public\n */\nexport async function showModel(\n  client: IOllamaClient,\n  model: string,\n  options?: { readonly verbose?: boolean }\n): Promise<Result<IOllamaModelInfo>> {\n  return captureAsyncResult(async () => {\n    // `verbose` is a valid `/api/show` body field that the lib forwards verbatim, but the upstream\n    // `ShowRequest` type omits it; building it as a non-literal object passes it through without a\n    // cast (and omits the key entirely when no flag was supplied).\n    const request = { model, ...(options?.verbose !== undefined && { verbose: options.verbose }) };\n    const response: ShowResponse = await client.show(request);\n    return normalizeShowResponse(response);\n  });\n}\n\n/**\n * Deletes a model from the local store (`DELETE /api/delete`). Returns a meaningful\n * {@link IOllamaDeleteResult} rather than `Result<void>`.\n *\n * @param client - A client from {@link createOllamaClient}.\n * @param model - The model name to delete.\n * @returns `Promise<Result<IOllamaDeleteResult>>`; a missing model or transport error surfaces as\n *   `Failure`.\n * @public\n */\nexport async function deleteModel(\n  client: IOllamaClient,\n  model: string\n): Promise<Result<IOllamaDeleteResult>> {\n  return captureAsyncResult(async () => {\n    await client.delete({ model });\n    return { model, deleted: true };\n  });\n}\n\n// ─── Pull with streamed progress (§3.4, §5) ─────────────────────────────────────\n\n/**\n * A single progress chunk from a streamed pull (`/api/pull`). Ollama emits a JSON-lines stream;\n * each line is one of these. Fields map 1:1 from the upstream `ProgressResponse`; the layer fields\n * (`digest`/`total`/`completed`) are `undefined` on the manifest / verify / write phases.\n * @public\n */\nexport interface IOllamaPullProgress {\n  /**\n   * Phase string, e.g. `'pulling manifest'`, `'pulling <digest>'`, `'verifying sha256 digest'`,\n   * `'writing manifest'`, `'success'`.\n   */\n  readonly status: string;\n  /** Layer digest being transferred (present during `'pulling <digest>'` phases). */\n  readonly digest?: string;\n  /** Total bytes for the current layer, when known. */\n  readonly total?: number;\n  /** Bytes transferred so far for the current layer, when known. */\n  readonly completed?: number;\n}\n\n/**\n * Terminal result of a completed pull. Returns a meaningful value (not `Result<void>`): the final\n * status plus a count of progress chunks observed.\n * @public\n */\nexport interface IOllamaPullResult {\n  /** The model that was pulled. */\n  readonly model: string;\n  /** The `status` of the final chunk, normally `'success'`. */\n  readonly finalStatus: string;\n  /** Number of progress chunks observed (useful for tests and diagnostics). */\n  readonly chunkCount: number;\n}\n\n/**\n * Parameters for {@link pullModel}.\n * @public\n */\nexport interface IPullModelParams {\n  /** Model to pull, e.g. `'llama3.1:8b'`. */\n  readonly model: string;\n  /** Allow pulling from insecure (non-TLS) registries. */\n  readonly insecure?: boolean;\n  /**\n   * Progress callback, invoked once per JSON-lines chunk as it arrives. The `Result` returned by\n   * {@link pullModel} resolves only after the stream terminates; progress is surfaced here in the\n   * interim. A throw from this callback fails the whole pull (it runs inside the captured loop).\n   */\n  readonly onProgress?: (progress: IOllamaPullProgress) => void;\n  /**\n   * Abort signal. Cancels the in-flight pull; the upstream stream throws an `AbortError`, which\n   * surfaces as `Result.fail`. An already-aborted signal cancels immediately.\n   */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Maps an upstream `ProgressResponse` chunk to {@link IOllamaPullProgress}. The upstream type marks\n * every field required, but the layer fields are omitted (and thus `undefined` at runtime) on the\n * non-transfer phases — a direct structural copy preserves that, matching the optional fields.\n */\nfunction normalizePullProgress(c: ProgressResponse): IOllamaPullProgress {\n  return {\n    status: c.status,\n    digest: c.digest,\n    total: c.total,\n    completed: c.completed\n  };\n}\n\n/**\n * Pulls a model with streamed progress (`POST /api/pull`). Drives the upstream JSON-lines stream\n * internally, invoking `params.onProgress` once per chunk, and resolves the `Result` once the\n * stream terminates. Any upstream error — connection drop, registry 404, abort, or a throwing\n * `onProgress` — becomes a single `Failure`; success returns a meaningful {@link IOllamaPullResult}\n * rather than `Result<void>`.\n *\n * @param client - A client from {@link createOllamaClient}.\n * @param params - {@link IPullModelParams} — the model, optional `insecure` flag, optional\n *   `onProgress` callback, and optional `AbortSignal`.\n * @returns `Promise<Result<IOllamaPullResult>>`.\n * @public\n */\nexport async function pullModel(\n  client: IOllamaClient,\n  params: IPullModelParams\n): Promise<Result<IOllamaPullResult>> {\n  return captureAsyncResult(async () => {\n    const request = {\n      model: params.model,\n      stream: true as const,\n      ...(params.insecure !== undefined && { insecure: params.insecure })\n    };\n    const iterator = await client.pull(request);\n\n    // Wire the abort signal to the upstream iterator's abort path. An already-aborted signal\n    // cancels immediately; otherwise abort on first fire (and clean the listener up in `finally`).\n    const abortListener = (): void => iterator.abort();\n    if (params.signal !== undefined) {\n      if (params.signal.aborted) {\n        iterator.abort();\n      } else {\n        params.signal.addEventListener('abort', abortListener, { once: true });\n      }\n    }\n\n    let chunkCount = 0;\n    let finalStatus = '';\n    try {\n      for await (const chunk of iterator) {\n        params.onProgress?.(normalizePullProgress(chunk));\n        chunkCount += 1;\n        finalStatus = chunk.status;\n      }\n    } finally {\n      params.signal?.removeEventListener('abort', abortListener);\n    }\n\n    return { model: params.model, finalStatus, chunkCount };\n  });\n}\n\n// ─── Grammar-constrained structured output (§3.5, §4) ───────────────────────────\n\n/**\n * A chat message in Ollama native shape.\n * @public\n */\nexport interface IOllamaChatMessage {\n  /** The message role. */\n  readonly role: 'system' | 'user' | 'assistant' | 'tool';\n  /** The message text. */\n  readonly content: string;\n  /** Base64 image data for vision models (no `data:` prefix). */\n  readonly images?: ReadonlyArray<string>;\n}\n\n/**\n * Result of a grammar-constrained structured chat. Carries both the validated typed value and the\n * raw JSON text the model emitted, for diagnostics.\n * @public\n */\nexport interface IOllamaChatStructuredResult<T> {\n  /** The parsed-and-validated value (validated by the same schema sent on the wire). */\n  readonly value: T;\n  /** The raw `message.content` JSON string the model emitted (assembled across stream chunks). */\n  readonly raw: string;\n  /** The model that produced the response. */\n  readonly model: string;\n  /** Provider-reported finish reason, when present. */\n  readonly doneReason?: string;\n}\n\n/**\n * Parameters for {@link chatStructured}.\n * @public\n */\nexport interface IChatStructuredParams<T> {\n  /** The model to chat with, e.g. `'llama3.1:8b'`. */\n  readonly model: string;\n  /** The conversation so far. */\n  readonly messages: ReadonlyArray<IOllamaChatMessage>;\n  /**\n   * The single source of truth for both the wire schema (`schema.toJson()`, sent as the native\n   * `format` field) and the result validator (`schema.validate()`). Author with\n   * `JsonSchema.object(...)` from `@fgv/ts-json-base`; `T` is derived via\n   * `JsonSchema.Static<typeof schema>`. A runtime-discovered (MCP) schema parsed via\n   * `JsonSchema.fromJson(raw)` also works — its `T` is `JsonValue`.\n   */\n  readonly schema: JsonSchema.ISchemaValidator<T>;\n  /** Native Ollama `options` (temperature, num_ctx, seed, …). Passed verbatim. */\n  readonly options?: Readonly<Record<string, JsonValue>>;\n  /** Native `keep_alive` (duration string or seconds). Passed verbatim — no policy applied. */\n  readonly keepAlive?: string | number;\n  /**\n   * Abort signal. Cancels the in-flight generation; the upstream stream throws an `AbortError`,\n   * which surfaces as `Result.fail`. An already-aborted signal cancels immediately.\n   */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Recursively removes the JSON-Schema keywords (`$schema`, `additionalProperties`) — *if present*\n * — that Ollama's `format` does not need. `JsonSchema.object(...).toJson()` emits\n * `additionalProperties: false` on object nodes; `$schema` is not added by default but may appear\n * on a runtime-discovered schema (`JsonSchema.fromJson(raw)`). Mirrors the ai-assist Gemini\n * precedent (`toGeminiParameterSchema`): the keywords are removed only where they appear as schema\n * *keywords* (siblings of `type`/`properties`/…). Inside a `properties` map the keys are\n * user-defined property names, not keywords, so they are preserved verbatim while each property's\n * subschema value is still recursively sanitized. Stripping is infallible, so it returns a plain\n * value rather than a `Result`.\n */\nfunction sanitizeFormatSchema(schema: JsonValue): JsonValue {\n  if (Array.isArray(schema)) {\n    return schema.map(sanitizeFormatSchema);\n  }\n  if (schema !== null && typeof schema === 'object') {\n    const out: JsonObject = {};\n    for (const [key, value] of Object.entries(schema)) {\n      if (key === '$schema' || key === 'additionalProperties') {\n        continue;\n      }\n      if (key === 'properties' && value !== null && typeof value === 'object' && !Array.isArray(value)) {\n        const properties: JsonObject = {};\n        for (const [name, propSchema] of Object.entries(value)) {\n          properties[name] = sanitizeFormatSchema(propSchema);\n        }\n        out[key] = properties;\n      } else {\n        out[key] = sanitizeFormatSchema(value);\n      }\n    }\n    return out;\n  }\n  return schema;\n}\n\n/**\n * Maps an {@link IOllamaChatMessage} to the upstream `Message` wire shape, copying the optional\n * base64 `images` array only when present.\n */\nfunction toWireMessage(message: IOllamaChatMessage): Message {\n  return {\n    role: message.role,\n    content: message.content,\n    ...(message.images !== undefined && { images: [...message.images] })\n  };\n}\n\n/**\n * Single-turn grammar-constrained structured chat (`POST /api/chat` with `format` = full JSON\n * schema). The fidelity win over ai-assist's prompt-and-parse path is **grammar-constrained\n * sampling**: Ollama restricts the token sampler to the supplied schema, so the response is\n * structurally guaranteed to match.\n *\n * The schema is the single source of truth: `schema.toJson()` (draft-07-sanitized) is sent as the\n * wire `format`, and the same `schema.validate()` checks the reply — they cannot drift. `T` flows\n * end-to-end from `JsonSchema.Static<typeof schema>`; no caller-supplied `T`, no cast.\n *\n * Runs over the streaming chat path internally, assembling the full document from the stream\n * chunks and validating it whole — partial JSON has no validation value. (The design §4 sketch\n * said `stream: false`, but the locked OQ-3 amendment requires an `AbortSignal`, and the `ollama`\n * lib only threads a signal on the streaming path — its non-streaming request has no signal\n * plumbing. The streaming `AbortableAsyncIterator.abort()` is \"the mechanism that already exists\n * for `pullModel`\".) Any upstream error, abort, parse failure, or validation failure surfaces as a\n * single `Failure` with context.\n *\n * @param client - A client from {@link createOllamaClient}.\n * @param params - {@link IChatStructuredParams} — model, messages, the `JsonSchema` schema, and\n *   optional `options` / `keepAlive` / `signal`.\n * @returns `Promise<Result<IOllamaChatStructuredResult<T>>>`.\n * @public\n */\nexport async function chatStructured<T>(\n  client: IOllamaClient,\n  params: IChatStructuredParams<T>\n): Promise<Result<IOllamaChatStructuredResult<T>>> {\n  const accumulated = await captureAsyncResult(async () => {\n    const wireFormat = sanitizeFormatSchema(params.schema.toJson());\n    const request: ChatRequest & { stream: true } = {\n      model: params.model,\n      messages: params.messages.map(toWireMessage),\n      // The wire schema accepts a plain object; the lib types `format` as `string | object`.\n      format: wireFormat as object,\n      stream: true,\n      // The lib types `options` narrowly as `Partial<Options>`, but the native API accepts an\n      // arbitrary option bag forwarded verbatim — bridge the (overly narrow) upstream type.\n      ...(params.options !== undefined && { options: params.options as unknown as Partial<Options> }),\n      ...(params.keepAlive !== undefined && { keep_alive: params.keepAlive })\n    };\n    const iterator = await client.chat(request);\n\n    const abortListener = (): void => iterator.abort();\n    if (params.signal !== undefined) {\n      if (params.signal.aborted) {\n        iterator.abort();\n      } else {\n        params.signal.addEventListener('abort', abortListener, { once: true });\n      }\n    }\n\n    let raw = '';\n    let model = params.model;\n    let doneReason: string | undefined;\n    try {\n      for await (const chunk of iterator) {\n        raw += chunk.message.content;\n        model = chunk.model;\n        if (chunk.done) {\n          doneReason = chunk.done_reason;\n        }\n      }\n    } finally {\n      params.signal?.removeEventListener('abort', abortListener);\n    }\n    return { raw, model, doneReason };\n  });\n\n  return accumulated.onSuccess(({ raw, model, doneReason }) =>\n    captureResult(() => JSON.parse(raw) as unknown)\n      .withErrorFormat(\n        (message) => `chatStructured(${params.model}): response was not valid JSON: ${message}`\n      )\n      .onSuccess((parsed) =>\n        params.schema\n          .validate(parsed)\n          .withErrorFormat(\n            (message) => `chatStructured(${params.model}): response failed schema validation: ${message}`\n          )\n          .onSuccess((value) => succeed({ value, raw, model, doneReason }))\n      )\n  );\n}\n"]}