chuk-tool-processor 0.12.2__tar.gz → 0.13__tar.gz

{chuk_tool_processor-0.12.2 → chuk_tool_processor-0.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chuk-tool-processor
-Version: 0.12.2
+Version: 0.13
 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>
@@ -652,6 +652,57 @@ async with ToolProcessor(
     ''')
 ```
 
+### Parallel Execution & Streaming Results
+
+Tools execute concurrently by default. Results return in **completion order** — faster tools return immediately without waiting for slower ones:
+
+```python
+import asyncio
+from chuk_tool_processor.execution.strategies.inprocess_strategy import InProcessStrategy
+from chuk_tool_processor.models.tool_call import ToolCall
+
+# Tools with different execution times
+calls = [
+    ToolCall(tool="slow_api", arguments={"query": "complex"}),    # 500ms
+    ToolCall(tool="medium_api", arguments={"query": "medium"}),   # 200ms
+    ToolCall(tool="fast_api", arguments={"query": "simple"}),     # 50ms
+]
+
+# Results return as: fast_api, medium_api, slow_api (completion order)
+results = await strategy.run(calls)
+
+# Match results back to original calls by tool name
+for result in results:
+    print(f"{result.tool}: {result.result}")
+```
+
+**Stream results as they arrive** with `stream_run()`:
+
+```python
+async for result in strategy.stream_run(calls):
+    # Process each result immediately as it completes
+    print(f"Completed: {result.tool}")
+```
+
+**Track when tools start** with `on_tool_start` callback:
+
+```python
+async def on_start(call: ToolCall):
+    print(f"Starting: {call.tool}")
+
+async for result in strategy.stream_run(calls, on_tool_start=on_start):
+    print(f"Completed: {result.tool}")
+```
+
+**Control concurrency** with `max_concurrency`:
+
+```python
+# Limit to 2 concurrent tools (others queue)
+strategy = InProcessStrategy(registry, max_concurrency=2)
+```
+
+> **See:** `examples/parallel_execution_demo.py` for a complete demonstration.
+
 ## Documentation Quick Reference
 
 | Document | What It Covers |
@@ -863,6 +914,8 @@ class WeatherTool(ValidatedTool):
 | **InProcessStrategy** | Fast, trusted tools | Speed ✅, Isolation ❌ |
 | **IsolatedStrategy** | Untrusted or risky code | Isolation ✅, Speed ❌ |
 
+**Parallel Execution:** Both strategies execute tools concurrently by default. Results return in **completion order** (faster tools return first), not submission order. Use `ToolResult.tool` to match results to original calls.
+
 ```python
 import asyncio
 from chuk_tool_processor import ToolProcessor, IsolatedStrategy, get_default_registry

{chuk_tool_processor-0.12.2 → chuk_tool_processor-0.13}/README.md

@@ -620,6 +620,57 @@ async with ToolProcessor(
     ''')
 ```
 
+### Parallel Execution & Streaming Results
+
+Tools execute concurrently by default. Results return in **completion order** — faster tools return immediately without waiting for slower ones:
+
+```python
+import asyncio
+from chuk_tool_processor.execution.strategies.inprocess_strategy import InProcessStrategy
+from chuk_tool_processor.models.tool_call import ToolCall
+
+# Tools with different execution times
+calls = [
+    ToolCall(tool="slow_api", arguments={"query": "complex"}),    # 500ms
+    ToolCall(tool="medium_api", arguments={"query": "medium"}),   # 200ms
+    ToolCall(tool="fast_api", arguments={"query": "simple"}),     # 50ms
+]
+
+# Results return as: fast_api, medium_api, slow_api (completion order)
+results = await strategy.run(calls)
+
+# Match results back to original calls by tool name
+for result in results:
+    print(f"{result.tool}: {result.result}")
+```
+
+**Stream results as they arrive** with `stream_run()`:
+
+```python
+async for result in strategy.stream_run(calls):
+    # Process each result immediately as it completes
+    print(f"Completed: {result.tool}")
+```
+
+**Track when tools start** with `on_tool_start` callback:
+
+```python
+async def on_start(call: ToolCall):
+    print(f"Starting: {call.tool}")
+
+async for result in strategy.stream_run(calls, on_tool_start=on_start):
+    print(f"Completed: {result.tool}")
+```
+
+**Control concurrency** with `max_concurrency`:
+
+```python
+# Limit to 2 concurrent tools (others queue)
+strategy = InProcessStrategy(registry, max_concurrency=2)
+```
+
+> **See:** `examples/parallel_execution_demo.py` for a complete demonstration.
+
 ## Documentation Quick Reference
 
 | Document | What It Covers |
@@ -831,6 +882,8 @@ class WeatherTool(ValidatedTool):
 | **InProcessStrategy** | Fast, trusted tools | Speed ✅, Isolation ❌ |
 | **IsolatedStrategy** | Untrusted or risky code | Isolation ✅, Speed ❌ |
 
+**Parallel Execution:** Both strategies execute tools concurrently by default. Results return in **completion order** (faster tools return first), not submission order. Use `ToolResult.tool` to match results to original calls.
+
 ```python
 import asyncio
 from chuk_tool_processor import ToolProcessor, IsolatedStrategy, get_default_registry

{chuk_tool_processor-0.12.2 → chuk_tool_processor-0.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chuk-tool-processor"
-version = "0.12.2"
+version = "0.13"
 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.12.2 → chuk_tool_processor-0.13}/src/chuk_tool_processor/execution/strategies/inprocess_strategy.py

@@ -7,6 +7,18 @@ This strategy executes tools concurrently in the same process using asyncio.
 It has special support for streaming tools, accessing their stream_execute method
 directly to enable true item-by-item streaming.
 
+PARALLEL EXECUTION:
+- All tool calls execute concurrently using asyncio tasks
+- Results are returned/yielded as each tool completes (completion order, not submission order)
+- Faster tools return immediately without waiting for slower ones
+- Use run() for batch results in completion order
+- Use stream_run() to yield results as they arrive
+
+STREAMING SUPPORT:
+- stream_run() yields ToolResult objects as each tool completes
+- Optional on_tool_start callback for emitting start events
+- True streaming for tools that implement stream_execute
+
 Enhanced tool name resolution that properly handles:
 - Simple names: "get_current_time"
 - Namespaced names: "diagnostic_test.get_current_time"
@@ -23,7 +35,7 @@ import builtins
 import inspect
 import os
 import platform
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Awaitable, Callable
 from contextlib import asynccontextmanager, suppress
 from datetime import UTC, datetime
 from typing import Any
@@ -122,14 +134,17 @@ class InProcessStrategy(ExecutionStrategy):
         timeout: float | None = None,
     ) -> list[ToolResult]:
         """
-        Execute tool calls concurrently and preserve order.
+        Execute tool calls concurrently and return results as they complete.
+
+        NOTE: Results are returned in COMPLETION ORDER, not submission order.
+        This allows faster tools to return immediately without waiting for slower ones.
 
         Args:
             calls: List of tool calls to execute
             timeout: Optional timeout for execution
 
         Returns:
-            List of tool results in the same order as calls
+            List of tool results in completion order (not submission order)
         """
         if not calls:
             return []
@@ -138,6 +153,7 @@ class InProcessStrategy(ExecutionStrategy):
         effective_timeout = timeout if timeout is not None else self.default_timeout
         logger.debug("Executing %d calls with %ss timeout each", len(calls), effective_timeout)
 
+        # Create all tasks immediately so they start running in parallel
         tasks = []
         for call in calls:
             task = asyncio.create_task(
@@ -148,17 +164,35 @@ class InProcessStrategy(ExecutionStrategy):
             tasks.append(task)
 
         async with log_context_span("inprocess_execution", {"num_calls": len(calls)}):
-            return await asyncio.gather(*tasks)
+            # Use as_completed to return results as they finish, not all at once
+            results = []
+            for completed_task in asyncio.as_completed(tasks):
+                result = await completed_task
+                results.append(result)
+            return results
 
     # ------------------------------------------------------------------ #
     async def stream_run(
         self,
         calls: list[ToolCall],
         timeout: float | None = None,
+        on_tool_start: Callable[[ToolCall], Awaitable[None]] | None = None,
     ) -> AsyncIterator[ToolResult]:
         """
         Execute tool calls concurrently and *yield* results as soon as they are
-        produced, preserving completion order.
+        produced in completion order (not submission order).
+
+        This method allows results to stream back as each tool completes, without
+        waiting for all tools to finish. Faster tools return immediately.
+
+        Args:
+            calls: List of tool calls to execute concurrently
+            timeout: Optional timeout for each tool execution
+            on_tool_start: Optional callback invoked when each tool starts execution.
+                          Useful for emitting start events before results arrive.
+
+        Yields:
+            ToolResult objects as each tool completes (in completion order)
         """
         if not calls:
             return
@@ -168,9 +202,7 @@ class InProcessStrategy(ExecutionStrategy):
 
         queue: asyncio.Queue[ToolResult] = asyncio.Queue()
         tasks = {
-            asyncio.create_task(
-                self._stream_tool_call(call, queue, effective_timeout)  # Always pass timeout
-            )
+            asyncio.create_task(self._stream_tool_call(call, queue, effective_timeout, on_tool_start))
             for call in calls
             if call.id not in self._direct_streaming_calls
         }
@@ -194,6 +226,7 @@ class InProcessStrategy(ExecutionStrategy):
         call: ToolCall,
         queue: asyncio.Queue,
         timeout: float,  # Make timeout required
+        on_tool_start: Callable[[ToolCall], Awaitable[None]] | None = None,
     ) -> None:
         """
         Execute a tool call with streaming support.
@@ -205,6 +238,7 @@ class InProcessStrategy(ExecutionStrategy):
             call: The tool call to execute
             queue: Queue to put results into
             timeout: Timeout in seconds (required)
+            on_tool_start: Optional callback to invoke when tool execution starts
         """
         # Skip if call is being handled directly by the executor
         if call.id in self._direct_streaming_calls:
@@ -225,6 +259,13 @@ class InProcessStrategy(ExecutionStrategy):
             await queue.put(result)
             return
 
+        # Invoke start callback if provided
+        if on_tool_start:
+            try:
+                await on_tool_start(call)
+            except Exception as e:
+                logger.warning(f"on_tool_start callback failed for {call.tool}: {e}")
+
         try:
             # Use enhanced tool resolution instead of direct lookup
             tool_impl, resolved_namespace = await self._resolve_tool_info(call.tool, call.namespace)

{chuk_tool_processor-0.12.2 → chuk_tool_processor-0.13}/src/chuk_tool_processor/execution/strategies/subprocess_strategy.py

@@ -25,7 +25,7 @@ import os
 import pickle
 import platform
 import signal
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Awaitable, Callable
 from datetime import UTC, datetime
 from typing import Any
 
@@ -264,14 +264,17 @@ class SubprocessStrategy(ExecutionStrategy):
         timeout: float | None = None,
     ) -> list[ToolResult]:
         """
-        Execute tool calls in separate processes.
+        Execute tool calls in separate processes and return results as they complete.
+
+        NOTE: Results are returned in COMPLETION ORDER, not submission order.
+        This allows faster tools to return immediately without waiting for slower ones.
 
         Args:
             calls: List of tool calls to execute
             timeout: Optional timeout for each execution (overrides default)
 
         Returns:
-            List of tool results in the same order as calls
+            List of tool results in completion order (not submission order)
         """
         if not calls:
             return []
@@ -308,14 +311,19 @@ class SubprocessStrategy(ExecutionStrategy):
             task.add_done_callback(self._active_tasks.discard)
             tasks.append(task)
 
-        # Execute all tasks concurrently
+        # Execute all tasks concurrently and return results in completion order
         async with log_context_span("subprocess_execution", {"num_calls": len(calls)}):
-            return await asyncio.gather(*tasks)
+            results = []
+            for completed_task in asyncio.as_completed(tasks):
+                result = await completed_task
+                results.append(result)
+            return results
 
     async def stream_run(
         self,
         calls: list[ToolCall],
         timeout: float | None = None,
+        on_tool_start: Callable[[ToolCall], Awaitable[None]] | None = None,
     ) -> AsyncIterator[ToolResult]:
         """
         Execute tool calls and yield results as they become available.
@@ -323,9 +331,11 @@ class SubprocessStrategy(ExecutionStrategy):
         Args:
             calls: List of tool calls to execute
             timeout: Optional timeout for each execution
+            on_tool_start: Optional callback invoked when each tool starts execution.
+                          Useful for emitting start events before results arrive.
 
         Yields:
-            Tool results as they complete (not necessarily in order)
+            Tool results as they complete (in completion order)
         """
         if not calls:
             return
@@ -358,6 +368,7 @@ class SubprocessStrategy(ExecutionStrategy):
                     call,
                     queue,
                     effective_timeout,  # Always pass concrete timeout
+                    on_tool_start,
                 )
             )
             self._active_tasks.add(task)
@@ -385,8 +396,16 @@ class SubprocessStrategy(ExecutionStrategy):
         call: ToolCall,
         queue: asyncio.Queue,
         timeout: float,  # Make timeout required
+        on_tool_start: Callable[[ToolCall], Awaitable[None]] | None = None,
     ) -> None:
         """Execute a single call and put the result in the queue."""
+        # Invoke start callback if provided
+        if on_tool_start:
+            try:
+                await on_tool_start(call)
+            except Exception as e:
+                logger.warning(f"on_tool_start callback failed for {call.tool}: {e}")
+
         result = await self._execute_single_call(call, timeout)
         await queue.put(result)
 

{chuk_tool_processor-0.12.2 → chuk_tool_processor-0.13}/src/chuk_tool_processor/execution/tool_executor.py

@@ -107,7 +107,8 @@ class ToolExecutor:
             use_cache: Whether to use cached results (for caching wrappers)
 
         Returns:
-            List of tool results in the same order as calls
+            List of tool results in completion order (not submission order).
+            Use ToolResult.tool to match results back to their original calls.
         """
         if not calls:
             return []

{chuk_tool_processor-0.12.2 → chuk_tool_processor-0.13}/src/chuk_tool_processor/models/execution_strategy.py

@@ -6,7 +6,7 @@ Abstract base class for tool execution strategies.
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Awaitable, Callable
 
 from chuk_tool_processor.models.tool_call import ToolCall
 from chuk_tool_processor.models.tool_result import ToolResult
@@ -18,6 +18,11 @@ class ExecutionStrategy(ABC):
 
     All execution strategies must implement at least the run method,
     and optionally stream_run for streaming support.
+
+    PARALLEL EXECUTION NOTE:
+    Results are returned in COMPLETION ORDER, not submission order.
+    This allows faster tools to return immediately without waiting for slower ones.
+    Use the ToolResult.tool attribute to match results back to their original calls.
     """
 
     @abstractmethod
@@ -30,11 +35,17 @@ class ExecutionStrategy(ABC):
             timeout: Optional timeout in seconds for each call
 
         Returns:
-            List of ToolResult objects in the same order as the calls
+            List of ToolResult objects in completion order (not submission order).
+            Use ToolResult.tool to match results back to their original calls.
         """
         pass
 
-    async def stream_run(self, calls: list[ToolCall], timeout: float | None = None) -> AsyncIterator[ToolResult]:
+    async def stream_run(
+        self,
+        calls: list[ToolCall],
+        timeout: float | None = None,
+        on_tool_start: Callable[[ToolCall], Awaitable[None]] | None = None,  # noqa: ARG002
+    ) -> AsyncIterator[ToolResult]:
         """
         Execute tool calls and yield results as they become available.
 
@@ -44,10 +55,14 @@ class ExecutionStrategy(ABC):
         Args:
             calls: List of ToolCall objects to execute
             timeout: Optional timeout in seconds for each call
+            on_tool_start: Optional callback invoked when each tool starts execution.
+                          Useful for emitting start events before results arrive.
 
         Yields:
-            ToolResult objects as they become available
+            ToolResult objects as they become available (in completion order)
         """
+        # Default implementation ignores on_tool_start since we batch execute
+        # Subclasses with true streaming can use the callback
         results = await self.run(calls, timeout=timeout)
         for result in results:
             yield result

{chuk_tool_processor-0.12.2 → chuk_tool_processor-0.13}/src/chuk_tool_processor.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chuk-tool-processor
-Version: 0.12.2
+Version: 0.13
 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>
@@ -652,6 +652,57 @@ async with ToolProcessor(
     ''')
 ```
 
+### Parallel Execution & Streaming Results
+
+Tools execute concurrently by default. Results return in **completion order** — faster tools return immediately without waiting for slower ones:
+
+```python
+import asyncio
+from chuk_tool_processor.execution.strategies.inprocess_strategy import InProcessStrategy
+from chuk_tool_processor.models.tool_call import ToolCall
+
+# Tools with different execution times
+calls = [
+    ToolCall(tool="slow_api", arguments={"query": "complex"}),    # 500ms
+    ToolCall(tool="medium_api", arguments={"query": "medium"}),   # 200ms
+    ToolCall(tool="fast_api", arguments={"query": "simple"}),     # 50ms
+]
+
+# Results return as: fast_api, medium_api, slow_api (completion order)
+results = await strategy.run(calls)
+
+# Match results back to original calls by tool name
+for result in results:
+    print(f"{result.tool}: {result.result}")
+```
+
+**Stream results as they arrive** with `stream_run()`:
+
+```python
+async for result in strategy.stream_run(calls):
+    # Process each result immediately as it completes
+    print(f"Completed: {result.tool}")
+```
+
+**Track when tools start** with `on_tool_start` callback:
+
+```python
+async def on_start(call: ToolCall):
+    print(f"Starting: {call.tool}")
+
+async for result in strategy.stream_run(calls, on_tool_start=on_start):
+    print(f"Completed: {result.tool}")
+```
+
+**Control concurrency** with `max_concurrency`:
+
+```python
+# Limit to 2 concurrent tools (others queue)
+strategy = InProcessStrategy(registry, max_concurrency=2)
+```
+
+> **See:** `examples/parallel_execution_demo.py` for a complete demonstration.
+
 ## Documentation Quick Reference
 
 | Document | What It Covers |
@@ -863,6 +914,8 @@ class WeatherTool(ValidatedTool):
 | **InProcessStrategy** | Fast, trusted tools | Speed ✅, Isolation ❌ |
 | **IsolatedStrategy** | Untrusted or risky code | Isolation ✅, Speed ❌ |
 
+**Parallel Execution:** Both strategies execute tools concurrently by default. Results return in **completion order** (faster tools return first), not submission order. Use `ToolResult.tool` to match results to original calls.
+
 ```python
 import asyncio
 from chuk_tool_processor import ToolProcessor, IsolatedStrategy, get_default_registry