chuk-tool-processor 0.1.6__py3-none-any.whl → 0.1.7__py3-none-any.whl

chuk_tool_processor/models/execution_strategy.py

@@ -1,14 +1,21 @@
 # chuk_tool_processor/models/execution_strategy.py
+"""
+Abstract base class for tool execution strategies.
+"""
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
-from typing import List, Optional
+from typing import List, Optional, Dict, Any, AsyncIterator
 
 from chuk_tool_processor.models.tool_call import ToolCall
 from chuk_tool_processor.models.tool_result import ToolResult
 
-
 class ExecutionStrategy(ABC):
     """
     Strategy interface for executing ToolCall objects.
+    
+    All execution strategies must implement at least the run method,
+    and optionally stream_run for streaming support.
     """
     @abstractmethod
     async def run(
@@ -16,4 +23,46 @@ class ExecutionStrategy(ABC):
         calls: List[ToolCall],
         timeout: Optional[float] = None
     ) -> List[ToolResult]:
-        pass
+        """
+        Execute a list of tool calls and return their results.
+        
+        Args:
+            calls: List of ToolCall objects to execute
+            timeout: Optional timeout in seconds for each call
+            
+        Returns:
+            List of ToolResult objects in the same order as the calls
+        """
+        pass
+    
+    async def stream_run(
+        self,
+        calls: List[ToolCall],
+        timeout: Optional[float] = None
+    ) -> AsyncIterator[ToolResult]:
+        """
+        Execute tool calls and yield results as they become available.
+        
+        Default implementation executes all calls with run() and yields the results.
+        Subclasses can override for true streaming behavior.
+        
+        Args:
+            calls: List of ToolCall objects to execute
+            timeout: Optional timeout in seconds for each call
+            
+        Yields:
+            ToolResult objects as they become available
+        """
+        results = await self.run(calls, timeout=timeout)
+        for result in results:
+            yield result
+    
+    @property
+    def supports_streaming(self) -> bool:
+        """
+        Check if this strategy supports true streaming.
+        
+        Default implementation returns False. Streaming-capable strategies
+        should override this to return True.
+        """
+        return False

chuk_tool_processor/models/streaming_tool.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python
+# chuk_tool_processor/models/streaming_tool.py
+"""
+Base class for tools that support streaming results.
+
+This enables tools to yield incremental results during their execution,
+which is useful for long-running operations or real-time data processing.
+"""
+from __future__ import annotations
+
+import asyncio
+from abc import abstractmethod
+from typing import Any, AsyncIterator, List, TypeVar, Generic, ClassVar, Optional, Dict
+
+from pydantic import BaseModel, ConfigDict
+
+from chuk_tool_processor.models.validated_tool import ValidatedTool
+
+T = TypeVar('T')
+
+class StreamingTool(ValidatedTool):
+    """
+    Base class for tools that support streaming responses.
+    
+    Subclasses must implement _stream_execute which yields results one by one.
+    The executor should use stream_execute to access streaming results directly.
+    
+    Example:
+    ```python
+    class Counter(StreamingTool):
+        class Arguments(BaseModel):
+            count: int = 10
+            delay: float = 0.5
+            
+        class Result(BaseModel):
+            value: int
+            
+        async def _stream_execute(self, count: int, delay: float) -> AsyncIterator[Result]:
+            for i in range(count):
+                await asyncio.sleep(delay)
+                yield self.Result(value=i)
+    ```
+    
+    Streaming usage:
+    ```python
+    counter_tool = Counter()
+    async for result in counter_tool.stream_execute(count=5, delay=0.1):
+        print(f"Count: {result.value}")
+    ```
+    """
+    # Mark this as a ClassVar so Pydantic doesn't treat it as a field
+    supports_streaming: ClassVar[bool] = True
+    
+    # Use ConfigDict to configure model behavior
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    
+    async def stream_execute(self, **kwargs: Any) -> AsyncIterator[Any]:
+        """
+        Execute the tool and stream results incrementally.
+        
+        This public method validates arguments and then delegates to _stream_execute.
+        It should be used directly by the executor to support true streaming.
+        
+        Args:
+            **kwargs: Keyword arguments for the tool
+            
+        Yields:
+            Results as they are generated by the tool
+        """
+        # Validate arguments using the Arguments model
+        args = self.Arguments(**kwargs)
+        
+        # Stream results directly from _stream_execute
+        async for result in self._stream_execute(**args.model_dump()):
+            yield result
+    
+    async def execute(self, **kwargs: Any) -> Any:
+        """
+        Execute the tool and collect all results.
+        
+        For streaming tools, this collects all results from stream_execute
+        into a list for compatibility with the regular execution model.
+        
+        Args:
+            **kwargs: Keyword arguments for the tool
+            
+        Returns:
+            List of all streamed results
+        """
+        # Collect all streamed results into a list
+        results = []
+        async for chunk in self.stream_execute(**kwargs):
+            results.append(chunk)
+            
+        return results
+    
+    @abstractmethod
+    async def _stream_execute(self, **kwargs: Any) -> AsyncIterator[Any]:
+        """
+        Execute the tool and yield results incrementally.
+        
+        This must be implemented by streaming tool subclasses.
+        
+        Args:
+            **kwargs: Tool-specific arguments
+            
+        Yields:
+            Results as they are generated
+        """
+        yield NotImplemented

chuk_tool_processor/models/tool_call.py

@@ -1,7 +1,59 @@
 # chuk_tool_processor/models/tool_call.py
-from pydantic import BaseModel, Field
-from typing import Any, Dict
+"""
+Model representing a tool call with arguments.
+"""
+from __future__ import annotations
+
+import uuid
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field, ConfigDict
 
 class ToolCall(BaseModel):
-    tool: str = Field(..., min_length=1, description="Name of the tool to call; must be non‐empty")
-    arguments: Dict[str, Any] = Field(default_factory=dict)
+    """
+    Represents a call to a tool with arguments.
+    
+    Attributes:
+        id: Unique identifier for the tool call
+        tool: Name of the tool to call
+        namespace: Namespace the tool belongs to
+        arguments: Arguments to pass to the tool
+    """
+    model_config = ConfigDict(extra='ignore')
+    
+    id: str = Field(
+        default_factory=lambda: str(uuid.uuid4()),
+        description="Unique identifier for the tool call"
+    )
+    tool: str = Field(
+        ..., 
+        min_length=1,
+        description="Name of the tool to call; must be non-empty"
+    )
+    namespace: str = Field(
+        default="default",
+        description="Namespace the tool belongs to"
+    )
+    arguments: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arguments to pass to the tool"
+    )
+    
+    async def to_dict(self) -> Dict[str, Any]:
+        """Convert to a dictionary for serialization."""
+        return {
+            "id": self.id,
+            "tool": self.tool,
+            "namespace": self.namespace,
+            "arguments": self.arguments
+        }
+    
+    @classmethod
+    async def from_dict(cls, data: Dict[str, Any]) -> ToolCall:
+        """Create a ToolCall from a dictionary."""
+        return cls(**data)
+    
+    def __str__(self) -> str:
+        """String representation of the tool call."""
+        args_str = ", ".join(f"{k}={v!r}" for k, v in self.arguments.items())
+        return f"ToolCall({self.tool}, {args_str})"

chuk_tool_processor/models/tool_result.py

@@ -1,23 +1,44 @@
 # chuk_tool_processor/models/tool_result.py
+"""
+Model representing the result of a tool execution.
+"""
+from __future__ import annotations
+
 import os
-from pydantic import BaseModel, Field, ConfigDict
-from typing import Any, Optional
+import uuid
 from datetime import datetime, timezone
+from typing import Any, Dict, Optional, List
+
+from pydantic import BaseModel, Field, ConfigDict
 
 class ToolResult(BaseModel):
     """
     Represents the result of executing a tool.
-    Includes timing, host, and process metadata for diagnostics.
+    
+    Includes timing, host, and process metadata for diagnostics and tracing.
+    
+    Attributes:
+        id: Unique identifier for the result
+        tool: Name of the tool that was executed
+        result: Return value from the tool execution
+        error: Error message if execution failed
+        start_time: UTC timestamp when execution started
+        end_time: UTC timestamp when execution finished
+        machine: Hostname where the tool ran
+        pid: Process ID of the worker
+        cached: Flag indicating if the result was retrieved from cache
+        attempts: Number of execution attempts made
+        stream_id: Optional identifier for streaming results
+        is_partial: Whether this is a partial streaming result
     """
-    # Configure Pydantic to ignore any extra fields
     model_config = ConfigDict(extra='ignore')
 
-    # Flag indicating whether this result was retrieved from cache
-    cached: bool = Field(
-        default=False,
-        description="True if this result was retrieved from cache"
+    id: str = Field(
+        default_factory=lambda: str(uuid.uuid4()),
+        description="Unique identifier for this result"
     )
-
+    
+    # Core fields
     tool: str = Field(
         ...,
         min_length=1,
@@ -31,6 +52,8 @@ class ToolResult(BaseModel):
         None,
         description="Error message if execution failed"
     )
+    
+    # Execution metadata
     start_time: datetime = Field(
         default_factory=lambda: datetime.now(timezone.utc),
         description="UTC timestamp when execution started"
@@ -47,3 +70,86 @@ class ToolResult(BaseModel):
         default_factory=lambda: os.getpid(),
         description="Process ID of the worker"
     )
+    
+    # Extended features
+    cached: bool = Field(
+        default=False,
+        description="True if this result was retrieved from cache"
+    )
+    attempts: int = Field(
+        default=1,
+        description="Number of execution attempts made"
+    )
+    
+    # Streaming support
+    stream_id: Optional[str] = Field(
+        default=None,
+        description="Identifier for this stream of results (for streaming tools)"
+    )
+    is_partial: bool = Field(
+        default=False,
+        description="True if this is a partial result in a stream"
+    )
+    
+    @property
+    def is_success(self) -> bool:
+        """Check if the execution was successful (no error)."""
+        return self.error is None
+    
+    @property
+    def duration(self) -> float:
+        """Calculate the execution duration in seconds."""
+        if not self.start_time or not self.end_time:
+            return 0.0
+        return (self.end_time - self.start_time).total_seconds()
+    
+    async def to_dict(self) -> Dict[str, Any]:
+        """Convert to a dictionary for serialization."""
+        return {
+            "id": self.id,
+            "tool": self.tool,
+            "result": self.result,
+            "error": self.error,
+            "success": self.is_success,
+            "duration": self.duration,
+            "start_time": self.start_time.isoformat(),
+            "end_time": self.end_time.isoformat(),
+            "machine": self.machine,
+            "pid": self.pid,
+            "cached": self.cached,
+            "attempts": self.attempts,
+            "stream_id": self.stream_id,
+            "is_partial": self.is_partial
+        }
+    
+    @classmethod
+    def create_stream_chunk(
+        cls, 
+        tool: str, 
+        result: Any, 
+        stream_id: Optional[str] = None
+    ) -> ToolResult:
+        """Create a partial streaming result."""
+        stream_id = stream_id or str(uuid.uuid4())
+        return cls(
+            tool=tool,
+            result=result,
+            stream_id=stream_id,
+            is_partial=True
+        )
+    
+    @classmethod
+    async def from_dict(cls, data: Dict[str, Any]) -> ToolResult:
+        """Create a ToolResult from a dictionary."""
+        # Handle datetime fields
+        if isinstance(data.get("start_time"), str):
+            data["start_time"] = datetime.fromisoformat(data["start_time"])
+        if isinstance(data.get("end_time"), str):
+            data["end_time"] = datetime.fromisoformat(data["end_time"])
+            
+        return cls(**data)
+    
+    def __str__(self) -> str:
+        """String representation of the tool result."""
+        status = "success" if self.is_success else f"error: {self.error}"
+        return f"ToolResult({self.tool}, {status}, duration={self.duration:.3f}s)"

chuk_tool_processor/models/validated_tool.py

@@ -1,6 +1,6 @@
 # chuk_tool_processor/models/validated_tool.py
 """
-Self-contained base-class for *declarative* tools.
+Self-contained base-class for *declarative* async-native tools.
 
 Subclass it like so:
 
@@ -12,7 +12,7 @@ Subclass it like so:
         class Result(BaseModel):
             sum: int
 
-        def _execute(self, *, x: int, y: int) -> Result:
+        async def _execute(self, *, x: int, y: int) -> Result:
             return self.Result(sum=x + y)
 """
 from __future__ import annotations
@@ -93,7 +93,7 @@ class _ExportMixin:
 # The public validated base-class
 # --------------------------------------------------------------------------- #
 class ValidatedTool(_ExportMixin, BaseModel):
-    """Pydantic-validated base for new tools."""
+    """Pydantic-validated base for new async-native tools."""
 
     # ------------------------------------------------------------------ #
     # Inner models – override in subclasses
@@ -107,11 +107,11 @@ class ValidatedTool(_ExportMixin, BaseModel):
     # ------------------------------------------------------------------ #
     # Public entry-point called by the processor
     # ------------------------------------------------------------------ #
-    def execute(self: T_Validated, **kwargs: Any) -> BaseModel:
+    async def execute(self: T_Validated, **kwargs: Any) -> BaseModel:
         """Validate *kwargs*, run `_execute`, validate the result."""
         try:
             args = self.Arguments(**kwargs)  # type: ignore[arg-type]
-            res = self._execute(**args.model_dump())  # type: ignore[arg-type]
+            res = await self._execute(**args.model_dump())  # type: ignore[arg-type]
 
             return (
                 res
@@ -124,16 +124,16 @@ class ValidatedTool(_ExportMixin, BaseModel):
     # ------------------------------------------------------------------ #
     # Sub-classes must implement this
     # ------------------------------------------------------------------ #
-    def _execute(self, **_kwargs: Any):  # noqa: D401 – expected override
-        raise NotImplementedError("Tool must implement _execute()")
+    async def _execute(self, **_kwargs: Any):  # noqa: D401 – expected override
+        raise NotImplementedError("Tool must implement async _execute()")
 
 
 # --------------------------------------------------------------------------- #
-# Decorator to retrofit validation onto classic “imperative” tools
+# Decorator to retrofit validation onto classic "imperative" tools
 # --------------------------------------------------------------------------- #
 def with_validation(cls):  # noqa: D401 – factory
     """
-    Decorator that wraps an existing ``execute`` method with:
+    Decorator that wraps an existing async ``execute`` method with:
 
     * argument validation (based on type hints)
     * result validation (based on return annotation)
@@ -143,13 +143,15 @@ def with_validation(cls):  # noqa: D401 – factory
         validate_result,
     )
 
-    original: Callable[..., Any] = cls.execute  # type: ignore[attr-defined]
+    original = cls.execute  # type: ignore[attr-defined]
+    if not inspect.iscoroutinefunction(original):
+        raise TypeError(f"Tool {cls.__name__} must have an async execute method")
 
-    def _wrapper(self, **kwargs):  # type: ignore[override]
+    async def _async_wrapper(self, **kwargs):  # type: ignore[override]
         tool_name = cls.__name__
         validated = validate_arguments(tool_name, original, kwargs)
-        result = original(self, **validated)
+        result = await original(self, **validated)
         return validate_result(tool_name, original, result)
 
-    cls.execute = _wrapper  # type: ignore[assignment]
+    cls.execute = _async_wrapper  # type: ignore[assignment]
     return cls