@nemesis-oss/ollama-sdk 1.3.0 → 1.4.0

package/README.md

@@ -16,7 +16,7 @@
 - 🎯 **Zod-Powered Structured Outputs**: Strictly typed schema enforcement via `chatWithSchema` and `generateWithSchema` with resilient markdown JSON parsing.
 - 🛠️ **Autonomous Agent & Tool Calling**: Multi-turn agent loop (`Agent`) with automated tool execution, parameter validation, and self-correcting error recovery.
 - 🌐 **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)**: Native adapters to convert MCP tools into Ollama-compatible function schemas.
+- 🔌 **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`.
 - 🌉 **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.
@@ -25,9 +25,126 @@
 - 📊 **Client-Side Quota Monitoring**: `QuotaManager` tracks token/request usage against budgets you configure across rolling windows (e.g. Ollama Cloud's 5-hour session / 7-day weekly resets) and fails fast with `OllamaQuotaExceededError` before a request is sent.
 - ⚡ **Edge Runtime Verified**: CI bundles and runs the client in a real Edge Runtime sandbox (Cloudflare Workers/Vercel Edge-compatible) with zero Node.js APIs.
 - 📦 **Dual ESM & CJS Build**: Full module support with clean TypeScript `.d.ts` declaration maps.
+- 🧩 **Contract-First Architecture**: A single canonical IR (`contracts/ir/ollama.ir.json`) drives TypeScript interfaces, generated API classes (`NativeApi`/`OpenAIApi`/`AnthropicApi`), MCP tool descriptors, Zod schemas, and field-level parity verification. New Ollama endpoints (like `/v1/systemone`) are caught automatically by bidirectional endpoint discovery. See [ADRs 0013-0019](./docs/adr/README.md).
 
 ---
 
+### Contract parity verification
+
+The repository keeps the Ollama compatibility contract in the canonical IR at
+`contracts/ir/ollama.ir.json` (compiled from `contracts/sources/` + `contracts/overlays/`)
+and checks it against the current official documentation with
+`npm run verify:contract-parity`. Each operation's `parity:` block distinguishes
+**supported**, **explicitly unsupported**, and **SDK-only** fields, and also tracks
+documented response fields plus the public streaming-event union for compatibility
+adapters. This prevents a field merely being mentioned in upstream documentation
+from being mistaken for a supported Ollama feature.
+
+For callers who want compile-time enforcement of the documented Ollama subset, the package
+also exports strict request types such as `OllamaOpenAIChatCompletionRequest`,
+`OllamaOpenAIResponsesRequest`, `OllamaOpenAIEmbeddingRequest`, and
+`OllamaAnthropicMessagesRequest`. The broader compatibility request types remain
+available for pass-through interoperability and vendor-specific fields.
+
+### SSE Streaming Foundation
+
+Compatibility endpoints use Server-Sent Events when `stream: true`. The SDK now exposes a provider-neutral `parseSseStream()` and `HttpClient.requestSseStream()`, plus typed adapters for OpenAI Chat/Completions/Responses and Anthropic Messages. Native Ollama NDJSON streaming remains separate.
+
+```typescript
+const stream = await client.openai.chatCompletions({
+  model: 'qwen3',
+  messages: [{ role: 'user', content: 'Explain SSE.' }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta.content ?? '');
+}
+
+const final = await stream.finalResult;
+console.log(final.usage);
+```
+
+## MCP bridge
+
+The SDK exposes a transport-neutral `McpBridge` that converts MCP `tools/list` descriptors into native Ollama function tools and registers executable MCP-backed tools. MCP tool arguments are validated against the advertised JSON Schema at the `ToolRegistry` boundary (including object, array, scalar, required, enum, and common numeric/string constraints).
+
+- Paginated `tools/list` discovery follows `nextCursor`, with repeated-cursor and page-limit protection.
+- MCP JSON Schema is preserved in the generated Ollama tool definition.
+- `structuredContent` and non-text MCP content blocks are retained in the model-visible tool result.
+- MCP `isError: true` results remain model-readable; they are not treated as transport failures.
+
+`loadMcpTools()` keeps the historical model-oriented string result by default. Set `resultMode: 'structured'` when application code needs the raw MCP `CallToolResult`, including `structuredContent`, content blocks, `isError`, and `_meta`:
+
+```typescript
+const tools = await loadMcpTools(mcpClient, { resultMode: 'structured' });
+```
+
+- Input JSON Schema validation happens before the MCP server is called, preventing invalid model-generated arguments from crossing the protocol boundary.
+- `resultMode: 'structured'` is available for lossless programmatic access to raw MCP tool results while preserving the legacy text mode by default.
+- `AbortSignal` propagates through discovery and tool execution.
+- The optional Node-only `@nemesis-oss/ollama-sdk/mcp/stdio` subpath uses the official MCP v2 stdio transport without importing Node-only code from the root package.
+
+For remote MCP servers, the optional `@nemesis-oss/ollama-sdk/mcp/http` subpath uses the official MCP client v2 transport. Streamable HTTP is the default; legacy SSE can be selected explicitly, or `transport: 'auto'` can try Streamable HTTP first and fall back to SSE only on a compatible non-authentication 4xx response.
+
+```typescript
+import { Agent, McpBridge, OllamaClient, ToolRegistry } from '@nemesis-oss/ollama-sdk';
+import { connectMcpHttpClient } from '@nemesis-oss/ollama-sdk/mcp/http';
+
+const connection = await connectMcpHttpClient({
+  url: 'https://example.com/mcp',
+  transport: 'auto',
+  requestInit: {
+    headers: { Authorization: `Bearer ${process.env.MCP_TOKEN}` },
+  },
+});
+
+const bridge = new McpBridge(connection.client, { namePrefix: 'mcp_' });
+const registry = new ToolRegistry();
+await bridge.register(registry);
+
+const agent = new Agent(new OllamaClient(), { tools: registry });
+const result = await agent.run({
+  model: 'qwen3',
+  messages: [{ role: 'user', content: 'Use the MCP tools to complete this task.' }],
+});
+
+await connection.close();
+console.log(result.finalMessage.content);
+```
+
+Use `connection.terminateSession()` when the remote Streamable HTTP server exposes a session you want to terminate explicitly. Legacy SSE connections do not expose that method.
+
+The MCP TypeScript SDK v2 treats Streamable HTTP as the preferred remote transport and keeps SSE as a legacy fallback during migration. citeturn514654search0turn514654search6
+
+The MCP TypeScript SDK v2 implements the 2026-07-28 protocol revision. Its `listTools()` client path aggregates pagination, and `CallToolResult` represents tool failures as ordinary results with `isError`, while `structuredContent` is available for machine-readable output. citeturn0search0turn1search4turn0search6
+
+### MCP stdio example
+
+```typescript
+import { connectStdioMcpClient } from '@nemesis-oss/ollama-sdk/mcp/stdio';
+import { Agent, McpBridge, OllamaClient, ToolRegistry } from '@nemesis-oss/ollama-sdk';
+
+const connection = await connectStdioMcpClient({
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+});
+
+const bridge = new McpBridge(connection.client, { namePrefix: 'mcp_' });
+const registry = new ToolRegistry();
+await bridge.register(registry);
+
+const client = new OllamaClient();
+const agent = new Agent(client, { tools: registry });
+const result = await agent.run({
+  model: 'qwen3',
+  messages: [{ role: 'user', content: 'List the available files.' }],
+});
+
+await connection.close();
+console.log(result.finalMessage.content);
+```
+
 ## Installation
 
 ```bash
@@ -57,7 +174,7 @@ console.log(answer);
 
 ### Thinking & Reasoning Token Streams
 
-`think` is Ollama's native reasoning-effort parameter, exposed directly on `chat()`/`generate()` — no bridge translation needed. It accepts `true`/`false` or a level (`'low' | 'medium' | 'high' | 'max'`); the OpenAI bridge's `reasoning_effort` (see below) is a compatibility alias for the same underlying knob.
+`think` is Ollama's native reasoning-effort parameter, exposed directly on `chat()`/`generate()`. It accepts `true`, `false`, `null` (model default), or a model-defined string. Use `client.capabilities(model).thinking` to discover the exact string values and default reported by `/api/show`. The OpenAI bridge's `reasoning_effort`/`reasoning.effort` follows the same model-defined convention.
 
 ```typescript
 const stream = await client.chatStream({
@@ -79,6 +196,20 @@ const final = await stream.finalResult;
 console.log(`\nEval tokens/sec: ${final.usage?.tokensPerSecond}`);
 ```
 
+### Cached Prompt Tokens
+
+Ollama reports `prompt_eval_cached_count` as the number of prompt tokens read from the KV cache. The raw value is preserved on native chat/generate responses, and normalized stream usage exposes it as `cachedPromptTokens`.
+
+```typescript
+const res = await client.chat({
+  model: 'gpt-oss:20b',
+  messages: [{ role: 'user', content: 'hello' }],
+});
+
+console.log(res.prompt_eval_count, res.prompt_eval_cached_count);
+console.log(res.prompt_eval_cached_count ?? 0);
+```
+
 ### 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.
@@ -231,12 +362,12 @@ const response = await agent.run({
 console.log(response.finalMessage.content);
 ```
 
-Ollama's native tool-calling protocol has no OpenAI-style call ID, but the SDK
-synthesizes a stable one so results are still correlatable without tracking array
-position by hand: `response.turns[0].toolCalls[0].id` matches
-`response.turns[0].toolResults[0].toolCallId`, and the `role: 'tool'` message `Agent`
-appends to history carries the same value as `tool_call_id`. See
-[ADR 0007](./docs/adr/0007-synthetic-tool-call-ids.md).
+Ollama's native tool-calling protocol has no OpenAI-style call ID, so the SDK
+synthesizes a stable client-side ID for tracing and execution correlation:
+`response.turns[0].toolCalls[0].id` matches
+`response.turns[0].toolResults[0].toolCallId`. Native `role: 'tool'` history entries
+use Ollama's documented `tool_name` field; the SDK-local `toolCallId` is not sent on
+the wire. See [ADR 0007](./docs/adr/0007-synthetic-tool-call-ids.md).
 
 Running several `Agent`s against different models/API keys for different roles (e.g. a
 planning model, a coding model, a research model) is a single `OllamaClient` with
@@ -247,6 +378,44 @@ unaware of credentials entirely. See
 [Guide: Benchmarking Agent Models Across Multiple Ollama Cloud Keys](./docs/guides/multi-model-agent-benchmarking.md)
 for a worked example and a runnable scenario.
 
+### MCP Bridge & Agent Capability Preflight
+
+The SDK exposes `McpBridge` as a transport-neutral adapter between an MCP client and
+Ollama's native function-tool format. The bridge does not own the MCP transport or spawn
+processes; your application supplies an MCP client with `listTools()` and `callTool()`.
+This keeps the package root Edge-runtime safe while still supporting Node-specific
+transports such as stdio through your chosen MCP implementation.
+
+```typescript
+import { McpBridge, ToolRegistry } from '@nemesis-oss/ollama-sdk';
+
+const bridge = new McpBridge(mcpClient, { namePrefix: 'mcp_' });
+
+const registry = new ToolRegistry();
+await bridge.register(registry);
+
+// The same MCP definitions can also be inspected before registration.
+const definitions = await bridge.definitions();
+console.log(definitions);
+```
+
+For tool-enabled `Agent` runs, capability preflight is enabled by default when the
+chat client exposes `capabilities()` (including `OllamaClient`). The agent queries
+`/api/show` before the first model turn and throws `OllamaIncompatibleModelError` when
+the selected model does not advertise `tools`.
+
+The same metadata can size the tool context automatically: when `options.num_ctx` is
+not supplied, the default is `32768`, clamped to the model-reported
+`capabilities.contextLength` when available. An explicit `options.num_ctx` always
+takes precedence.
+
+For legacy or custom `AgentChatClient` implementations, set
+`validateToolCapability: false` to skip capability discovery and the automatic
+context-size override.
+
+See [ADR 0011](./docs/adr/0011-mcp-boundary-and-agent-tool-preconditions.md) for the
+MCP boundary and agent-precondition rationale.
+
 ### Tool Execution Safety & Sandboxing
 
 Tool arguments and, indirectly, which tools get called at all are driven by model
@@ -385,9 +554,24 @@ so it never burns a request retrying an unrelated key:
 const client = new OllamaClient({
   baseUrl: 'https://ollama.com',
   endpoints: [
-    { name: 'gpt-oss-key', apiKey: process.env.OLLAMA_KEY_1!, baseUrl: 'https://ollama.com', models: ['gpt-oss:120b'] },
-    { name: 'minimax-key', apiKey: process.env.OLLAMA_KEY_2!, baseUrl: 'https://ollama.com', models: ['minimax-m3'] },
-    { name: 'nemotron-key', apiKey: process.env.OLLAMA_KEY_3!, baseUrl: 'https://ollama.com', models: ['nemotron-3-super'] },
+    {
+      name: 'gpt-oss-key',
+      apiKey: process.env.OLLAMA_KEY_1!,
+      baseUrl: 'https://ollama.com',
+      models: ['gpt-oss:120b'],
+    },
+    {
+      name: 'minimax-key',
+      apiKey: process.env.OLLAMA_KEY_2!,
+      baseUrl: 'https://ollama.com',
+      models: ['minimax-m3'],
+    },
+    {
+      name: 'nemotron-key',
+      apiKey: process.env.OLLAMA_KEY_3!,
+      baseUrl: 'https://ollama.com',
+      models: ['nemotron-3-super'],
+    },
   ],
 });
 
@@ -526,7 +710,7 @@ always tried first regardless of its active count.
 
 #### Queueing past capacity, instead of overrunning an account
 
-`'least-connections'` alone only guarantees no collision for up to `N` *simultaneous*
+`'least-connections'` alone only guarantees no collision for up to `N` _simultaneous_
 calls against `N` candidates — an `(N+1)`th concurrent call would still be routed to
 whichever account looks least busy at that instant, which, once all `N` already have one
 request each, means sending it to an account that's already at its real limit. Add
@@ -621,7 +805,7 @@ compute, not a fixed token count, so a budget you set for one model won't transf
 exactly to another.
 
 `QuotaManager` is a client-side safety net, not a mirror of Ollama's real limits: it
-tracks usage you record against budgets *you* configure over one or more rolling
+tracks usage you record against budgets _you_ configure over one or more rolling
 windows, and fails fast — before a request is even sent — once a window's budget is
 spent. Pair it with catching `OllamaRateLimitError` (the server's actual `429`) as the
 authoritative signal.
@@ -647,7 +831,10 @@ async function chatWithQuota(prompt: string) {
   quota.assertCanProceed(); // throws OllamaQuotaExceededError if any window is spent
 
   try {
-    const res = await client.chat({ model: 'qwen3:8b', messages: [{ role: 'user', content: prompt }] });
+    const res = await client.chat({
+      model: 'qwen3:8b',
+      messages: [{ role: 'user', content: prompt }],
+    });
     quota.recordUsage(res); // reads prompt_eval_count/eval_count off the raw response
     return res.message.content;
   } catch (error) {
@@ -685,6 +872,130 @@ real Edge Runtime sandbox exposing only Web Standard globals. See
 
 ---
 
+## Contract-First Architecture
+
+Starting with v1.4.0, the SDK ships a **contract-first hybrid architecture** where a single
+canonical IR (`contracts/ir/ollama.ir.json`) drives seven consumers:
+
+1. **TypeScript interfaces** — `src/generated/models/<name>.ts` (36 schemas)
+2. **Generated API classes** — `NativeApi` / `OpenAIApi` / `AnthropicApi` in `src/generated/api/`
+3. **MCP tool descriptors** — `src/generated/mcp/tools.json` (21 tools, one per documented operation)
+4. **Operation metadata** — `src/generated/metadata/operations.json`
+5. **Field-level parity** — overlay `parity:` blocks verified by `npm run verify:contract-parity`
+6. **Zod schemas** — `src/generated/models/<name>.schema.ts` (paired with every TypeScript interface)
+7. **Bidirectional endpoint discovery** — catches new Ollama endpoints like `/v1/systemone` that the OpenAPI spec doesn't yet cover
+
+The IR is compiled from upstream OpenAPI + hand-maintained behavioral overlays by
+`npm run contract:normalize`. Run `npm run contract:generate` to regenerate every TypeScript /
+Zod / MCP artifact from the IR. See [ADRs 0013-0019](./docs/adr/README.md) for the full design.
+
+### Using the generated `NativeApi` (recommended for new code)
+
+The generated surface is opt-in — existing `OllamaClient` callers don't need to change anything.
+For new code, the generated API inherits every contract-layer guarantee (environment guards,
+version guards, streaming defaults) automatically:
+
+```typescript
+import { HttpClient } from '@nemesis-oss/ollama-sdk';
+import { OllamaRuntime } from '@nemesis-oss/ollama-sdk/generated/runtime';
+import { NativeApi } from '@nemesis-oss/ollama-sdk/generated/api';
+
+const http = new HttpClient({ baseUrl: 'http://localhost:11434' });
+const runtime = new OllamaRuntime({ http });
+const api = new NativeApi(runtime);
+
+// Non-streaming chat:
+const res = await api.chat({
+  model: 'qwen3:8b',
+  messages: [{ role: 'user', content: 'Hello' }],
+  stream: false,
+});
+
+// Streaming chat — explicitly request a stream:
+const stream = await api.chat({
+  model: 'qwen3:8b',
+  messages: [{ role: 'user', content: 'Hello' }],
+  stream: true,
+});
+for await (const chunk of stream) {
+  console.log(chunk.message?.content);
+}
+```
+
+### Mixing the legacy client with the generated surface
+
+`OllamaClient.runtime` returns a cached `OllamaRuntime` that shares the client's
+transport (HttpClient + middleware + retry + telemetry), so you can mix both
+surfaces in the same process without configuring two HttpClient instances:
+
+```typescript
+import { OllamaClient } from '@nemesis-oss/ollama-sdk';
+import { NativeApi } from '@nemesis-oss/ollama-sdk/generated/api';
+
+const client = new OllamaClient({ baseUrl: 'http://localhost:11434' });
+
+// Existing API:
+const res = await client.chat({ model: 'qwen3:8b', messages });
+
+// Generated API (shares transport):
+const api = new NativeApi(client.runtime);
+const res2 = await api.chat({ model: 'qwen3:8b', messages, stream: false });
+```
+
+`OllamaClient` carries a deprecation notice pointing to `NativeApi` for new code, but
+no method signatures have changed — existing callers continue to work.
+
+### Runtime validation with generated Zod schemas
+
+Every TypeScript interface in `src/generated/models/<name>.ts` has a paired Zod schema
+in `src/generated/models/<name>.schema.ts`. Use them for runtime validation of user
+input, server responses, or anywhere you need to confirm a value matches the IR shape:
+
+```typescript
+import { ChatRequestSchema } from '@nemesis-oss/ollama-sdk/generated/models/schemas';
+
+const result = ChatRequestSchema.safeParse(userInput);
+if (!result.success) {
+  console.error(result.error.issues);
+} else {
+  // result.data is typed as ChatRequest
+}
+```
+
+### Generated MCP tools
+
+The IR also produces 21 MCP tool descriptors (one per documented Ollama operation) at
+`src/generated/mcp/tools.json`. The runtime adapter at
+`@nemesis-oss/ollama-sdk/mcp/generated` exposes them as a callable tool registry:
+
+```typescript
+import { OllamaRuntime } from '@nemesis-oss/ollama-sdk/generated/runtime';
+import {
+  listGeneratedOllamaTools,
+  callGeneratedOllamaTool,
+} from '@nemesis-oss/ollama-sdk/mcp/generated';
+
+const tools = listGeneratedOllamaTools();
+// tools: [{ name: 'ollama_chat', inputSchema: {...}, annotations: {...} }, ...]
+
+const result = await callGeneratedOllamaTool(runtime, 'ollama_version', {});
+console.log(result.structuredContent); // { version: '0.5.0' }
+```
+
+### Contract maintenance commands
+
+| Command                          | What it does                                                                                                                       |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `npm run contract:fetch`         | Re-pull the upstream OpenAPI spec into `contracts/sources/`                                                                        |
+| `npm run contract:normalize`     | Compile sources + overlays → `contracts/ir/ollama.ir.json`                                                                         |
+| `npm run contract:validate`      | Run schema + compatibility + bidirectional endpoint discovery validators                                                           |
+| `npm run contract:diff`          | Fail if the committed IR is stale (CI gate)                                                                                        |
+| `npm run contract:generate`      | Regenerate every TypeScript / Zod / MCP artifact from the IR (idempotent)                                                          |
+| `npm run contract:drift`         | Print drift report between generated types and `src/types.ts` (pass `--strict` to fail CI on unexpected drift)                     |
+| `npm run verify:contract-parity` | Verify parity blocks against `src/types.ts` (structural) and `docs.ollama.com` (live-docs); pass `--skip-live-docs` for offline CI |
+
+---
+
 ## Error Handling
 
 Every failure thrown by the client is an `OllamaClientError` subclass, so you can catch the base
@@ -697,13 +1008,14 @@ class or narrow to a specific `code`:
 | `OllamaAuthError`                  | `auth_error`                    | `false`     | The endpoint returned `401`/`403`.                                                                                                                                                                                                                       |
 | `OllamaNotFoundError`              | `not_found`                     | `false`     | The endpoint returned `404` (e.g. unknown model).                                                                                                                                                                                                        |
 | `OllamaRateLimitError`             | `rate_limited`                  | `true`      | The endpoint returned `429`.                                                                                                                                                                                                                             |
-| `OllamaQuotaExceededError`         | `quota_exceeded`                | `false`     | `QuotaManager.assertCanProceed` was called and would exceed a configured usage budget. Thrown client-side, before any network call — see [Quota Monitoring](#quota-monitoring).                                                                        |
-| `OllamaModelRoutingError`          | `model_routing_error`           | `false`     | No configured `endpoints` entry's `models` allow-list includes the requested model. Thrown client-side, before any network call — see [Multiple API keys, each entitled to different models](#multiple-api-keys-each-entitled-to-different-models).   |
+| `OllamaQuotaExceededError`         | `quota_exceeded`                | `false`     | `QuotaManager.assertCanProceed` was called and would exceed a configured usage budget. Thrown client-side, before any network call — see [Quota Monitoring](#quota-monitoring).                                                                          |
+| `OllamaModelRoutingError`          | `model_routing_error`           | `false`     | No configured `endpoints` entry's `models` allow-list includes the requested model. Thrown client-side, before any network call — see [Multiple API keys, each entitled to different models](#multiple-api-keys-each-entitled-to-different-models).      |
 | `OllamaServerError`                | `server_error`                  | `true`      | The endpoint returned `5xx`.                                                                                                                                                                                                                             |
 | `OllamaAbortError`                 | `aborted`                       | `false`     | The request was cancelled via `AbortSignal`.                                                                                                                                                                                                             |
 | `OllamaToolValidationError`        | `tool_validation_error`         | `false`     | A tool call's arguments, or a `chatWithSchema`/`generateWithSchema` result, failed Zod validation.                                                                                                                                                       |
 | `OllamaUnsupportedCapabilityError` | `unsupported_capability`        | `false`     | A `format` (structured output) request was made against an endpoint inferred as Ollama Cloud, which doesn't currently support it. Thrown before any network call; in `DEFAULT_FAILOVER_CODES`, so a multi-endpoint setup tries the next candidate first. |
-| `OllamaAgentMaxIterationsError`    | `agent_max_iterations_exceeded` | `false`     | An `Agent` run exceeded `maxTurns` without producing a final answer.                                                                                                                                                                                     |
+| `OllamaIncompatibleModelError`     | `incompatible_model`            | `false`     | A tool-enabled `Agent` run was blocked by capability preflight because `/api/show` did not advertise `tools`.                                                                                                                                            |
+| `OllamaAgentMaxIterationsError`    | `agent_max_iterations_exceeded` | `false`     | An `Agent` run exceeded `maxIterations` without producing a final answer.                                                                                                                                                                                |
 | `OllamaMcpError`                   | `mcp_error`                     | varies      | An MCP `listTools`/`callTool` call failed.                                                                                                                                                                                                               |
 | `OllamaSkillNotFoundError`         | `skill_not_found`               | `false`     | `applySkill` referenced a skill that isn't registered.                                                                                                                                                                                                   |
 | `OllamaSkillInvalidError`          | `skill_invalid`                 | `false`     | A skill's frontmatter or contents failed to parse.                                                                                                                                                                                                       |
@@ -736,9 +1048,70 @@ observe per-endpoint circuit state directly.
 
 ---
 
+## Documentation
+
+The repository maintains implementation-facing documentation alongside the package README:
+
+- [Architecture Decision Records](./docs/adr/README.md) — rationale for durable API and architecture choices.
+- [Canonical Ollama IR](./contracts/ir/ollama.ir.json) — machine-readable Ollama contract compiled from sources + overlays, checked by CI.
+- [Multi-model agent benchmarking guide](./docs/guides/multi-model-agent-benchmarking.md) — running agent roles across multiple Ollama endpoints.
+- [Upstream compatibility notes](./docs/upstream/) — pinned OpenAI/Anthropic compatibility references and the upstream OpenAPI snapshot.
+- [Manual laboratory](./LAB_README.md) — runnable experiments for protocol, tool, streaming, and agent behavior.
+
+## Contract parity verification
+
+`npm run verify:contract-parity` checks the canonical IR against the official Ollama
+documentation. The structural half verifies that every `parity.request.fields` /
+`parity.response.fields` entry exists on the hand-written TypeScript interfaces
+in `src/types.ts` and `src/integrations/*`. The live-docs half (when run without
+`--skip-live-docs`) fetches the rendered docs at `docs.ollama.com` and asserts each
+supported field is documented as supported, each unsupported field is explicitly
+marked as such, and each streaming event type is present.
+
+The gate covers every documented native REST endpoint (`chat`, `generate`, `embed`,
+`tags`, `ps`, `show`, `create`, `copy`, `pull`, `push`, `delete`, and `version`)
+plus the OpenAI and Anthropic compatibility request surfaces. SDK-only fields
+that exist in `src/types.ts` but are absent from the OpenAPI snapshot are declared
+as `sdkOnlyFields` in the overlay parity blocks and treated as expected drift,
+not findings.
+
+## Middleware and request lifecycle
+
+`OllamaClient` accepts `middleware` and `onLifecycleEvent` configuration. Middleware runs
+around the underlying HTTP request for native endpoints, OpenAI/Anthropic compatibility,
+model health checks, and the hosted web tools. Lifecycle events expose `start`, `success`,
+`retry`, and `error` events with a request id, timing, and status/error information.
+
+```ts
+const client = new OllamaClient({
+  middleware: [
+    async ({ request, next }) => {
+      request.headers['X-Request-Source'] = 'my-app';
+      return next();
+    },
+  ],
+  onLifecycleEvent: (event) => {
+    console.log(event.type, event.requestId);
+  },
+});
+```
+
+Retry backoff is also cancellation-aware: passing an `AbortSignal` to `withRetry` or cancelling an `OllamaClient` request interrupts an in-progress backoff immediately instead of waiting for the next retry delay.
+
+## Compatibility routing and stream lifecycle
+
+OpenAI and Anthropic compatibility requests use the same endpoint registry, model-scoped
+routing, failover, concurrency limits, and request cancellation as native inference calls.
+When `stream: true`, an endpoint capacity slot remains held until the compatibility stream
+finishes, errors, or is explicitly aborted.
+
+Compatibility stream objects expose `.abort()` and `finalResult`. The configured request
+timeout remains active for the lifetime of the stream rather than ending when HTTP headers
+arrive.
+
 ## Testing
 
-The test suite contains 121 automated tests across 4 testing tiers:
+The test suite is exercised across unit, integration, and functional coverage:
 
 ```bash
 # Run unit, integration, and functional test suite