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

chuk_tool_processor/__init__.py

@@ -0,0 +1,114 @@
+"""
+CHUK Tool Processor - Async-native framework for processing LLM tool calls.
+
+This package provides a production-ready framework for:
+- Processing tool calls from various LLM output formats
+- Executing tools with timeouts, retries, and rate limiting
+- Connecting to remote MCP servers
+- Caching results and circuit breaking
+
+Quick Start:
+    >>> import asyncio
+    >>> from chuk_tool_processor import ToolProcessor
+    >>>
+    >>> async def main():
+    ...     async with ToolProcessor() as processor:
+    ...         llm_output = '<tool name="calculator" args=\'{"a": 5, "b": 3}\'/>'
+    ...         results = await processor.process(llm_output)
+    ...         print(results[0].result)
+    >>>
+    >>> asyncio.run(main())
+"""
+
+from typing import TYPE_CHECKING
+
+# Version
+__version__ = "0.9.7"
+
+# Core processor
+from chuk_tool_processor.core.processor import ToolProcessor
+
+# Execution strategies
+from chuk_tool_processor.execution.strategies.inprocess_strategy import InProcessStrategy
+from chuk_tool_processor.execution.strategies.subprocess_strategy import SubprocessStrategy
+from chuk_tool_processor.execution.strategies.subprocess_strategy import SubprocessStrategy as IsolatedStrategy
+
+# MCP setup helpers
+from chuk_tool_processor.mcp import (
+    setup_mcp_http_streamable,
+    setup_mcp_sse,
+    setup_mcp_stdio,
+)
+
+# Stream manager for advanced MCP usage
+from chuk_tool_processor.mcp.stream_manager import StreamManager
+
+# Models (commonly used)
+from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.models.tool_result import ToolResult
+
+# Registry functions
+from chuk_tool_processor.registry import (
+    ToolRegistryProvider,
+    get_default_registry,
+    initialize,
+)
+from chuk_tool_processor.registry.auto_register import register_fn_tool
+
+# Decorators for registering tools
+from chuk_tool_processor.registry.decorators import register_tool
+
+# Type checking imports (not available at runtime)
+if TYPE_CHECKING:
+    # Advanced models for type hints
+    # Execution strategies
+    from chuk_tool_processor.execution.strategies.inprocess_strategy import InProcessStrategy
+    from chuk_tool_processor.execution.strategies.subprocess_strategy import SubprocessStrategy
+
+    # Retry config
+    from chuk_tool_processor.execution.wrappers.retry import RetryConfig
+    from chuk_tool_processor.models.streaming_tool import StreamingTool
+    from chuk_tool_processor.models.tool_spec import ToolSpec
+    from chuk_tool_processor.models.validated_tool import ValidatedTool
+
+    # Registry interface
+    from chuk_tool_processor.registry.interface import ToolRegistryInterface
+
+# Public API
+__all__ = [
+    # Version
+    "__version__",
+    # Core classes
+    "ToolProcessor",
+    "StreamManager",
+    # Models
+    "ToolCall",
+    "ToolResult",
+    # Registry
+    "initialize",
+    "get_default_registry",
+    "ToolRegistryProvider",
+    # Decorators
+    "register_tool",
+    "register_fn_tool",
+    # Execution strategies
+    "InProcessStrategy",
+    "IsolatedStrategy",
+    "SubprocessStrategy",
+    # MCP setup
+    "setup_mcp_stdio",
+    "setup_mcp_sse",
+    "setup_mcp_http_streamable",
+]
+
+# Type checking exports (documentation only)
+if TYPE_CHECKING:
+    __all__ += [
+        "ValidatedTool",
+        "StreamingTool",
+        "ToolSpec",
+        "InProcessStrategy",
+        "SubprocessStrategy",
+        "ToolRegistryInterface",
+        "RetryConfig",
+    ]

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},
+        )