chuk-tool-processor 0.6.4__py3-none-any.whl → 0.9.7__py3-none-any.whl

chuk_tool_processor/models/__init__.py

@@ -1 +1,21 @@
-# chuk_tool_processor/models/__init__.py
+# chuk_tool_processor/models/__init__.py
+"""Data models for the tool processor."""
+
+from chuk_tool_processor.models.execution_strategy import ExecutionStrategy
+from chuk_tool_processor.models.streaming_tool import StreamingTool
+from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.models.tool_result import ToolResult
+from chuk_tool_processor.models.tool_spec import ToolCapability, ToolSpec, tool_spec
+from chuk_tool_processor.models.validated_tool import ValidatedTool, with_validation
+
+__all__ = [
+    "ExecutionStrategy",
+    "StreamingTool",
+    "ToolCall",
+    "ToolResult",
+    "ToolSpec",
+    "ToolCapability",
+    "tool_spec",
+    "ValidatedTool",
+    "with_validation",
+]

chuk_tool_processor/models/execution_strategy.py

@@ -2,67 +2,62 @@
 """
 Abstract base class for tool execution strategies.
 """
+
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import List, Optional, Dict, Any, AsyncIterator
+from collections.abc import 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(
-        self,
-        calls: List[ToolCall],
-        timeout: Optional[float] = None
-    ) -> List[ToolResult]:
+    async def run(self, calls: list[ToolCall], timeout: float | None = None) -> list[ToolResult]:
         """
         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]:
+
+    async def stream_run(self, calls: list[ToolCall], timeout: float | None = 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
+        return False

chuk_tool_processor/models/streaming_tool.py

@@ -6,41 +6,43 @@ 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 collections.abc import AsyncIterator
+from typing import Any, ClassVar, TypeVar
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import ConfigDict
 
 from chuk_tool_processor.models.validated_tool import ValidatedTool
 
-T = TypeVar('T')
+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()
@@ -48,42 +50,43 @@ class StreamingTool(ValidatedTool):
         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
         """
@@ -91,20 +94,20 @@ class StreamingTool(ValidatedTool):
         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
+        yield NotImplemented

chuk_tool_processor/models/tool_call.py

@@ -2,58 +2,76 @@
 """
 Model representing a tool call with arguments.
 """
+
 from __future__ import annotations
 
+import hashlib
+import json
 import uuid
-from typing import Any, Dict, Optional
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
-from pydantic import BaseModel, Field, ConfigDict
 
 class ToolCall(BaseModel):
     """
     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
+        idempotency_key: Optional key for deduplicating duplicate calls (auto-generated)
     """
-    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"
+
+    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")
+    idempotency_key: str | None = Field(
+        None,
+        description="Idempotency key for deduplication. Auto-generated if not provided.",
     )
-    
-    async def to_dict(self) -> Dict[str, Any]:
-        """Convert to a dictionary for serialization."""
-        return {
-            "id": self.id,
+
+    @model_validator(mode="after")
+    def generate_idempotency_key(self) -> ToolCall:
+        """Generate idempotency key if not provided."""
+        if self.idempotency_key is None:
+            self.idempotency_key = self._compute_idempotency_key()
+        return self
+
+    def _compute_idempotency_key(self) -> str:
+        """
+        Compute a stable idempotency key from tool name, namespace, and arguments.
+
+        Uses SHA256 hash of the sorted JSON representation.
+        Returns first 16 characters of the hex digest for brevity.
+        """
+        # Create a stable representation
+        payload = {
             "tool": self.tool,
             "namespace": self.namespace,
-            "arguments": self.arguments
+            "arguments": self.arguments,
         }
-    
+        # Sort keys for stability
+        json_str = json.dumps(payload, sort_keys=True, default=str)
+        # Hash it
+        hash_obj = hashlib.sha256(json_str.encode(), usedforsecurity=False)
+        return hash_obj.hexdigest()[:16]  # Use first 16 chars for brevity
+
+    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:
+    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})"
+        return f"ToolCall({self.tool}, {args_str})"

chuk_tool_processor/models/tool_export_mixin.py

@@ -1,29 +1,43 @@
 # chuk_tool_processor/models/tool_export_mix_in.py
-from typing import Dict
+
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+
+@runtime_checkable
+class HasArguments(Protocol):
+    """Protocol for classes that have an Arguments attribute."""
+
+    Arguments: type[BaseModel]
+
 
 class ToolExportMixin:
     """Mixin that lets any ValidatedTool advertise its schema."""
 
     @classmethod
-    def to_openai(cls) -> Dict:
-        schema = cls.Arguments.model_json_schema()
+    def to_openai(cls) -> dict[str, Any]:
+        assert hasattr(cls, "Arguments"), f"{cls.__name__} must have an Arguments attribute"
+        schema = cls.Arguments.model_json_schema()  # type: ignore[attr-defined]
         return {
             "type": "function",
             "function": {
-                "name": cls.__name__.removesuffix("Tool").lower(),   # or keep explicit name
+                "name": cls.__name__.removesuffix("Tool").lower(),  # or keep explicit name
                 "description": (cls.__doc__ or "").strip(),
                 "parameters": schema,
             },
         }
 
     @classmethod
-    def to_json_schema(cls) -> Dict:
-        return cls.Arguments.model_json_schema()
+    def to_json_schema(cls) -> dict[str, Any]:
+        assert hasattr(cls, "Arguments"), f"{cls.__name__} must have an Arguments attribute"
+        return cls.Arguments.model_json_schema()  # type: ignore[attr-defined, no-any-return]
 
     @classmethod
     def to_xml(cls) -> str:
         """Very small helper so existing XML-based parsers still work."""
+        assert hasattr(cls, "Arguments"), f"{cls.__name__} must have an Arguments attribute"
         name = cls.__name__.removesuffix("Tool").lower()
-        params = cls.Arguments.model_json_schema()["properties"]
+        params = cls.Arguments.model_json_schema()["properties"]  # type: ignore[attr-defined]
         args = ", ".join(params)
-        return f"<tool name=\"{name}\" args=\"{{{args}}}\"/>"
+        return f'<tool name="{name}" args="{{{args}}}"/>'

chuk_tool_processor/models/tool_result.py

@@ -2,21 +2,24 @@
 """
 Model representing the result of a tool execution.
 """
+
 from __future__ import annotations
 
 import os
+import platform
 import uuid
-from datetime import datetime, timezone
-from typing import Any, Dict, Optional, List
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
 
-from pydantic import BaseModel, Field, ConfigDict
 
 class ToolResult(BaseModel):
     """
     Represents the result of executing a tool.
-    
+
     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
@@ -31,79 +34,49 @@ class ToolResult(BaseModel):
         stream_id: Optional identifier for streaming results
         is_partial: Whether this is a partial streaming result
     """
-    model_config = ConfigDict(extra='ignore')
 
-    id: str = Field(
-        default_factory=lambda: str(uuid.uuid4()),
-        description="Unique identifier for this result"
-    )
-    
+    model_config = ConfigDict(extra="ignore")
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()), description="Unique identifier for this result")
+
     # Core fields
-    tool: str = Field(
-        ...,
-        min_length=1,
-        description="Name of the tool; must be non-empty"
-    )
-    result: Any = Field(
-        None,
-        description="Return value from the tool execution"
-    )
-    error: Optional[str] = Field(
-        None,
-        description="Error message if execution failed"
-    )
-    
+    tool: str = Field(..., min_length=1, description="Name of the tool; must be non-empty")
+    result: Any = Field(None, description="Return value from the tool execution")
+    error: str | None = Field(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"
+        default_factory=lambda: datetime.now(UTC), description="UTC timestamp when execution started"
     )
     end_time: datetime = Field(
-        default_factory=lambda: datetime.now(timezone.utc),
-        description="UTC timestamp when execution finished"
-    )
-    machine: str = Field(
-        default_factory=lambda: os.uname().nodename,
-        description="Hostname where the tool ran"
-    )
-    pid: int = Field(
-        default_factory=lambda: os.getpid(),
-        description="Process ID of the worker"
+        default_factory=lambda: datetime.now(UTC), description="UTC timestamp when execution finished"
     )
-    
+    machine: str = Field(default_factory=lambda: platform.node(), description="Hostname where the tool ran")
+    pid: int = Field(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"
-    )
-    
+    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"
+    stream_id: str | None = 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]:
+
+    async def to_dict(self) -> dict[str, Any]:
         """Convert to a dictionary for serialization."""
         return {
             "id": self.id,
@@ -119,37 +92,27 @@ class ToolResult(BaseModel):
             "cached": self.cached,
             "attempts": self.attempts,
             "stream_id": self.stream_id,
-            "is_partial": self.is_partial
+            "is_partial": self.is_partial,
         }
-    
+
     @classmethod
-    def create_stream_chunk(
-        cls, 
-        tool: str, 
-        result: Any, 
-        stream_id: Optional[str] = None
-    ) -> ToolResult:
+    def create_stream_chunk(cls, tool: str, result: Any, stream_id: str | None = 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
-        )
-    
+        return cls(tool=tool, result=result, error=None, stream_id=stream_id, is_partial=True)
+
     @classmethod
-    async def from_dict(cls, data: Dict[str, Any]) -> ToolResult:
+    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)"
+        return f"ToolResult({self.tool}, {status}, duration={self.duration:.3f}s)"