chuk-tool-processor 0.7.0__py3-none-any.whl → 0.9__py3-none-any.whl

chuk_tool_processor/core/__init__.py

@@ -1 +1,32 @@
 # chuk_tool_processor/core/__init__.py
+"""Core functionality for the tool processor."""
+
+from chuk_tool_processor.core.exceptions import (
+    ErrorCode,
+    MCPConnectionError,
+    MCPError,
+    MCPTimeoutError,
+    ParserError,
+    ToolCircuitOpenError,
+    ToolExecutionError,
+    ToolNotFoundError,
+    ToolProcessorError,
+    ToolRateLimitedError,
+    ToolTimeoutError,
+    ToolValidationError,
+)
+
+__all__ = [
+    "ErrorCode",
+    "ToolProcessorError",
+    "ToolNotFoundError",
+    "ToolExecutionError",
+    "ToolTimeoutError",
+    "ToolValidationError",
+    "ParserError",
+    "ToolRateLimitedError",
+    "ToolCircuitOpenError",
+    "MCPError",
+    "MCPConnectionError",
+    "MCPTimeoutError",
+]

chuk_tool_processor/core/exceptions.py

@@ -1,51 +1,257 @@
 # chuk_tool_processor/exceptions.py
+from enum import Enum
 from typing import Any
 
 
+class ErrorCode(str, Enum):
+    """Machine-readable error codes for tool processor errors."""
+
+    # Tool registry errors
+    TOOL_NOT_FOUND = "TOOL_NOT_FOUND"
+    TOOL_REGISTRATION_FAILED = "TOOL_REGISTRATION_FAILED"
+
+    # Execution errors
+    TOOL_EXECUTION_FAILED = "TOOL_EXECUTION_FAILED"
+    TOOL_TIMEOUT = "TOOL_TIMEOUT"
+    TOOL_CANCELLED = "TOOL_CANCELLED"
+
+    # Validation errors
+    TOOL_VALIDATION_ERROR = "TOOL_VALIDATION_ERROR"
+    TOOL_ARGUMENT_ERROR = "TOOL_ARGUMENT_ERROR"
+    TOOL_RESULT_ERROR = "TOOL_RESULT_ERROR"
+
+    # Rate limiting and circuit breaker
+    TOOL_RATE_LIMITED = "TOOL_RATE_LIMITED"
+    TOOL_CIRCUIT_OPEN = "TOOL_CIRCUIT_OPEN"
+
+    # Parser errors
+    PARSER_ERROR = "PARSER_ERROR"
+    PARSER_INVALID_FORMAT = "PARSER_INVALID_FORMAT"
+
+    # MCP errors
+    MCP_CONNECTION_FAILED = "MCP_CONNECTION_FAILED"
+    MCP_TRANSPORT_ERROR = "MCP_TRANSPORT_ERROR"
+    MCP_SERVER_ERROR = "MCP_SERVER_ERROR"
+    MCP_TIMEOUT = "MCP_TIMEOUT"
+
+    # System errors
+    RESOURCE_EXHAUSTED = "RESOURCE_EXHAUSTED"
+    CONFIGURATION_ERROR = "CONFIGURATION_ERROR"
+
+
 class ToolProcessorError(Exception):
-    """Base exception for all tool processor errors."""
+    """Base exception for all tool processor errors with machine-readable codes."""
 
-    pass
+    def __init__(
+        self,
+        message: str,
+        code: ErrorCode | None = None,
+        details: dict[str, Any] | None = None,
+        original_error: Exception | None = None,
+    ):
+        super().__init__(message)
+        self.code = code or ErrorCode.TOOL_EXECUTION_FAILED
+        self.details = details or {}
+        self.original_error = original_error
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert exception to a structured dictionary for logging/monitoring."""
+        result = {
+            "error": self.__class__.__name__,
+            "code": self.code.value,
+            "message": str(self),
+            "details": self.details,
+        }
+        if self.original_error:
+            result["original_error"] = {
+                "type": type(self.original_error).__name__,
+                "message": str(self.original_error),
+            }
+        return result
 
 
 class ToolNotFoundError(ToolProcessorError):
     """Raised when a requested tool is not found in the registry."""
 
-    def __init__(self, tool_name: str):
+    def __init__(self, tool_name: str, available_tools: list[str] | None = None):
         self.tool_name = tool_name
-        super().__init__(f"Tool '{tool_name}' not found in registry")
+        details: dict[str, Any] = {"tool_name": tool_name}
+        if available_tools:
+            details["available_tools"] = available_tools
+        super().__init__(
+            f"Tool '{tool_name}' not found in registry",
+            code=ErrorCode.TOOL_NOT_FOUND,
+            details=details,
+        )
 
 
 class ToolExecutionError(ToolProcessorError):
     """Raised when a tool execution fails."""
 
-    def __init__(self, tool_name: str, original_error: Exception | None = None):
+    def __init__(
+        self,
+        tool_name: str,
+        original_error: Exception | None = None,
+        details: dict[str, Any] | None = None,
+    ):
         self.tool_name = tool_name
-        self.original_error = original_error
         message = f"Tool '{tool_name}' execution failed"
         if original_error:
             message += f": {str(original_error)}"
-        super().__init__(message)
+
+        error_details = {"tool_name": tool_name}
+        if details:
+            error_details.update(details)
+
+        super().__init__(
+            message,
+            code=ErrorCode.TOOL_EXECUTION_FAILED,
+            details=error_details,
+            original_error=original_error,
+        )
 
 
 class ToolTimeoutError(ToolExecutionError):
     """Raised when a tool execution times out."""
 
-    def __init__(self, tool_name: str, timeout: float):
+    def __init__(self, tool_name: str, timeout: float, attempts: int = 1):
         self.timeout = timeout
-        super().__init__(tool_name, Exception(f"Execution timed out after {timeout}s"))
+        self.attempts = attempts
+        # Call ToolProcessorError.__init__ directly to set the right code
+        ToolProcessorError.__init__(
+            self,
+            f"Tool '{tool_name}' timed out after {timeout}s (attempts: {attempts})",
+            code=ErrorCode.TOOL_TIMEOUT,
+            details={"tool_name": tool_name, "timeout": timeout, "attempts": attempts},
+        )
+        self.tool_name = tool_name
 
 
 class ToolValidationError(ToolProcessorError):
     """Raised when tool arguments or results fail validation."""
 
-    def __init__(self, tool_name: str, errors: dict[str, Any]):
+    def __init__(
+        self,
+        tool_name: str,
+        errors: dict[str, Any],
+        validation_type: str = "arguments",
+    ):
         self.tool_name = tool_name
         self.errors = errors
-        super().__init__(f"Validation failed for tool '{tool_name}': {errors}")
+        self.validation_type = validation_type
+        super().__init__(
+            f"Validation failed for tool '{tool_name}' {validation_type}: {errors}",
+            code=ErrorCode.TOOL_VALIDATION_ERROR,
+            details={"tool_name": tool_name, "validation_type": validation_type, "errors": errors},
+        )
 
 
 class ParserError(ToolProcessorError):
     """Raised when parsing tool calls from raw input fails."""
 
-    pass
+    def __init__(
+        self,
+        message: str,
+        parser_name: str | None = None,
+        input_sample: str | None = None,
+    ):
+        self.parser_name = parser_name
+        self.input_sample = input_sample
+        details = {}
+        if parser_name:
+            details["parser_name"] = parser_name
+        if input_sample:
+            # Truncate sample for logging
+            details["input_sample"] = input_sample[:200] + "..." if len(input_sample) > 200 else input_sample
+        super().__init__(
+            message,
+            code=ErrorCode.PARSER_ERROR,
+            details=details,
+        )
+
+
+class ToolRateLimitedError(ToolProcessorError):
+    """Raised when a tool call is rate limited."""
+
+    def __init__(
+        self,
+        tool_name: str,
+        retry_after: float | None = None,
+        limit: int | None = None,
+    ):
+        self.tool_name = tool_name
+        self.retry_after = retry_after
+        self.limit = limit
+        message = f"Tool '{tool_name}' rate limited"
+        if retry_after:
+            message += f" (retry after {retry_after}s)"
+        super().__init__(
+            message,
+            code=ErrorCode.TOOL_RATE_LIMITED,
+            details={"tool_name": tool_name, "retry_after": retry_after, "limit": limit},
+        )
+
+
+class ToolCircuitOpenError(ToolProcessorError):
+    """Raised when a tool circuit breaker is open."""
+
+    def __init__(
+        self,
+        tool_name: str,
+        failure_count: int,
+        reset_timeout: float | None = None,
+    ):
+        self.tool_name = tool_name
+        self.failure_count = failure_count
+        self.reset_timeout = reset_timeout
+        message = f"Tool '{tool_name}' circuit breaker is open (failures: {failure_count})"
+        if reset_timeout:
+            message += f" (reset in {reset_timeout}s)"
+        super().__init__(
+            message,
+            code=ErrorCode.TOOL_CIRCUIT_OPEN,
+            details={"tool_name": tool_name, "failure_count": failure_count, "reset_timeout": reset_timeout},
+        )
+
+
+class MCPError(ToolProcessorError):
+    """Base class for MCP-related errors."""
+
+    def __init__(
+        self,
+        message: str,
+        code: ErrorCode,
+        server_name: str | None = None,
+        details: dict[str, Any] | None = None,
+    ):
+        error_details = details or {}
+        if server_name:
+            error_details["server_name"] = server_name
+        super().__init__(message, code=code, details=error_details)
+
+
+class MCPConnectionError(MCPError):
+    """Raised when MCP connection fails."""
+
+    def __init__(self, server_name: str, reason: str | None = None):
+        message = f"Failed to connect to MCP server '{server_name}'"
+        if reason:
+            message += f": {reason}"
+        super().__init__(
+            message,
+            code=ErrorCode.MCP_CONNECTION_FAILED,
+            server_name=server_name,
+            details={"reason": reason} if reason else None,
+        )
+
+
+class MCPTimeoutError(MCPError):
+    """Raised when MCP operation times out."""
+
+    def __init__(self, server_name: str, operation: str, timeout: float):
+        super().__init__(
+            f"MCP operation '{operation}' on server '{server_name}' timed out after {timeout}s",
+            code=ErrorCode.MCP_TIMEOUT,
+            server_name=server_name,
+            details={"operation": operation, "timeout": timeout},
+        )

chuk_tool_processor/core/processor.py

@@ -18,6 +18,10 @@ from typing import Any
 
 from chuk_tool_processor.execution.strategies.inprocess_strategy import InProcessStrategy
 from chuk_tool_processor.execution.wrappers.caching import CachingToolExecutor, InMemoryCache
+from chuk_tool_processor.execution.wrappers.circuit_breaker import (
+    CircuitBreakerConfig,
+    CircuitBreakerExecutor,
+)
 from chuk_tool_processor.execution.wrappers.rate_limiting import RateLimitedToolExecutor, RateLimiter
 from chuk_tool_processor.execution.wrappers.retry import RetryableToolExecutor, RetryConfig
 from chuk_tool_processor.logging import get_logger, log_context_span, log_tool_call, metrics, request_logging
@@ -46,6 +50,10 @@ class ToolProcessor:
         tool_rate_limits: dict[str, tuple] | None = None,
         enable_retries: bool = True,
         max_retries: int = 3,
+        retry_config: RetryConfig | None = None,
+        enable_circuit_breaker: bool = False,
+        circuit_breaker_threshold: int = 5,
+        circuit_breaker_timeout: float = 60.0,
         parser_plugins: list[str] | None = None,
     ):
         """
@@ -63,6 +71,9 @@ class ToolProcessor:
             tool_rate_limits: Dict mapping tool names to (limit, period) tuples.
             enable_retries: Whether to enable automatic retries.
             max_retries: Maximum number of retry attempts.
+            enable_circuit_breaker: Whether to enable circuit breaker pattern.
+            circuit_breaker_threshold: Number of failures before opening circuit.
+            circuit_breaker_timeout: Seconds to wait before testing recovery.
             parser_plugins: List of parser plugin names to use.
                 If None, uses all available parsers.
         """
@@ -80,6 +91,10 @@ class ToolProcessor:
         self.tool_rate_limits = tool_rate_limits
         self.enable_retries = enable_retries
         self.max_retries = max_retries
+        self.retry_config = retry_config
+        self.enable_circuit_breaker = enable_circuit_breaker
+        self.circuit_breaker_threshold = circuit_breaker_threshold
+        self.circuit_breaker_timeout = circuit_breaker_timeout
         self.parser_plugin_names = parser_plugins
 
         # Placeholder for initialized components
@@ -131,11 +146,25 @@ class ToolProcessor:
             executor = self.strategy
 
             # Apply wrappers in reverse order (innermost first)
+            # Circuit breaker goes innermost (closest to actual execution)
+            if self.enable_circuit_breaker:
+                self.logger.debug("Enabling circuit breaker")
+                circuit_config = CircuitBreakerConfig(
+                    failure_threshold=self.circuit_breaker_threshold,
+                    reset_timeout=self.circuit_breaker_timeout,
+                )
+                executor = CircuitBreakerExecutor(
+                    executor=executor,
+                    default_config=circuit_config,
+                )
+
             if self.enable_retries:
                 self.logger.debug("Enabling retry logic")
+                # Use custom retry config if provided, otherwise create default
+                retry_cfg = self.retry_config or RetryConfig(max_retries=self.max_retries)
                 executor = RetryableToolExecutor(
                     executor=executor,
-                    default_config=RetryConfig(max_retries=self.max_retries),
+                    default_config=retry_cfg,
                 )
 
             if self.enable_rate_limiting:

chuk_tool_processor/execution/wrappers/__init__.py

@@ -0,0 +1,42 @@
+# chuk_tool_processor/execution/wrappers/__init__.py
+"""Execution wrappers for adding production features to tool execution."""
+
+from chuk_tool_processor.execution.wrappers.caching import (
+    CacheInterface,
+    CachingToolExecutor,
+    InMemoryCache,
+    cacheable,
+)
+from chuk_tool_processor.execution.wrappers.circuit_breaker import (
+    CircuitBreakerConfig,
+    CircuitBreakerExecutor,
+    CircuitState,
+)
+from chuk_tool_processor.execution.wrappers.rate_limiting import (
+    RateLimitedToolExecutor,
+    RateLimiter,
+)
+from chuk_tool_processor.execution.wrappers.retry import (
+    RetryableToolExecutor,
+    RetryConfig,
+    retryable,
+)
+
+__all__ = [
+    # Caching
+    "CacheInterface",
+    "CachingToolExecutor",
+    "InMemoryCache",
+    "cacheable",
+    # Circuit breaker
+    "CircuitBreakerConfig",
+    "CircuitBreakerExecutor",
+    "CircuitState",
+    # Rate limiting
+    "RateLimitedToolExecutor",
+    "RateLimiter",
+    # Retry
+    "RetryableToolExecutor",
+    "RetryConfig",
+    "retryable",
+]

chuk_tool_processor/execution/wrappers/caching.py

@@ -29,6 +29,24 @@ from chuk_tool_processor.models.tool_result import ToolResult
 
 logger = get_logger("chuk_tool_processor.execution.wrappers.caching")
 
+# Optional observability imports
+try:
+    from chuk_tool_processor.observability.metrics import get_metrics
+    from chuk_tool_processor.observability.tracing import trace_cache_operation
+
+    _observability_available = True
+except ImportError:
+    _observability_available = False
+
+    # No-op functions when observability not available
+    def get_metrics():
+        return None
+
+    def trace_cache_operation(*_args, **_kwargs):
+        from contextlib import nullcontext
+
+        return nullcontext()
+
 
 # --------------------------------------------------------------------------- #
 # Cache primitives
@@ -428,8 +446,17 @@ class CachingToolExecutor:
                     uncached.append((idx, call))
                     continue
 
-                h = self._hash_arguments(call.arguments)
-                cached_val = await self.cache.get(call.tool, h)
+                # Use idempotency_key if available, otherwise hash arguments
+                cache_key = call.idempotency_key or self._hash_arguments(call.arguments)
+
+                # Trace cache lookup operation
+                with trace_cache_operation("lookup", call.tool):
+                    cached_val = await self.cache.get(call.tool, cache_key)
+
+                # Record metrics
+                metrics = get_metrics()
+                if metrics:
+                    metrics.record_cache_operation(call.tool, "lookup", hit=(cached_val is not None))
 
                 if cached_val is None:
                     # Cache miss
@@ -480,19 +507,25 @@ class CachingToolExecutor:
         # ------------------------------------------------------------------
         if use_cache:
             cache_tasks = []
+            metrics = get_metrics()
+
             for (_idx, call), result in zip(uncached, uncached_results, strict=False):
                 if result.error is None and self._is_cacheable(call.tool):
                     ttl = self._ttl_for(call.tool)
                     logger.debug(f"Caching result for {call.tool} with TTL={ttl}s")
 
-                    # Create task but don't await yet (for concurrent caching)
-                    task = self.cache.set(
-                        call.tool,
-                        self._hash_arguments(call.arguments),
-                        result.result,
-                        ttl=ttl,
-                    )
-                    cache_tasks.append(task)
+                    # Use idempotency_key if available, otherwise hash arguments
+                    cache_key = call.idempotency_key or self._hash_arguments(call.arguments)
+
+                    # Trace and record cache set operation
+                    # Bind loop variables to avoid B023 error
+                    async def cache_with_trace(tool=call.tool, key=cache_key, value=result.result, ttl_val=ttl):
+                        with trace_cache_operation("set", tool, attributes={"ttl": ttl_val}):
+                            await self.cache.set(tool, key, value, ttl=ttl_val)
+                        if metrics:
+                            metrics.record_cache_operation(tool, "set")
+
+                    cache_tasks.append(cache_with_trace())
 
                 # Flag as non-cached so callers can tell
                 if hasattr(result, "cached"):