@nemesis-oss/ollama-sdk 1.12.1 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [1.14.0] — Speculative-decoding model assembly & the public testing subpath: `draftGguf`, `draft_num_predict` docs, `@nemesis-oss/ollama-sdk/testing`
+
+The October 12 digest ("Speculative Decoding & Draft Model Creation") reviewed the official model-creation surfaces — `draft_files` + `draft_quantize` on `POST /api/create`, the `draft_num_predict` Modelfile parameter and runtime option — and asked for an exportable zero-network mock server. Audited against the codebase first (see [ADR 0029](./docs/adr/0029-public-testing-subpath-speculative-draft-conveniences.md)): the digest's headline typing claims were stale — `draft_files`/`draft_quantize` already shipped on both the generated `CreateRequest` and the hand-written `CreateRequestOptions` (official OpenAPI, 2026-10-07 pin), and `draft_num_predict` was already typed + documented on the runtime `ModelOptions`; the "DRAFT `<model>`" Modelfile instruction the digest describes is not in the current official docs (only the parameter is). The real gaps — a path-based draft upload convenience, wire tests, discoverable documentation, and the not-exported mock server — are closed here. All additive, no breaking changes. 932 pre-existing tests stay green, 28 new tests added.
+
+### Speculative model assembly (`createModelFromGguf` → `draftGguf`)
+
+- **`CreateModelFromGgufOptions.draftGguf`**: pass the draft network's GGUF path(s) alongside the primary shards — each is uploaded as a blob and assembled into `draft_files` under its basename, the same protocol as primary shards. Split draft GGUFs, explicit `draft_files` digest maps (merged; path uploads win on basename collision), and `draft_quantize` passthrough all work; no draft → no `draft_files` key on the wire at all.
+- **Discoverable speculative-decoding docs**: `CreateRequestOptions.parameters` now documents `draft_num_predict` (separate draft models default to 4; `0` disables drafting; embedded MTP tensors require setting it explicitly — official Modelfile reference), and `draft_files`/`draft_quantize` carry the speculative-decoding context with the verification-semantics note that makes aggressive draft compression safe.
+- Wire tests pin the whole contract: `createModel` round-trips `draft_files` + `draft_quantize` + `parameters.draft_num_predict`; `createModelFromGguf` uploads draft blobs separately (HEAD + POST per shard) and never leaks `draftGguf` or empty maps into the request body.
+
+### Public testing subpath (`@nemesis-oss/ollama-sdk/testing`)
+
+- The SDK's internal mock engine is **promoted, not forked** (ADR 0029, same discipline as ADRs 0027/0028): `test/mocks/ollama-mock-server.ts` is now a re-export shim, so the SDK's own suite exercises exactly the code consumers import.
+- **`createMockOllamaServer(options?)`** — the recommended factory. Built-in **default routes** answer the official liveness probe (`HEAD /` → 200, `GET /` → the plain-text body "Ollama is running" byte-for-byte) and `GET /api/version` (configurable version, default `0.14.0`), so `client.ping()` works against a fresh mock with zero setup. `defaultRoutes: false` restores bare 404s; `register()` always wins over the defaults.
+- **Request recording** — `server.requests` captures every request (method, path, parsed body, timestamp), including default-route hits and 404s; `clearRequests()` for `beforeEach` hooks. Wire-level assertions without per-route callbacks.
+- **In-band mid-stream error injection** — `injectErrorFrame: { message, after? }` emits an `{"error": "..."}` NDJSON frame while HTTP stays 200, exactly how a real daemon reports GPU OOM/driver crashes mid-generation. The default injection point is `chunks.length - 1`: every content chunk, then the error frame, with the final `done` frame never emitted — an error frame after `done` would be unread (the stream has already completed cleanly). `after: 0` errors before any content; explicit larger values move the position. The SDK's stream readers raise `OllamaStreamError` with the partial content.
+- **`rawBody`** route option for exact non-NDJSON bodies (the liveness body uses it — no trailing newline).
+- **Chunk builders** producing correctly-shaped `/api/chat` frames: `mockChatChunk` (one frame, counter defaults on the done frame for telemetry paths), `mockTextChunks` (chunked text + done frame), and `mockToolCallChunks` — parallel tool calls in one frame, the documented native shape, followed by the done frame.
+- **Packaging**: dedicated `./testing` entry in the exports map (paired `.d.ts`/`.d.cts`), a new tsup entry, and the consumer-type verification now compiles a real CJS (node16) **and** ESM (nodenext) consumer importing the subpath. Node.js-only by design (`node:http`) — never imported from the Edge-safe main entry, so `verify:edge-runtime` stays clean.
+
+### Lab
+
+- `lab/15-speculative-draft/measure-draft-speedup.ts`: live harness comparing `draft_num_predict` 0/4/8/16 — warm-up per setting, 5 samples each, median `tokensPerSecond` via `formatTelemetry`, and a speedup table against drafting-disabled. Makes "the server has no draft network, the option is being ignored" obvious at a glance.
+
+## [1.13.0] — docs.ollama.com re-audit: parity verifier reads checkbox state, strict compat types, web-search agent tools
+
+A full re-read of docs.ollama.com (API reference, capability guides, integrations, OpenAPI spec) against the SDK. The native API was already at parity except for two upstream changes; the real defect was in the compatibility-parity tooling, which had been reporting fields Ollama documents as unsupported as "supported".
+
+### Fixed
+
+- **Contract-parity verifier ignored `[ ]` (unsupported) checkboxes.** `verify:contract-parity` fetched the rendered HTML docs, which drop checkbox state, and the pinned fallback had been rewritten to `[Input]` markers — so every listed field read as supported and the OpenAI overlay claimed support for `tool_choice`, `logit_bias`, `user`, `n` and logprobs (chat), `best_of`, `echo`, `logit_bias`, `user`, `n` and logprobs (completions), `user` (embeddings) and `truncation` (responses). The fetcher now prefers the Mintlify markdown twin (`<page>.md`), endpoint sections are bounded by heading level (backticked headings supported), unchecked feature items (`* [ ] Logprobs`) read as unsupported, and unchecked request-field items count as explicit unsupported evidence. The overlay and IR are corrected (`logprobs` capability is now `unsupported` on `/v1/chat/completions` and `/v1/completions`), and the pinned fallbacks are re-pinned from the live markdown with checkbox state intact.
+- **Strict compatibility request types now exclude documented-unsupported fields.** `OllamaOpenAIChatCompletionRequest` drops `tool_choice`, `logit_bias`, `user`, `n`, `logprobs`, `top_logprobs`; `OllamaOpenAICompletionRequest` drops `best_of`, `echo`, `logit_bias`, `user`, `n`, `logprobs`; `OllamaOpenAIEmbeddingRequest` drops `user` and narrows `input` to `string | string[]`; `OllamaOpenAIResponsesRequest` also drops `truncation`. Passing them is now a compile error (pinned by `@ts-expect-error` tests run under `npm run typecheck`). **Type-level breaking change only for code that opted into the strict types** — the broad `OpenAI*` interop types are unchanged.
+
+### Upstream API changes picked up
+
+- **System One `choice` criteria limit raised from 26 to 255** (model-dependent) — generated Zod schema and request type updated; `score` stays at 2–26.
+- **`/api/copy` documents a JSON `{ "status": "success" }` body** plus 400/404 error responses — the generated `NativeApi.copy()` now returns `StatusResponse` instead of `unknown`.
+
+### Added
+
+- **`createWebTools(client, options?)`** (plus `createWebSearchTool`, `createWebFetchTool`, `formatWebSearchResult`, `formatWebFetchResult`): Ollama Cloud web search/fetch as model-callable `web_search`/`web_fetch` tools for `ToolRegistry`/`Agent` — the documented "Building a search agent" pattern. Arguments are validated at the registry boundary (`query`/`url` non-empty, `max_results` 1–10) before any network call; the abort signal propagates; output is bounded by `maxOutputChars` (default `2000 * 4`, as in the docs) by trimming content fields so it always stays valid JSON; `web_fetch` caps links (`maxLinks`, default 25). New example: `examples/web-search-agent.ts`.
+- Tests for direct Ollama Cloud access through the bridges (`https://ollama.com/v1/chat/completions`, `/v1/responses`, `/v1/messages` with `Authorization: Bearer` and `anthropic-version: 2023-06-01`), docs-parser regression tests against the pinned markdown, and strict-type compile tests.
+
+- **Strict chat images are base64-only.** `OllamaOpenAIChatContentPart.image_url` is now `` `data:${string}` `` (string or `{ url, detail? }`), so a remote `http(s)://` image URL — documented as unsupported on `/v1/chat/completions` — is a compile error. `OllamaOpenAIChatMessage`, `OllamaOpenAIChatContentPart`, and `OllamaOpenAIImageDataUrl` are now exported from the package root.
+- OpenAPI source descriptions synced with upstream (System One `noul`/`score` criteria, `UsageResponse.granularity`). The one remaining intentional deviation — nullable `ModelSummary.details.families`, because the server serializes a nil slice as `null` — is documented in the source header and pinned by a test.
+
+### Documentation
+
+- README and docs-site OpenAI/Anthropic guides: per-endpoint supported vs documented-unsupported tables, direct cloud access sections, and a web search agent section.
+
 ## [1.12.1] — Fix: model-affinity routing respects priority tiers
 
 ### Fixed

package/README.md

@@ -28,12 +28,13 @@ Nexum’s model harness (2026-10-09) exercised this SDK via `gemma4:cloud` and `
 - 🌐 **High Availability & Failover**: Multi-endpoint registry with priority routing, circuit breaker failover, active health checks, and per-endpoint `models` allow-lists for routing several model-specific API keys through one client.
 - 🔌 **Model Context Protocol (MCP)**: First-class, transport-neutral `McpBridge` for converting MCP tool descriptors into Ollama function definitions and registering executable MCP-backed tools.
 - 📚 **Full Model Lifecycle**: `pullModel`, `pushModel`, `createModel`, `copyModel`, `deleteModel`, `listModels`, `showModel`, and `ps()` (currently loaded models) — full parity with Ollama's model management API.
-- 🔎 **Ollama Cloud Web Tools**: `webSearch`/`webFetch` wrap Ollama's hosted `/api/web_search` and `/api/web_fetch` tools at `ollama.com` (requires an `OLLAMA_API_KEY`), independent of any local `baseUrl`.
+- 🔎 **Ollama Cloud Web Tools**: `webSearch`/`webFetch` wrap Ollama's hosted `/api/web_search` and `/api/web_fetch` tools at `ollama.com` (requires an `OLLAMA_API_KEY`), independent of any local `baseUrl` — and `createWebTools(client)` exposes them as model-callable `web_search`/`web_fetch` tools with bounded, valid-JSON output for the documented search-agent pattern.
 - 💳 **Ollama Cloud Usage & Balance**: `usage()`/`balance()` wrap Ollama's hosted account endpoints (`GET /api/usage`, `GET /api/balance`) — request counts, USD spend, cached-token totals bucketed by hour/day, and remaining included/purchased credits (including the legacy session/weekly plan shapes) — with the same fixed-cloud-host, API-key, timeout, and retry semantics as the web tools.
 - 🌉 **OpenAI & Anthropic Compatibility Bridges**: Built-in clients for `/v1/chat/completions`, `/v1/responses`, `/v1/models`, and `/v1/messages`, including `reasoning_effort`/`reasoning.effort` for thinking models — plus an ergonomic dual-mode `client.responses.create()` bridge that prefers native `/v1/responses` and transparently re-issues via `/api/chat` on older servers (pre-v0.13.3).
 - 💬 **KV-Cache-Aware Conversation Sessions**: `client.session(model, systemPrompt)` keeps an append-only, prefix-stable history that maximizes Ollama's KV-cache reuse across turns, surfaces per-turn + cumulative cache hit rates (`prompt_eval_cached_count`) so cache degradation is visible instead of silent, and offers a one-call `compact()` sliding-window escape hatch when a session outgrows its window.
 - 🛑 **Context-Window Safety**: Heuristic client-side token estimation warns (or throws, `onContextOverflow: 'throw'`) before a request is sent when the prompt approaches the effective `num_ctx` window — Ollama's default behavior is to _silently truncate_ oversized prompts — and `defaultContextLength` makes the window explicit on every request.
-- 📦 **Blob & Custom Model Publishing**: Content-addressed blob management per Ollama's documented protocol — `computeBlobDigest()` (SHA-256 → `sha256:<hex>`), `createBlobFromData()`/`createBlobFromFile()` (HEAD-check + upload, skipping existing blobs), and one-shot `createModelFromGguf()` (upload GGUF shard blobs, then `/api/create` with `files: {name: digest}`).
+- 📦 **Blob & Custom Model Publishing**: Content-addressed blob management per Ollama's documented protocol — `computeBlobDigest()` (SHA-256 → `sha256:<hex>`), `createBlobFromData()`/`createBlobFromFile()` (HEAD-check + upload, skipping existing blobs), and one-shot `createModelFromGguf()` (upload GGUF shard blobs, then `/api/create` with `files: {name: digest}`) — with **speculative-decoding assembly**: `draftGguf` uploads the draft network's shards into `draft_files`, `draft_quantize` compresses them independently, and `parameters.draft_num_predict` tunes the per-step draft length.
+- 🧪 **In-Memory Mock Server (`@nemesis-oss/ollama-sdk/testing`)**: The SDK's own deterministic test double, promoted public — `createMockOllamaServer()` with scriptable NDJSON routes, built-in liveness/version defaults (so `ping()` works out of the box), request recording for wire-level assertions, mid-stream **in-band error injection** (`{"error": "..."}` frames at HTTP 200, exactly how a real daemon reports GPU OOM), connection drops, and correctly-shaped chunk builders for streaming text and **parallel tool calls** — zero network, zero daemon, CI-deterministic.
 - 🧵 **Batched Embeddings with Backpressure**: `client.embedBatch()` splits corpora of any size into bounded `/api/embed` batches (default 32 inputs × 3 in flight) — order-preserving, fail-fast, progress-reporting — so RAG/vector ingestion can't OOM a local daemon or saturate `OLLAMA_MAX_QUEUE` the way `Promise.all` floods do, with per-string context-window pre-flight against silent truncation.
 - 🧹 **Client Teardown (`destroy()`)**: One call aborts every in-flight request, active stream, and queued capacity waiter with `OllamaAbortError` — the clean-exit path for `worker_threads`, CLI runners, and short-lived scripts where dangling fetch bodies keep the event loop alive.
 - 🧠 **Dynamic Context-Window Discovery**: `client.models.getContextLength({ model })` resolves the real window from the server — the allocated window of the running instance (`/api/ps`), the Modelfile `num_ctx` default, and the native GGUF maximum (`model_info`), in precedence order — so applications stop hardcoding 2048/4096 guesses.
@@ -497,6 +498,45 @@ await client.models.createModelFromGguf('my-model', [
 ]);
 ```
 
+### Speculative Decoding (Draft Models)
+
+Ollama packages speculative decoding as a small **draft network** whose token
+guesses are batch-verified against the primary weights in a single forward
+pass — the draft runs ahead, the primary model confirms. On the wire this is
+`draft_files` (draft GGUF digests) + `draft_quantize` on `/api/create`, the
+`draft_num_predict` Modelfile parameter, and the `draft_num_predict` runtime
+option at generation time. The SDK covers the full flow:
+
+```typescript
+// 1. Assemble: primary + draft shards, draft weights quantized independently
+//    (draft tokens are verified, never returned — aggressive compression is
+//    usually safe). Separate draft models default draft_num_predict to 4;
+//    0 disables drafting; models with embedded MTP tensors require setting
+//    it explicitly.
+await client.models.createModelFromGguf('my-model', '/models/model.gguf', {
+  draftGguf: '/models/draft.gguf',
+  draftQuantize: 'q8_0',
+  parameters: { draft_num_predict: 8 },
+});
+
+// 2. Generate with drafting (also available ad hoc via options at runtime)
+const response = await client.chat({
+  model: 'my-model',
+  messages: [{ role: 'user', content: 'Describe a lighthouse in a storm.' }],
+  options: { draft_num_predict: 8 },
+});
+
+// 3. Measure the speedup with the standardized telemetry
+const t = formatTelemetry(response);
+console.log(`${t.tokensPerSecond} tok/s (load ${t.modelLoadMs}ms)`);
+```
+
+Already have the draft blobs uploaded? Pass the digest map directly —
+`createModel({ draft_files: { 'draft.gguf': digest } })` — or merge both
+(path uploads win on basename collision). A live measurement harness
+comparing `draft_num_predict` settings lives at
+`lab/15-speculative-draft/measure-draft-speedup.ts`.
+
 ### Token Log Probabilities (`logprobs`)
 
 Set `logprobs: true` (optionally with `top_logprobs`) on `chat()`/`generate()` to get per-token log probabilities back — useful for confidence scoring, speculative decoding, or agent routing decisions.
@@ -681,6 +721,21 @@ const page = await client.webFetch({ url: 'https://ollama.com/blog' });
 console.log(page.title, page.content.slice(0, 200));
 ```
 
+#### Web search agent
+
+`createWebTools(client)` turns the two endpoints into `web_search` / `web_fetch` tools for `ToolRegistry`/`Agent` — the [search-agent pattern](https://docs.ollama.com/capabilities/web-search#building-a-search-agent) from the Ollama docs. Arguments are validated (`query` non-empty, `max_results` 1–10) before any network call, the abort signal propagates, and output is trimmed to `maxOutputChars` (default `2000 * 4`, as in the docs) while staying valid JSON:
+
+```typescript
+import { Agent, ToolRegistry, createWebTools } from '@nemesis-oss/ollama-sdk';
+
+const agent = new Agent(client, { tools: new ToolRegistry(createWebTools(client)) });
+const { finalMessage } = await agent.run({
+  model: 'qwen3:4b',
+  messages: [{ role: 'user', content: "what is ollama's new engine" }],
+  think: true,
+});
+```
+
 These two methods don't participate in the multi-endpoint failover below — there's only ever the one cloud host to call — but they do use the same default `timeoutMs` and retry policy as everything else.
 
 ### Cloud Usage & Balance (Ollama Cloud account)
@@ -925,9 +980,38 @@ await client.openai.chatCompletions({
 });
 ```
 
-`tool_choice` and `parallel_tool_calls` are also typed on the request so a standard
-OpenAI request object type-checks unmodified, but Ollama's compat layer does not honor
-either — see the `@remarks` on each field in `OpenAIChatCompletionRequest`.
+Fields Ollama documents as **unsupported** — `tool_choice`, `logit_bias`, `user`, `n`
+and logprobs on `/v1/chat/completions`; `best_of`, `echo`, `logit_bias`, `user`, `n` and
+logprobs on `/v1/completions`; `user` and token inputs on `/v1/embeddings`;
+`previous_response_id`, `conversation` and `truncation` on `/v1/responses`; `tool_choice`
+and `metadata` on `/v1/messages` — stay typed on the broad `OpenAI*`/`Anthropic*` request
+types so a standard request object type-checks unmodified, and are compile-time errors on
+the strict `OllamaOpenAI*`/`OllamaAnthropicMessagesRequest` types. For token log
+probabilities use native `chat()`/`generate()` with `logprobs: true`.
+
+**Direct Ollama Cloud access** needs no local server — the bridges speak to
+`https://ollama.com/v1/...` with `Authorization: Bearer` (the hosted Anthropic endpoint
+rejects `x-api-key`-only auth; the SDK always sends the bearer header plus
+`anthropic-version: 2023-06-01`):
+
+```typescript
+const cloud = new OllamaClient({
+  baseUrl: 'https://ollama.com',
+  apiKey: process.env.OLLAMA_API_KEY,
+});
+await cloud.openai.chatCompletions({
+  model: 'gemma4:31b',
+  messages: [{ role: 'user', content: 'Hi' }],
+});
+await cloud.anthropic.messages({
+  model: 'gemma4:31b',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hi' }],
+});
+```
+
+The cloud API does not support stateful Responses, built-in web search through
+`/v1/responses`, or custom/freeform tool-call replay.
 
 ### Multi-Endpoint High Availability Failover
 
@@ -1420,6 +1504,62 @@ windows: [...] })` directly with your own `windowMs`/`maxTokens`/`maxRequests` p
 
 ---
 
+### Testing with the In-Memory Mock Server (`/testing`)
+
+The SDK ships its own deterministic test double as a dedicated subpath —
+`@nemesis-oss/ollama-sdk/testing` — the same engine the SDK's own test suite
+runs against (ADR 0029: promote, don't fork). No daemon, no network, no GPU:
+scriptable NDJSON routes on a real `node:http` server, built-in defaults for
+the official liveness probe and `/api/version`, wire-level request recording,
+and failure injection that covers what static cassettes can't.
+
+```typescript
+import {
+  createMockOllamaServer,
+  mockTextChunks,
+  mockToolCallChunks,
+} from '@nemesis-oss/ollama-sdk/testing';
+import { OllamaClient } from '@nemesis-oss/ollama-sdk';
+
+const server = createMockOllamaServer(); // ephemeral port, defaults on
+await server.start();
+const client = new OllamaClient({ baseUrl: server.baseUrl });
+
+// Defaults answer out of the box: HEAD / (ping) and GET /api/version.
+// Register everything else — register() always wins over the defaults.
+server.register('/api/chat', {
+  chunks: mockToolCallChunks([
+    // Parallel tool calls: one frame, complete calls — the native shape.
+    { name: 'get_weather', arguments: { city: 'Tokyo' } },
+    { name: 'get_time', arguments: { tz: 'Asia/Tokyo' } },
+  ]),
+  chunkDelayMs: 10, // inter-chunk backpressure testing
+});
+
+// Mid-stream failure, GPU-OOM style: HTTP stays 200, the done frame is
+// replaced by an {"error": "..."} frame — the SDK raises OllamaStreamError.
+server.register('/api/generate', {
+  chunks: mockTextChunks('partial answer', { chunkSize: 8 }),
+  injectErrorFrame: { message: 'CUDA out of memory' }, // after: N to move it
+});
+
+// ... run your code against the client ...
+
+// Wire-level assertions: every request was recorded.
+expect(server.requests[0]?.body).toMatchObject({ model: 'llama3.2' });
+server.clearRequests(); // and server.clear() between tests
+
+await server.stop(); // idempotent — safe in afterEach
+```
+
+Per-route controls: `status` (503/502/429 bodies), `chunkDelayMs`,
+`dropConnectionMidStream` (connection reset mid-response), `onRequest`
+(per-route body capture), and `injectErrorFrame.after` (error position).
+Chunk builders: `mockChatChunk` (one frame with counter defaults),
+`mockTextChunks` (chunked text + done frame), `mockToolCallChunks` (parallel
+tool calls + done frame). Node.js only — the subpath builds on `node:http`
+and is never imported from the Edge-safe main entry.
+
 ### Edge Runtime Compatibility
 
 The core client (`OllamaClient`, `Agent`, `ToolRegistry`, and everything exported from

package/dist/{anthropic-CKp5TmAP.d.ts → anthropic-DrDUfbfQ.d.ts}

@@ -1,4 +1,4 @@
-import { O as OllamaRuntime, H as HttpClient, A as AbortableAsyncIterable, af as SseEvent, y as OllamaClientError } from './runtime-CIQYCRL3.js';
+import { O as OllamaRuntime, H as HttpClient, A as AbortableAsyncIterable, af as SseEvent, y as OllamaClientError } from './runtime-BIjr5ME4.js';
 
 /**
  * AUTO-GENERATED by `npm run contract:generate`. DO NOT EDIT.
@@ -484,7 +484,7 @@ interface SystemOneChoiceAnswer {
 interface SystemOneChoiceQuestion {
     readonly type: 'choice';
     readonly instructions: SystemOneContent;
-    /** Option keys mapped to descriptions. A null description uses the key itself. Keys must not be blank; ties follow the model's option order. */
+    /** Option keys mapped to descriptions, or null for a bare label. Keys must not be blank; ties follow the model's option order. The option limit depends on the model. */
     readonly criteria: {
         [key: string]: string | null;
     };
@@ -528,7 +528,7 @@ interface SystemOneNoulAnswer {
 interface SystemOneNoulQuestion {
     readonly type: 'noul';
     readonly instructions: SystemOneContent;
-    /** Optional descriptions for the two outcomes. Omitted entries use No and Yes. */
+    /** Optional descriptions for the two outcomes. Omitted entries use model-specific defaults. */
     readonly criteria?: {
         readonly false?: string | undefined;
         readonly true?: string | undefined;
@@ -614,7 +614,7 @@ interface SystemOneScoreAnswer {
 interface SystemOneScoreQuestion {
     readonly type: 'score';
     readonly instructions: SystemOneContent;
-    /** Descriptions ordered from the lowest score (index 0) to the highest. Defines a scale from 0 to the number of criteria minus 1. */
+    /** Descriptions ordered from the lowest score (index 0) to the highest. Defines a scale from 0 to the number of criteria minus 1. The maximum number of levels depends on the model. */
     readonly criteria: readonly string[];
 }
 
@@ -721,7 +721,7 @@ declare class NativeApi {
     chat(request: ChatRequest & {
         stream: true;
     }): Promise<AsyncGenerator<ChatResponse, void, undefined>>;
-    copy(request: CopyRequest): Promise<unknown>;
+    copy(request: CopyRequest): Promise<StatusResponse>;
     create(request: CreateRequest & {
         stream?: false;
     }): Promise<StatusResponse>;
@@ -859,11 +859,18 @@ interface OpenAIChatCompletionRequest {
     readonly seed?: number | undefined;
     readonly presence_penalty?: number | undefined;
     readonly frequency_penalty?: number | undefined;
+    /** @remarks Documented as unsupported by Ollama — accepted for OpenAI interop, ignored by the server. */
     readonly user?: string | undefined;
+    /** @remarks Documented as unsupported by Ollama — accepted for OpenAI interop, ignored by the server. */
     readonly logit_bias?: Record<string, number> | undefined;
+    /** @remarks Documented as unsupported by Ollama — accepted for OpenAI interop, ignored by the server. */
     readonly n?: number | undefined;
-    /** Ollama exposes log probabilities for supported reasoning/chat models. */
+    /**
+     * @remarks Logprobs are documented as unsupported on Ollama's `/v1/chat/completions`.
+     * Use native `chat({ logprobs: true, top_logprobs })` for token log probabilities.
+     */
     readonly logprobs?: boolean | undefined;
+    /** @remarks Documented as unsupported by Ollama — accepted for OpenAI interop, ignored by the server. */
     readonly top_logprobs?: number | undefined;
     readonly tools?: readonly OpenAITool[] | undefined;
     /**
@@ -895,18 +902,34 @@ interface OpenAIChatCompletionRequest {
         readonly effort?: OpenAIReasoningEffort | undefined;
     } | undefined;
 }
-/** Ollama Chat Completions supports text plus base64 image content via a string image URL. */
+/** A base64 data URL (`data:image/png;base64,...`) — the only image form Ollama accepts here. */
+type OllamaOpenAIImageDataUrl = `data:${string}`;
+/** Ollama Chat Completions supports text plus base64 image content. */
 type OllamaOpenAIChatContentPart = OpenAITextContentPart | {
     readonly type: 'image_url';
-    /** Ollama's current compatibility docs accept an image URL string, including data URLs. */
-    readonly image_url: string;
+    /**
+     * A base64 `data:` URL, as a string or inside the OpenAI `{ url, detail? }` object.
+     * Ollama documents remote image URLs as unsupported on `/v1/chat/completions`, so
+     * `http(s)://` URLs are a compile error here; resolve remote images to base64 first
+     * (e.g. with {@link resolveImageInput}) or use the native `images` field.
+     */
+    readonly image_url: OllamaOpenAIImageDataUrl | {
+        readonly url: OllamaOpenAIImageDataUrl;
+        readonly detail?: 'auto' | 'low' | 'high' | 'original' | undefined;
+    };
 };
 type OllamaOpenAIReasoningEffort = 'high' | 'medium' | 'low' | 'max' | 'none';
 type OllamaOpenAIChatMessage = Omit<OpenAIMessage, 'content'> & {
     readonly content: string | readonly OllamaOpenAIChatContentPart[];
 };
-/** Strict Ollama-documented Chat Completions request; excludes only the SDK-only parallel tool flag. */
-type OllamaOpenAIChatCompletionRequest = Omit<OpenAIChatCompletionRequest, 'messages' | 'parallel_tool_calls' | 'reasoning_effort' | 'reasoning'> & {
+/**
+ * Strict Ollama-documented Chat Completions request. Excludes the fields
+ * https://docs.ollama.com/api/openai-compatibility marks unsupported (`tool_choice`,
+ * `logit_bias`, `user`, `n`, `logprobs`/`top_logprobs`) and the SDK-only
+ * `parallel_tool_calls` flag, so passing any of them is a compile-time error instead of
+ * a silently ignored request field.
+ */
+type OllamaOpenAIChatCompletionRequest = Omit<OpenAIChatCompletionRequest, 'messages' | 'parallel_tool_calls' | 'reasoning_effort' | 'reasoning' | 'tool_choice' | 'logit_bias' | 'user' | 'n' | 'logprobs' | 'top_logprobs'> & {
     readonly messages: readonly OllamaOpenAIChatMessage[];
     readonly reasoning_effort?: OllamaOpenAIReasoningEffort | undefined;
     readonly reasoning?: {
@@ -985,7 +1008,10 @@ interface OpenAICompletionRequest {
     readonly model: string;
     /** Ollama currently accepts a string prompt for /v1/completions. */
     readonly prompt: string;
-    /** Number of log probability alternatives requested for completion tokens. */
+    /**
+     * @remarks Logprobs are documented as unsupported on Ollama's `/v1/completions`. Use
+     * native `generate({ logprobs: true, top_logprobs })` for token log probabilities.
+     */
     readonly logprobs?: number | undefined;
     readonly frequency_penalty?: number | undefined;
     readonly presence_penalty?: number | undefined;
@@ -997,14 +1023,23 @@ interface OpenAICompletionRequest {
     readonly top_p?: number | undefined;
     readonly max_tokens?: number | undefined;
     readonly suffix?: string | undefined;
+    /** @remarks Documented as unsupported by Ollama — accepted for OpenAI interop, ignored by the server. */
     readonly best_of?: number | undefined;
+    /** @remarks Documented as unsupported by Ollama — accepted for OpenAI interop, ignored by the server. */
     readonly echo?: boolean | undefined;
+    /** @remarks Documented as unsupported by Ollama — accepted for OpenAI interop, ignored by the server. */
     readonly logit_bias?: Record<string, number> | undefined;
+    /** @remarks Documented as unsupported by Ollama — accepted for OpenAI interop, ignored by the server. */
     readonly user?: string | undefined;
+    /** @remarks Documented as unsupported by Ollama — accepted for OpenAI interop, ignored by the server. */
     readonly n?: number | undefined;
 }
 /** Strict Ollama-documented Completions request. */
-type OllamaOpenAICompletionRequest = OpenAICompletionRequest;
+/**
+ * Strict Ollama-documented Completions request: excludes `best_of`, `echo`,
+ * `logit_bias`, `user`, `n`, and `logprobs`, which Ollama documents as unsupported.
+ */
+type OllamaOpenAICompletionRequest = Omit<OpenAICompletionRequest, 'best_of' | 'echo' | 'logit_bias' | 'user' | 'n' | 'logprobs'>;
 interface OpenAICompletionChoice {
     readonly text: string;
     readonly index: number;
@@ -1044,10 +1079,18 @@ interface OpenAIEmbeddingRequest {
     readonly input: OpenAIEmbeddingInput;
     readonly encoding_format?: 'float' | 'base64' | undefined;
     readonly dimensions?: number | undefined;
+    /** @remarks Documented as unsupported by Ollama — accepted for OpenAI interop, ignored by the server. */
     readonly user?: string | undefined;
 }
 /** Strict Ollama-documented Embeddings request. */
-type OllamaOpenAIEmbeddingRequest = OpenAIEmbeddingRequest;
+/**
+ * Strict Ollama-documented Embeddings request: `input` is a string or an array of
+ * strings (token and token-array inputs are documented as unsupported), and `user` is
+ * excluded.
+ */
+type OllamaOpenAIEmbeddingRequest = Omit<OpenAIEmbeddingRequest, 'input' | 'user'> & {
+    readonly input: string | readonly string[];
+};
 interface OpenAIEmbeddingItem {
     readonly object: 'embedding';
     readonly embedding: readonly number[] | string;
@@ -1084,6 +1127,7 @@ interface OpenAIResponsesRequest {
     readonly previous_response_id?: string | undefined;
     /** @remarks Not supported by Ollama, which is stateless across calls — accepted but ignored. */
     readonly conversation?: string | undefined;
+    /** @remarks Documented as unsupported by Ollama — accepted but ignored. */
     readonly truncation?: string | undefined;
     readonly reasoning?: {
         readonly effort?: OpenAIReasoningEffort | undefined;
@@ -1091,9 +1135,12 @@ interface OpenAIResponsesRequest {
     /** Ollama extension: boolean, model-defined string, or null for model default. */
     readonly think?: boolean | string | null | undefined;
 }
-/** Strict Ollama-documented Responses request; excludes stateful and SDK-only request fields. */
-/** Strict Ollama-documented Responses request; excludes only unsupported stateful fields. */
-type OllamaOpenAIResponsesRequest = Omit<OpenAIResponsesRequest, 'previous_response_id' | 'conversation'>;
+/**
+ * Strict Ollama-documented Responses request: excludes the stateful fields
+ * (`previous_response_id`, `conversation`) and `truncation`, which Ollama documents as
+ * unsupported.
+ */
+type OllamaOpenAIResponsesRequest = Omit<OpenAIResponsesRequest, 'previous_response_id' | 'conversation' | 'truncation'>;
 type OpenAIResponsesStatus = 'completed' | 'failed' | 'in_progress' | 'cancelled' | 'queued' | 'incomplete';
 interface OpenAIResponsesError {
     readonly code?: string | undefined;
@@ -1646,4 +1693,4 @@ declare class AnthropicCompatClient {
     messages(request: AnthropicMessagesRequest, signal?: AbortSignal): Promise<AnthropicMessagesResponse | AnthropicMessagesStream>;
 }
 
-export { type OllamaAnthropicThinkingConfig as $, type AnthropicMessagesRequest as A, type AnthropicImageContentBlock as B, type AnthropicMessage as C, AnthropicMessagesStream as D, type AnthropicMetadata as E, type AnthropicOutputConfig as F, type AnthropicRedactedThinkingContentBlock as G, type AnthropicSystem as H, type AnthropicSystemTextBlock as I, type AnthropicTextContentBlock as J, type AnthropicThinkingConfig as K, type AnthropicThinkingContentBlock as L, type AnthropicTool as M, NativeApi as N, type OpenAIChatCompletionRequest as O, type AnthropicToolChoice as P, type AnthropicToolResultContentBlock as Q, type RequestRunner as R, type SystemOneChoiceAnswer as S, type AnthropicToolUseContentBlock as T, type AnthropicUnknownStreamEvent as U, type OllamaAnthropicContentBlock as V, type OllamaAnthropicMessage as W, type OllamaAnthropicMessagesRequest as X, type OllamaAnthropicSystem as Y, type OllamaAnthropicSystemTextBlock as Z, type OllamaAnthropicTextContentBlock as _, type OpenAIChatCompletionResponse as a, type SystemOneConfidence as a$, type OllamaAnthropicTool as a0, type OllamaAnthropicToolResultContentBlock as a1, type OllamaOpenAIChatCompletionRequest as a2, type OllamaOpenAICompletionRequest as a3, type OllamaOpenAIEmbeddingRequest as a4, type OllamaOpenAIReasoningEffort as a5, type OllamaOpenAIResponsesRequest as a6, type OpenAIChatCompletionChoice as a7, type OpenAIChatCompletionChunkChoice as a8, type OpenAIChatCompletionDelta as a9, type OpenAIResponsesOutputItemAddedEvent as aA, type OpenAIResponsesOutputItemDoneEvent as aB, type OpenAIResponsesOutputMessage as aC, type OpenAIResponsesOutputReasoning as aD, type OpenAIResponsesOutputRefusal as aE, type OpenAIResponsesOutputTextContent as aF, type OpenAIResponsesOutputTextDeltaEvent as aG, type OpenAIResponsesOutputTextDoneEvent as aH, type OpenAIResponsesQueuedEvent as aI, type OpenAIResponsesReasoningSummaryPartAddedEvent as aJ, type OpenAIResponsesReasoningSummaryPartDoneEvent as aK, type OpenAIResponsesReasoningSummaryTextDeltaEvent as aL, type OpenAIResponsesReasoningSummaryTextDoneEvent as aM, type OpenAIResponsesReasoningTextDeltaEvent as aN, type OpenAIResponsesReasoningTextDoneEvent as aO, type OpenAIResponsesRefusalDeltaEvent as aP, type OpenAIResponsesRefusalDoneEvent as aQ, type OpenAIResponsesStatus as aR, OpenAIResponsesStream as aS, OpenAIResponsesStreamError as aT, type OpenAIResponsesUsage as aU, type OpenAIStreamOptions as aV, type OpenAITextContentPart as aW, type OpenAITool as aX, type OpenAIToolCall as aY, type OpenAIToolCallDelta as aZ, type OpenAIUsage as a_, OpenAIChatCompletionStream as aa, type OpenAICompletionChoice as ab, OpenAICompletionStream as ac, type OpenAIContentPart as ad, type OpenAIEmbeddingInput as ae, type OpenAIEmbeddingItem as af, type OpenAIFunctionDefinition as ag, type OpenAIImageUrlContentPart as ah, type OpenAIMessage as ai, type OpenAIReasoningEffort as aj, type OpenAIResponseFormat as ak, type OpenAIResponsesCompletedEvent as al, type OpenAIResponsesContentPartAddedEvent as am, type OpenAIResponsesContentPartDoneEvent as an, type OpenAIResponsesCreatedEvent as ao, type OpenAIResponsesError as ap, type OpenAIResponsesEventBase as aq, type OpenAIResponsesFailedEvent as ar, type OpenAIResponsesFunctionCallArgumentsDeltaEvent as as, type OpenAIResponsesFunctionCallArgumentsDoneEvent as at, type OpenAIResponsesInProgressEvent as au, type OpenAIResponsesIncompleteDetails as av, type OpenAIResponsesIncompleteEvent as aw, type OpenAIResponsesOutputContent as ax, type OpenAIResponsesOutputFunctionCall as ay, type OpenAIResponsesOutputItem as az, type OpenAIChatCompletionChunk as b, type SystemOneProbabilities as b0, type OpenAICompletionRequest as c, type OpenAICompletionResponse as d, type OpenAICompletionChunk as e, type OpenAIEmbeddingRequest as f, type OpenAIEmbeddingResponse as g, type OpenAIListModelsResponse as h, type OpenAIModelItem as i, type OpenAIResponsesRequest as j, type OpenAIResponsesResponse as k, type OpenAIResponsesStreamEvent as l, type AnthropicMessagesResponse as m, type AnthropicMessageStreamEvent as n, type SystemOneNoulAnswer as o, type SystemOneScoreAnswer as p, type SystemOneChoiceQuestion as q, type SystemOneNoulQuestion as r, type SystemOneScoreQuestion as s, type SystemOneRequest as t, type SystemOneResponse as u, type SystemOneContent as v, OpenAICompatClient as w, AnthropicCompatClient as x, type AnthropicCacheControl as y, type AnthropicContentBlock as z };
+export { type OllamaAnthropicThinkingConfig as $, type AnthropicMessagesRequest as A, type AnthropicImageContentBlock as B, type AnthropicMessage as C, AnthropicMessagesStream as D, type AnthropicMetadata as E, type AnthropicOutputConfig as F, type AnthropicRedactedThinkingContentBlock as G, type AnthropicSystem as H, type AnthropicSystemTextBlock as I, type AnthropicTextContentBlock as J, type AnthropicThinkingConfig as K, type AnthropicThinkingContentBlock as L, type AnthropicTool as M, NativeApi as N, type OpenAIChatCompletionRequest as O, type AnthropicToolChoice as P, type AnthropicToolResultContentBlock as Q, type RequestRunner as R, type SystemOneChoiceAnswer as S, type AnthropicToolUseContentBlock as T, type AnthropicUnknownStreamEvent as U, type OllamaAnthropicContentBlock as V, type OllamaAnthropicMessage as W, type OllamaAnthropicMessagesRequest as X, type OllamaAnthropicSystem as Y, type OllamaAnthropicSystemTextBlock as Z, type OllamaAnthropicTextContentBlock as _, type OpenAIChatCompletionResponse as a, type OpenAIToolCall as a$, type OllamaAnthropicTool as a0, type OllamaAnthropicToolResultContentBlock as a1, type OllamaOpenAIChatCompletionRequest as a2, type OllamaOpenAIChatContentPart as a3, type OllamaOpenAIChatMessage as a4, type OllamaOpenAICompletionRequest as a5, type OllamaOpenAIEmbeddingRequest as a6, type OllamaOpenAIImageDataUrl as a7, type OllamaOpenAIReasoningEffort as a8, type OllamaOpenAIResponsesRequest as a9, type OpenAIResponsesOutputContent as aA, type OpenAIResponsesOutputFunctionCall as aB, type OpenAIResponsesOutputItem as aC, type OpenAIResponsesOutputItemAddedEvent as aD, type OpenAIResponsesOutputItemDoneEvent as aE, type OpenAIResponsesOutputMessage as aF, type OpenAIResponsesOutputReasoning as aG, type OpenAIResponsesOutputRefusal as aH, type OpenAIResponsesOutputTextContent as aI, type OpenAIResponsesOutputTextDeltaEvent as aJ, type OpenAIResponsesOutputTextDoneEvent as aK, type OpenAIResponsesQueuedEvent as aL, type OpenAIResponsesReasoningSummaryPartAddedEvent as aM, type OpenAIResponsesReasoningSummaryPartDoneEvent as aN, type OpenAIResponsesReasoningSummaryTextDeltaEvent as aO, type OpenAIResponsesReasoningSummaryTextDoneEvent as aP, type OpenAIResponsesReasoningTextDeltaEvent as aQ, type OpenAIResponsesReasoningTextDoneEvent as aR, type OpenAIResponsesRefusalDeltaEvent as aS, type OpenAIResponsesRefusalDoneEvent as aT, type OpenAIResponsesStatus as aU, OpenAIResponsesStream as aV, OpenAIResponsesStreamError as aW, type OpenAIResponsesUsage as aX, type OpenAIStreamOptions as aY, type OpenAITextContentPart as aZ, type OpenAITool as a_, type OpenAIChatCompletionChoice as aa, type OpenAIChatCompletionChunkChoice as ab, type OpenAIChatCompletionDelta as ac, OpenAIChatCompletionStream as ad, type OpenAICompletionChoice as ae, OpenAICompletionStream as af, type OpenAIContentPart as ag, type OpenAIEmbeddingInput as ah, type OpenAIEmbeddingItem as ai, type OpenAIFunctionDefinition as aj, type OpenAIImageUrlContentPart as ak, type OpenAIMessage as al, type OpenAIReasoningEffort as am, type OpenAIResponseFormat as an, type OpenAIResponsesCompletedEvent as ao, type OpenAIResponsesContentPartAddedEvent as ap, type OpenAIResponsesContentPartDoneEvent as aq, type OpenAIResponsesCreatedEvent as ar, type OpenAIResponsesError as as, type OpenAIResponsesEventBase as at, type OpenAIResponsesFailedEvent as au, type OpenAIResponsesFunctionCallArgumentsDeltaEvent as av, type OpenAIResponsesFunctionCallArgumentsDoneEvent as aw, type OpenAIResponsesInProgressEvent as ax, type OpenAIResponsesIncompleteDetails as ay, type OpenAIResponsesIncompleteEvent as az, type OpenAIChatCompletionChunk as b, type OpenAIToolCallDelta as b0, type OpenAIUsage as b1, type SystemOneConfidence as b2, type SystemOneProbabilities as b3, type OpenAICompletionRequest as c, type OpenAICompletionResponse as d, type OpenAICompletionChunk as e, type OpenAIEmbeddingRequest as f, type OpenAIEmbeddingResponse as g, type OpenAIListModelsResponse as h, type OpenAIModelItem as i, type OpenAIResponsesRequest as j, type OpenAIResponsesResponse as k, type OpenAIResponsesStreamEvent as l, type AnthropicMessagesResponse as m, type AnthropicMessageStreamEvent as n, type SystemOneNoulAnswer as o, type SystemOneScoreAnswer as p, type SystemOneChoiceQuestion as q, type SystemOneNoulQuestion as r, type SystemOneScoreQuestion as s, type SystemOneRequest as t, type SystemOneResponse as u, type SystemOneContent as v, OpenAICompatClient as w, AnthropicCompatClient as x, type AnthropicCacheControl as y, type AnthropicContentBlock as z };