chuk-tool-processor 0.1.0__py3-none-any.whl

chuk_tool_processor/execution/wrappers/caching.py

@@ -0,0 +1,234 @@
+# chuk_tool_processor/execution/wrappers/caching.py
+import asyncio
+import hashlib
+import json
+import time
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta
+from functools import wraps
+from typing import Any, Dict, Optional, Tuple, List, Callable
+from pydantic import BaseModel
+
+# imports
+from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.models.tool_result import ToolResult
+
+
+class CacheEntry(BaseModel):
+    """
+    Entry in the tool result cache.
+    """
+    tool: str
+    arguments_hash: str
+    result: Any
+    created_at: datetime
+    expires_at: Optional[datetime] = None
+
+
+class CacheInterface(ABC):
+    """
+    Abstract interface for cache implementations.
+    """
+    @abstractmethod
+    async def get(self, tool: str, arguments_hash: str) -> Optional[Any]:
+        """
+        Get a cached result for a tool with given arguments hash.
+        """
+        pass
+    
+    @abstractmethod
+    async def set(
+        self, 
+        tool: str, 
+        arguments_hash: str, 
+        result: Any, 
+        ttl: Optional[int] = None
+    ) -> None:
+        """
+        Set a cached result for a tool with given arguments hash.
+        """
+        pass
+    
+    @abstractmethod
+    async def invalidate(self, tool: str, arguments_hash: Optional[str] = None) -> None:
+        """
+        Invalidate cached results for a tool, optionally for specific arguments.
+        """
+        pass
+
+
+class InMemoryCache(CacheInterface):
+    """
+    In-memory implementation of the cache interface.
+    """
+    def __init__(self, default_ttl: Optional[int] = 300):
+        self._cache: Dict[str, Dict[str, CacheEntry]] = {}
+        self._default_ttl = default_ttl
+        self._lock = asyncio.Lock()
+    
+    async def get(self, tool: str, arguments_hash: str) -> Optional[Any]:
+        async with self._lock:
+            tool_cache = self._cache.get(tool)
+            if not tool_cache:
+                return None
+            entry = tool_cache.get(arguments_hash)
+            if not entry:
+                return None
+            now = datetime.now()
+            if entry.expires_at and entry.expires_at < now:
+                del tool_cache[arguments_hash]
+                return None
+            return entry.result
+    
+    async def set(
+        self, 
+        tool: str, 
+        arguments_hash: str, 
+        result: Any, 
+        ttl: Optional[int] = None
+    ) -> None:
+        async with self._lock:
+            if tool not in self._cache:
+                self._cache[tool] = {}
+            now = datetime.now()
+            expires_at = None
+            actual_ttl = ttl if ttl is not None else self._default_ttl
+            if actual_ttl is not None:
+                expires_at = now + timedelta(seconds=actual_ttl)
+            entry = CacheEntry(
+                tool=tool,
+                arguments_hash=arguments_hash,
+                result=result,
+                created_at=now,
+                expires_at=expires_at
+            )
+            self._cache[tool][arguments_hash] = entry
+    
+    async def invalidate(self, tool: str, arguments_hash: Optional[str] = None) -> None:
+        async with self._lock:
+            if tool not in self._cache:
+                return
+            if arguments_hash is not None:
+                self._cache[tool].pop(arguments_hash, None)
+            else:
+                del self._cache[tool]
+
+
+class CachingToolExecutor:
+    """
+    Wrapper for a tool executor that caches results.
+    """
+    def __init__(
+        self,
+        executor: Any,
+        cache: CacheInterface,
+        default_ttl: Optional[int] = None,
+        tool_ttls: Optional[Dict[str, int]] = None,
+        cacheable_tools: Optional[List[str]] = None
+    ):
+        self.executor = executor
+        self.cache = cache
+        self.default_ttl = default_ttl
+        self.tool_ttls = tool_ttls or {}
+        self.cacheable_tools = cacheable_tools
+    
+    def _get_arguments_hash(self, arguments: Dict[str, Any]) -> str:
+        serialized = json.dumps(arguments, sort_keys=True)
+        return hashlib.md5(serialized.encode()).hexdigest()
+    
+    def _is_cacheable(self, tool: str) -> bool:
+        if self.cacheable_tools is None:
+            return True
+        return tool in self.cacheable_tools
+    
+    def _get_ttl(self, tool: str) -> Optional[int]:
+        return self.tool_ttls.get(tool, self.default_ttl)
+    
+    async def execute(
+        self,
+        calls: List[ToolCall],
+        timeout: Optional[float] = None,
+        use_cache: bool = True
+    ) -> List[ToolResult]:
+        results: List[ToolResult] = []
+        uncached_calls: List[Tuple[int, ToolCall]] = []
+        
+        if use_cache:
+            for i, call in enumerate(calls):
+                if not self._is_cacheable(call.tool):
+                    uncached_calls.append((i, call))
+                    continue
+                arguments_hash = self._get_arguments_hash(call.arguments)
+                cached_result = await self.cache.get(call.tool, arguments_hash)
+                if cached_result is not None:
+                    now = datetime.now()
+                    results.append(ToolResult(
+                        tool=call.tool,
+                        result=cached_result,
+                        error=None,
+                        start_time=now,
+                        end_time=now,
+                        machine="cache",
+                        pid=0,
+                        cached=True
+                    ))
+                else:
+                    uncached_calls.append((i, call))
+        else:
+            uncached_calls = [(i, call) for i, call in enumerate(calls)]
+
+        # Early return if all served from cache
+        if use_cache and not uncached_calls:
+            return results
+
+        if uncached_calls:
+            uncached_results = await self.executor.execute(
+                [call for _, call in uncached_calls],
+                timeout=timeout
+            )
+            
+            if use_cache:
+                for idx, result in enumerate(uncached_results):
+                    _, call = uncached_calls[idx]
+                    if result.error is None and self._is_cacheable(call.tool):
+                        arguments_hash = self._get_arguments_hash(call.arguments)
+                        ttl = self._get_ttl(call.tool)
+                        await self.cache.set(
+                            call.tool,
+                            arguments_hash,
+                            result.result,
+                            ttl=ttl
+                        )
+                        result.cached = False
+
+            final_results: List[ToolResult] = [None] * len(calls)
+            uncached_indices = {idx for idx, _ in uncached_calls}
+            uncached_iter = iter(uncached_results)
+            cache_iter = iter(results)
+            for i in range(len(calls)):
+                if i in uncached_indices:
+                    final_results[i] = next(uncached_iter)
+                else:
+                    final_results[i] = next(cache_iter)
+            return final_results
+
+
+def cacheable(ttl: Optional[int] = None):
+    def decorator(cls):
+        cls._cacheable = True
+        if ttl is not None:
+            cls._cache_ttl = ttl
+        return cls
+    return decorator
+
+
+def invalidate_cache(tool: str, arguments: Optional[Dict[str, Any]] = None):
+    async def _invalidate(cache: CacheInterface):
+        if arguments is not None:
+            arguments_hash = hashlib.md5(
+                json.dumps(arguments, sort_keys=True).encode()
+            ).hexdigest()
+            await cache.invalidate(tool, arguments_hash)
+        else:
+            await cache.invalidate(tool)
+    return _invalidate

chuk_tool_processor/execution/wrappers/rate_limiting.py

@@ -0,0 +1,149 @@
+# chuk_tool_processor/execution/wrappers/rate_limiting.py
+import asyncio
+import time
+from datetime import datetime
+from typing import Dict, Optional, List, Any, Tuple
+
+# imports
+from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.models.tool_result import ToolResult
+from chuk_tool_processor.core.exceptions import ToolExecutionError
+
+
+class RateLimiter:
+    """
+    Rate limiter for tool executions.
+    Supports per-tool rate limits and global rate limits.
+    """
+    def __init__(
+        self,
+        global_limit: Optional[int] = None,
+        global_period: float = 60.0,
+        tool_limits: Optional[Dict[str, Tuple[int, float]]] = None
+    ):
+        """
+        Initialize the rate limiter.
+        """
+        self.global_limit = global_limit
+        self.global_period = global_period
+        self.tool_limits = tool_limits or {}
+        
+        # Track request timestamps
+        self._global_timestamps: List[float] = []
+        self._tool_timestamps: Dict[str, List[float]] = {}
+        
+        # Locks for concurrency safety
+        self._global_lock = asyncio.Lock()
+        self._tool_locks: Dict[str, asyncio.Lock] = {}
+    
+    async def _wait_for_global_limit(self) -> None:
+        """
+        Wait until global rate limit allows another request.
+        """
+        if self.global_limit is None:
+            return
+        
+        while True:
+            # Acquire lock to check and possibly record
+            async with self._global_lock:
+                now = time.time()
+                # Remove expired timestamps
+                cutoff = now - self.global_period
+                self._global_timestamps = [ts for ts in self._global_timestamps if ts > cutoff]
+                # If under limit, record and proceed
+                if len(self._global_timestamps) < self.global_limit:
+                    self._global_timestamps.append(now)
+                    return
+                # Otherwise compute wait time
+                oldest = min(self._global_timestamps)
+                wait_time = (oldest + self.global_period) - now
+            # Sleep outside lock
+            if wait_time > 0:
+                await asyncio.sleep(wait_time)
+            else:
+                # retry immediately
+                continue
+    
+    async def _wait_for_tool_limit(self, tool: str) -> None:
+        """
+        Wait until tool-specific rate limit allows another request.
+        """
+        # Check if tool has a limit
+        if tool not in self.tool_limits:
+            return
+        limit, period = self.tool_limits[tool]
+        
+        # Initialize lock and timestamps list if needed
+        if tool not in self._tool_locks:
+            self._tool_locks[tool] = asyncio.Lock()
+        if tool not in self._tool_timestamps:
+            self._tool_timestamps[tool] = []
+        
+        while True:
+            async with self._tool_locks[tool]:
+                now = time.time()
+                # Remove expired timestamps
+                cutoff = now - period
+                self._tool_timestamps[tool] = [ts for ts in self._tool_timestamps[tool] if ts > cutoff]
+                # If under limit, record and proceed
+                if len(self._tool_timestamps[tool]) < limit:
+                    self._tool_timestamps[tool].append(now)
+                    return
+                # Otherwise compute wait time
+                oldest = min(self._tool_timestamps[tool])
+                wait_time = (oldest + period) - now
+            # Sleep outside lock
+            if wait_time > 0:
+                await asyncio.sleep(wait_time)
+            else:
+                continue
+    
+    async def wait(self, tool: str) -> None:
+        """
+        Wait until rate limits allow execution of the given tool.
+        """
+        # Wait for global limit first
+        await self._wait_for_global_limit()
+        # Then wait for tool-specific limit
+        await self._wait_for_tool_limit(tool)
+
+
+class RateLimitedToolExecutor:
+    """
+    Wrapper for a tool executor that applies rate limiting.
+    """
+    def __init__(
+        self,
+        executor: Any,
+        rate_limiter: RateLimiter
+    ):
+        """
+        Initialize the rate-limited executor.
+        """
+        self.executor = executor
+        self.rate_limiter = rate_limiter
+    
+    async def execute(
+        self,
+        calls: List[ToolCall],
+        timeout: Optional[float] = None
+    ) -> List[ToolResult]:
+        """
+        Execute tool calls with rate limiting.
+        """
+        # Apply rate limiting to each call
+        for call in calls:
+            await self.rate_limiter.wait(call.tool)
+        # Delegate to inner executor
+        return await self.executor.execute(calls, timeout=timeout)
+
+
+def rate_limited(limit: int, period: float = 60.0):
+    """
+    Decorator to specify rate limits for a tool class.
+    """
+    def decorator(cls):
+        cls._rate_limit = limit
+        cls._rate_period = period
+        return cls
+    return decorator

chuk_tool_processor/execution/wrappers/retry.py

@@ -0,0 +1,176 @@
+# chuk_tool_processor/retry.py
+import asyncio
+import logging
+import random
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Type
+
+# imports
+from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.models.tool_result import ToolResult
+
+logger = logging.getLogger(__name__)
+
+
+class RetryConfig:
+    """
+    Configuration for retry behavior.
+    """
+    def __init__(
+        self,
+        max_retries: int = 3,
+        base_delay: float = 1.0,
+        max_delay: float = 60.0,
+        jitter: bool = True,
+        retry_on_exceptions: Optional[List[Type[Exception]]] = None,
+        retry_on_error_substrings: Optional[List[str]] = None
+    ):
+        self.max_retries = max_retries
+        self.base_delay = base_delay
+        self.max_delay = max_delay
+        self.jitter = jitter
+        self.retry_on_exceptions = retry_on_exceptions or []
+        self.retry_on_error_substrings = retry_on_error_substrings or []
+    
+    def should_retry(self, attempt: int, error: Optional[Exception] = None, error_str: Optional[str] = None) -> bool:
+        if attempt >= self.max_retries:
+            return False
+        if not self.retry_on_exceptions and not self.retry_on_error_substrings:
+            return True
+        if error is not None and any(isinstance(error, exc) for exc in self.retry_on_exceptions):
+            return True
+        if error_str and any(substr in error_str for substr in self.retry_on_error_substrings):
+            return True
+        return False
+    
+    def get_delay(self, attempt: int) -> float:
+        delay = min(self.base_delay * (2 ** attempt), self.max_delay)
+        if self.jitter:
+            delay *= (0.5 + random.random())
+        return delay
+
+
+class RetryableToolExecutor:
+    """
+    Wrapper for a tool executor that applies retry logic.
+    """
+    def __init__(
+        self,
+        executor: Any,
+        default_config: RetryConfig = None,
+        tool_configs: Dict[str, RetryConfig] = None
+    ):
+        self.executor = executor
+        self.default_config = default_config or RetryConfig()
+        self.tool_configs = tool_configs or {}
+    
+    def _get_config(self, tool: str) -> RetryConfig:
+        return self.tool_configs.get(tool, self.default_config)
+    
+    async def execute(
+        self,
+        calls: List[ToolCall],
+        timeout: Optional[float] = None
+    ) -> List[ToolResult]:
+        results: List[ToolResult] = []
+        for call in calls:
+            config = self._get_config(call.tool)
+            result = await self._execute_with_retry(call, config, timeout)
+            results.append(result)
+        return results
+    
+    async def _execute_with_retry(
+        self,
+        call: ToolCall,
+        config: RetryConfig,
+        timeout: Optional[float]
+    ) -> ToolResult:
+        attempt = 0
+        last_error: Optional[str] = None
+        pid = 0
+        machine = "unknown"
+        
+        while True:
+            start_time = datetime.now(timezone.utc)
+            try:
+                # execute call
+                tool_results = await self.executor.execute([call], timeout=timeout)
+                result = tool_results[0]
+                pid = result.pid
+                machine = result.machine
+                
+                # error in result
+                if result.error:
+                    last_error = result.error
+                    if config.should_retry(attempt, error_str=result.error):
+                        logger.info(
+                            f"Retrying tool {call.tool} after error: {result.error} (attempt {attempt + 1})"
+                        )
+                        await asyncio.sleep(config.get_delay(attempt))
+                        attempt += 1
+                        continue
+                    # no retry: if any retries happened, wrap final error
+                    if attempt > 0:
+                        end_time = datetime.now(timezone.utc)
+                        final = ToolResult(
+                            tool=call.tool,
+                            result=None,
+                            error=f"Max retries reached ({config.max_retries}): {last_error}",
+                            start_time=start_time,
+                            end_time=end_time,
+                            machine=machine,
+                            pid=pid
+                        )
+                        # attach attempts
+                        object.__setattr__(final, 'attempts', attempt)
+                        return final
+                    # no retries occurred, return the original failure
+                    return result
+                
+                # success: attach attempts and return
+                object.__setattr__(result, 'attempts', attempt)
+                return result
+            except Exception as e:
+                err_str = str(e)
+                last_error = err_str
+                if config.should_retry(attempt, error=e):
+                    logger.info(
+                        f"Retrying tool {call.tool} after exception: {err_str} (attempt {attempt + 1})"
+                    )
+                    await asyncio.sleep(config.get_delay(attempt))
+                    attempt += 1
+                    continue
+                # no more retries: return error result
+                end_time = datetime.now(timezone.utc)
+                final_exc = ToolResult(
+                    tool=call.tool,
+                    result=None,
+                    error=err_str,
+                    start_time=start_time,
+                    end_time=end_time,
+                    machine=machine,
+                    pid=pid
+                )
+                object.__setattr__(final_exc, 'attempts', attempt + 1)
+                return final_exc
+
+
+def retryable(
+    max_retries: int = 3,
+    base_delay: float = 1.0,
+    max_delay: float = 60.0,
+    jitter: bool = True,
+    retry_on_exceptions: Optional[List[Type[Exception]]] = None,
+    retry_on_error_substrings: Optional[List[str]] = None
+):
+    def decorator(cls):
+        cls._retry_config = RetryConfig(
+            max_retries=max_retries,
+            base_delay=base_delay,
+            max_delay=max_delay,
+            jitter=jitter,
+            retry_on_exceptions=retry_on_exceptions,
+            retry_on_error_substrings=retry_on_error_substrings
+        )
+        return cls
+    return decorator

chuk_tool_processor/models/__init__.py

@@ -0,0 +1 @@
+# chuk_tool_processor/models/__init__.py

chuk_tool_processor/models/execution_strategy.py

@@ -0,0 +1,19 @@
+# chuk_tool_processor/execution/execution_strategy.py
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+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.
+    """
+    @abstractmethod
+    async def run(
+        self,
+        calls: List[ToolCall],
+        timeout: Optional[float] = None
+    ) -> List[ToolResult]:
+        pass

chuk_tool_processor/models/tool_call.py

@@ -0,0 +1,7 @@
+# chuk_tool_processor/models/tool_call.py
+from pydantic import BaseModel, Field
+from typing import Any, Dict
+
+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)

chuk_tool_processor/models/tool_result.py

@@ -0,0 +1,49 @@
+# chuk_tool_processor/models/tool_result.py
+import os
+from pydantic import BaseModel, Field, ConfigDict
+from typing import Any, Optional
+from datetime import datetime, timezone
+
+class ToolResult(BaseModel):
+    """
+    Represents the result of executing a tool.
+    Includes timing, host, and process metadata for diagnostics.
+    """
+    # 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"
+    )
+
+    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"
+    )
+    start_time: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.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"
+    )

chuk_tool_processor/plugins/__init__.py

@@ -0,0 +1 @@
+# chuk_tool_processor/plugins/parsers__init__.py