@nemesis-oss/ollama-sdk 1.1.0 → 1.4.0

package/README.md

@@ -11,19 +11,140 @@
 ## Key Features
 
 - 🚀 **Native Web Standards**: Built on native `fetch` and Web Streams. Zero external HTTP dependencies.
-- 🧠 **Reasoning & Thinking Tokens**: First-class support for reasoning models (`qwen3:8b`, `deepseek-r1:8b`) with discrete `thinking` and `token` streaming events.
+- 🧠 **Reasoning & Thinking Tokens**: First-class support for reasoning models (`qwen3:8b`, `deepseek-r1:8b`) via the native `think` parameter, with discrete `thinking` and `token` streaming events, plus `logprobs`/`top_logprobs` for token-level confidence scoring.
+- 🖼️ **Multimodal / Vision Input**: `images` on `Message`/`generate()` accepts base64 strings or raw `Uint8Array` bytes (auto-encoded) for vision models like `llava` or `qwen2.5vl`.
 - 🎯 **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, and active health checks.
-- 🔌 **Model Context Protocol (MCP)**: Native adapters to convert MCP tools into Ollama-compatible function schemas.
+- 🌐 **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`.
 - 🌉 **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.
 - 🌊 **Web Stream Adapters**: Drop-in adapters (`toTextStream`, `toDataStream`, `toResponse`) for Next.js Route Handlers and Vercel AI SDK.
 - 📈 **OpenTelemetry Instrumentation**: Automatic spans for HTTP requests, endpoint failover, chat/generate calls, and agent runs — zero-cost when OpenTelemetry isn't installed.
+- 📊 **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
@@ -53,10 +174,13 @@ console.log(answer);
 
 ### Thinking & Reasoning Token Streams
 
+`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({
   model: 'qwen3:8b',
   messages: [{ role: 'user', content: 'What is 18 * 4?' }],
+  think: 'high',
   options: { temperature: 0 },
 });
 
@@ -72,6 +196,61 @@ 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.
+
+```typescript
+const res = await client.chat({
+  model: 'llama3.2',
+  messages: [{ role: 'user', content: 'Is Paris the capital of France?' }],
+  logprobs: true,
+  top_logprobs: 3,
+  stream: false,
+});
+
+for (const entry of res.logprobs ?? []) {
+  console.log(entry.token, entry.logprob, entry.top_logprobs);
+}
+```
+
+### Multimodal / Vision Input
+
+`images` on a `Message` (or on `generate()`'s top-level request) accepts base64-encoded strings or raw `Uint8Array` bytes — `Uint8Array` entries are base64-encoded automatically before the request is sent.
+
+```typescript
+import { readFile } from 'node:fs/promises';
+
+const imageBytes = await readFile('./cat.png'); // Buffer, a Uint8Array subclass
+
+const res = await client.chatText({
+  model: 'llava',
+  messages: [{ role: 'user', content: 'What is in this image?', images: [imageBytes] }],
+});
+console.log(res);
+
+// Base64 strings work too, unchanged:
+const base64Res = await client.generateText({
+  model: 'llava',
+  prompt: 'Describe this image.',
+  images: ['iVBORw0KGgoAAAANSUhEUgAA...'],
+});
+```
+
 ### Structured Outputs with Zod
 
 ```typescript
@@ -112,6 +291,51 @@ console.log(
 );
 ```
 
+`embed()` targets the modern `/api/embed` endpoint (batch `input`, `truncate`, and `dimensions` truncation are all supported). The older single-prompt `/api/embeddings` is still available as `client.embeddings()`, but it's `@deprecated` — Ollama's own docs consider it legacy in favor of `/api/embed`.
+
+### Model Lifecycle Management
+
+Full parity with Ollama's model catalog and blob-store API — every method targets one specific endpoint's local state and deliberately does **not** cross-endpoint fail over (see [ADR 0008](./docs/adr/0008-endpoint-failover-scope.md)):
+
+```typescript
+// What's currently loaded in VRAM right now
+const running = await client.ps();
+console.log(running.models.map((m) => `${m.name} (${m.size_vram} bytes VRAM)`));
+
+// Create a custom model from an existing base, without hand-writing a Modelfile string
+await client.createModel({
+  model: 'my-assistant',
+  from: 'llama3.2',
+  system: 'You are a terse, no-nonsense assistant.',
+  parameters: { temperature: 0.2 },
+});
+
+await client.copyModel({ source: 'my-assistant', destination: 'my-assistant-backup' });
+await client.pushModel({ model: 'my-namespace/my-assistant' });
+await client.deleteModel({ model: 'my-assistant-backup' });
+```
+
+### Web Search & Web Fetch (Ollama Cloud)
+
+`webSearch`/`webFetch` wrap Ollama's **hosted** web tools (`POST https://ollama.com/api/web_search` and `/api/web_fetch`) — a fixed Ollama Cloud service, entirely separate from whatever local `baseUrl`/`endpoints` the client is configured with. They require an Ollama account API key (`apiKey` on the client, or the `OLLAMA_API_KEY` environment variable) regardless of where your inference traffic goes:
+
+```typescript
+const client = new OllamaClient({
+  baseUrl: 'http://localhost:11434', // local inference — unrelated to the calls below
+  apiKey: process.env.OLLAMA_API_KEY, // required for webSearch/webFetch specifically
+});
+
+const search = await client.webSearch({ query: 'latest Ollama release notes', max_results: 5 });
+for (const result of search.results) {
+  console.log(result.title, result.url, result.content);
+}
+
+const page = await client.webFetch({ url: 'https://ollama.com/blog' });
+console.log(page.title, page.content.slice(0, 200));
+```
+
+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.
+
 ### Autonomous Agent & Tool Calling
 
 ```typescript
@@ -138,12 +362,59 @@ 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
+per-endpoint `models` allow-lists (see
+["Multiple API keys, each entitled to different models"](#multiple-api-keys-each-entitled-to-different-models)) —
+the client resolves the right key from the model name, and `Agent` itself stays
+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
 
@@ -271,6 +542,224 @@ etc.) and `capabilities()` target one specific endpoint's local state and delibe
 server doesn't retry the same operation, it silently acts on a different model catalog.
 See [ADR 0008](./docs/adr/0008-endpoint-failover-scope.md).
 
+#### Multiple API keys, each entitled to different models
+
+A common Ollama Cloud shape: several API keys, each unlocking a different set of models
+under your plan (e.g. one free-tier key per model family). Give each endpoint a `models`
+allow-list and the client resolves the right credential from the `model` you request —
+cross-endpoint failover only ever considers endpoints actually authorized for that model,
+so it never burns a request retrying an unrelated key:
+
+```typescript
+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'],
+    },
+  ],
+});
+
+// Routed to KEY_1 automatically:
+await client.chat({ model: 'gpt-oss:120b', messages });
+// Routed to KEY_2 automatically:
+await client.chat({ model: 'minimax-m3', messages });
+```
+
+An endpoint with no `models` field stays eligible for every model (the pre-existing
+behavior), so this is fully opt-in and mixes freely with unscoped endpoints. Requesting a
+model no configured endpoint is scoped to throws `OllamaModelRoutingError` immediately —
+no network call, no probing every key to see which one happens to work. Two or more
+endpoints can share the same model in their `models` list to get ordinary failover
+between multiple keys/replicas for that one model. See
+[Guide: Benchmarking Agent Models Across Multiple Ollama Cloud Keys](./docs/guides/multi-model-agent-benchmarking.md)
+for the full multi-key/multi-role pattern this was built for.
+
+**`credentials` + `modelBindings`** is an equivalent, map-based way to write the same
+config, if you prefer keying by an id you choose over an array of endpoint objects — both
+compile down to the same `endpoints`/`models` routing underneath, so pick whichever reads
+better in your codebase:
+
+```typescript
+const client = new OllamaClient({
+  baseUrl: 'https://ollama.com',
+  credentials: {
+    supervisor: { apiKey: process.env.OLLAMA_KEY_1! },
+    coder: { apiKey: process.env.OLLAMA_KEY_2! },
+    researcher: { apiKey: process.env.OLLAMA_KEY_3! },
+  },
+  modelBindings: {
+    'gpt-oss:120b': 'supervisor',
+    'minimax-m3': 'coder',
+    'nemotron-3-super': 'researcher',
+    // A model can also be bound to several credentials — failover applies between them:
+    // 'gpt-oss:120b': ['supervisor', 'supervisor-backup'],
+  },
+  // Optional: serves any model with no entry above, at lower priority than an explicit binding.
+  // defaultCredential: 'supervisor',
+});
+```
+
+`modelBindings` referencing a `credentials` id that doesn't exist throws immediately at
+construction — a typo in this config fails loudly, not by silently routing nowhere.
+`credentials`/`modelBindings` merge additively with an `endpoints` array if you pass both.
+
+#### A free pool of interchangeable keys — and spreading load across it
+
+Register several keys as `credentials` and skip `modelBindings` for them entirely: an
+unbound credential is eligible for every model, so any of them can serve any request:
+
+```typescript
+const client = new OllamaClient({
+  baseUrl: 'https://ollama.com',
+  credentials: {
+    key1: { apiKey: process.env.OLLAMA_KEY_1! },
+    key2: { apiKey: process.env.OLLAMA_KEY_2! },
+    key3: { apiKey: process.env.OLLAMA_KEY_3! },
+  },
+});
+
+await client.chat({ model: 'any-model-you-like', messages });
+```
+
+By default, candidates at the same priority (the case here — none of these keys were
+given an explicit `priority`) are tried in registration order every time: `key1` first,
+falling over to `key2`/`key3` only if `key1` fails. To spread consecutive requests across
+the pool instead — so `key1`, `key2`, `key3` each take a turn rather than `key1` always
+going first — set `endpointHealth: { strategy: 'round-robin' }`:
+
+```typescript
+const client = new OllamaClient({
+  baseUrl: 'https://ollama.com',
+  credentials: {
+    key1: { apiKey: process.env.OLLAMA_KEY_1! },
+    key2: { apiKey: process.env.OLLAMA_KEY_2! },
+    key3: { apiKey: process.env.OLLAMA_KEY_3! },
+  },
+  endpointHealth: { strategy: 'round-robin' },
+});
+```
+
+Each `chat`/`generate`/`embed`/etc. call rotates the starting candidate by one position
+within its priority tier — `key1, key2, key3, key1, key2, key3, ...` — while failover
+still applies if whichever key ends up first happens to fail. Round-robin never lets a
+lower-priority candidate jump ahead of a higher-priority one; it only reorders candidates
+that were already tied. This works identically with plain `endpoints` (no `credentials`
+required) and composes with `models`/`modelBindings` scoping — a scoped credential's tier
+of one is unaffected, only an actual multi-candidate tier rotates.
+
+#### Concurrent requests across single-slot accounts (least-connections)
+
+Round-robin spreads requests over time, but it doesn't track whether a previous request
+on a given account is still running — with uneven request durations, two round-robin
+picks can still land on the same still-busy account back to back. That matters
+specifically for Ollama Cloud's free tier, which caps each account at **1 concurrent
+request**: if your application fires several requests at once (e.g. `Promise.all` across
+different models) using $N$ free-tier accounts, you want a guarantee that no two land on
+the same account while it's still busy — not just "spread out on average".
+
+`strategy: 'least-connections'` provides that guarantee. Each request is routed to
+whichever candidate currently has the fewest requests still in flight:
+
+```typescript
+const client = new OllamaClient({
+  baseUrl: 'https://ollama.com',
+  credentials: {
+    account1: { apiKey: process.env.OLLAMA_KEY_1! },
+    account2: { apiKey: process.env.OLLAMA_KEY_2! },
+    account3: { apiKey: process.env.OLLAMA_KEY_3! },
+  },
+  endpointHealth: { strategy: 'least-connections' },
+});
+
+// Each of these lands on a different account — none has to wait on another's
+// in-flight request, and no single free-tier account gets hit with a 2nd concurrent
+// request while its 1st is still running.
+const [llama, qwen, mistral] = await Promise.all([
+  client.chat({ model: 'llama3', messages: llamaMessages }),
+  client.chat({ model: 'qwen2.5', messages: qwenMessages }),
+  client.chat({ model: 'mistral', messages: mistralMessages }),
+]);
+```
+
+This is deterministic, not probabilistic: the endpoint chosen for one request and the
+`acquire()` that marks it in-flight happen synchronously with no `await` in between, and
+JS's single-threaded execution means no two concurrent calls can ever observe the same
+"0 active" snapshot for the same candidate — so `N` concurrent calls against `N`
+same-priority candidates always land on `N` distinct ones, regardless of how the calls
+happen to interleave. In-flight counts are also exposed via `client.endpointStatus()[].activeRequests`
+for observability, and release automatically on both success and failure (including when
+an account's actual 429 forces failover to the next-least-busy candidate). Priority tiers
+are respected the same way as `'round-robin'` — a higher-priority candidate is still
+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_
+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
+`maxConcurrentPerEndpoint` to cap that exactly and queue instead:
+
+```typescript
+const client = new OllamaClient({
+  baseUrl: 'https://ollama.com',
+  credentials: {
+    account1: { apiKey: process.env.OLLAMA_KEY_1! },
+    account2: { apiKey: process.env.OLLAMA_KEY_2! },
+  },
+  endpointHealth: { strategy: 'least-connections', maxConcurrentPerEndpoint: 1 },
+});
+
+// With 2 accounts capped at 1 request each: the first two calls run immediately, one
+// per account; the third waits (no fetch is made for it yet) until either finishes,
+// then takes that freed slot.
+const [a, b, c] = await Promise.all([
+  client.chat({ model: 'm1', messages: m1Messages }),
+  client.chat({ model: 'm2', messages: m2Messages }),
+  client.chat({ model: 'm3', messages: m3Messages }),
+]);
+```
+
+Waiting is bounded by the same `timeoutMs`/`AbortSignal` as the rest of the request — a
+queued call that times out or is cancelled is removed from the queue and rejects without
+ever having been sent, rather than hanging indefinitely. Queue wake order is best-effort
+FIFO (a slot that frees can, rarely, be won by a brand-new call instead of the
+longest-waiting one) — the exact cap, not fairness, is the guarantee this exists for.
+
+#### Slot lifecycle: streaming and tool-calling agents
+
+Two details matter for the concurrency accounting (`'least-connections'`/
+`maxConcurrentPerEndpoint`/`activeRequests`) to reflect reality rather than just the
+initial HTTP round trip:
+
+- **Streaming (`chatStream`/`generateStream`) holds the slot for as long as the stream is
+  actually being consumed**, not just until the response headers arrive. The promise
+  `chatStream` returns resolves as soon as the stream object exists (mirroring the real
+  HTTP connection, which is still open at that point); the slot releases only once the
+  stream is fully drained, errors, or is aborted. A returned stream that's never iterated
+  (or `.on()`'d) holds its slot indefinitely — same as the underlying HTTP connection
+  would stay open — so always consume or `stream.abort()` a stream you no longer need.
+- **`Agent`'s tool-execution phase never holds a slot.** Each turn's `chat()` call
+  acquires and releases its own slot independently; tool execution happens entirely
+  between turns, outside any `chat()` call, so a slow tool never ties up one of your
+  scarce concurrent-request accounts.
+
 ---
 
 ### Observability with OpenTelemetry
@@ -304,6 +793,67 @@ for exactly which spans and attributes are emitted, and the tradeoffs behind tha
 
 ---
 
+### Quota Monitoring
+
+Ollama Cloud doesn't expose account-level quota through the API — chat/generate
+responses carry only per-request token counts, and there's no header or endpoint that
+reports how much of your plan's session or weekly limit is left. The only way to see
+that today is the [ollama.com dashboard](https://ollama.com) or the 90%-usage email (see
+[ollama/ollama#15663](https://github.com/ollama/ollama/issues/15663)). Free-tier usage
+resets on a session window (~5 hours) and a weekly window (7 days), and is measured in
+compute, not a fixed token count, so a budget you set for one model won't transfer
+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
+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.
+
+```typescript
+import {
+  OllamaClient,
+  OllamaQuotaExceededError,
+  OllamaRateLimitError,
+  createOllamaCloudFreeTierQuota,
+} from '@nemesis-oss/ollama-sdk';
+
+const client = new OllamaClient({ apiKey: process.env.OLLAMA_API_KEY });
+
+// Session (5h) and weekly (7d) windows, with budgets you choose empirically —
+// Ollama doesn't publish the actual ceilings.
+const quota = createOllamaCloudFreeTierQuota({
+  session: { maxTokens: 50_000 },
+  weekly: { maxTokens: 200_000 },
+});
+
+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 }],
+    });
+    quota.recordUsage(res); // reads prompt_eval_count/eval_count off the raw response
+    return res.message.content;
+  } catch (error) {
+    if (error instanceof OllamaRateLimitError) {
+      console.warn('Server-side rate limit hit — pause until the session window resets.');
+    }
+    throw error;
+  }
+}
+```
+
+`quota.status()` returns per-window `tokensUsed`/`requestsMade`/`remainingTokens`/
+`windowResetAt` for building your own usage dashboard, and `quota.reset(windowId?)` lets
+you clear a window manually (e.g. after confirming a reset on the ollama.com dashboard).
+For budgets that don't match the free tier's cadence, construct `new QuotaManager({
+windows: [...] })` directly with your own `windowMs`/`maxTokens`/`maxRequests` per window.
+
+---
+
 ### Edge Runtime Compatibility
 
 The core client (`OllamaClient`, `Agent`, `ToolRegistry`, and everything exported from
@@ -322,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
@@ -334,11 +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).      |
 | `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.                                                                                                                                                                                                       |
@@ -371,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 114 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