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

chuk_tool_processor/core/__init__.py

@@ -1 +1,32 @@
-# chuk_tool_processor/core/__init__.py
+# 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,45 +1,257 @@
 # chuk_tool_processor/exceptions.py
-from typing import Optional, Any, Dict
+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."""
-    pass
+    """Base exception for all tool processor errors with machine-readable codes."""
+
+    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: Optional[Exception] = 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},
+        )