chuk-tool-processor 0.15__tar.gz → 0.18__tar.gz

{chuk_tool_processor-0.15 → chuk_tool_processor-0.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chuk-tool-processor
-Version: 0.15
+Version: 0.18
 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>
@@ -27,8 +27,13 @@ Requires-Dist: pydantic>=2.11.3
 Requires-Dist: uuid>=1.30
 Provides-Extra: fast-json
 Requires-Dist: orjson<4,>=3.10.0; extra == "fast-json"
+Provides-Extra: redis
+Requires-Dist: redis[hiredis]<6,>=5.0.0; extra == "redis"
 Provides-Extra: full
 Requires-Dist: orjson<4,>=3.10.0; extra == "full"
+Provides-Extra: all
+Requires-Dist: orjson<4,>=3.10.0; extra == "all"
+Requires-Dist: redis[hiredis]<6,>=5.0.0; extra == "all"
 
 # CHUK Tool Processor — A Tool Execution Runtime for AI Systems
 
@@ -182,6 +187,7 @@ results = await processor.process(json_output)
 | **Rate Limiting** | Global and per-tool rate limits with sliding windows |
 | **Caching** | Result caching with TTL and SHA256-based idempotency keys |
 | **Circuit Breakers** | Prevent cascading failures with automatic recovery |
+| **Structured Errors** | Machine-readable error categories with retry hints for planners |
 
 ### Multi-Tenant & Isolation
 
@@ -192,6 +198,7 @@ results = await processor.process(json_output)
 | **Scoped Registries** | Isolated registries for multi-tenant apps and testing |
 | **ExecutionContext** | Request-scoped metadata propagation (user, tenant, tracing, deadlines) |
 | **Isolated Strategy** | Subprocess execution for untrusted code (zero crash blast radius) |
+| **Redis Registry** | Distributed tool registry for multi-process/multi-machine deployments |
 
 ### Advanced Scheduling
 
@@ -201,6 +208,32 @@ results = await processor.process(json_output)
 | **SchedulerPolicy** | DAG-based scheduling with dependencies, deadlines, pool limits |
 | **GreedyDagScheduler** | Built-in scheduler with topological sort and deadline-aware skipping |
 
+### Runtime Guards (Constitution Layer)
+
+| Guard | Description |
+|-------|-------------|
+| **SchemaStrictnessGuard** | Validates arguments against JSON schemas, optional type coercion |
+| **SensitiveDataGuard** | Detects and blocks/redacts secrets (API keys, JWTs, private keys) |
+| **NetworkPolicyGuard** | SSRF defense — blocks private IPs, metadata endpoints, enforces HTTPS |
+| **SideEffectGuard** | Labels tools as read_only/write/destructive, enforces policies |
+| **ConcurrencyGuard** | Limits simultaneous in-flight calls (global, per-tool, per-namespace) |
+| **TimeoutBudgetGuard** | Enforces wall-clock time budgets with soft/hard limits |
+| **OutputSizeGuard** | Prevents pathological payloads from blowing up context |
+| **RetrySafetyGuard** | Guards retry behavior (backoff, idempotency keys, non-retryable errors) |
+| **ProvenanceGuard** | Tracks output attribution and lineage |
+| **PlanShapeGuard** | Detects pathological patterns (fan-out explosions, long chains) |
+| **SaturationGuard** | Detects degenerate statistical outputs (extreme Z-scores, saturated CDFs) |
+
+### Dynamic Tool Discovery
+
+| Feature | Description |
+|---------|-------------|
+| **Intelligent Search** | Natural language queries find tools ("gaussian" → "normal_cdf") |
+| **Synonym Expansion** | Built-in synonyms for math, statistics, file ops, networking |
+| **Fuzzy Matching** | Typo tolerance ("multipley" finds "multiply") |
+| **Session Boosting** | Recently used tools rank higher in search results |
+| **Dynamic Provider** | Base class for LLM-driven tool discovery and execution |
+
 ### Integration & Observability
 
 | Feature | Description |
@@ -365,6 +398,157 @@ result = await middleware.call_tool("notion.search", {"query": "docs"})
 
 ---
 
+## Distributed Deployments (Redis)
+
+For multi-process or multi-machine deployments, configure Redis backends via environment variables:
+
+```bash
+# Enable Redis for everything
+export CHUK_REGISTRY_BACKEND=redis
+export CHUK_RESILIENCE_BACKEND=redis
+export CHUK_REDIS_URL=redis://localhost:6379/0
+
+# Enable resilience features
+export CHUK_CIRCUIT_BREAKER_ENABLED=true
+export CHUK_RATE_LIMIT_ENABLED=true
+export CHUK_RATE_LIMIT_GLOBAL=100
+```
+
+```python
+from chuk_tool_processor import ProcessorConfig
+
+# Load from environment and create fully-configured processor
+config = ProcessorConfig.from_env()
+processor = await config.create_processor()
+
+async with processor:
+    results = await processor.process(llm_output)
+```
+
+Or configure programmatically:
+
+```python
+from chuk_tool_processor import ProcessorConfig, RegistryConfig, BackendType
+from chuk_tool_processor.config import CircuitBreakerConfig, RateLimitConfig
+
+config = ProcessorConfig(
+    # Registry and resilience use Redis
+    registry=RegistryConfig(backend=BackendType.REDIS),
+    resilience_backend=BackendType.REDIS,
+    redis_url="redis://localhost:6379/0",
+
+    # Enable features
+    circuit_breaker=CircuitBreakerConfig(enabled=True, failure_threshold=5),
+    rate_limit=RateLimitConfig(enabled=True, global_limit=100),
+)
+
+processor = await config.create_processor()
+```
+
+**Key features:**
+- **Distributed registry**: Tool metadata shared across processes
+- **Distributed circuit breaker**: Failure counts shared (prevents cascading failures across instances)
+- **Distributed rate limiting**: Global limits enforced across all instances
+- **Multi-tenant isolation**: Key prefixes isolate data per tenant
+
+**Installation:**
+```bash
+pip install chuk-tool-processor[redis]  # or: uv add chuk-tool-processor[redis]
+```
+
+See [examples/02_production_features/distributed_config_demo.py](examples/02_production_features/distributed_config_demo.py) for a complete example.
+
+---
+
+## Runtime Guards
+
+Protect your tool execution with composable guards that enforce safety policies:
+
+```python
+from chuk_tool_processor.guards import (
+    GuardChain,
+    SchemaStrictnessGuard,
+    SensitiveDataGuard,
+    NetworkPolicyGuard,
+    ConcurrencyGuard,
+)
+
+# Create individual guards
+schema_guard = SchemaStrictnessGuard(get_schema=my_schema_getter)
+sensitive_guard = SensitiveDataGuard()  # Detects API keys, JWTs, etc.
+network_guard = NetworkPolicyGuard(block_private_ips=True)
+concurrency_guard = ConcurrencyGuard(global_max=50, per_tool_max={"heavy_api": 2})
+
+# Compose into a chain
+chain = GuardChain([schema_guard, sensitive_guard, network_guard, concurrency_guard])
+
+# Check before execution
+result = await chain.check_all_async("api.fetch", {"url": "https://example.com"})
+if result.blocked:
+    print(f"Blocked by {result.stopped_at}: {result.reason}")
+```
+
+**Key Guards:**
+- **SchemaStrictnessGuard** — Validate args against JSON schemas, auto-coerce types
+- **SensitiveDataGuard** — Block or redact secrets (API keys, JWTs, private keys)
+- **NetworkPolicyGuard** — SSRF defense (block localhost, private IPs, metadata endpoints)
+- **SideEffectGuard** — Enforce read-only mode, block destructive ops in production
+- **ConcurrencyGuard** — Limit in-flight calls globally, per-tool, or per-namespace
+- **TimeoutBudgetGuard** — Enforce wall-clock budgets with soft/hard limits
+- **OutputSizeGuard** — Prevent pathological payloads (size, depth, array length)
+- **SaturationGuard** — Detect degenerate statistical outputs (extreme Z-scores, saturated CDFs)
+
+See [GUARDS.md](docs/GUARDS.md) for complete documentation and examples.
+
+---
+
+## Dynamic Tool Discovery
+
+When you have hundreds of tools, LLMs can't load all schemas upfront. The discovery module provides intelligent search and on-demand tool loading:
+
+```python
+from chuk_tool_processor.discovery import ToolSearchEngine, BaseDynamicToolProvider
+
+# Create a search engine for your tools
+engine = ToolSearchEngine()
+engine.set_tools(my_tools)
+
+# Natural language search with synonym expansion
+results = engine.search("gaussian distribution")  # Finds "normal_cdf"
+results = engine.search("find the average")       # Finds "calculate_mean"
+results = engine.search("multipley")              # Finds "multiply" (typo tolerance)
+
+# Session boosting - recently used tools rank higher
+engine.record_tool_use("calculate_mean", success=True)
+engine.advance_turn()
+results = engine.search("calculate")  # "calculate_mean" now boosted
+```
+
+**Dynamic Provider Pattern** — give LLMs meta-tools for discovery:
+
+```python
+class MyToolProvider(BaseDynamicToolProvider):
+    async def get_all_tools(self) -> list[Tool]:
+        return self._tools
+
+    async def execute_tool(self, name: str, args: dict) -> dict:
+        return await self._tools[name].execute(**args)
+
+provider = MyToolProvider()
+
+# LLM gets 4 meta-tools: list_tools, search_tools, get_tool_schema, call_tool
+tools_for_llm = provider.get_dynamic_tools()
+
+# LLM workflow: search → get schema → call
+results = await provider.search_tools("calculate average")
+schema = await provider.get_tool_schema("calculate_mean")
+result = await provider.call_tool("calculate_mean", {"values": [1, 2, 3]})
+```
+
+See [DISCOVERY.md](docs/DISCOVERY.md) for complete documentation.
+
+---
+
 ## Observability
 
 One-line setup for production monitoring:
@@ -391,6 +575,30 @@ See [OBSERVABILITY.md](docs/OBSERVABILITY.md) for complete setup guide.
 
 ---
 
+## Structured Error Handling
+
+Errors include machine-readable categories and retry hints for planner decision-making:
+
+```python
+from chuk_tool_processor.core.exceptions import ErrorCategory
+
+results = await processor.process(llm_output)
+for result in results:
+    if result.error_info:
+        match result.error_info.category:
+            case ErrorCategory.RATE_LIMIT:
+                await asyncio.sleep(result.retry_after_ms / 1000)
+                return await retry()
+            case ErrorCategory.CIRCUIT_OPEN:
+                return await use_fallback_tool()
+            case _ if not result.retryable:
+                return await report_permanent_failure()
+```
+
+See [ERRORS.md](docs/ERRORS.md) for complete error taxonomy.
+
+---
+
 ## Documentation
 
 | Document | Description |
@@ -398,6 +606,8 @@ See [OBSERVABILITY.md](docs/OBSERVABILITY.md) for complete setup guide.
 | [**GETTING_STARTED.md**](docs/GETTING_STARTED.md) | Creating tools, using the processor, ValidatedTool, StreamingTool |
 | [**CORE_CONCEPTS.md**](docs/CORE_CONCEPTS.md) | Registry, strategies, wrappers, parsers, MCP overview |
 | [**PRODUCTION_PATTERNS.md**](docs/PRODUCTION_PATTERNS.md) | Bulkheads, scoped registries, ExecutionContext, parallel execution |
+| [**DISCOVERY.md**](docs/DISCOVERY.md) | Dynamic tool discovery, intelligent search, synonym expansion |
+| [**GUARDS.md**](docs/GUARDS.md) | Runtime guards for safety, validation, and resource management |
 | [**MCP_INTEGRATION.md**](docs/MCP_INTEGRATION.md) | HTTP Streamable, STDIO, SSE, OAuth, Middleware Stack |
 | [**ADVANCED_TOPICS.md**](docs/ADVANCED_TOPICS.md) | Deferred loading, code sandbox, isolated strategy, testing |
 | [**CONFIGURATION.md**](docs/CONFIGURATION.md) | All config options and environment variables |
@@ -412,6 +622,9 @@ See [OBSERVABILITY.md](docs/OBSERVABILITY.md) for complete setup guide.
 # Getting started
 python examples/01_getting_started/hello_tool.py
 
+# Dynamic tool discovery (search, synonyms, fuzzy matching)
+python examples/07_discovery/dynamic_tools_demo.py
+
 # Hero demo: 8 tools, 5-second deadline, 3 pools (DAG + bulkheads + context)
 python examples/02_production_features/hero_runtime_demo.py
 
@@ -421,6 +634,18 @@ python examples/02_production_features/production_patterns_demo.py
 # Runtime features (return order, pattern bulkheads, scheduling)
 python examples/02_production_features/runtime_features_demo.py
 
+# Structured error handling for planners
+python examples/02_production_features/structured_errors_demo.py
+
+# Runtime guards (validation, security, resource limits)
+python examples/guards_demo.py
+
+# Redis registry for distributed deployments
+python examples/02_production_features/redis_registry_demo.py
+
+# Distributed configuration (Redis registry + resilience)
+python examples/02_production_features/distributed_config_demo.py
+
 # Observability demo
 python examples/02_production_features/observability_demo.py
 
@@ -458,6 +683,9 @@ pip install chuk-tool-processor[observability]
 # With MCP support
 pip install chuk-tool-processor[mcp]
 
+# With Redis registry (distributed deployments)
+pip install chuk-tool-processor[redis]
+
 # With fast JSON (2-3x faster with orjson)
 pip install chuk-tool-processor[fast-json]
 

{chuk_tool_processor-0.15 → chuk_tool_processor-0.18}/README.md

@@ -150,6 +150,7 @@ results = await processor.process(json_output)
 | **Rate Limiting** | Global and per-tool rate limits with sliding windows |
 | **Caching** | Result caching with TTL and SHA256-based idempotency keys |
 | **Circuit Breakers** | Prevent cascading failures with automatic recovery |
+| **Structured Errors** | Machine-readable error categories with retry hints for planners |
 
 ### Multi-Tenant & Isolation
 
@@ -160,6 +161,7 @@ results = await processor.process(json_output)
 | **Scoped Registries** | Isolated registries for multi-tenant apps and testing |
 | **ExecutionContext** | Request-scoped metadata propagation (user, tenant, tracing, deadlines) |
 | **Isolated Strategy** | Subprocess execution for untrusted code (zero crash blast radius) |
+| **Redis Registry** | Distributed tool registry for multi-process/multi-machine deployments |
 
 ### Advanced Scheduling
 
@@ -169,6 +171,32 @@ results = await processor.process(json_output)
 | **SchedulerPolicy** | DAG-based scheduling with dependencies, deadlines, pool limits |
 | **GreedyDagScheduler** | Built-in scheduler with topological sort and deadline-aware skipping |
 
+### Runtime Guards (Constitution Layer)
+
+| Guard | Description |
+|-------|-------------|
+| **SchemaStrictnessGuard** | Validates arguments against JSON schemas, optional type coercion |
+| **SensitiveDataGuard** | Detects and blocks/redacts secrets (API keys, JWTs, private keys) |
+| **NetworkPolicyGuard** | SSRF defense — blocks private IPs, metadata endpoints, enforces HTTPS |
+| **SideEffectGuard** | Labels tools as read_only/write/destructive, enforces policies |
+| **ConcurrencyGuard** | Limits simultaneous in-flight calls (global, per-tool, per-namespace) |
+| **TimeoutBudgetGuard** | Enforces wall-clock time budgets with soft/hard limits |
+| **OutputSizeGuard** | Prevents pathological payloads from blowing up context |
+| **RetrySafetyGuard** | Guards retry behavior (backoff, idempotency keys, non-retryable errors) |
+| **ProvenanceGuard** | Tracks output attribution and lineage |
+| **PlanShapeGuard** | Detects pathological patterns (fan-out explosions, long chains) |
+| **SaturationGuard** | Detects degenerate statistical outputs (extreme Z-scores, saturated CDFs) |
+
+### Dynamic Tool Discovery
+
+| Feature | Description |
+|---------|-------------|
+| **Intelligent Search** | Natural language queries find tools ("gaussian" → "normal_cdf") |
+| **Synonym Expansion** | Built-in synonyms for math, statistics, file ops, networking |
+| **Fuzzy Matching** | Typo tolerance ("multipley" finds "multiply") |
+| **Session Boosting** | Recently used tools rank higher in search results |
+| **Dynamic Provider** | Base class for LLM-driven tool discovery and execution |
+
 ### Integration & Observability
 
 | Feature | Description |
@@ -333,6 +361,157 @@ result = await middleware.call_tool("notion.search", {"query": "docs"})
 
 ---
 
+## Distributed Deployments (Redis)
+
+For multi-process or multi-machine deployments, configure Redis backends via environment variables:
+
+```bash
+# Enable Redis for everything
+export CHUK_REGISTRY_BACKEND=redis
+export CHUK_RESILIENCE_BACKEND=redis
+export CHUK_REDIS_URL=redis://localhost:6379/0
+
+# Enable resilience features
+export CHUK_CIRCUIT_BREAKER_ENABLED=true
+export CHUK_RATE_LIMIT_ENABLED=true
+export CHUK_RATE_LIMIT_GLOBAL=100
+```
+
+```python
+from chuk_tool_processor import ProcessorConfig
+
+# Load from environment and create fully-configured processor
+config = ProcessorConfig.from_env()
+processor = await config.create_processor()
+
+async with processor:
+    results = await processor.process(llm_output)
+```
+
+Or configure programmatically:
+
+```python
+from chuk_tool_processor import ProcessorConfig, RegistryConfig, BackendType
+from chuk_tool_processor.config import CircuitBreakerConfig, RateLimitConfig
+
+config = ProcessorConfig(
+    # Registry and resilience use Redis
+    registry=RegistryConfig(backend=BackendType.REDIS),
+    resilience_backend=BackendType.REDIS,
+    redis_url="redis://localhost:6379/0",
+
+    # Enable features
+    circuit_breaker=CircuitBreakerConfig(enabled=True, failure_threshold=5),
+    rate_limit=RateLimitConfig(enabled=True, global_limit=100),
+)
+
+processor = await config.create_processor()
+```
+
+**Key features:**
+- **Distributed registry**: Tool metadata shared across processes
+- **Distributed circuit breaker**: Failure counts shared (prevents cascading failures across instances)
+- **Distributed rate limiting**: Global limits enforced across all instances
+- **Multi-tenant isolation**: Key prefixes isolate data per tenant
+
+**Installation:**
+```bash
+pip install chuk-tool-processor[redis]  # or: uv add chuk-tool-processor[redis]
+```
+
+See [examples/02_production_features/distributed_config_demo.py](examples/02_production_features/distributed_config_demo.py) for a complete example.
+
+---
+
+## Runtime Guards
+
+Protect your tool execution with composable guards that enforce safety policies:
+
+```python
+from chuk_tool_processor.guards import (
+    GuardChain,
+    SchemaStrictnessGuard,
+    SensitiveDataGuard,
+    NetworkPolicyGuard,
+    ConcurrencyGuard,
+)
+
+# Create individual guards
+schema_guard = SchemaStrictnessGuard(get_schema=my_schema_getter)
+sensitive_guard = SensitiveDataGuard()  # Detects API keys, JWTs, etc.
+network_guard = NetworkPolicyGuard(block_private_ips=True)
+concurrency_guard = ConcurrencyGuard(global_max=50, per_tool_max={"heavy_api": 2})
+
+# Compose into a chain
+chain = GuardChain([schema_guard, sensitive_guard, network_guard, concurrency_guard])
+
+# Check before execution
+result = await chain.check_all_async("api.fetch", {"url": "https://example.com"})
+if result.blocked:
+    print(f"Blocked by {result.stopped_at}: {result.reason}")
+```
+
+**Key Guards:**
+- **SchemaStrictnessGuard** — Validate args against JSON schemas, auto-coerce types
+- **SensitiveDataGuard** — Block or redact secrets (API keys, JWTs, private keys)
+- **NetworkPolicyGuard** — SSRF defense (block localhost, private IPs, metadata endpoints)
+- **SideEffectGuard** — Enforce read-only mode, block destructive ops in production
+- **ConcurrencyGuard** — Limit in-flight calls globally, per-tool, or per-namespace
+- **TimeoutBudgetGuard** — Enforce wall-clock budgets with soft/hard limits
+- **OutputSizeGuard** — Prevent pathological payloads (size, depth, array length)
+- **SaturationGuard** — Detect degenerate statistical outputs (extreme Z-scores, saturated CDFs)
+
+See [GUARDS.md](docs/GUARDS.md) for complete documentation and examples.
+
+---
+
+## Dynamic Tool Discovery
+
+When you have hundreds of tools, LLMs can't load all schemas upfront. The discovery module provides intelligent search and on-demand tool loading:
+
+```python
+from chuk_tool_processor.discovery import ToolSearchEngine, BaseDynamicToolProvider
+
+# Create a search engine for your tools
+engine = ToolSearchEngine()
+engine.set_tools(my_tools)
+
+# Natural language search with synonym expansion
+results = engine.search("gaussian distribution")  # Finds "normal_cdf"
+results = engine.search("find the average")       # Finds "calculate_mean"
+results = engine.search("multipley")              # Finds "multiply" (typo tolerance)
+
+# Session boosting - recently used tools rank higher
+engine.record_tool_use("calculate_mean", success=True)
+engine.advance_turn()
+results = engine.search("calculate")  # "calculate_mean" now boosted
+```
+
+**Dynamic Provider Pattern** — give LLMs meta-tools for discovery:
+
+```python
+class MyToolProvider(BaseDynamicToolProvider):
+    async def get_all_tools(self) -> list[Tool]:
+        return self._tools
+
+    async def execute_tool(self, name: str, args: dict) -> dict:
+        return await self._tools[name].execute(**args)
+
+provider = MyToolProvider()
+
+# LLM gets 4 meta-tools: list_tools, search_tools, get_tool_schema, call_tool
+tools_for_llm = provider.get_dynamic_tools()
+
+# LLM workflow: search → get schema → call
+results = await provider.search_tools("calculate average")
+schema = await provider.get_tool_schema("calculate_mean")
+result = await provider.call_tool("calculate_mean", {"values": [1, 2, 3]})
+```
+
+See [DISCOVERY.md](docs/DISCOVERY.md) for complete documentation.
+
+---
+
 ## Observability
 
 One-line setup for production monitoring:
@@ -359,6 +538,30 @@ See [OBSERVABILITY.md](docs/OBSERVABILITY.md) for complete setup guide.
 
 ---
 
+## Structured Error Handling
+
+Errors include machine-readable categories and retry hints for planner decision-making:
+
+```python
+from chuk_tool_processor.core.exceptions import ErrorCategory
+
+results = await processor.process(llm_output)
+for result in results:
+    if result.error_info:
+        match result.error_info.category:
+            case ErrorCategory.RATE_LIMIT:
+                await asyncio.sleep(result.retry_after_ms / 1000)
+                return await retry()
+            case ErrorCategory.CIRCUIT_OPEN:
+                return await use_fallback_tool()
+            case _ if not result.retryable:
+                return await report_permanent_failure()
+```
+
+See [ERRORS.md](docs/ERRORS.md) for complete error taxonomy.
+
+---
+
 ## Documentation
 
 | Document | Description |
@@ -366,6 +569,8 @@ See [OBSERVABILITY.md](docs/OBSERVABILITY.md) for complete setup guide.
 | [**GETTING_STARTED.md**](docs/GETTING_STARTED.md) | Creating tools, using the processor, ValidatedTool, StreamingTool |
 | [**CORE_CONCEPTS.md**](docs/CORE_CONCEPTS.md) | Registry, strategies, wrappers, parsers, MCP overview |
 | [**PRODUCTION_PATTERNS.md**](docs/PRODUCTION_PATTERNS.md) | Bulkheads, scoped registries, ExecutionContext, parallel execution |
+| [**DISCOVERY.md**](docs/DISCOVERY.md) | Dynamic tool discovery, intelligent search, synonym expansion |
+| [**GUARDS.md**](docs/GUARDS.md) | Runtime guards for safety, validation, and resource management |
 | [**MCP_INTEGRATION.md**](docs/MCP_INTEGRATION.md) | HTTP Streamable, STDIO, SSE, OAuth, Middleware Stack |
 | [**ADVANCED_TOPICS.md**](docs/ADVANCED_TOPICS.md) | Deferred loading, code sandbox, isolated strategy, testing |
 | [**CONFIGURATION.md**](docs/CONFIGURATION.md) | All config options and environment variables |
@@ -380,6 +585,9 @@ See [OBSERVABILITY.md](docs/OBSERVABILITY.md) for complete setup guide.
 # Getting started
 python examples/01_getting_started/hello_tool.py
 
+# Dynamic tool discovery (search, synonyms, fuzzy matching)
+python examples/07_discovery/dynamic_tools_demo.py
+
 # Hero demo: 8 tools, 5-second deadline, 3 pools (DAG + bulkheads + context)
 python examples/02_production_features/hero_runtime_demo.py
 
@@ -389,6 +597,18 @@ python examples/02_production_features/production_patterns_demo.py
 # Runtime features (return order, pattern bulkheads, scheduling)
 python examples/02_production_features/runtime_features_demo.py
 
+# Structured error handling for planners
+python examples/02_production_features/structured_errors_demo.py
+
+# Runtime guards (validation, security, resource limits)
+python examples/guards_demo.py
+
+# Redis registry for distributed deployments
+python examples/02_production_features/redis_registry_demo.py
+
+# Distributed configuration (Redis registry + resilience)
+python examples/02_production_features/distributed_config_demo.py
+
 # Observability demo
 python examples/02_production_features/observability_demo.py
 
@@ -426,6 +646,9 @@ pip install chuk-tool-processor[observability]
 # With MCP support
 pip install chuk-tool-processor[mcp]
 
+# With Redis registry (distributed deployments)
+pip install chuk-tool-processor[redis]
+
 # With fast JSON (2-3x faster with orjson)
 pip install chuk-tool-processor[fast-json]
 

{chuk_tool_processor-0.15 → chuk_tool_processor-0.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chuk-tool-processor"
-version = "0.15"
+version = "0.18"
 description = "Async-native framework for registering, discovering, and executing tools referenced in LLM responses"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -55,11 +55,22 @@ fast-json = [
     "orjson>=3.10.0,<4",
 ]
 
+# Redis registry for distributed deployments
+redis = [
+    "redis[hiredis]>=5.0.0,<6",
+]
+
 # Full feature set with performance optimizations
 full = [
     "orjson>=3.10.0,<4",
 ]
 
+# All extras combined
+all = [
+    "orjson>=3.10.0,<4",
+    "redis[hiredis]>=5.0.0,<6",
+]
+
 # Tell setuptools to look in src/ for your a2a package
 [tool.setuptools.packages.find]
 where   = ["src"]
@@ -93,6 +104,8 @@ dev = [
     "pre-commit>=3.8.0",
     "coverage[toml]>=7.6.0",
     "orjson>=3.10.0",
+    "redis[hiredis]>=5.0.0,<6",
+    "fakeredis[lua]>=2.32.1",
 ]
 
 observability = [