@nemesis-oss/ollama-sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to `@nemesis-oss/ollama-sdk` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-08-17
+
+First public release. The version was `0.1.0` throughout development but was never
+published to npm, so the entire feature set below ships as the initial `1.0.0`.
+
+`1.0.0` marks the public API surface (`OllamaClient`, `Agent`, `ToolRegistry`, the
+streaming adapters, the error hierarchy, and the compatibility bridges) as stable under
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) — breaking changes to it now
+require a major version bump.
+
+### Added
+
+- **Core Ollama REST API Client:**
+  - Full support for `chat`, `generate`, `embed`, `embeddings`, `ps`, and `version`.
+  - Zero-runtime-dependency HTTP transport with native `fetch`, streaming NDJSON parsing, and binary body blob uploads.
+  - Multi-endpoint high availability registry with circuit breaker failover, priority routing, and health checks.
+  - Configurable exponential backoff with full jitter, retryable error predicates, and timeout signal propagation.
+- **Model Lifecycle & Blob Management:**
+  - `createModel`, `pullModel`, `pushModel`, `copyModel`, `deleteModel`, `listModels`, `showModel`.
+  - Dedicated blob management endpoints: `createBlob` (`POST /api/blobs/:digest`) and `checkBlob` (`HEAD /api/blobs/:digest`).
+- **Structured Outputs & Schema Validation:**
+  - Seamless Zod schema conversion to JSON Schema, supporting both Zod v4 (native `z.toJSONSchema`) and Zod v3 (structural fallback).
+  - Structured output parsing with resilient markdown code fence JSON extraction and strict validation errors (`OllamaToolValidationError`).
+  - `zod` is a peer dependency (`^3.22.0 || ^4.0.0`) rather than a bundled dependency, so consumers don't end up with a duplicate copy in `node_modules`.
+- **Reasoning & Thinking Tokens:**
+  - Native parsing of reasoning traces (`<think>` tags and `message.thinking`) with dual stream events (`thinking` vs `token`).
+- **Agentic Workflow & Tool Calling:**
+  - Autonomous multi-turn agent execution loop (`Agent`).
+  - Tool definition helper (`defineTool`) with Zod parameter schemas.
+  - Tool registry with duplicate detection and execution error recovery.
+  - Model Context Protocol (MCP) server integration (`createMcpToolSet`, `registerMcpTools`).
+  - Opt-in tool execution sandboxing: per-tool/registry `timeoutMs` (cooperative cancellation via `AbortSignal`, surfaced as `OllamaToolTimeoutError`), `maxConcurrency` bounding parallel tool calls, and `maxOutputChars` truncating oversized tool output before it re-enters the conversation history. See [ADR 0004](./docs/adr/0004-tool-execution-sandboxing.md).
+  - Synthetic, client-generated `tool_call_id` correlation: `ToolCall.id`, `Message.tool_call_id`, and `ToolExecutionResult.toolCallId` — Ollama's native protocol has no call ID, so the SDK synthesizes a stable one (`crypto.randomUUID()`, the Web Standard global, not `node:crypto`, to stay Edge-safe) the first time it sees a call without one, and reuses it consistently across the streamed `tool_call` event, the final aggregated message, the tool execution result, and the `role: 'tool'` history entry `Agent` appends. Execution/result correlation by array order still works exactly as before; `id` is an additive convenience. See [ADR 0007](./docs/adr/0007-synthetic-tool-call-ids.md).
+- **Architecture Decision Records:** `docs/adr/` documents the rationale behind the circuit breaker failure model, the dual ESM/CJS packaging strategy, Zod v3/v4 dual support, the tool execution sandboxing model, OpenTelemetry instrumentation, Edge runtime CI verification, synthetic tool-call IDs, endpoint failover scope, and registry parameter variance.
+- **OpenTelemetry Instrumentation:** Automatic spans (`@opentelemetry/api` is an optional peer dependency, a no-op when absent or unconfigured) for HTTP requests, endpoint failover attempts, non-streaming `chat`/`generate` calls (using the Gen AI semantic conventions, including token usage), and `Agent` runs (`invoke_agent` → `ollama.agent.turn` → `execute_tool`). See [ADR 0005](./docs/adr/0005-opentelemetry-instrumentation.md).
+- **Edge Runtime CI Verification:** `npm run verify:edge-runtime` bundles `dist/index.js` for a browser/edge platform with `esbuild` (failing on any `node:*` import, matching Cloudflare Workers/Vercel Edge Runtime's own bundlers) and runs a full `OllamaClient` + `Agent` + tool-calling round trip inside `@edge-runtime/vm`'s sandboxed Edge Runtime — a real V8 context exposing only Web Standard globals. Wired into CI as its own job and into `verify`/`prepublishOnly`. See [ADR 0006](./docs/adr/0006-edge-runtime-ci-and-benchmarks.md).
+- **Benchmarks:** `npm run bench` (via `vitest bench`, no new dependency) covers NDJSON stream parsing, Zod schema conversion/structured output parsing, `ToolRegistry` dispatch overhead, and `OllamaClient.chat`'s end-to-end request pipeline overhead. Wired into CI as its own job.
+- **Protocol Compatibility Bridges:**
+  - OpenAI compatibility bridge (`/v1/chat/completions`, `/v1/models`), including `stream_options.include_usage` and `tools` (function calling) typing — both confirmed supported by Ollama's OpenAI-compat layer; `tool_choice`/`parallel_tool_calls` are deliberately not typed, since Ollama documents `tool_choice` as explicitly unsupported. `@remarks` JSDoc on `OpenAICompatClient` scopes it as a documented subset of the OpenAI API, not the full Responses API surface.
+  - Anthropic compatibility bridge (`/v1/messages`), including `cache_control` typing on content blocks for prompt caching. `@remarks` JSDoc on `AnthropicCompatClient` scopes it as a subset of the Messages API (no tool use, extended thinking, citations, files, or Batches API).
+- **Capability Detection Fixes:** `ModelCapabilities.supportsStructuredOutputRequest` is no longer hardcoded `true` — it's inferred `false` for endpoints classified as `cloud` by `inferRuntimeMode` (Ollama Cloud does not currently support structured outputs) and documented as a best-effort heuristic, not a guarantee, since Ollama doesn't expose this as a queryable capability. Added `supportsThinking`, derived from the model's reported `thinking` capability.
+- **Fail-Fast `OllamaUnsupportedCapabilityError`:** `chat`/`chatStream`/`chatWithSchema` and `generate`/`generateStream`/`generateWithSchema` now throw this error _before making any network call_ when `format` is set against an endpoint inferred as Ollama Cloud, instead of sending a request Ollama Cloud is known to reject. `unsupported_capability` is included in `DEFAULT_FAILOVER_CODES`, so a multi-endpoint setup tries the next candidate (e.g. a local fallback) before the error ever reaches the caller — verified with a test asserting the rejected cloud endpoint's URL is never actually fetched.
+- **`dimensions` on `embed()`:** `EmbedRequestOptions.dimensions` lets callers request truncated embedding vectors, matching Ollama's `/api/embed` parameter.
+- **Environment Variable Fallbacks:** `OllamaClient`'s default single-endpoint `baseUrl`/`apiKey` fall back to `OLLAMA_HOST`/`OLLAMA_API_KEY` (the same variables the official `ollama` CLI and client libraries read) when not passed explicitly, matching the convention of other major LLM SDKs. Guarded to remain a no-op (not a `ReferenceError`) on Edge runtimes where `process` doesn't exist. Explicit `config.baseUrl`/`config.apiKey`, and any use of `config.endpoints`, always take precedence.
+- **Web Standard Stream Adapters:**
+  - `toTextStream`, `toDataStream`, and `toResponse` for direct integration with Next.js, Vercel AI SDK, and Web standard streams.
+- **Skills System:**
+  - Frontmatter parser for `SKILL.md` documents.
+  - Skill composition and prompt injection into system messages (`applySkill`).
+- **Documentation Hygiene:** `OllamaClient.embeddings()` is now marked `@deprecated` (Ollama's `/api/embeddings` was superseded by `/api/embed`, exposed as `embed()`). `ToolCall`, `Agent`, and `ToolRegistry.executeToolCalls` document that Ollama's native tool-calling protocol has no wire-level call ID, dispatch/results are still ordered/concurrency-bounded rather than ID-driven, and that `id`/`tool_call_id` (see above) is a client-synthesized convenience layered on top, not a protocol guarantee.
+- **Testing & Quality Assurance:**
+  - New cancellation tests prove `AbortSignal` genuinely aborts the underlying `fetch` call (not just racing a promise) and propagates from `Agent.run` into `ToolExecutionContext.signal`, including the early-abort race where the signal is already aborted before the request starts.
+  - 4-tier test architecture: Unit, Integration, Functional, and Behavioral testing (50 tests).
+  - VCR record and replay harness with real cassettes generated against `qwen3.5:2b` and `nomic-embed-text:latest`.
+  - Multi-node CI/CD workflow (Node 18, 20, 22) and automated npm release with provenance.
+
+### Fixed
+
+- **`ToolRegistry` rejected every concretely-typed tool.** Its constructor, `register`, and `registerMany` accepted `Tool<never, unknown>`; because `Tool` is invariant in `TParams` (it appears in both `schema: z.ZodType<TParams>` and `execute`), _nothing_ was assignable to it — so `new ToolRegistry([myTool])`, `new ToolRegistry({ tools: [myTool] })`, and `.register(myTool)` all failed to compile for consumers, including the exact example in this README. Replaced with a new exported `AnyTool` alias. Tool authoring keeps full type safety (`defineTool` still infers `TParams` from the Zod schema and type-checks `execute` against it); only the registry's storage type is widened. Found by installing the packed tarball into a throwaway TypeScript project during pre-publish verification. See [ADR 0009](./docs/adr/0009-anytool-registry-variance.md).
+- **Tests are now type-checked.** `tsconfig.json` scoped checking to `src/`, and Vitest's esbuild transform strips types without verifying them — so all 20 test files were unchecked, and had masked the bug above with `as never` casts. `npm run typecheck` now uses `tsconfig.typecheck.json`, covering `src/`, `test/`, `bench/`, and `scripts/`. The casts (and a matching `as unknown as z.ZodType<never>` in `mcp-tools.ts`) are gone.
+
+### Changed
+
+- **Endpoint Failover Scope:** `ModelsClient` operations (`list`, `show`, `pull`, `push`, `create`, `delete`, `copy`, `ps`, `version`, `createBlob`, `checkBlob`) and `OllamaClient.capabilities()` no longer participate in cross-endpoint failover — each now targets only the single best candidate endpoint (same-endpoint retry via backoff still applies). These operations act on a specific server's local model catalog/blob store, which isn't an interchangeable resource across endpoints the way `chat`/`generate`/`embed` inference is; failing `deleteModel`/`listModels`/etc. over to a different endpoint was silently operating on the wrong server's state, not retrying "the same" request. `chat`/`generate`/`embed`/`embeddings`/`webSearch`/`webFetch` failover behavior is unchanged. See [ADR 0008](./docs/adr/0008-endpoint-failover-scope.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shubham Taywade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,378 @@
+# @nemesis-oss/ollama-sdk
+
+[![CI](https://github.com/shubhamtaywade82/ollama-client-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/shubhamtaywade82/ollama-client-ts/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@nemesis-oss/ollama-sdk.svg)](https://www.npmjs.com/package/@nemesis-oss/ollama-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> Production-grade TypeScript SDK for Ollama. Built with native fetch, high availability failover, multi-turn tool calling, structured outputs with Zod, reasoning stream tokens, OpenAI & Anthropic compatibility bridges, MCP integration, and Web Stream adapters.
+
+---
+
+## 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.5:2b`, `deepseek-r1`) with discrete `thinking` and `token` streaming events.
+- 🎯 **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.
+- 🌉 **OpenAI & Anthropic Compatibility Bridges**: Built-in clients for `/v1/chat/completions`, `/v1/models`, and `/v1/messages`.
+- 🌊 **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.
+- ⚡ **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.
+
+---
+
+## Installation
+
+```bash
+npm install @nemesis-oss/ollama-sdk zod
+```
+
+`zod` is a peer dependency (`^3.22.0 || ^4.0.0`) — install whichever major version your project already uses instead of getting a second copy bundled in.
+
+---
+
+## Quick Start
+
+### Basic Chat & Completion
+
+```typescript
+import { OllamaClient } from '@nemesis-oss/ollama-sdk';
+
+const client = new OllamaClient();
+
+// Text helper
+const answer = await client.chatText({
+  model: 'qwen3.5:2b',
+  messages: [{ role: 'user', content: 'Explain quantum computing in one sentence.' }],
+});
+console.log(answer);
+```
+
+### Thinking & Reasoning Token Streams
+
+```typescript
+const stream = await client.chatStream({
+  model: 'qwen3.5:2b',
+  messages: [{ role: 'user', content: 'What is 18 * 4?' }],
+  options: { temperature: 0 },
+});
+
+for await (const event of stream) {
+  if (event.type === 'thinking') {
+    process.stdout.write(`\x1b[33m${event.data.delta}\x1b[0m`); // Thinking trace
+  } else if (event.type === 'token') {
+    process.stdout.write(event.data.delta); // Final answer token
+  }
+}
+
+const final = await stream.finalResult;
+console.log(`\nEval tokens/sec: ${final.usage?.tokensPerSecond}`);
+```
+
+### Structured Outputs with Zod
+
+```typescript
+import { z } from 'zod';
+
+const ProductSchema = z.object({
+  name: z.string(),
+  category: z.enum(['electronics', 'books', 'apparel']),
+  price: z.number(),
+  tags: z.array(z.string()),
+});
+
+const product = await client.chatWithSchema(
+  {
+    model: 'qwen3.5:2b',
+    messages: [{ role: 'user', content: 'Generate a gaming keyboard item.' }],
+  },
+  ProductSchema,
+);
+
+console.log(product.name, product.price);
+```
+
+### Vector Embeddings & Similarity
+
+```typescript
+const res = await client.embed({
+  model: 'nomic-embed-text:latest',
+  input: [
+    'Machine learning and neural networks',
+    'Artificial intelligence algorithms',
+    'Baking traditional French sourdough bread',
+  ],
+});
+
+console.log(
+  `Generated ${res.embeddings.length} vectors with dimension ${res.embeddings[0].length}`,
+);
+```
+
+### Autonomous Agent & Tool Calling
+
+```typescript
+import { Agent, defineTool, ToolRegistry, OllamaClient } from '@nemesis-oss/ollama-sdk';
+import { z } from 'zod';
+
+const client = new OllamaClient();
+
+const weatherTool = defineTool({
+  name: 'get_weather',
+  description: 'Get the current weather for a city',
+  schema: z.object({ city: z.string() }),
+  execute: async ({ city }) => ({ city, temperature: '22°C', condition: 'Sunny' }),
+});
+
+const registry = new ToolRegistry([weatherTool]);
+const agent = new Agent(client, { tools: registry, maxIterations: 5 });
+
+const response = await agent.run({
+  model: 'qwen3.5:2b',
+  messages: [{ role: 'user', content: 'What is the weather in Tokyo?' }],
+});
+
+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).
+
+### Tool Execution Safety & Sandboxing
+
+Tool arguments and, indirectly, which tools get called at all are driven by model
+output — treat them as untrusted input. `ToolRegistry` supports three defensive
+controls, all opt-in (disabled by default, matching prior behavior) so existing agents
+aren't affected until you turn them on:
+
+```typescript
+const registry = new ToolRegistry({
+  tools: [weatherTool],
+  // Fail a call that runs longer than this instead of stalling the agent loop forever.
+  // Override per-tool via `defineTool({ ..., timeoutMs: 2_000 })`.
+  timeoutMs: 10_000,
+  // Cap how many tool calls run in parallel when the model requests several at once.
+  maxConcurrency: 4,
+  // Truncate oversized tool output before it re-enters the conversation history.
+  maxOutputChars: 20_000,
+});
+```
+
+- **`timeoutMs`** races the tool call against a timer and rejects with
+  `OllamaToolTimeoutError` on expiry. Enforcement is cooperative: it stops the _agent_
+  from waiting indefinitely, but genuinely halting a tool's in-flight work still
+  requires the tool itself to check `ToolExecutionContext.signal` (which the registry
+  aborts on timeout) — plain synchronous or non-abort-aware async code cannot be
+  force-killed from the same thread. See [ADR 0004](./docs/adr/0004-tool-execution-sandboxing.md)
+  for the full rationale and what a stronger guarantee would require.
+- **`maxConcurrency`** bounds parallel execution instead of the previous unconditional
+  `Promise.all`, so a model requesting dozens of simultaneous tool calls can't exhaust
+  connection pools, rate limits, or memory all at once.
+- **`maxOutputChars`** truncates `outputString` (what gets fed back into the
+  conversation) while leaving the untruncated value on `result.result` for callers who
+  need it — bounding how much a single tool call can inflate context size or memory.
+- Zod's `safeParse` already validates every tool call's arguments against its schema
+  before `execute` runs (`OllamaToolValidationError` on mismatch). By default, Zod
+  objects silently strip unrecognized keys rather than rejecting them; call `.strict()`
+  on a tool's schema if you need to reject unexpected extra arguments outright.
+
+### Web Standard Streams & Next.js Integration
+
+```typescript
+import { toResponse } from '@nemesis-oss/ollama-sdk';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const stream = await client.chatStream({
+    model: 'qwen3.5:2b',
+    messages,
+  });
+
+  return toResponse(stream);
+}
+```
+
+### OpenAI & Anthropic Compatibility Bridges
+
+```typescript
+// OpenAI compatibility endpoint (/v1/chat/completions)
+const openAIRes = await client.openai.chatCompletions({
+  model: 'llama3.2',
+  messages: [{ role: 'user', content: 'Hello via OpenAI bridge' }],
+});
+
+// Anthropic compatibility endpoint (/v1/messages)
+const anthropicRes = await client.anthropic.messages({
+  model: 'llama3.2',
+  messages: [{ role: 'user', content: 'Hello via Anthropic bridge' }],
+});
+```
+
+### Multi-Endpoint High Availability Failover
+
+```typescript
+const client = new OllamaClient({
+  endpoints: [
+    { name: 'local-gpu', baseUrl: 'http://localhost:11434', priority: 10 },
+    {
+      name: 'cloud-replica',
+      baseUrl: 'https://ollama.internal.net',
+      apiKey: 'secret',
+      priority: 5,
+    },
+  ],
+  timeoutMs: 30_000,
+  retries: 3,
+});
+
+// Active health check probe
+const health = await client.healthCheck();
+console.log(health);
+```
+
+Failover applies to inference calls (`chat`, `generate`, `embed`, `embeddings`,
+`webSearch`, `webFetch`) — a different endpoint serving the same model is a genuine
+substitute for those. Model/blob management (`listModels`, `pullModel`, `deleteModel`,
+etc.) and `capabilities()` target one specific endpoint's local state and deliberately do
+**not** fail over to a different candidate: retrying `deleteModel` against a different
+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).
+
+---
+
+### Observability with OpenTelemetry
+
+The client automatically emits [OpenTelemetry](https://opentelemetry.io/) spans for HTTP
+requests, endpoint failover attempts, `chat`/`generate` calls (using the
+[Gen AI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)), and
+`Agent` runs (`invoke_agent` → `ollama.agent.turn` → `execute_tool`) — no client
+configuration required. `@opentelemetry/api` is an **optional peer dependency**: if it
+isn't installed, or if your process hasn't registered a `TracerProvider`, tracing is a
+no-op and costs nothing beyond a single cached import attempt.
+
+```bash
+npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node
+```
+
+```typescript
+// instrumentation.ts — run before importing the rest of your app
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+
+const sdk = new NodeSDK({
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+sdk.start();
+```
+
+Once a `TracerProvider` is registered, every `OllamaClient`/`Agent` call in your process
+produces spans automatically. See [ADR 0005](./docs/adr/0005-opentelemetry-instrumentation.md)
+for exactly which spans and attributes are emitted, and the tradeoffs behind that design.
+
+---
+
+### Edge Runtime Compatibility
+
+The core client (`OllamaClient`, `Agent`, `ToolRegistry`, and everything exported from
+the package root) is built entirely on native `fetch` and Web Streams, so it runs
+unmodified on Cloudflare Workers, Vercel Edge Runtime, and Next.js Edge middleware/route
+handlers — no Node.js APIs required. The only Node-specific code (`SkillRegistry`, which
+reads `SKILL.md` files from disk) lives behind the separate `@nemesis-oss/ollama-sdk/skills`
+subpath export and is never pulled into the main bundle.
+
+This is enforced in CI, not just asserted: `npm run verify:edge-runtime` bundles
+`dist/index.js` with `esbuild` targeting a browser/edge platform (which hard-fails on any
+`node:*` import, the same way Cloudflare's and Vercel's own bundlers do) and then runs a
+full `OllamaClient` + `Agent` + tool-calling round trip inside `@edge-runtime/vm` — a
+real Edge Runtime sandbox exposing only Web Standard globals. See
+[ADR 0006](./docs/adr/0006-edge-runtime-ci-and-benchmarks.md) for the full rationale.
+
+---
+
+## Error Handling
+
+Every failure thrown by the client is an `OllamaClientError` subclass, so you can catch the base
+class or narrow to a specific `code`:
+
+| Class                              | `code`                          | `retryable` | Thrown when                                                                                                                                                                                                                                              |
+| ---------------------------------- | ------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OllamaNetworkError`               | `network_error`                 | `true`      | The request failed before a response was received (DNS, connection refused, etc).                                                                                                                                                                        |
+| `OllamaTimeoutError`               | `timeout`                       | `true`      | The request exceeded `timeoutMs`.                                                                                                                                                                                                                        |
+| `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`.                                                                                                                                                                                                                             |
+| `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.                                                                                                                                                                                     |
+| `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.                                                                                                                                                                                                       |
+| `OllamaGenericClientError`         | `client_error`                  | `false`     | Any other non-2xx response not covered above.                                                                                                                                                                                                            |
+
+All subclasses carry `status`, `retryable`, and optional `request`/`response` context, and preserve
+the original error via the standard `cause` property:
+
+```typescript
+import { OllamaClientError, OllamaRateLimitError } from '@nemesis-oss/ollama-sdk';
+
+try {
+  await client.chatText({ model: 'qwen3.5:2b', messages: [...] });
+} catch (err) {
+  if (err instanceof OllamaRateLimitError) {
+    console.warn(`Rate limited, retry after ${err.retryAfterMs}ms`);
+  } else if (err instanceof OllamaClientError) {
+    console.error(`[${err.code}] ${err.message}`, { retryable: err.retryable, cause: err.cause });
+  } else {
+    throw err;
+  }
+}
+```
+
+Multi-endpoint failover (`endpoints: [...]`) fails open rather than throwing a dedicated
+"circuit open" error: once an endpoint's failure count crosses `failureThreshold`, it's skipped in
+favor of healthy endpoints for `cooldownMs`, and only used again — sorted soonest-to-recover — if
+every endpoint is cooling down. Call `client.healthCheck()` or inspect the registry's `status()` to
+observe per-endpoint circuit state directly.
+
+---
+
+## Testing
+
+The test suite contains 105 automated tests across 4 testing tiers:
+
+```bash
+# Run unit, integration, and functional test suite
+npm test
+
+# Run typechecker
+npm run typecheck
+
+# Run linter
+npm run lint
+
+# Verify the built package runs correctly in a real Edge Runtime sandbox with zero
+# Node.js APIs (see "Edge Runtime Compatibility" above) — requires `npm run build` first
+npm run verify:edge-runtime
+
+# Run the benchmark suite (NDJSON streaming, schema conversion, tool dispatch, the
+# request pipeline)
+npm run bench
+
+# Run full CI verification pipeline (typecheck, lint, test, build, edge runtime check)
+npm run verify
+```
+
+---
+
+## License
+
+MIT © [Shubham Taywade](https://github.com/shubhamtaywade82)