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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chuk-tool-processor
-Version: 0.14
+Version: 0.15
 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>
@@ -30,7 +30,7 @@ Requires-Dist: orjson<4,>=3.10.0; extra == "fast-json"
 Provides-Extra: full
 Requires-Dist: orjson<4,>=3.10.0; extra == "full"
 
-# CHUK Tool Processor — Production-grade execution for LLM tool calls
+# CHUK Tool Processor — A Tool Execution Runtime for AI Systems
 
 [![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/)
@@ -43,16 +43,18 @@ Requires-Dist: orjson<4,>=3.10.0; extra == "full"
 
 ---
 
-## The Missing Layer for Reliable Tool Execution
+## The Missing Runtime Layer
 
-LLMs are good at *calling* tools. The hard part is **executing** those tools reliably.
+LLMs are good at *deciding which tools to call*. The hard part is **executing** those tools reliably.
 
-**CHUK Tool Processor:**
+**CHUK Tool Processor** is a **tool execution runtime** — it doesn't plan workflows or decide which tools to call. It executes tool calls reliably, under constraints, as directed by higher-level planners (your agent, LangChain, LlamaIndex, or a custom orchestrator).
+
+**What it does:**
 - 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**
 
-Works with OpenAI, Anthropic, local models (Ollama/MLX/vLLM), and any framework (LangChain, LlamaIndex, custom).
+Works with OpenAI, Anthropic, local models (Ollama/MLX/vLLM), and any framework.
 
 ---
 
@@ -110,18 +112,20 @@ uv pip install chuk-tool-processor
 
 ```python
 import asyncio
-from chuk_tool_processor import ToolProcessor, tool
+from chuk_tool_processor import ToolProcessor, create_registry
 
-@tool(name="calculator")
 class Calculator:
     async def execute(self, operation: str, a: float, b: float) -> dict:
         ops = {"add": a + b, "multiply": a * b, "subtract": a - b}
         return {"result": ops.get(operation, 0)}
 
 async def main():
-    async with ToolProcessor(enable_caching=True, enable_retries=True) as p:
+    registry = create_registry()
+    await registry.register_tool(Calculator, name="math.calculator")  # Dotted name → namespace="math"
+
+    async with ToolProcessor(registry=registry, enable_caching=True, enable_retries=True) as p:
         # Works with OpenAI, Anthropic, or JSON formats
-        result = await p.process('<tool name="calculator" args=\'{"operation": "multiply", "a": 15, "b": 23}\'/>')
+        result = await p.process('<tool name="math.calculator" args=\'{"operation": "multiply", "a": 15, "b": 23}\'/>')
         print(result[0].result)  # {'result': 345}
 
 asyncio.run(main())
@@ -129,6 +133,19 @@ asyncio.run(main())
 
 **That's it.** You now have production-ready tool execution with timeouts, retries, and caching.
 
+### Dotted Names for Namespacing
+
+Dotted names are auto-parsed into namespace and tool name:
+
+```python
+# These are equivalent:
+await registry.register_tool(FetchUser, name="web.fetch_user")           # Auto-parsed
+await registry.register_tool(FetchUser, name="fetch_user", namespace="web")  # Explicit
+
+# Call using the full dotted name
+result = await processor.process([{"tool": "web.fetch_user", "arguments": {"user_id": "123"}}])
+```
+
 ### Works with Any LLM Format
 
 ```python
@@ -171,10 +188,19 @@ results = await processor.process(json_output)
 | Feature | Description |
 |---------|-------------|
 | **Bulkheads** | Per-tool/namespace concurrency limits to prevent resource starvation |
+| **Pattern Bulkheads** | Glob patterns like `"db.*": 3` for grouped concurrency limits |
 | **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) |
 
+### Advanced Scheduling
+
+| Feature | Description |
+|---------|-------------|
+| **Return Order** | Choose completion order (fast first) or submission order (deterministic) |
+| **SchedulerPolicy** | DAG-based scheduling with dependencies, deadlines, pool limits |
+| **GreedyDagScheduler** | Built-in scheduler with topological sort and deadline-aware skipping |
+
 ### Integration & Observability
 
 | Feature | Description |
@@ -211,6 +237,7 @@ async with ToolProcessor(
     bulkhead_config=BulkheadConfig(
         default_limit=10,
         tool_limits={"slow_api": 2},
+        patterns={"db.*": 3, "mcp.notion.*": 2},  # Pattern-based limits
     ),
 ) as processor:
     # Execute with request context
@@ -224,6 +251,56 @@ async with ToolProcessor(
 
 ---
 
+## Return Order & Scheduling
+
+Control how results are returned and plan complex execution graphs:
+
+```python
+from chuk_tool_processor import ToolProcessor, ReturnOrder
+
+async with ToolProcessor() as processor:
+    # Results return as tools complete (fast tools first) - default
+    results = await processor.process(calls, return_order="completion")
+
+    # Results return in submission order (deterministic)
+    results = await processor.process(calls, return_order="submission")
+```
+
+### DAG Scheduling with Dependencies
+
+```python
+from chuk_tool_processor import (
+    GreedyDagScheduler,
+    SchedulingConstraints,
+    ToolCallSpec,
+    ToolMetadata,
+)
+
+scheduler = GreedyDagScheduler()
+
+# Define calls with dependencies
+calls = [
+    ToolCallSpec(call_id="fetch", tool_name="api.fetch",
+                 metadata=ToolMetadata(pool="web", est_ms=300)),
+    ToolCallSpec(call_id="transform", tool_name="compute.transform",
+                 depends_on=("fetch",)),
+    ToolCallSpec(call_id="store", tool_name="db.write",
+                 depends_on=("transform",)),
+]
+
+# Plan execution with constraints
+constraints = SchedulingConstraints(
+    deadline_ms=5000,
+    pool_limits={"web": 2, "db": 1},
+)
+plan = scheduler.plan(calls, constraints)
+
+# plan.stages: (('fetch',), ('transform',), ('store',))
+# plan.skip: () or low-priority calls that would miss deadline
+```
+
+---
+
 ## MCP Integration
 
 Connect to remote tool servers using the [Model Context Protocol](https://modelcontextprotocol.io):
@@ -259,6 +336,33 @@ results = await processor.process(
 
 See [MCP_INTEGRATION.md](docs/MCP_INTEGRATION.md) for complete examples with OAuth token refresh.
 
+### MCP Middleware Stack
+
+For production deployments, wrap MCP connections with resilience middleware:
+
+```python
+from chuk_tool_processor.mcp.middleware import (
+    MiddlewareConfig,
+    MiddlewareStack,
+    RetrySettings,
+    CircuitBreakerSettings,
+    RateLimitSettings,
+)
+
+# Configure middleware layers
+config = MiddlewareConfig(
+    retry=RetrySettings(max_retries=3, base_delay=1.0),
+    circuit_breaker=CircuitBreakerSettings(failure_threshold=5),
+    rate_limiting=RateLimitSettings(enabled=True, global_limit=100),
+)
+
+# Wrap StreamManager with middleware
+middleware = MiddlewareStack(stream_manager, config=config)
+
+# Execute with automatic retry, circuit breaking, and rate limiting
+result = await middleware.call_tool("notion.search", {"query": "docs"})
+```
+
 ---
 
 ## Observability
@@ -294,7 +398,7 @@ 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 |
-| [**MCP_INTEGRATION.md**](docs/MCP_INTEGRATION.md) | HTTP Streamable, STDIO, SSE, OAuth token refresh |
+| [**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 |
 | [**OBSERVABILITY.md**](docs/OBSERVABILITY.md) | OpenTelemetry, Prometheus, metrics reference |
@@ -308,15 +412,22 @@ See [OBSERVABILITY.md](docs/OBSERVABILITY.md) for complete setup guide.
 # Getting started
 python examples/01_getting_started/hello_tool.py
 
+# Hero demo: 8 tools, 5-second deadline, 3 pools (DAG + bulkheads + context)
+python examples/02_production_features/hero_runtime_demo.py
+
 # Production patterns (bulkheads, context, scoped registries)
 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
+
 # Observability demo
 python examples/02_production_features/observability_demo.py
 
 # MCP integration
 python examples/04_mcp_integration/stdio_echo.py
 python examples/04_mcp_integration/notion_oauth.py
+python examples/04_mcp_integration/middleware_demo.py
 ```
 
 See [examples/](examples/) for 20+ working examples.
@@ -367,10 +478,30 @@ pip install chuk-tool-processor[all]
 - You want production-grade observability
 
 **Don't use this if:**
-- You want an agent framework (this is the execution layer, not the agent)
+- You want an agent framework (this is the execution runtime, not the agent)
 - You want conversation flow/memory orchestration
+- You need a planner to decide *which* tools to call
+
+### The Seam: Runtime vs Planner
+
+CHUK Tool Processor deliberately does not plan workflows or decide which tools to call. It executes tool calls reliably, under constraints, as directed by higher-level planners.
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Your Agent / LangChain / LlamaIndex / Custom       │  ← Decides WHICH tools
+└─────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────┐
+│            CHUK Tool Processor                      │  ← Executes tools RELIABLY
+│  (timeouts, retries, caching, rate limits, etc.)   │
+└─────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────┐
+│          Local Tools / MCP Servers                  │  ← Does the actual work
+└─────────────────────────────────────────────────────┘
+```
 
-> **Not a framework.** If LangChain/LlamaIndex help decide *which* tool to call, CHUK Tool Processor makes sure the tool call **actually succeeds**.
+This separation means you can swap planners without changing execution infrastructure, and vice versa.
 
 ---
 

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

@@ -1,4 +1,4 @@
-# CHUK Tool Processor — Production-grade execution for LLM tool calls
+# CHUK Tool Processor — A Tool Execution Runtime for AI Systems
 
 [![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/)
@@ -11,16 +11,18 @@
 
 ---
 
-## The Missing Layer for Reliable Tool Execution
+## The Missing Runtime Layer
 
-LLMs are good at *calling* tools. The hard part is **executing** those tools reliably.
+LLMs are good at *deciding which tools to call*. The hard part is **executing** those tools reliably.
 
-**CHUK Tool Processor:**
+**CHUK Tool Processor** is a **tool execution runtime** — it doesn't plan workflows or decide which tools to call. It executes tool calls reliably, under constraints, as directed by higher-level planners (your agent, LangChain, LlamaIndex, or a custom orchestrator).
+
+**What it does:**
 - 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**
 
-Works with OpenAI, Anthropic, local models (Ollama/MLX/vLLM), and any framework (LangChain, LlamaIndex, custom).
+Works with OpenAI, Anthropic, local models (Ollama/MLX/vLLM), and any framework.
 
 ---
 
@@ -78,18 +80,20 @@ uv pip install chuk-tool-processor
 
 ```python
 import asyncio
-from chuk_tool_processor import ToolProcessor, tool
+from chuk_tool_processor import ToolProcessor, create_registry
 
-@tool(name="calculator")
 class Calculator:
     async def execute(self, operation: str, a: float, b: float) -> dict:
         ops = {"add": a + b, "multiply": a * b, "subtract": a - b}
         return {"result": ops.get(operation, 0)}
 
 async def main():
-    async with ToolProcessor(enable_caching=True, enable_retries=True) as p:
+    registry = create_registry()
+    await registry.register_tool(Calculator, name="math.calculator")  # Dotted name → namespace="math"
+
+    async with ToolProcessor(registry=registry, enable_caching=True, enable_retries=True) as p:
         # Works with OpenAI, Anthropic, or JSON formats
-        result = await p.process('<tool name="calculator" args=\'{"operation": "multiply", "a": 15, "b": 23}\'/>')
+        result = await p.process('<tool name="math.calculator" args=\'{"operation": "multiply", "a": 15, "b": 23}\'/>')
         print(result[0].result)  # {'result': 345}
 
 asyncio.run(main())
@@ -97,6 +101,19 @@ asyncio.run(main())
 
 **That's it.** You now have production-ready tool execution with timeouts, retries, and caching.
 
+### Dotted Names for Namespacing
+
+Dotted names are auto-parsed into namespace and tool name:
+
+```python
+# These are equivalent:
+await registry.register_tool(FetchUser, name="web.fetch_user")           # Auto-parsed
+await registry.register_tool(FetchUser, name="fetch_user", namespace="web")  # Explicit
+
+# Call using the full dotted name
+result = await processor.process([{"tool": "web.fetch_user", "arguments": {"user_id": "123"}}])
+```
+
 ### Works with Any LLM Format
 
 ```python
@@ -139,10 +156,19 @@ results = await processor.process(json_output)
 | Feature | Description |
 |---------|-------------|
 | **Bulkheads** | Per-tool/namespace concurrency limits to prevent resource starvation |
+| **Pattern Bulkheads** | Glob patterns like `"db.*": 3` for grouped concurrency limits |
 | **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) |
 
+### Advanced Scheduling
+
+| Feature | Description |
+|---------|-------------|
+| **Return Order** | Choose completion order (fast first) or submission order (deterministic) |
+| **SchedulerPolicy** | DAG-based scheduling with dependencies, deadlines, pool limits |
+| **GreedyDagScheduler** | Built-in scheduler with topological sort and deadline-aware skipping |
+
 ### Integration & Observability
 
 | Feature | Description |
@@ -179,6 +205,7 @@ async with ToolProcessor(
     bulkhead_config=BulkheadConfig(
         default_limit=10,
         tool_limits={"slow_api": 2},
+        patterns={"db.*": 3, "mcp.notion.*": 2},  # Pattern-based limits
     ),
 ) as processor:
     # Execute with request context
@@ -192,6 +219,56 @@ async with ToolProcessor(
 
 ---
 
+## Return Order & Scheduling
+
+Control how results are returned and plan complex execution graphs:
+
+```python
+from chuk_tool_processor import ToolProcessor, ReturnOrder
+
+async with ToolProcessor() as processor:
+    # Results return as tools complete (fast tools first) - default
+    results = await processor.process(calls, return_order="completion")
+
+    # Results return in submission order (deterministic)
+    results = await processor.process(calls, return_order="submission")
+```
+
+### DAG Scheduling with Dependencies
+
+```python
+from chuk_tool_processor import (
+    GreedyDagScheduler,
+    SchedulingConstraints,
+    ToolCallSpec,
+    ToolMetadata,
+)
+
+scheduler = GreedyDagScheduler()
+
+# Define calls with dependencies
+calls = [
+    ToolCallSpec(call_id="fetch", tool_name="api.fetch",
+                 metadata=ToolMetadata(pool="web", est_ms=300)),
+    ToolCallSpec(call_id="transform", tool_name="compute.transform",
+                 depends_on=("fetch",)),
+    ToolCallSpec(call_id="store", tool_name="db.write",
+                 depends_on=("transform",)),
+]
+
+# Plan execution with constraints
+constraints = SchedulingConstraints(
+    deadline_ms=5000,
+    pool_limits={"web": 2, "db": 1},
+)
+plan = scheduler.plan(calls, constraints)
+
+# plan.stages: (('fetch',), ('transform',), ('store',))
+# plan.skip: () or low-priority calls that would miss deadline
+```
+
+---
+
 ## MCP Integration
 
 Connect to remote tool servers using the [Model Context Protocol](https://modelcontextprotocol.io):
@@ -227,6 +304,33 @@ results = await processor.process(
 
 See [MCP_INTEGRATION.md](docs/MCP_INTEGRATION.md) for complete examples with OAuth token refresh.
 
+### MCP Middleware Stack
+
+For production deployments, wrap MCP connections with resilience middleware:
+
+```python
+from chuk_tool_processor.mcp.middleware import (
+    MiddlewareConfig,
+    MiddlewareStack,
+    RetrySettings,
+    CircuitBreakerSettings,
+    RateLimitSettings,
+)
+
+# Configure middleware layers
+config = MiddlewareConfig(
+    retry=RetrySettings(max_retries=3, base_delay=1.0),
+    circuit_breaker=CircuitBreakerSettings(failure_threshold=5),
+    rate_limiting=RateLimitSettings(enabled=True, global_limit=100),
+)
+
+# Wrap StreamManager with middleware
+middleware = MiddlewareStack(stream_manager, config=config)
+
+# Execute with automatic retry, circuit breaking, and rate limiting
+result = await middleware.call_tool("notion.search", {"query": "docs"})
+```
+
 ---
 
 ## Observability
@@ -262,7 +366,7 @@ 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 |
-| [**MCP_INTEGRATION.md**](docs/MCP_INTEGRATION.md) | HTTP Streamable, STDIO, SSE, OAuth token refresh |
+| [**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 |
 | [**OBSERVABILITY.md**](docs/OBSERVABILITY.md) | OpenTelemetry, Prometheus, metrics reference |
@@ -276,15 +380,22 @@ See [OBSERVABILITY.md](docs/OBSERVABILITY.md) for complete setup guide.
 # Getting started
 python examples/01_getting_started/hello_tool.py
 
+# Hero demo: 8 tools, 5-second deadline, 3 pools (DAG + bulkheads + context)
+python examples/02_production_features/hero_runtime_demo.py
+
 # Production patterns (bulkheads, context, scoped registries)
 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
+
 # Observability demo
 python examples/02_production_features/observability_demo.py
 
 # MCP integration
 python examples/04_mcp_integration/stdio_echo.py
 python examples/04_mcp_integration/notion_oauth.py
+python examples/04_mcp_integration/middleware_demo.py
 ```
 
 See [examples/](examples/) for 20+ working examples.
@@ -335,10 +446,30 @@ pip install chuk-tool-processor[all]
 - You want production-grade observability
 
 **Don't use this if:**
-- You want an agent framework (this is the execution layer, not the agent)
+- You want an agent framework (this is the execution runtime, not the agent)
 - You want conversation flow/memory orchestration
+- You need a planner to decide *which* tools to call
+
+### The Seam: Runtime vs Planner
+
+CHUK Tool Processor deliberately does not plan workflows or decide which tools to call. It executes tool calls reliably, under constraints, as directed by higher-level planners.
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Your Agent / LangChain / LlamaIndex / Custom       │  ← Decides WHICH tools
+└─────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────┐
+│            CHUK Tool Processor                      │  ← Executes tools RELIABLY
+│  (timeouts, retries, caching, rate limits, etc.)   │
+└─────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────┐
+│          Local Tools / MCP Servers                  │  ← Does the actual work
+└─────────────────────────────────────────────────────┘
+```
 
-> **Not a framework.** If LangChain/LlamaIndex help decide *which* tool to call, CHUK Tool Processor makes sure the tool call **actually succeeds**.
+This separation means you can swap planners without changing execution infrastructure, and vice versa.
 
 ---
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chuk-tool-processor"
-version = "0.14"
+version = "0.15"
 description = "Async-native framework for registering, discovering, and executing tools referenced in LLM responses"
 readme = "README.md"
 requires-python = ">=3.11"

{chuk_tool_processor-0.14 → chuk_tool_processor-0.15}/src/chuk_tool_processor/__init__.py

@@ -59,6 +59,7 @@ from chuk_tool_processor.mcp import (
 from chuk_tool_processor.mcp.stream_manager import StreamManager
 
 # Models (commonly used)
+from chuk_tool_processor.models.return_order import ReturnOrder
 from chuk_tool_processor.models.tool_call import ToolCall
 from chuk_tool_processor.models.tool_result import ToolResult
 
@@ -75,6 +76,16 @@ from chuk_tool_processor.registry.auto_register import register_fn_tool
 # Decorators for registering tools
 from chuk_tool_processor.registry.decorators import register_tool, tool
 
+# Scheduling
+from chuk_tool_processor.scheduling import (
+    ExecutionPlan,
+    GreedyDagScheduler,
+    SchedulerPolicy,
+    SchedulingConstraints,
+    ToolCallSpec,
+    ToolMetadata,
+)
+
 # Type checking imports (not available at runtime)
 if TYPE_CHECKING:
     # Advanced models for type hints
@@ -114,6 +125,14 @@ __all__ = [
     # Models
     "ToolCall",
     "ToolResult",
+    "ReturnOrder",
+    # Scheduling
+    "ToolMetadata",
+    "ToolCallSpec",
+    "SchedulingConstraints",
+    "ExecutionPlan",
+    "SchedulerPolicy",
+    "GreedyDagScheduler",
     # Registry
     "ToolInfo",
     "initialize",

{chuk_tool_processor-0.14 → chuk_tool_processor-0.15}/src/chuk_tool_processor/core/processor.py

@@ -339,6 +339,7 @@ class ToolProcessor:
         use_cache: bool = True,  # noqa: ARG002
         request_id: str | None = None,
         context: ExecutionContext | None = None,
+        return_order: str | None = None,
     ) -> list[ToolResult]:
         """
         Process tool calls from various LLM output formats.
@@ -393,6 +394,9 @@ class ToolProcessor:
             context: Optional ExecutionContext for request-scoped data.
                 Carries user_id, tenant_id, traceparent, deadline, etc.
                 If provided, context.request_id takes precedence over request_id.
+            return_order: Order to return results in. Can be:
+                - "completion" (default): Results return as each tool completes
+                - "submission": Results return in the same order as submitted
 
         Returns:
             List of ToolResult objects. Each result contains:
@@ -514,7 +518,14 @@ class ToolProcessor:
                 # Execute tools (with context scope if provided)
                 async def _execute_with_context() -> list[ToolResult]:
                     assert self.executor is not None
-                    result: list[ToolResult] = await self.executor.execute(calls, timeout=effective_timeout)
+                    # If return_order is specified and strategy supports it, call run() directly
+                    # This bypasses the wrapper chain but preserves return_order semantics
+                    if return_order is not None and self.strategy is not None and hasattr(self.strategy, "run"):
+                        result: list[ToolResult] = await self.strategy.run(
+                            calls, timeout=effective_timeout, return_order=return_order
+                        )
+                    else:
+                        result = await self.executor.execute(calls, timeout=effective_timeout)
                     return result
 
                 if context_manager: