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

chuk_tool_processor/mcp/transport/sse_transport.py

@@ -596,16 +596,29 @@ class SSETransport(MCPBaseTransport):
         self._metrics.update_call_metrics(response_time, success)
 
     def _is_oauth_error(self, error_msg: str) -> bool:
-        """Detect if error is OAuth-related (NEW)."""
+        """
+        Detect if error is OAuth-related per RFC 6750 and MCP OAuth spec.
+
+        Checks for:
+        - RFC 6750 Section 3.1 Bearer token errors (invalid_token, insufficient_scope)
+        - OAuth 2.1 token refresh errors (invalid_grant)
+        - MCP spec OAuth validation failures (401/403 responses)
+        """
         if not error_msg:
             return False
 
         error_lower = error_msg.lower()
         oauth_indicators = [
-            "invalid_token",
-            "expired token",
+            # RFC 6750 Section 3.1 - Standard Bearer token errors
+            "invalid_token",  # Token expired, revoked, malformed, or invalid
+            "insufficient_scope",  # Request requires higher privileges (403 Forbidden)
+            # OAuth 2.1 token refresh errors
+            "invalid_grant",  # Refresh token errors
+            # MCP spec - OAuth validation failures (401 Unauthorized)
             "oauth validation",
             "unauthorized",
+            # Common OAuth error descriptions
+            "expired token",
             "token expired",
             "authentication failed",
             "invalid access token",

chuk_tool_processor/models/__init__.py

@@ -1 +1,21 @@
 # chuk_tool_processor/models/__init__.py
+"""Data models for the tool processor."""
+
+from chuk_tool_processor.models.execution_strategy import ExecutionStrategy
+from chuk_tool_processor.models.streaming_tool import StreamingTool
+from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.models.tool_result import ToolResult
+from chuk_tool_processor.models.tool_spec import ToolCapability, ToolSpec, tool_spec
+from chuk_tool_processor.models.validated_tool import ValidatedTool, with_validation
+
+__all__ = [
+    "ExecutionStrategy",
+    "StreamingTool",
+    "ToolCall",
+    "ToolResult",
+    "ToolSpec",
+    "ToolCapability",
+    "tool_spec",
+    "ValidatedTool",
+    "with_validation",
+]

chuk_tool_processor/models/tool_call.py

@@ -5,10 +5,12 @@ Model representing a tool call with arguments.
 
 from __future__ import annotations
 
+import hashlib
+import json
 import uuid
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 
 class ToolCall(BaseModel):
@@ -20,6 +22,7 @@ class ToolCall(BaseModel):
         tool: Name of the tool to call
         namespace: Namespace the tool belongs to
         arguments: Arguments to pass to the tool
+        idempotency_key: Optional key for deduplicating duplicate calls (auto-generated)
     """
 
     model_config = ConfigDict(extra="ignore")
@@ -28,6 +31,36 @@ class ToolCall(BaseModel):
     tool: str = Field(..., min_length=1, description="Name of the tool to call; must be non-empty")
     namespace: str = Field(default="default", description="Namespace the tool belongs to")
     arguments: dict[str, Any] = Field(default_factory=dict, description="Arguments to pass to the tool")
+    idempotency_key: str | None = Field(
+        None,
+        description="Idempotency key for deduplication. Auto-generated if not provided.",
+    )
+
+    @model_validator(mode="after")
+    def generate_idempotency_key(self) -> ToolCall:
+        """Generate idempotency key if not provided."""
+        if self.idempotency_key is None:
+            self.idempotency_key = self._compute_idempotency_key()
+        return self
+
+    def _compute_idempotency_key(self) -> str:
+        """
+        Compute a stable idempotency key from tool name, namespace, and arguments.
+
+        Uses SHA256 hash of the sorted JSON representation.
+        Returns first 16 characters of the hex digest for brevity.
+        """
+        # Create a stable representation
+        payload = {
+            "tool": self.tool,
+            "namespace": self.namespace,
+            "arguments": self.arguments,
+        }
+        # Sort keys for stability
+        json_str = json.dumps(payload, sort_keys=True, default=str)
+        # Hash it
+        hash_obj = hashlib.sha256(json_str.encode(), usedforsecurity=False)
+        return hash_obj.hexdigest()[:16]  # Use first 16 chars for brevity
 
     async def to_dict(self) -> dict[str, Any]:
         """Convert to a dictionary for serialization."""

chuk_tool_processor/models/tool_export_mixin.py

@@ -1,6 +1,6 @@
 # chuk_tool_processor/models/tool_export_mix_in.py
 
-from typing import Any, Protocol, runtime_checkable
+from typing import Any, Protocol, cast, runtime_checkable
 
 from pydantic import BaseModel
 
@@ -18,7 +18,7 @@ class ToolExportMixin:
     @classmethod
     def to_openai(cls) -> dict[str, Any]:
         assert hasattr(cls, "Arguments"), f"{cls.__name__} must have an Arguments attribute"
-        schema = cls.Arguments.model_json_schema()  # type: ignore[attr-defined]
+        schema = cls.Arguments.model_json_schema()  # noqa: ANN401
         return {
             "type": "function",
             "function": {
@@ -31,13 +31,13 @@ class ToolExportMixin:
     @classmethod
     def to_json_schema(cls) -> dict[str, Any]:
         assert hasattr(cls, "Arguments"), f"{cls.__name__} must have an Arguments attribute"
-        return cls.Arguments.model_json_schema()  # type: ignore[attr-defined, no-any-return]
+        return cast(dict[str, Any], cls.Arguments.model_json_schema())
 
     @classmethod
     def to_xml(cls) -> str:
         """Very small helper so existing XML-based parsers still work."""
         assert hasattr(cls, "Arguments"), f"{cls.__name__} must have an Arguments attribute"
         name = cls.__name__.removesuffix("Tool").lower()
-        params = cls.Arguments.model_json_schema()["properties"]  # type: ignore[attr-defined]
+        params = cls.Arguments.model_json_schema()["properties"]  # noqa: ANN401
         args = ", ".join(params)
         return f'<tool name="{name}" args="{{{args}}}"/>'

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/observability/__init__.py

@@ -0,0 +1,30 @@
+"""
+OpenTelemetry observability integration for chuk-tool-processor.
+
+This module provides drop-in OpenTelemetry tracing and Prometheus metrics
+for tool execution, making it trivial to instrument your tool pipeline.
+
+Example:
+    from chuk_tool_processor.observability import setup_observability
+
+    # Enable both tracing and metrics
+    setup_observability(
+        service_name="my-tool-service",
+        enable_tracing=True,
+        enable_metrics=True,
+        metrics_port=9090
+    )
+"""
+
+from __future__ import annotations
+
+from .metrics import PrometheusMetrics, get_metrics
+from .setup import setup_observability
+from .tracing import get_tracer
+
+__all__ = [
+    "setup_observability",
+    "get_tracer",
+    "get_metrics",
+    "PrometheusMetrics",
+]