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

chuk_tool_processor/models/tool_spec.py

@@ -0,0 +1,350 @@
+# chuk_tool_processor/models/tool_spec.py
+"""
+Formal tool specification with JSON Schema export, versioning, and capability discovery.
+
+This module provides a unified way to describe tools with their:
+- Input/output schemas (JSON Schema)
+- Versioning information
+- Capabilities (streaming, cancellable, idempotent, etc.)
+- Export to various formats (OpenAI, MCP, Anthropic)
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ToolCapability(str, Enum):
+    """Capabilities that a tool can support."""
+
+    STREAMING = "streaming"  # Tool supports streaming responses
+    CANCELLABLE = "cancellable"  # Tool supports cancellation
+    IDEMPOTENT = "idempotent"  # Tool is safe to retry (same result)
+    CACHEABLE = "cacheable"  # Results can be cached
+    RATE_LIMITED = "rate_limited"  # Tool has rate limits
+    REQUIRES_AUTH = "requires_auth"  # Tool requires authentication
+    LONG_RUNNING = "long_running"  # Tool may take >30s
+    STATEFUL = "stateful"  # Tool maintains state across calls
+
+
+class ToolSpec(BaseModel):
+    """
+    Formal tool specification with JSON Schema export and versioning.
+
+    This provides a complete description of a tool's interface, capabilities,
+    and metadata for discovery and validation.
+    """
+
+    # Core metadata
+    name: str = Field(..., description="Tool name (must be unique within namespace)")
+    version: str = Field(default="1.0.0", description="Semantic version (e.g., '1.2.3')")
+    description: str = Field(..., description="Human-readable description of what the tool does")
+    namespace: str = Field(default="default", description="Namespace for organizing tools")
+
+    # Schema definitions
+    parameters: dict[str, Any] = Field(
+        ...,
+        description="JSON Schema for tool parameters (input)",
+    )
+    returns: dict[str, Any] | None = Field(
+        None,
+        description="JSON Schema for return value (output). None if unstructured.",
+    )
+
+    # Capabilities and metadata
+    capabilities: list[ToolCapability] = Field(
+        default_factory=list,
+        description="List of capabilities this tool supports",
+    )
+    tags: list[str] = Field(
+        default_factory=list,
+        description="Tags for categorization (e.g., ['search', 'web'])",
+    )
+    examples: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Example input/output pairs for documentation",
+    )
+
+    # Optional metadata
+    author: str | None = Field(None, description="Tool author/maintainer")
+    license: str | None = Field(None, description="License (e.g., 'MIT', 'Apache-2.0')")
+    documentation_url: str | None = Field(None, description="Link to full documentation")
+    source_url: str | None = Field(None, description="Link to source code")
+
+    # Execution hints
+    estimated_duration_seconds: float | None = Field(
+        None,
+        description="Typical execution time in seconds (for timeout planning)",
+    )
+    max_retries: int | None = Field(
+        None,
+        description="Maximum recommended retries (None = use default)",
+    )
+
+    # ------------------------------------------------------------------ #
+    # Capability checks
+    # ------------------------------------------------------------------ #
+    def has_capability(self, capability: ToolCapability) -> bool:
+        """Check if tool has a specific capability."""
+        return capability in self.capabilities
+
+    def is_streaming(self) -> bool:
+        """Check if tool supports streaming."""
+        return self.has_capability(ToolCapability.STREAMING)
+
+    def is_idempotent(self) -> bool:
+        """Check if tool is safe to retry."""
+        return self.has_capability(ToolCapability.IDEMPOTENT)
+
+    def is_cacheable(self) -> bool:
+        """Check if results can be cached."""
+        return self.has_capability(ToolCapability.CACHEABLE)
+
+    # ------------------------------------------------------------------ #
+    # Export formats
+    # ------------------------------------------------------------------ #
+    def to_openai(self) -> dict[str, Any]:
+        """
+        Export as OpenAI function calling format.
+
+        Returns:
+            Dict compatible with OpenAI's tools=[...] parameter
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    def to_anthropic(self) -> dict[str, Any]:
+        """
+        Export as Anthropic tool format.
+
+        Returns:
+            Dict compatible with Anthropic's tools parameter
+        """
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.parameters,
+        }
+
+    def to_mcp(self) -> dict[str, Any]:
+        """
+        Export as MCP tool format.
+
+        Returns:
+            Dict compatible with MCP tool schema
+        """
+        result = {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.parameters,
+        }
+
+        # Add optional fields if present
+        if self.returns:
+            result["outputSchema"] = self.returns
+
+        return result
+
+    def to_json_schema(self) -> dict[str, Any]:
+        """
+        Export as pure JSON Schema (parameters only).
+
+        Returns:
+            JSON Schema dict for tool parameters
+        """
+        return self.parameters
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Export complete spec as dict.
+
+        Returns:
+            Full tool specification as dictionary
+        """
+        return self.model_dump(exclude_none=True)
+
+    # ------------------------------------------------------------------ #
+    # Factory methods
+    # ------------------------------------------------------------------ #
+    @classmethod
+    def from_validated_tool(
+        cls,
+        tool_cls: type,
+        name: str | None = None,
+        namespace: str = "default",
+    ) -> ToolSpec:
+        """
+        Create ToolSpec from a ValidatedTool class.
+
+        Args:
+            tool_cls: ValidatedTool subclass
+            name: Override tool name (default: class name)
+            namespace: Tool namespace
+
+        Returns:
+            ToolSpec instance
+        """
+        from chuk_tool_processor.models.validated_tool import ValidatedTool
+
+        if not issubclass(tool_cls, ValidatedTool):
+            raise TypeError(f"{tool_cls.__name__} must be a ValidatedTool subclass")
+
+        # Extract metadata
+        tool_name = name or tool_cls.__name__
+        description = (tool_cls.__doc__ or f"{tool_name} tool").strip()
+
+        # Extract schemas
+        parameters = tool_cls.Arguments.model_json_schema()
+        returns = tool_cls.Result.model_json_schema() if hasattr(tool_cls, "Result") else None
+
+        # Detect capabilities
+        capabilities = []
+
+        # Check if tool is marked cacheable
+        if hasattr(tool_cls, "_cacheable") and tool_cls._cacheable:
+            capabilities.append(ToolCapability.CACHEABLE)
+
+        # Check if idempotent (common pattern: GET-like operations)
+        if "get" in tool_name.lower() or "read" in tool_name.lower():
+            capabilities.append(ToolCapability.IDEMPOTENT)
+
+        # Check if streaming
+        from chuk_tool_processor.models.streaming_tool import StreamingTool
+
+        if issubclass(tool_cls, StreamingTool):
+            capabilities.append(ToolCapability.STREAMING)
+
+        return cls(  # type: ignore[call-arg]
+            name=tool_name,
+            description=description,
+            namespace=namespace,
+            parameters=parameters,
+            returns=returns,
+            capabilities=capabilities,
+        )
+
+    @classmethod
+    def from_function(
+        cls,
+        func: Callable,
+        name: str | None = None,
+        description: str | None = None,
+        namespace: str = "default",
+    ) -> ToolSpec:
+        """
+        Create ToolSpec from a plain function.
+
+        Args:
+            func: Function to wrap
+            name: Tool name (default: function name)
+            description: Tool description (default: function docstring)
+            namespace: Tool namespace
+
+        Returns:
+            ToolSpec instance
+        """
+        # Extract metadata
+        tool_name = name or func.__name__
+        tool_description = description or (func.__doc__ or f"{tool_name} function").strip()
+
+        # Build parameter schema from function signature
+        sig = inspect.signature(func)
+        parameters: dict[str, Any] = {
+            "type": "object",
+            "properties": {},
+            "required": [],
+        }
+
+        for param_name, param in sig.parameters.items():
+            if param_name == "self":
+                continue
+
+            # Build property schema
+            prop: dict[str, Any] = {}
+
+            # Try to infer type from annotation
+            if param.annotation != inspect.Parameter.empty:
+                annotation = param.annotation
+                # Handle basic types
+                if annotation is str:
+                    prop["type"] = "string"
+                elif annotation is int:
+                    prop["type"] = "integer"
+                elif annotation is float:
+                    prop["type"] = "number"
+                elif annotation is bool:
+                    prop["type"] = "boolean"
+                elif annotation is list:
+                    prop["type"] = "array"
+                elif annotation is dict:
+                    prop["type"] = "object"
+
+            # Add to schema
+            parameters["properties"][param_name] = prop
+
+            # Mark as required if no default
+            if param.default == inspect.Parameter.empty:
+                parameters["required"].append(param_name)
+
+        return cls(  # type: ignore[call-arg]
+            name=tool_name,
+            description=tool_description,
+            namespace=namespace,
+            parameters=parameters,
+            returns=None,  # Can't infer return type from plain function
+            capabilities=[],
+        )
+
+
+# ------------------------------------------------------------------ #
+# Convenience decorators
+# ------------------------------------------------------------------ #
+def tool_spec(
+    *,
+    version: str = "1.0.0",
+    capabilities: list[ToolCapability] | None = None,
+    tags: list[str] | None = None,
+    estimated_duration_seconds: float | None = None,
+) -> Callable:
+    """
+    Decorator to attach tool specification metadata to a tool class.
+
+    Example:
+        @tool_spec(
+            version="2.1.0",
+            capabilities=[ToolCapability.CACHEABLE, ToolCapability.IDEMPOTENT],
+            tags=["search", "web"],
+            estimated_duration_seconds=2.0,
+        )
+        class SearchTool(ValidatedTool):
+            ...
+
+    Args:
+        version: Semantic version
+        capabilities: List of capabilities
+        tags: List of tags
+        estimated_duration_seconds: Estimated execution time
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(cls):
+        cls._tool_spec_version = version
+        cls._tool_spec_capabilities = capabilities or []
+        cls._tool_spec_tags = tags or []
+        cls._tool_spec_estimated_duration = estimated_duration_seconds
+        return cls
+
+    return decorator

chuk_tool_processor/models/validated_tool.py

@@ -23,7 +23,7 @@ import inspect
 import json
 from typing import Any, TypeVar
 
-from pydantic import BaseModel, ValidationError
+from pydantic import BaseModel, ConfigDict, ValidationError
 
 from chuk_tool_processor.core.exceptions import ToolValidationError
 
@@ -97,11 +97,31 @@ class ValidatedTool(_ExportMixin, BaseModel):
     # Inner models - override in subclasses
     # ------------------------------------------------------------------ #
     class Arguments(BaseModel):  # noqa: D401 - acts as a namespace
-        """Input model"""
+        """Input model with LLM-friendly coercion defaults."""
+
+        model_config = ConfigDict(
+            # Coerce string numbers to actual numbers
+            coerce_numbers_to_str=False,
+            # Strip whitespace from strings
+            str_strip_whitespace=True,
+            # Validate default values
+            validate_default=True,
+            # Be lenient with extra fields (ignore them)
+            extra="ignore",
+            # Use enum values instead of enum objects
+            use_enum_values=True,
+        )
 
     class Result(BaseModel):  # noqa: D401
         """Output model"""
 
+        model_config = ConfigDict(
+            # Validate default values in results too
+            validate_default=True,
+            # Use enum values in outputs
+            use_enum_values=True,
+        )
+
     # ------------------------------------------------------------------ #
     # Public entry-point called by the processor
     # ------------------------------------------------------------------ #

{chuk_tool_processor-0.7.0.dist-info → chuk_tool_processor-0.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chuk-tool-processor
-Version: 0.7.0
+Version: 0.8
 Summary: Async-native framework for registering, discovering, and executing tools referenced in LLM responses
 Author-email: CHUK Team <chrishayuk@somejunkmailbox.com>
 Maintainer-email: CHUK Team <chrishayuk@somejunkmailbox.com>
@@ -72,12 +72,15 @@ Unlike full-fledged LLM frameworks (LangChain, LlamaIndex, etc.), CHUK Tool Proc
 Research code vs production code is about handling the edges:
 
 - **Timeouts**: Every tool execution has proper timeout handling
-- **Retries**: Automatic retry with exponential backoff
+- **Retries**: Automatic retry with exponential backoff and deadline awareness
 - **Rate Limiting**: Global and per-tool rate limits with sliding windows
-- **Caching**: Intelligent result caching with TTL
-- **Error Handling**: Graceful degradation, never crashes your app
+- **Caching**: Intelligent result caching with TTL and idempotency key support
+- **Circuit Breakers**: Prevent cascading failures with automatic fault detection
+- **Error Handling**: Machine-readable error codes with structured details
 - **Observability**: Structured logging, metrics, request tracing
 - **Safety**: Subprocess isolation for untrusted code
+- **Type Safety**: Pydantic validation with LLM-friendly argument coercion
+- **Tool Discovery**: Formal schema export (OpenAI, Anthropic, MCP formats)
 
 ### It's About Stacks
 
@@ -91,11 +94,13 @@ CHUK Tool Processor uses a **composable stack architecture**:
              │ tool calls
              ▼
 ┌─────────────────────────────────┐
-│   Caching Wrapper               │  ← Cache expensive results
+│   Caching Wrapper               │  ← Cache expensive results (idempotency keys)
 ├─────────────────────────────────┤
 │   Rate Limiting Wrapper         │  ← Prevent API abuse
 ├─────────────────────────────────┤
-│   Retry Wrapper                 │  ← Handle transient failures
+│   Retry Wrapper                 │  ← Handle transient failures (exponential backoff)
+├─────────────────────────────────┤
+│   Circuit Breaker Wrapper       │  ← Prevent cascading failures (CLOSED/OPEN/HALF_OPEN)
 ├─────────────────────────────────┤
 │   Execution Strategy            │  ← How to run tools
 │   • InProcess (fast)            │
@@ -639,6 +644,192 @@ processor = ToolProcessor(
 )
 ```
 
+### Advanced Production Features
+
+Beyond basic configuration, CHUK Tool Processor includes several advanced features for production environments:
+
+#### Circuit Breaker Pattern
+
+Prevent cascading failures by automatically opening circuits for failing tools:
+
+```python
+from chuk_tool_processor.core.processor import ToolProcessor
+
+processor = ToolProcessor(
+    enable_circuit_breaker=True,
+    circuit_breaker_threshold=5,      # Open after 5 failures
+    circuit_breaker_timeout=60.0,     # Try recovery after 60s
+)
+
+# Circuit states: CLOSED → OPEN → HALF_OPEN → CLOSED
+# - CLOSED: Normal operation
+# - OPEN: Blocking requests (too many failures)
+# - HALF_OPEN: Testing recovery with limited requests
+```
+
+**How it works:**
+1. Tool fails repeatedly (hits threshold)
+2. Circuit opens → requests blocked immediately
+3. After timeout, circuit enters HALF_OPEN
+4. If test requests succeed → circuit closes
+5. If test requests fail → back to OPEN
+
+**Benefits:**
+- Prevents wasting resources on failing services
+- Fast-fail for better UX
+- Automatic recovery detection
+
+#### Idempotency Keys
+
+Automatically deduplicate LLM tool calls using SHA256-based keys:
+
+```python
+from chuk_tool_processor.models.tool_call import ToolCall
+
+# Idempotency keys are auto-generated
+call1 = ToolCall(tool="search", arguments={"query": "Python"})
+call2 = ToolCall(tool="search", arguments={"query": "Python"})
+
+# Same arguments = same idempotency key
+assert call1.idempotency_key == call2.idempotency_key
+
+# Used automatically by caching layer
+processor = ToolProcessor(enable_caching=True)
+results1 = await processor.execute([call1])  # Executes
+results2 = await processor.execute([call2])  # Cache hit!
+```
+
+**Benefits:**
+- Prevents duplicate executions from LLM retries
+- Deterministic cache keys
+- No manual key management needed
+
+#### Tool Schema Export
+
+Export tool definitions to multiple formats for LLM prompting:
+
+```python
+from chuk_tool_processor.models.tool_spec import ToolSpec, ToolCapability
+from chuk_tool_processor.models.validated_tool import ValidatedTool
+
+@register_tool(name="weather")
+class WeatherTool(ValidatedTool):
+    """Get current weather for a location."""
+
+    class Arguments(BaseModel):
+        location: str = Field(..., description="City name")
+
+    class Result(BaseModel):
+        temperature: float
+        conditions: str
+
+# Generate tool spec
+spec = ToolSpec.from_validated_tool(WeatherTool)
+
+# Export to different formats
+openai_format = spec.to_openai()       # For OpenAI function calling
+anthropic_format = spec.to_anthropic() # For Claude tools
+mcp_format = spec.to_mcp()             # For MCP servers
+
+# Example OpenAI format:
+# {
+#   "type": "function",
+#   "function": {
+#     "name": "weather",
+#     "description": "Get current weather for a location.",
+#     "parameters": {...}  # JSON Schema
+#   }
+# }
+```
+
+**Use cases:**
+- Generate tool definitions for LLM system prompts
+- Documentation generation
+- API contract validation
+- Cross-platform tool sharing
+
+#### Machine-Readable Error Codes
+
+Structured error handling with error codes for programmatic responses:
+
+```python
+from chuk_tool_processor.core.exceptions import (
+    ErrorCode,
+    ToolNotFoundError,
+    ToolTimeoutError,
+    ToolCircuitOpenError,
+)
+
+try:
+    results = await processor.process(llm_output)
+except ToolNotFoundError as e:
+    if e.code == ErrorCode.TOOL_NOT_FOUND:
+        # Suggest available tools to LLM
+        available = e.details.get("available_tools", [])
+        print(f"Try one of: {available}")
+except ToolTimeoutError as e:
+    if e.code == ErrorCode.TOOL_TIMEOUT:
+        # Inform LLM to use faster alternative
+        timeout = e.details["timeout"]
+        print(f"Tool timed out after {timeout}s")
+except ToolCircuitOpenError as e:
+    if e.code == ErrorCode.TOOL_CIRCUIT_OPEN:
+        # Tell LLM this service is temporarily down
+        reset_time = e.details.get("reset_timeout")
+        print(f"Service unavailable, retry in {reset_time}s")
+
+# All errors include .to_dict() for logging
+error_dict = e.to_dict()
+# {
+#   "error": "ToolCircuitOpenError",
+#   "code": "TOOL_CIRCUIT_OPEN",
+#   "message": "Tool 'api_tool' circuit breaker is open...",
+#   "details": {"tool_name": "api_tool", "failure_count": 5, ...}
+# }
+```
+
+**Available error codes:**
+- `TOOL_NOT_FOUND` - Tool doesn't exist in registry
+- `TOOL_EXECUTION_FAILED` - Tool execution error
+- `TOOL_TIMEOUT` - Tool exceeded timeout
+- `TOOL_CIRCUIT_OPEN` - Circuit breaker is open
+- `TOOL_RATE_LIMITED` - Rate limit exceeded
+- `TOOL_VALIDATION_ERROR` - Argument validation failed
+- `MCP_CONNECTION_FAILED` - MCP server unreachable
+- Plus 11 more for comprehensive error handling
+
+#### LLM-Friendly Argument Coercion
+
+Automatically coerce LLM outputs to correct types:
+
+```python
+from chuk_tool_processor.models.validated_tool import ValidatedTool
+
+class SearchTool(ValidatedTool):
+    class Arguments(BaseModel):
+        query: str
+        limit: int = 10
+        category: str = "all"
+
+    # Pydantic config for LLM outputs:
+    # - str_strip_whitespace=True    → Remove accidental whitespace
+    # - extra="ignore"               → Ignore unknown fields
+    # - use_enum_values=True         → Convert enums to values
+    # - coerce_numbers_to_str=False  → Keep type strictness
+
+# LLM outputs often have quirks:
+llm_output = {
+    "query": "  Python tutorials  ",  # Extra whitespace
+    "limit": "5",                      # String instead of int
+    "unknown_field": "ignored"         # Extra field
+}
+
+# ValidatedTool automatically coerces and validates
+tool = SearchTool()
+result = await tool.execute(**llm_output)
+# ✅ Works! Whitespace stripped, "5" → 5, extra field ignored
+```
+
 ## Advanced Topics
 
 ### Using Subprocess Strategy