chuk-tool-processor 0.9.7__tar.gz → 0.10__tar.gz

{chuk_tool_processor-0.9.7 → chuk_tool_processor-0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chuk-tool-processor
-Version: 0.9.7
+Version: 0.10
 Summary: Async-native framework for registering, discovering, and executing tools referenced in LLM responses
 Author-email: CHUK Team <chrishayuk@somejunkmailbox.com>
 Maintainer-email: CHUK Team <chrishayuk@somejunkmailbox.com>
@@ -26,65 +26,147 @@ Requires-Dist: psutil>=7.0.0
 Requires-Dist: pydantic>=2.11.3
 Requires-Dist: uuid>=1.30
 
-# CHUK Tool Processor
+# CHUK Tool Processor — Production-grade execution for LLM tool calls
 
 [![PyPI](https://img.shields.io/pypi/v/chuk-tool-processor.svg)](https://pypi.org/project/chuk-tool-processor/)
 [![Python](https://img.shields.io/pypi/pyversions/chuk-tool-processor.svg)](https://pypi.org/project/chuk-tool-processor/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Type Checked](https://img.shields.io/badge/type%20checked-PEP%20561-blue.svg)](https://www.python.org/dev/peps/pep-0561/)
+[![Wheels](https://img.shields.io/badge/wheels-macOS%20%7C%20Linux%20%7C%20Windows-blue.svg)](https://pypi.org/project/chuk-tool-processor/)
+[![OpenTelemetry](https://img.shields.io/badge/observability-OpenTelemetry%20%7C%20Prometheus-blue.svg)](docs/OBSERVABILITY.md)
 
-**The missing link between LLM tool calls and reliable execution.**
+**Reliable tool execution for LLMs — timeouts, retries, caching, rate limits, circuit breakers, and MCP integration — in one composable layer.**
 
-CHUK Tool Processor is a focused, production-ready framework that solves one problem exceptionally well: **processing tool calls from LLM outputs**. It's not a chatbot framework or LLM orchestration platform—it's the glue layer that bridges LLM responses and actual tool execution.
+---
 
-## The Problem
+## The Missing Layer for Reliable Tool Execution
 
-When you build LLM applications, you face a gap:
+LLMs are good at *calling* tools. The hard part is **executing** those tools reliably.
 
-1. **LLM generates tool calls** in various formats (XML tags, OpenAI `tool_calls`, JSON)
-2. **??? Mystery step ???** where you need to:
-   - Parse those calls reliably
-   - Handle timeouts, retries, failures
-   - Cache expensive results
-   - Rate limit API calls
-   - Run untrusted code safely
-   - Connect to external tool servers
-   - Log everything for debugging
-3. **Get results back** to continue the LLM conversation
+**CHUK Tool Processor:**
+- Parses tool calls from any model (Anthropic XML, OpenAI `tool_calls`, JSON)
+- Executes them with **timeouts, retries, caching, rate limits, circuit breaker, observability**
+- Runs tools locally, in **isolated subprocesses**, or **remote via MCP**
 
-Most frameworks give you steps 1 and 3, but step 2 is where the complexity lives. CHUK Tool Processor **is** step 2.
+CHUK Tool Processor is the execution layer between LLM responses and real tools.
 
-## Why chuk-tool-processor?
+It sits **below** agent frameworks and prompt orchestration, and **above** raw tool implementations.
 
-### It's a Building Block, Not a Framework
+```
+    LLM Output
+        ↓
+CHUK Tool Processor
+        ↓
+ ┌──────────────┬────────────────────┐
+ │ Local Tools  │ Remote Tools (MCP) │
+ └──────────────┴────────────────────┘
+```
 
-Unlike full-fledged LLM frameworks (LangChain, LlamaIndex, etc.), CHUK Tool Processor:
+**How it works internally:**
 
-- ✅ **Does one thing well**: Process tool calls reliably
-- ✅ **Plugs into any LLM app**: Works with any framework or no framework
-- ✅ **Composable by design**: Stack strategies and wrappers like middleware
-- ✅ **No opinions about your LLM**: Bring your own OpenAI, Anthropic, local model
-- ❌ **Doesn't manage conversations**: That's your job
-- ❌ **Doesn't do prompt engineering**: Use whatever prompting you want
-- ❌ **Doesn't bundle an LLM client**: Use any client library you prefer
+```
+    LLM Output
+        ↓
+Parsers (XML / OpenAI / JSON)
+        ↓
+┌─────────────────────────────┐
+│   Execution Middleware      │
+│  (Applied in this order)    │
+│   • Cache                   │
+│   • Rate Limit              │
+│   • Retry (with backoff)    │
+│   • Circuit Breaker         │
+└─────────────────────────────┘
+        ↓
+   Execution Strategy
+   ┌──────────────────────┐
+   │ • InProcess          │  ← Fast, trusted
+   │ • Isolated/Subprocess│  ← Safe, untrusted
+   │ • Remote via MCP     │  ← Distributed
+   └──────────────────────┘
+```
 
-### It's Built for Production
+Works with OpenAI, Anthropic, local models (Ollama/MLX/vLLM), and any framework (LangChain, LlamaIndex, custom).
+
+## Executive TL;DR
+
+* **Parse any format:** `XML` (Anthropic), `OpenAI tool_calls`, or raw `JSON`
+* **Execute with production policies:** timeouts/retries/cache/rate-limits/circuit-breaker/idempotency
+* **Run anywhere:** locally (fast), isolated (subprocess sandbox), or remote via MCP (HTTP/STDIO/SSE)
+
+```python
+import asyncio
+from chuk_tool_processor import ToolProcessor, register_tool, initialize
+
+@register_tool(name="weather")
+class WeatherTool:
+    async def execute(self, city: str) -> dict:
+        return {"temp": 72, "condition": "sunny", "city": city}
+
+async def main():
+    await initialize()
+    async with ToolProcessor(enable_caching=True, enable_retries=True) as p:
+        # Works with OpenAI, Anthropic, or JSON formats
+        result = await p.process('<tool name="weather" args=\'{"city": "SF"}\'/>')
+        print(result[0].result)  # {'temp': 72, 'condition': 'sunny', 'city': 'SF'}
 
-Research code vs production code is about handling the edges:
+asyncio.run(main())
+```
 
-- **Timeouts**: Every tool execution has proper timeout handling
-- **Retries**: Automatic retry with exponential backoff and deadline awareness
-- **Rate Limiting**: Global and per-tool rate limits with sliding windows
-- **Caching**: Intelligent result caching with TTL and idempotency key support
-- **Circuit Breakers**: Prevent cascading failures with automatic fault detection
-- **Error Handling**: Machine-readable error codes with structured details
-- **Observability**: Structured logging, metrics, request tracing
-- **Safety**: Subprocess isolation for untrusted code
-- **Type Safety**: Pydantic validation with LLM-friendly argument coercion
-- **Tool Discovery**: Formal schema export (OpenAI, Anthropic, MCP formats)
+> **If you only remember three things:**
+>
+> 1. **Parse** `XML`, `OpenAI tool_calls`, or raw `JSON` automatically
+> 2. **Execute** with timeouts/retries/cache/rate-limits/circuit-breaker
+> 3. **Run** tools locally, isolated (subprocess), or remote via MCP
+
+## When to Use This
+
+Use **CHUK Tool Processor** when:
+- Your LLM calls tools or APIs
+- You need **retries, timeouts, caching, or rate limits**
+- You need to **run untrusted tools safely**
+- Your tools are **local or remote (MCP)**
+
+Do **not** use this if:
+- You want an agent framework
+- You want conversation flow/memory orchestration
+
+**This is the execution layer, not the agent.**
+
+> **Not a framework.**
+> If LangChain/LlamaIndex help decide *which* tool to call,
+> CHUK Tool Processor makes sure the tool call **actually succeeds**.
+
+## Table of Contents
+
+- [The Problem](#the-problem)
+- [Why chuk-tool-processor?](#why-chuk-tool-processor)
+- [Compatibility Matrix](#compatibility-matrix)
+- [Developer Experience Highlights](#developer-experience-highlights)
+- [Quick Start](#quick-start)
+- [Documentation Quick Reference](#documentation-quick-reference)
+- [Choose Your Path](#choose-your-path)
+- [Core Concepts](#core-concepts)
+- [Getting Started](#getting-started)
+- [Advanced Topics](#advanced-topics)
+- [Configuration](#configuration)
+- [Architecture Principles](#architecture-principles)
+- [Examples](#examples)
+- [FAQ](#faq)
+- [Comparison with Other Tools](#comparison-with-other-tools)
+- [Development & Publishing](#development--publishing)
+- [Stability & Versioning](#stability--versioning)
+- [Contributing & Support](#contributing--support)
+
+## The Problem
 
-### It's About Stacks
+LLMs generate tool calls. **The hard part is executing them reliably.**
+
+CHUK Tool Processor **is that execution layer.**
+
+## Why chuk-tool-processor?
 
-CHUK Tool Processor uses a **composable stack architecture**:
+**Composable execution layers:**
 
 ```
 ┌─────────────────────────────────┐
@@ -104,7 +186,7 @@ CHUK Tool Processor uses a **composable stack architecture**:
 ├─────────────────────────────────┤
 │   Execution Strategy            │  ← How to run tools
 │   • InProcess (fast)            │
-│   • Subprocess (isolated)       │
+│   • Isolated (subprocess)       │
 ├─────────────────────────────────┤
 │   Tool Registry                 │  ← Your registered tools
 └─────────────────────────────────┘
@@ -112,8 +194,40 @@ CHUK Tool Processor uses a **composable stack architecture**:
 
 Each layer is **optional** and **configurable**. Mix and match what you need.
 
+### It's a Building Block, Not a Framework
+
+Unlike full-fledged LLM frameworks (LangChain, LlamaIndex, etc.), CHUK Tool Processor:
+
+- ✅ **Does one thing well**: Process tool calls reliably
+- ✅ **Plugs into any LLM app**: Works with any framework or no framework
+- ✅ **Composable by design**: Stack strategies and wrappers like middleware
+- ✅ **No opinions about your LLM**: Bring your own OpenAI, Anthropic, local model
+- ❌ **Doesn't manage conversations**: That's your job
+- ❌ **Doesn't do prompt engineering**: Use whatever prompting you want
+- ❌ **Doesn't bundle an LLM client**: Use any client library you prefer
+
+### It's Built for Production
+
+Research code vs production code is about handling the edges. CHUK Tool Processor includes:
+
+- ✅ **Timeouts** — Every tool execution has proper timeout handling
+- ✅ **Retries** — Automatic retry with exponential backoff and deadline awareness
+- ✅ **Rate Limiting** — Global and per-tool rate limits with sliding windows → [CONFIGURATION.md](docs/CONFIGURATION.md)
+- ✅ **Caching** — Intelligent result caching with TTL and idempotency key support
+- ✅ **Circuit Breakers** — Prevent cascading failures with automatic fault detection
+- ✅ **Idempotency** — SHA256-based deduplication of LLM retry quirks
+- ✅ **Error Handling** — Machine-readable error codes with structured details → [ERRORS.md](docs/ERRORS.md)
+- ✅ **Observability** — Structured logging, metrics, OpenTelemetry tracing → [OBSERVABILITY.md](docs/OBSERVABILITY.md)
+- ✅ **Safety** — Subprocess isolation for untrusted code (zero crash blast radius)
+- ✅ **Type Safety** — PEP 561 compliant with full mypy support
+- ✅ **Resource Management** — Context managers for automatic cleanup
+- ✅ **Tool Discovery** — Formal schema export (OpenAI, Anthropic, MCP formats)
+- ✅ **Cancellation** — Cooperative cancellation with request-scoped deadlines
+
 ## Compatibility Matrix
 
+Runs the same on macOS, Linux, and Windows — locally, serverside, and inside containers.
+
 | Component | Supported Versions | Notes |
 |-----------|-------------------|-------|
 | **Python** | 3.11, 3.12, 3.13 | Python 3.11+ required |
@@ -131,6 +245,19 @@ Each layer is **optional** and **configurable**. Mix and match what you need.
 - ✅ Anthropic Claude 3 (Opus, Sonnet, Haiku)
 - ✅ Local models (Ollama, LM Studio)
 
+## Developer Experience Highlights
+
+**What makes CHUK Tool Processor easy to use:**
+
+* **Auto-parsing**: XML (Claude), OpenAI `tool_calls`, direct JSON—all work automatically
+* **One call**: `process()` handles multiple calls & formats in a single invocation
+* **Auto-coercion**: Pydantic-powered argument cleanup (whitespace, type conversion, extra fields ignored)
+* **Safe defaults**: timeouts, retries, caching toggles built-in
+* **Observability in one line**: `setup_observability(...)` for traces + metrics
+* **MCP in one call**: `setup_mcp_http_streamable|stdio|sse(...)` connects to remote tools instantly
+* **Context managers**: `async with ToolProcessor() as p:` ensures automatic cleanup
+* **Full type safety**: PEP 561 compliant—mypy, pyright, and IDEs get complete type information
+
 ## Quick Start
 
 ### Installation
@@ -143,19 +270,95 @@ pip install chuk-tool-processor
 
 # Using uv (recommended)
 uv pip install chuk-tool-processor
+```
+
+<details>
+<summary><strong>Install from source or with extras</strong></summary>
 
-# Or from source
+```bash
+# From source
 git clone https://github.com/chrishayuk/chuk-tool-processor.git
 cd chuk-tool-processor
 uv pip install -e .
+
+# With observability extras (OpenTelemetry + Prometheus)
+pip install chuk-tool-processor[observability]
+
+# With MCP extras
+pip install chuk-tool-processor[mcp]
+
+# All extras
+pip install chuk-tool-processor[all]
+```
+
+</details>
+
+<details>
+<summary><strong>Type Checking Support (PEP 561 compliant)</strong></summary>
+
+CHUK Tool Processor includes **full type checking support**:
+
+```python
+# mypy, pyright, and IDEs get full type information!
+from chuk_tool_processor import ToolProcessor, ToolCall, ToolResult
+
+async with ToolProcessor() as processor:
+    # Full autocomplete and type checking
+    results: list[ToolResult] = await processor.process(llm_output)
+    tools: list[str] = await processor.list_tools()
 ```
 
+**Features:**
+- ✅ `py.typed` marker for PEP 561 compliance
+- ✅ Comprehensive type hints on all public APIs
+- ✅ Works with mypy, pyright, pylance
+- ✅ Full IDE autocomplete support
+
+**No special mypy configuration needed** - just import and use!
+
+</details>
+
 ## 60-Second Quick Start
 
-**Absolutely minimal example** → See `examples/hello_tool.py`:
+### From raw LLM output to safe execution in 3 lines
+
+```python
+from chuk_tool_processor import ToolProcessor, initialize
+
+await initialize()
+async with ToolProcessor() as p:
+    results = await p.process('<tool name="calculator" args=\'{"operation":"multiply","a":15,"b":23}\'/>')
+```
+
+**Note:** This assumes you've registered a "calculator" tool. See complete example below.
+
+### Works with Both OpenAI and Anthropic (No Adapters Needed)
+
+```python
+from chuk_tool_processor import ToolProcessor, register_tool, initialize
+
+@register_tool(name="search")
+class SearchTool:
+    async def execute(self, query: str) -> dict:
+        return {"results": [f"Found: {query}"]}
+
+await initialize()
+async with ToolProcessor() as p:
+    # OpenAI format
+    openai_response = {"tool_calls": [{"type": "function", "function": {"name": "search", "arguments": '{"query": "Python"}'}}]}
+
+    # Anthropic format
+    anthropic_response = '<tool name="search" args=\'{"query": "Python"}\'/>'
+
+    # Both work identically
+    results_openai = await p.process(openai_response)
+    results_anthropic = await p.process(anthropic_response)
+```
+
+**Absolutely minimal example** → See `examples/01_getting_started/hello_tool.py`:
 
 ```bash
-python examples/hello_tool.py
+python examples/01_getting_started/hello_tool.py
 ```
 
 Single file that demonstrates:
@@ -171,8 +374,7 @@ Copy-paste this into a file and run it:
 
 ```python
 import asyncio
-from chuk_tool_processor.core.processor import ToolProcessor
-from chuk_tool_processor.registry import initialize, register_tool
+from chuk_tool_processor import ToolProcessor, register_tool, initialize
 
 # Step 1: Define a tool
 @register_tool(name="calculator")
@@ -186,29 +388,142 @@ class Calculator:
 # Step 2: Process LLM output
 async def main():
     await initialize()
-    processor = ToolProcessor()
 
-    # Your LLM returned this tool call
-    llm_output = '<tool name="calculator" args=\'{"operation": "multiply", "a": 15, "b": 23}\'/>'
+    # Use context manager for automatic cleanup
+    async with ToolProcessor() as processor:
+        # Your LLM returned this tool call
+        llm_output = '<tool name="calculator" args=\'{"operation": "multiply", "a": 15, "b": 23}\'/>'
 
-    # Process it
-    results = await processor.process(llm_output)
+        # Process it
+        results = await processor.process(llm_output)
 
-    # Each result is a ToolExecutionResult with: tool, args, result, error, duration, cached
-    # results[0].result contains the tool output
-    # results[0].error contains any error message (None if successful)
-    if results[0].error:
-        print(f"Error: {results[0].error}")
-    else:
-        print(results[0].result)  # {'result': 345}
+        # Each result is a ToolResult with: tool, result, error, duration, cached
+        if results[0].error:
+            print(f"Error: {results[0].error}")
+        else:
+            print(results[0].result)  # {'result': 345}
+
+    # Processor automatically cleaned up!
 
 asyncio.run(main())
 ```
 
-**That's it.** You now have production-ready tool execution with timeouts, retries, and caching.
+**That's it.** You now have production-ready tool execution with:
+- ✅ Automatic timeouts, retries, and caching
+- ✅ Clean resource management (context manager)
+- ✅ Full type checking support
 
 > **Why not just use OpenAI tool calls?**
-> OpenAI's function calling is great for parsing, but you still need: parsing multiple formats (Anthropic XML, etc.), timeouts, retries, rate limits, caching, subprocess isolation, and connecting to external MCP servers. CHUK Tool Processor **is** that missing middle layer.
+> OpenAI's function calling is great for parsing, but you still need: parsing multiple formats (Anthropic XML, etc.), timeouts, retries, rate limits, caching, subprocess isolation, connecting to external MCP servers, and **per-tool** policy control with cross-provider parsing and MCP fan-out. CHUK Tool Processor **is** that missing middle layer.
+
+## Quick Decision Tree (Commit This to Memory)
+
+```
+╭──────────────────────────────────────────╮
+│ Do you trust the code you're executing?  │
+│   ✅ Yes → InProcessStrategy              │
+│   ⚠️ No → IsolatedStrategy (sandboxed)     │
+│                                          │
+│ Where do your tools live?                │
+│   📦 Local → @register_tool               │
+│   🌐 Remote → setup_mcp_http_streamable    │
+╰──────────────────────────────────────────╯
+```
+
+**That's all you need to pick the right pattern.**
+
+## Registry & Processor Lifecycle
+
+Understanding the lifecycle helps you use CHUK Tool Processor correctly:
+
+1. **`await initialize()`** — loads the global registry; call **once per process** at application startup
+2. Create a **`ToolProcessor(...)`** (or use the one returned by `setup_mcp_*`)
+3. Use **`async with ToolProcessor() as p:`** to ensure cleanup
+4. **`setup_mcp_*`** returns `(processor, manager)` — reuse that `processor`
+5. If you need a custom registry, pass it explicitly to the strategy
+6. You rarely need `get_default_registry()` unless you're composing advanced setups
+
+**⚠️ Important:** `initialize()` must run **once per process**, not once per request or processor instance. Running it multiple times will duplicate tools in the registry.
+
+```python
+# Standard pattern
+await initialize()  # Step 1: Register tools
+
+async with ToolProcessor() as p:  # Step 2-3: Create + auto cleanup
+    results = await p.process(llm_output)
+    # Step 4: Processor automatically cleaned up on exit
+```
+
+## Production Features by Example
+
+### Idempotency & Deduplication
+
+Automatically deduplicate LLM retry quirks using SHA256-based idempotency keys:
+
+```python
+from chuk_tool_processor import ToolProcessor, initialize
+
+await initialize()
+async with ToolProcessor(enable_caching=True, cache_ttl=300) as p:
+    # LLM retries the same call (common with streaming or errors)
+    call1 = '<tool name="search" args=\'{"query": "Python"}\'/>'
+    call2 = '<tool name="search" args=\'{"query": "Python"}\'/>'  # Identical
+
+    results1 = await p.process(call1)  # Executes
+    results2 = await p.process(call2)  # Cache hit! (idempotency key match)
+
+    assert results1[0].cached == False
+    assert results2[0].cached == True
+```
+
+### Cancellation & Deadlines
+
+Cooperative cancellation with request-scoped deadlines:
+
+```python
+import asyncio
+from chuk_tool_processor import ToolProcessor, initialize
+
+async def main():
+    await initialize()
+    async with ToolProcessor(default_timeout=60.0) as p:
+        try:
+            # Hard deadline for the whole batch (e.g., user request budget)
+            async with asyncio.timeout(5.0):
+                async for event in p.astream('<tool name="slow_report" args=\'{"n": 1000000}\'/>'):
+                    print("chunk:", event)
+        except TimeoutError:
+            print("Request cancelled: deadline exceeded")
+            # Processor automatically cancels the tool and cleans up
+
+asyncio.run(main())
+```
+
+### Per-Tool Policy Overrides
+
+Override timeouts, retries, and rate limits per tool:
+
+```python
+from chuk_tool_processor import ToolProcessor, initialize
+
+await initialize()
+async with ToolProcessor(
+    default_timeout=30.0,
+    enable_retries=True,
+    max_retries=2,
+    enable_rate_limiting=True,
+    global_rate_limit=120,  # 120 requests/min across all tools
+    tool_rate_limits={
+        "expensive_api": (5, 60),  # 5 requests per 60 seconds
+        "fast_local": (1000, 60),  # 1000 requests per 60 seconds
+    }
+) as p:
+    # Tools run with their specific policies
+    results = await p.process('''
+        <tool name="expensive_api" args='{"q":"abc"}'/>
+        <tool name="fast_local" args='{"data":"xyz"}'/>
+    ''')
+```
 
 ## Documentation Quick Reference
 
@@ -217,17 +532,19 @@ asyncio.run(main())
 | 📘 [CONFIGURATION.md](docs/CONFIGURATION.md) | **All config knobs & defaults**: ToolProcessor options, timeouts, retry policy, rate limits, circuit breakers, caching, environment variables |
 | 🚨 [ERRORS.md](docs/ERRORS.md) | **Error taxonomy**: All error codes, exception classes, error details structure, handling patterns, retryability guide |
 | 📊 [OBSERVABILITY.md](docs/OBSERVABILITY.md) | **Metrics & tracing**: OpenTelemetry setup, Prometheus metrics, spans reference, PromQL queries |
-| 🔌 [examples/hello_tool.py](examples/hello_tool.py) | **60-second starter**: Single-file, copy-paste-and-run example |
+| 🔌 [examples/01_getting_started/hello_tool.py](examples/01_getting_started/hello_tool.py) | **60-second starter**: Single-file, copy-paste-and-run example |
 | 🎯 [examples/](examples/) | **20+ working examples**: MCP integration, OAuth flows, streaming, production patterns |
 
 ## Choose Your Path
 
+**Use this when OpenAI/Claude tool calling is not enough** — because you need retries, caching, rate limits, subprocess isolation, or MCP integration.
+
 | Your Goal | What You Need | Where to Look |
 |-----------|---------------|---------------|
 | ☕ **Just process LLM tool calls** | Basic tool registration + processor | [60-Second Quick Start](#60-second-quick-start) |
 | 🔌 **Connect to external tools** | MCP integration (HTTP/STDIO/SSE) | [MCP Integration](#5-mcp-integration-external-tools) |
 | 🛡️ **Production deployment** | Timeouts, retries, rate limits, caching | [CONFIGURATION.md](docs/CONFIGURATION.md) |
-| 🔒 **Run untrusted code safely** | Subprocess isolation strategy | [Subprocess Strategy](#using-subprocess-strategy) |
+| 🔒 **Run untrusted code safely** | Isolated strategy (subprocess) | [Isolated Strategy](#using-isolated-strategy) |
 | 📊 **Monitor and observe** | OpenTelemetry + Prometheus | [OBSERVABILITY.md](docs/OBSERVABILITY.md) |
 | 🌊 **Stream incremental results** | StreamingTool pattern | [StreamingTool](#streamingtool-real-time-results) |
 | 🚨 **Handle errors reliably** | Error codes & taxonomy | [ERRORS.md](docs/ERRORS.md) |
@@ -239,8 +556,7 @@ Here are the most common patterns you'll use:
 **Pattern 1: Local tools only**
 ```python
 import asyncio
-from chuk_tool_processor.core.processor import ToolProcessor
-from chuk_tool_processor.registry import initialize, register_tool
+from chuk_tool_processor import ToolProcessor, register_tool, initialize
 
 @register_tool(name="my_tool")
 class MyTool:
@@ -249,20 +565,22 @@ class MyTool:
 
 async def main():
     await initialize()
-    processor = ToolProcessor()
 
-    llm_output = '<tool name="my_tool" args=\'{"arg": "hello"}\'/>'
-    results = await processor.process(llm_output)
-    print(results[0].result)  # {'result': 'Processed: hello'}
+    async with ToolProcessor() as processor:
+        llm_output = '<tool name="my_tool" args=\'{"arg": "hello"}\'/>'
+        results = await processor.process(llm_output)
+        print(results[0].result)  # {'result': 'Processed: hello'}
 
 asyncio.run(main())
 ```
 
+<details>
+<summary><strong>More patterns: MCP integration (local + remote tools)</strong></summary>
+
 **Pattern 2: Mix local + remote MCP tools (Notion)**
 ```python
 import asyncio
-from chuk_tool_processor.registry import initialize, register_tool
-from chuk_tool_processor.mcp import setup_mcp_http_streamable
+from chuk_tool_processor import register_tool, initialize, setup_mcp_http_streamable
 
 @register_tool(name="local_calculator")
 class Calculator:
@@ -292,10 +610,13 @@ async def main():
     print(f"Local result: {results[0].result}")
     print(f"Notion result: {results[1].result}")
 
+    # Clean up
+    await manager.close()
+
 asyncio.run(main())
 ```
 
-See `examples/notion_oauth.py` for complete OAuth flow.
+See `examples/04_mcp_integration/notion_oauth.py` for complete OAuth flow.
 
 **Pattern 3: Local SQLite database via STDIO**
 ```python
@@ -334,7 +655,9 @@ async def main():
 asyncio.run(main())
 ```
 
-See `examples/stdio_sqlite.py` for complete working example.
+See `examples/04_mcp_integration/stdio_sqlite.py` for complete working example.
+
+</details>
 
 ## Core Concepts
 
@@ -347,8 +670,10 @@ The **registry** is where you register tools for execution. Tools can be:
 - **StreamingTool** for real-time incremental results
 - **Functions** registered via `register_fn_tool()`
 
+> **Note:** The registry is global, processors are scoped.
+
 ```python
-from chuk_tool_processor.registry import register_tool
+from chuk_tool_processor import register_tool
 from chuk_tool_processor.models.validated_tool import ValidatedTool
 from pydantic import BaseModel, Field
 
@@ -374,18 +699,16 @@ class WeatherTool(ValidatedTool):
 | Strategy | Use Case | Trade-offs |
 |----------|----------|------------|
 | **InProcessStrategy** | Fast, trusted tools | Speed ✅, Isolation ❌ |
-| **SubprocessStrategy** | Untrusted or risky code | Isolation ✅, Speed ❌ |
+| **IsolatedStrategy** | Untrusted or risky code | Isolation ✅, Speed ❌ |
 
 ```python
 import asyncio
-from chuk_tool_processor.core.processor import ToolProcessor
-from chuk_tool_processor.execution.strategies.subprocess_strategy import SubprocessStrategy
-from chuk_tool_processor.registry import get_default_registry
+from chuk_tool_processor import ToolProcessor, IsolatedStrategy, get_default_registry
 
 async def main():
     registry = await get_default_registry()
     processor = ToolProcessor(
-        strategy=SubprocessStrategy(
+        strategy=IsolatedStrategy(
             registry=registry,
             max_workers=4,
             default_timeout=30.0
@@ -396,6 +719,8 @@ async def main():
 asyncio.run(main())
 ```
 
+**Note:** `IsolatedStrategy` is an alias of `SubprocessStrategy` for backwards compatibility. Use `IsolatedStrategy` for clarity—it better communicates the security boundary intent.
+
 ### 3. Execution Wrappers (Middleware)
 
 **Wrappers** add production features as composable layers:
@@ -461,6 +786,8 @@ Connect to **remote tool servers** using the [Model Context Protocol](https://mo
 
 #### HTTP Streamable (⭐ Recommended for Cloud Services)
 
+**Use for:** Cloud SaaS services (OAuth, long-running streams, resilient reconnects)
+
 Modern HTTP streaming transport for cloud-based MCP servers like Notion:
 
 ```python
@@ -489,8 +816,13 @@ results = await processor.process(
 )
 ```
 
+<details>
+<summary><strong>Other MCP Transports (STDIO for local tools, SSE for legacy)</strong></summary>
+
 #### STDIO (Best for Local/On-Device Tools)
 
+**Use for:** Local/embedded tools and databases (SQLite, file systems, local services)
+
 For running local MCP servers as subprocesses—great for databases, file systems, and local tools:
 
 ```python
@@ -529,6 +861,8 @@ results = await processor.process(
 
 #### SSE (Legacy Support)
 
+**Use for:** Legacy compatibility only. Prefer HTTP Streamable for new integrations.
+
 For backward compatibility with older MCP servers using Server-Sent Events:
 
 ```python
@@ -550,6 +884,8 @@ processor, manager = await setup_mcp_sse(
 )
 ```
 
+</details>
+
 **Transport Comparison:**
 
 | Transport | Use Case | Real Examples |
@@ -558,6 +894,18 @@ processor, manager = await setup_mcp_sse(
 | **STDIO** | Local tools, databases | SQLite (`mcp-server-sqlite`), Echo (`chuk-mcp-echo`) |
 | **SSE** | Legacy cloud services | Atlassian (`mcp.atlassian.com`) |
 
+**How MCP fits into the architecture:**
+
+```
+    LLM Output
+        ↓
+  Tool Processor
+        ↓
+ ┌──────────────┬────────────────────┐
+ │ Local Tools  │ Remote Tools (MCP) │
+ └──────────────┴────────────────────┘
+```
+
 **Relationship with [chuk-mcp](https://github.com/chrishayuk/chuk-mcp):**
 - `chuk-mcp` is a low-level MCP protocol client (handles transports, protocol negotiation)
 - `chuk-tool-processor` wraps `chuk-mcp` to integrate external tools into your execution pipeline
@@ -571,7 +919,7 @@ CHUK Tool Processor supports multiple patterns for defining tools:
 
 #### Simple Function-Based Tools
 ```python
-from chuk_tool_processor.registry.auto_register import register_fn_tool
+from chuk_tool_processor import register_fn_tool
 from datetime import datetime
 from zoneinfo import ZoneInfo
 
@@ -629,17 +977,26 @@ class FileProcessor(StreamingTool):
 
 ```python
 import asyncio
-from chuk_tool_processor.core.processor import ToolProcessor
-from chuk_tool_processor.registry import initialize
+from chuk_tool_processor import ToolProcessor, initialize
 
 async def main():
     await initialize()
     processor = ToolProcessor()
-    async for event in processor.astream('<tool name="file_processor" args=\'{"file_path":"README.md"}\'/>'):
-        # 'event' is a streamed chunk (either your Result model instance or a dict)
-        line = event["line"] if isinstance(event, dict) else getattr(event, "line", None)
-        content = event["content"] if isinstance(event, dict) else getattr(event, "content", None)
-        print(f"Line {line}: {content}")
+
+    # Stream can be cancelled by breaking or raising an exception
+    try:
+        async for event in processor.astream('<tool name="file_processor" args=\'{"file_path":"README.md"}\'/>'):
+            # 'event' is a streamed chunk (either your Result model instance or a dict)
+            line = event["line"] if isinstance(event, dict) else getattr(event, "line", None)
+            content = event["content"] if isinstance(event, dict) else getattr(event, "content", None)
+            print(f"Line {line}: {content}")
+
+            # Example: cancel after 100 lines
+            if line and line > 100:
+                break  # Cleanup happens automatically
+    except asyncio.CancelledError:
+        # Stream cleanup is automatic even on cancellation
+        pass
 
 asyncio.run(main())
 ```
@@ -648,23 +1005,32 @@ asyncio.run(main())
 
 #### Basic Usage
 
-Call `await initialize()` once at startup to load your registry.
+Call `await initialize()` once at startup to load your registry. Use context managers for automatic cleanup:
 
 ```python
 import asyncio
-from chuk_tool_processor.core.processor import ToolProcessor
-from chuk_tool_processor.registry import initialize
+from chuk_tool_processor import ToolProcessor, initialize
 
 async def main():
     await initialize()
-    processor = ToolProcessor()
-    llm_output = '<tool name="calculator" args=\'{"operation":"add","a":2,"b":3}\'/>'
-    results = await processor.process(llm_output)
-    for result in results:
-        if result.error:
-            print(f"Error: {result.error}")
-        else:
-            print(f"Success: {result.result}")
+
+    # Context manager automatically handles cleanup
+    async with ToolProcessor() as processor:
+        # Discover available tools
+        tools = await processor.list_tools()
+        print(f"Available tools: {tools}")
+
+        # Process LLM output
+        llm_output = '<tool name="calculator" args=\'{"operation":"add","a":2,"b":3}\'/>'
+        results = await processor.process(llm_output)
+
+        for result in results:
+            if result.error:
+                print(f"Error: {result.error}")
+            else:
+                print(f"Success: {result.result}")
+
+    # Processor automatically cleaned up here!
 
 asyncio.run(main())
 ```
@@ -672,21 +1038,32 @@ asyncio.run(main())
 #### Production Configuration
 
 ```python
-from chuk_tool_processor.core.processor import ToolProcessor
+from chuk_tool_processor import ToolProcessor, initialize
+import asyncio
 
-processor = ToolProcessor(
-    # Execution settings
-    default_timeout=30.0,
-    max_concurrency=20,
+async def main():
+    await initialize()
 
-    # Production features
-    enable_caching=True,
-    cache_ttl=600,
-    enable_rate_limiting=True,
-    global_rate_limit=100,
-    enable_retries=True,
-    max_retries=3
-)
+    # Use context manager with production config
+    async with ToolProcessor(
+        # Execution settings
+        default_timeout=30.0,
+        max_concurrency=20,
+
+        # Production features
+        enable_caching=True,
+        cache_ttl=600,
+        enable_rate_limiting=True,
+        global_rate_limit=100,
+        enable_retries=True,
+        max_retries=3
+    ) as processor:
+        # Use processor...
+        results = await processor.process(llm_output)
+
+    # Automatic cleanup on exit
+
+asyncio.run(main())
 ```
 
 ### Advanced Production Features
@@ -698,7 +1075,7 @@ Beyond basic configuration, CHUK Tool Processor includes several advanced featur
 Prevent cascading failures by automatically opening circuits for failing tools:
 
 ```python
-from chuk_tool_processor.core.processor import ToolProcessor
+from chuk_tool_processor import ToolProcessor
 
 processor = ToolProcessor(
     enable_circuit_breaker=True,
@@ -740,8 +1117,8 @@ assert call1.idempotency_key == call2.idempotency_key
 
 # Used automatically by caching layer
 processor = ToolProcessor(enable_caching=True)
-results1 = await processor.execute([call1])  # Executes
-results2 = await processor.execute([call2])  # Cache hit!
+results1 = await processor.process([call1])  # Executes
+results2 = await processor.process([call2])  # Cache hit!
 ```
 
 **Benefits:**
@@ -749,6 +1126,8 @@ results2 = await processor.execute([call2])  # Cache hit!
 - Deterministic cache keys
 - No manual key management needed
 
+**Cache scope:** In-memory per-process by default. Cache backend is pluggable—see [CONFIGURATION.md](docs/CONFIGURATION.md) for custom cache backends.
+
 #### Tool Schema Export
 
 Export tool definitions to multiple formats for LLM prompting:
@@ -795,7 +1174,9 @@ mcp_format = spec.to_mcp()             # For MCP servers
 
 #### Machine-Readable Error Codes
 
-Structured error handling with error codes for programmatic responses:
+Structured error handling with error codes for programmatic responses.
+
+**Error Contract:** Every error includes a machine-readable code, human-readable message, and structured details:
 
 ```python
 from chuk_tool_processor.core.exceptions import (
@@ -877,22 +1258,20 @@ result = await tool.execute(**llm_output)
 
 ## Advanced Topics
 
-### Using Subprocess Strategy
+### Using Isolated Strategy
 
-Use `SubprocessStrategy` when running untrusted, third-party, or potentially unsafe code that shouldn't share the same process as your main app.
+Use `IsolatedStrategy` when running untrusted, third-party, or potentially unsafe code that shouldn't share the same process as your main app.
 
 For isolation and safety when running untrusted code:
 
 ```python
 import asyncio
-from chuk_tool_processor.core.processor import ToolProcessor
-from chuk_tool_processor.execution.strategies.subprocess_strategy import SubprocessStrategy
-from chuk_tool_processor.registry import get_default_registry
+from chuk_tool_processor import ToolProcessor, IsolatedStrategy, get_default_registry
 
 async def main():
     registry = await get_default_registry()
     processor = ToolProcessor(
-        strategy=SubprocessStrategy(
+        strategy=IsolatedStrategy(
             registry=registry,
             max_workers=4,
             default_timeout=30.0
@@ -903,6 +1282,10 @@ async def main():
 asyncio.run(main())
 ```
 
+> **Security & Isolation — Threat Model**
+>
+> Untrusted tool code runs in subprocesses; faults and crashes don't bring down your app. **Zero crash blast radius.** For hard CPU/RAM/network limits, run the processor inside a container with `--cpus`, `--memory`, and egress filtering. Secrets are never injected by default—pass them explicitly via tool arguments or scoped environment variables.
+
 ### Real-World MCP Examples
 
 #### Example 1: Notion Integration with OAuth
@@ -912,7 +1295,7 @@ Complete OAuth flow connecting to Notion's MCP server:
 ```python
 from chuk_tool_processor.mcp import setup_mcp_http_streamable
 
-# After completing OAuth flow (see examples/notion_oauth.py for full flow)
+# After completing OAuth flow (see examples/04_mcp_integration/notion_oauth.py for full flow)
 processor, manager = await setup_mcp_http_streamable(
     servers=[{
         "name": "notion",
@@ -933,6 +1316,9 @@ results = await processor.process(
 )
 ```
 
+<details>
+<summary><strong>Click to expand more MCP examples (SQLite, Echo Server)</strong></summary>
+
 #### Example 2: Local SQLite Database Access
 
 Run SQLite MCP server locally for database operations:
@@ -1004,10 +1390,15 @@ results = await processor.process(
 )
 ```
 
-See `examples/notion_oauth.py`, `examples/stdio_sqlite.py`, and `examples/stdio_echo.py` for complete working implementations.
+</details>
+
+See `examples/04_mcp_integration/notion_oauth.py`, `examples/04_mcp_integration/stdio_sqlite.py`, and `examples/04_mcp_integration/stdio_echo.py` for complete working implementations.
 
 #### OAuth Token Refresh
 
+<details>
+<summary><strong>Click to expand OAuth token refresh guide</strong></summary>
+
 For MCP servers that use OAuth authentication, CHUK Tool Processor supports automatic token refresh when access tokens expire. This prevents your tools from failing due to expired tokens during long-running sessions.
 
 **How it works:**
@@ -1076,7 +1467,9 @@ processor, manager = await setup_mcp_sse(
 - Token refresh is attempted only once per tool call (no infinite retry loops)
 - After successful refresh, the updated headers are used for all subsequent calls
 
-See `examples/notion_oauth.py` for a complete OAuth 2.1 implementation with PKCE and automatic token refresh.
+See `examples/04_mcp_integration/notion_oauth.py` for a complete OAuth 2.1 implementation with PKCE and automatic token refresh.
+
+</details>
 
 ### Observability
 
@@ -1145,6 +1538,9 @@ asyncio.run(main())
 
 #### OpenTelemetry & Prometheus (Drop-in Observability)
 
+<details>
+<summary><strong>Click to expand complete observability guide</strong></summary>
+
 **3-Line Setup:**
 
 ```python
@@ -1208,8 +1604,7 @@ uv pip install chuk-tool-processor --group observability
 ```python
 import asyncio
 from chuk_tool_processor.observability import setup_observability
-from chuk_tool_processor.core.processor import ToolProcessor
-from chuk_tool_processor.registry import initialize, register_tool
+from chuk_tool_processor import ToolProcessor, initialize, register_tool
 
 @register_tool(name="weather_api")
 class WeatherTool:
@@ -1427,7 +1822,7 @@ export OTEL_EXPORTER_OTLP_ENDPOINT=http://datadog-agent:4317
 - Testing observability features
 - Environment variable configuration
 
-🎯 **Working Example**: See `examples/observability_demo.py` for a complete demonstration with retries, caching, and circuit breakers
+🎯 **Working Example**: See `examples/02_production_features/observability_demo.py` for a complete demonstration with retries, caching, and circuit breakers
 
 **Benefits**
 
@@ -1438,6 +1833,8 @@ export OTEL_EXPORTER_OTLP_ENDPOINT=http://datadog-agent:4317
 ✅ **Optional** - Gracefully degrades if packages not installed
 ✅ **Zero-overhead** - No performance impact when disabled
 
+</details>
+
 ### Error Handling
 
 ```python
@@ -1455,8 +1852,7 @@ for result in results:
 
 ```python
 import pytest
-from chuk_tool_processor.core.processor import ToolProcessor
-from chuk_tool_processor.registry import initialize
+from chuk_tool_processor import ToolProcessor, initialize
 
 @pytest.mark.asyncio
 async def test_calculator():
@@ -1470,6 +1866,40 @@ async def test_calculator():
     assert results[0].result["result"] == 8
 ```
 
+**Fake tool pattern for testing:**
+
+```python
+import pytest
+from chuk_tool_processor import ToolProcessor, register_tool, initialize
+
+@register_tool(name="fake_tool")
+class FakeTool:
+    """No-op tool for testing processor behavior."""
+    call_count = 0
+
+    async def execute(self, **kwargs) -> dict:
+        FakeTool.call_count += 1
+        return {"called": True, "args": kwargs}
+
+@pytest.mark.asyncio
+async def test_processor_with_fake_tool():
+    await initialize()
+    processor = ToolProcessor()
+
+    # Reset counter
+    FakeTool.call_count = 0
+
+    # Execute fake tool
+    results = await processor.process(
+        '<tool name="fake_tool" args=\'{"test_arg": "value"}\'/>'
+    )
+
+    # Assert behavior
+    assert FakeTool.call_count == 1
+    assert results[0].result["called"] is True
+    assert results[0].result["args"]["test_arg"] == "value"
+```
+
 ## Configuration
 
 ### Timeout Configuration
@@ -1480,6 +1910,7 @@ CHUK Tool Processor uses a unified timeout configuration system that applies to
 from chuk_tool_processor.mcp.transport import TimeoutConfig
 
 # Create custom timeout configuration
+# (Defaults are: connect=30, operation=30, quick=5, shutdown=2)
 timeout_config = TimeoutConfig(
     connect=30.0,     # Connection establishment, initialization, session discovery
     operation=30.0,   # Normal operations (tool calls, listing tools/resources/prompts)
@@ -1607,7 +2038,7 @@ CHUK Tool Processor provides multiple layers of safety:
 | Concern | Protection | Configuration |
 |---------|------------|---------------|
 | **Timeouts** | Every tool has a timeout | `default_timeout=30.0` |
-| **Process Isolation** | Run tools in separate processes | `strategy=SubprocessStrategy()` |
+| **Process Isolation** | Run tools in separate processes | `strategy=IsolatedStrategy()` |
 | **Rate Limiting** | Prevent abuse and API overuse | `enable_rate_limiting=True` |
 | **Input Validation** | Pydantic validation on arguments | Use `ValidatedTool` |
 | **Error Containment** | Failures don't crash the processor | Built-in exception handling |
@@ -1619,13 +2050,58 @@ CHUK Tool Processor provides multiple layers of safety:
 - **Resource Limits**: For hard CPU/memory caps, use OS-level controls (cgroups on Linux, Job Objects on Windows, or Docker resource limits).
 - **Secrets**: Never injected automatically. Pass secrets explicitly via tool arguments or environment variables, and prefer scoped env vars for subprocess tools to minimize exposure.
 
+#### OS-Level Hardening
+
+For production deployments, add these hardening measures:
+
+| Concern | Docker/Container Solution | Direct Example |
+|---------|--------------------------|----------------|
+| **CPU/RAM caps** | `--cpus`, `--memory` flags | `docker run --cpus="1.5" --memory="512m" myapp` |
+| **Network egress** | Deny-by-default with firewall rules | `--network=none` or custom network with egress filtering |
+| **Filesystem** | Read-only root + writable scratch | `--read-only --tmpfs /tmp:rw,size=100m` |
+
+**Example: Run processor in locked-down container**
+
+```bash
+# Dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt --no-cache-dir
+COPY . .
+USER nobody  # Run as non-root
+CMD ["python", "app.py"]
+
+# Run with resource limits and network restrictions
+docker run \
+  --cpus="2" \
+  --memory="1g" \
+  --memory-swap="1g" \
+  --read-only \
+  --tmpfs /tmp:rw,size=200m,mode=1777 \
+  --network=custom-net \
+  --cap-drop=ALL \
+  myapp:latest
+```
+
+**Network egress controls (deny-by-default)**
+
+```bash
+# Create restricted network with no internet access (for local-only tools)
+docker network create --internal restricted-net
+
+# Or use iptables for per-tool CIDR allowlists
+iptables -A OUTPUT -d 10.0.0.0/8 -j ACCEPT   # Allow private ranges
+iptables -A OUTPUT -d 172.16.0.0/12 -j ACCEPT
+iptables -A OUTPUT -d 192.168.0.0/16 -j ACCEPT
+iptables -A OUTPUT -j DROP  # Deny everything else
+```
+
 Example security-focused setup for untrusted code:
 
 ```python
 import asyncio
-from chuk_tool_processor.core.processor import ToolProcessor
-from chuk_tool_processor.execution.strategies.subprocess_strategy import SubprocessStrategy
-from chuk_tool_processor.registry import get_default_registry
+from chuk_tool_processor import ToolProcessor, IsolatedStrategy, get_default_registry
 
 async def create_secure_processor():
     # Maximum isolation for untrusted code
@@ -1633,7 +2109,7 @@ async def create_secure_processor():
     registry = await get_default_registry()
 
     processor = ToolProcessor(
-        strategy=SubprocessStrategy(
+        strategy=IsolatedStrategy(
             registry=registry,
             max_workers=4,
             default_timeout=10.0
@@ -1651,6 +2127,25 @@ async def create_secure_processor():
 # - Use read-only filesystems where possible
 ```
 
+## Design Goals & Non-Goals
+
+**What CHUK Tool Processor does:**
+- ✅ Parse tool calls from any LLM format (XML, OpenAI, JSON)
+- ✅ Execute tools with production policies (timeouts, retries, rate limits, caching)
+- ✅ Isolate untrusted code in subprocesses
+- ✅ Connect to remote tool servers via MCP (HTTP/STDIO/SSE)
+- ✅ Provide composable execution layers (strategies + wrappers)
+- ✅ Export tool schemas for LLM prompting
+
+**What CHUK Tool Processor explicitly does NOT do:**
+- ❌ Manage conversations or chat history
+- ❌ Provide prompt engineering or prompt templates
+- ❌ Bundle an LLM client (bring your own OpenAI/Anthropic/local)
+- ❌ Implement agent frameworks or chains
+- ❌ Make decisions about which tools to call
+
+**Why this matters:** CHUK Tool Processor stays focused on reliable tool execution. It's a building block, not a framework. This makes it composable with any LLM application architecture.
+
 ## Architecture Principles
 
 1. **Composability**: Stack strategies and wrappers like middleware
@@ -1664,29 +2159,26 @@ async def create_secure_processor():
 Check out the [`examples/`](examples/) directory for complete working examples:
 
 ### Getting Started
-- **60-second hello**: `examples/hello_tool.py` - Absolute minimal example (copy-paste-run)
-- **Quick start**: `examples/quickstart_demo.py` - Basic tool registration and execution
-- **Execution strategies**: `examples/execution_strategies_demo.py` - InProcess vs Subprocess
-- **Production wrappers**: `examples/wrappers_demo.py` - Caching, retries, rate limiting
-- **Streaming tools**: `examples/streaming_demo.py` - Real-time incremental results
-- **Streaming tool calls**: `examples/streaming_tool_calls_demo.py` - Handle partial tool calls from streaming LLMs
-- **Schema helper**: `examples/schema_helper_demo.py` - Auto-generate schemas from typed tools (Pydantic → OpenAI/Anthropic/MCP)
-- **Observability**: `examples/observability_demo.py` - OpenTelemetry + Prometheus integration
+- **60-second hello**: `examples/01_getting_started/hello_tool.py` - Absolute minimal example (copy-paste-run)
+- **Quick start**: `examples/01_getting_started/quickstart_demo.py` - Basic tool registration and execution
+- **Execution strategies**: `examples/01_getting_started/execution_strategies_demo.py` - InProcess vs Subprocess
+- **Production wrappers**: `examples/02_production_features/wrappers_demo.py` - Caching, retries, rate limiting
+- **Streaming tools**: `examples/03_streaming/streaming_demo.py` - Real-time incremental results
+- **Streaming tool calls**: `examples/03_streaming/streaming_tool_calls_demo.py` - Handle partial tool calls from streaming LLMs
+- **Schema helper**: `examples/05_schema_and_types/schema_helper_demo.py` - Auto-generate schemas from typed tools (Pydantic → OpenAI/Anthropic/MCP)
+- **Observability**: `examples/02_production_features/observability_demo.py` - OpenTelemetry + Prometheus integration
 
 ### MCP Integration (Real-World)
-- **Notion + OAuth**: `examples/notion_oauth.py` - Complete OAuth 2.1 flow with HTTP Streamable
+- **Notion + OAuth**: `examples/04_mcp_integration/notion_oauth.py` - Complete OAuth 2.1 flow with HTTP Streamable
   - Shows: Authorization Server discovery, client registration, PKCE flow, token exchange
-- **SQLite Local**: `examples/stdio_sqlite.py` - Local database access via STDIO
+- **SQLite Local**: `examples/04_mcp_integration/stdio_sqlite.py` - Local database access via STDIO
   - Shows: Command/args passing, environment variables, file paths, initialization timeouts
-- **Echo Server**: `examples/stdio_echo.py` - Minimal STDIO transport example
+- **Echo Server**: `examples/04_mcp_integration/stdio_echo.py` - Minimal STDIO transport example
   - Shows: Simplest possible MCP integration for testing
-- **Atlassian + OAuth**: `examples/atlassian_sse.py` - OAuth with SSE transport (legacy)
+- **Atlassian + OAuth**: `examples/04_mcp_integration/atlassian_sse.py` - OAuth with SSE transport (legacy)
 
 ### Advanced MCP
-- **HTTP Streamable**: `examples/mcp_http_streamable_example.py`
-- **STDIO**: `examples/mcp_stdio_example.py`
-- **SSE**: `examples/mcp_sse_example.py`
-- **Plugin system**: `examples/plugins_builtins_demo.py`, `examples/plugins_custom_parser_demo.py`
+- **Plugin system**: `examples/06_plugins/plugins_builtins_demo.py`, `examples/06_plugins/plugins_custom_parser_demo.py`
 
 ## FAQ
 
@@ -1711,18 +2203,20 @@ A: Use pytest with `@pytest.mark.asyncio`. See [Testing Tools](#testing-tools) f
 **Q: Does this work with streaming LLM responses?**
 A: Yes—as tool calls appear in the stream, extract and process them. The processor handles partial/incremental tool call lists.
 
-**Q: What's the difference between InProcess and Subprocess strategies?**
-A: InProcess is faster (same process), Subprocess is safer (isolated process). Use InProcess for trusted code, Subprocess for untrusted.
+**Q: What's the difference between InProcess and Isolated strategies?**
+A: InProcess is faster (same process), Isolated is safer (separate subprocess). Use InProcess for trusted code, Isolated for untrusted.
 
 ## Comparison with Other Tools
 
 | Feature | chuk-tool-processor | LangChain Tools | OpenAI Tools | MCP SDK |
 |---------|-------------------|-----------------|--------------|---------|
 | **Async-native** | ✅ | ⚠️ Partial | ✅ | ✅ |
-| **Process isolation** | ✅ SubprocessStrategy | ❌ | ❌ | ⚠️ |
+| **Process isolation** | ✅ IsolatedStrategy | ❌ | ❌ | ⚠️ |
 | **Built-in retries** | ✅ | ❌ † | ❌ | ❌ |
 | **Rate limiting** | ✅ | ❌ † | ⚠️ ‡ | ❌ |
 | **Caching** | ✅ | ⚠️ † | ❌ ‡ | ❌ |
+| **Idempotency & de-dup** | ✅ SHA256 keys | ❌ | ❌ | ❌ |
+| **Per-tool policies** | ✅ (timeouts/retries/limits) | ⚠️ | ❌ | ❌ |
 | **Multiple parsers** | ✅ (XML, OpenAI, JSON) | ⚠️ | ✅ | ✅ |
 | **Streaming tools** | ✅ | ⚠️ | ⚠️ | ✅ |
 | **MCP integration** | ✅ All transports | ❌ | ❌ | ✅ (protocol only) |
@@ -1799,6 +2293,25 @@ For detailed release documentation, see:
 - **[RELEASING.md](RELEASING.md)** - Complete release process guide
 - **[docs/CI-CD.md](docs/CI-CD.md)** - Full CI/CD pipeline documentation
 
+## Stability & Versioning
+
+CHUK Tool Processor follows **[Semantic Versioning 2.0.0](https://semver.org/)** for predictable upgrades:
+
+* **Breaking changes** = **major** version bump (e.g., 1.x → 2.0)
+* **New features** (backward-compatible) = **minor** version bump (e.g., 1.2 → 1.3)
+* **Bug fixes** (backward-compatible) = **patch** version bump (e.g., 1.2.3 → 1.2.4)
+
+**Public API surface**: Everything exported via the package root (`from chuk_tool_processor import ...`) is considered public API and follows semver guarantees.
+
+**Deprecation policy**: Deprecated APIs will:
+1. Log a warning for **one minor release**
+2. Be removed in the **next major release**
+
+**Upgrading safely**:
+* Patch and minor updates are **safe to deploy** without code changes
+* Major updates may require migration—see release notes
+* Pin to `chuk-tool-processor~=1.2` for minor updates only, or `chuk-tool-processor==1.2.3` for exact versions
+
 ## Contributing & Support
 
 - **GitHub**: [chrishayuk/chuk-tool-processor](https://github.com/chrishayuk/chuk-tool-processor)