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

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
@@ -430,7 +448,15 @@ class CachingToolExecutor:
 
                 # Use idempotency_key if available, otherwise hash arguments
                 cache_key = call.idempotency_key or self._hash_arguments(call.arguments)
-                cached_val = await self.cache.get(call.tool, cache_key)
+
+                # 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
@@ -481,6 +507,8 @@ 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)
@@ -489,14 +517,15 @@ class CachingToolExecutor:
                     # Use idempotency_key if available, otherwise hash arguments
                     cache_key = call.idempotency_key or self._hash_arguments(call.arguments)
 
-                    # Create task but don't await yet (for concurrent caching)
-                    task = self.cache.set(
-                        call.tool,
-                        cache_key,
-                        result.result,
-                        ttl=ttl,
-                    )
-                    cache_tasks.append(task)
+                    # 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"):

chuk_tool_processor/execution/wrappers/circuit_breaker.py

@@ -28,6 +28,24 @@ from chuk_tool_processor.models.tool_result import ToolResult
 
 logger = get_logger("chuk_tool_processor.execution.wrappers.circuit_breaker")
 
+# Optional observability imports
+try:
+    from chuk_tool_processor.observability.metrics import get_metrics
+    from chuk_tool_processor.observability.tracing import trace_circuit_breaker
+
+    _observability_available = True
+except ImportError:
+    _observability_available = False
+
+    # No-op functions when observability not available
+    def get_metrics():
+        return None
+
+    def trace_circuit_breaker(*_args, **_kwargs):
+        from contextlib import nullcontext
+
+        return nullcontext()
+
 
 # --------------------------------------------------------------------------- #
 # Circuit breaker state
@@ -234,8 +252,14 @@ class CircuitBreakerExecutor:
         for call in calls:
             state = await self._get_state(call.tool)
 
-            # Check if circuit allows execution
-            can_execute = await state.can_execute()
+            # Record circuit breaker state
+            metrics = get_metrics()
+            if metrics:
+                metrics.record_circuit_breaker_state(call.tool, state.state.value)
+
+            # Check if circuit allows execution with tracing
+            with trace_circuit_breaker(call.tool, state.state.value):
+                can_execute = await state.can_execute()
 
             if not can_execute:
                 # Circuit is OPEN - reject immediately
@@ -283,6 +307,9 @@ class CircuitBreakerExecutor:
 
                 if is_error or is_timeout:
                     await state.record_failure()
+                    # Record circuit breaker failure metric
+                    if metrics:
+                        metrics.record_circuit_breaker_failure(call.tool)
                 else:
                     await state.record_success()
 

chuk_tool_processor/execution/wrappers/rate_limiting.py

@@ -25,6 +25,24 @@ from chuk_tool_processor.models.tool_result import ToolResult
 
 logger = get_logger("chuk_tool_processor.execution.wrappers.rate_limiting")
 
+# Optional observability imports
+try:
+    from chuk_tool_processor.observability.metrics import get_metrics
+    from chuk_tool_processor.observability.tracing import trace_rate_limit
+
+    _observability_available = True
+except ImportError:
+    _observability_available = False
+
+    # No-op functions when observability not available
+    def get_metrics():
+        return None
+
+    def trace_rate_limit(*_args, **_kwargs):
+        from contextlib import nullcontext
+
+        return nullcontext()
+
 
 # --------------------------------------------------------------------------- #
 # Core limiter
@@ -220,8 +238,20 @@ class RateLimitedToolExecutor:
             return []
 
         # Block for each call *before* dispatching to the wrapped executor
+        metrics = get_metrics()
+
         for c in calls:
-            await self.limiter.wait(c.tool)
+            # Check limits first for metrics
+            global_limited, tool_limited = await self.limiter.check_limits(c.tool)
+            allowed = not (global_limited or tool_limited)
+
+            # Trace rate limit check
+            with trace_rate_limit(c.tool, allowed):
+                await self.limiter.wait(c.tool)
+
+            # Record metrics
+            if metrics:
+                metrics.record_rate_limit_check(c.tool, allowed)
 
         # Check if the executor has a use_cache parameter
         if hasattr(self.executor, "execute"):

chuk_tool_processor/execution/wrappers/retry.py

@@ -21,6 +21,24 @@ from chuk_tool_processor.models.tool_result import ToolResult
 
 logger = get_logger("chuk_tool_processor.execution.wrappers.retry")
 
+# Optional observability imports
+try:
+    from chuk_tool_processor.observability.metrics import get_metrics
+    from chuk_tool_processor.observability.tracing import trace_retry_attempt
+
+    _observability_available = True
+except ImportError:
+    _observability_available = False
+
+    # No-op functions when observability not available
+    def get_metrics():
+        return None
+
+    def trace_retry_attempt(*_args, **_kwargs):
+        from contextlib import nullcontext
+
+        return nullcontext()
+
 
 # --------------------------------------------------------------------------- #
 # Retry configuration
@@ -177,63 +195,73 @@ class RetryableToolExecutor:
             # Execute one attempt
             # ---------------------------------------------------------------- #
             start_time = datetime.now(UTC)
-            try:
-                kwargs = {"timeout": remaining} if remaining is not None else {}
-                if hasattr(self.executor, "use_cache"):
-                    kwargs["use_cache"] = use_cache
-
-                result = (await self.executor.execute([call], **kwargs))[0]
-                pid = result.pid
-                machine = result.machine
 
-                # Success?
-                if not result.error:
+            # Trace retry attempt
+            with trace_retry_attempt(call.tool, attempt, cfg.max_retries):
+                try:
+                    kwargs = {"timeout": remaining} if remaining is not None else {}
+                    if hasattr(self.executor, "use_cache"):
+                        kwargs["use_cache"] = use_cache
+
+                    result = (await self.executor.execute([call], **kwargs))[0]
+                    pid = result.pid
+                    machine = result.machine
+
+                    # Record retry metrics
+                    metrics = get_metrics()
+                    success = result.error is None
+
+                    if metrics:
+                        metrics.record_retry_attempt(call.tool, attempt, success)
+
+                    # Success?
+                    if success:
+                        result.attempts = attempt + 1
+                        return result
+
+                    # Error: decide on retry
+                    last_error = result.error
+                    if cfg.should_retry(attempt, error_str=result.error):
+                        delay = cfg.get_delay(attempt)
+                        # never overshoot the deadline
+                        if deadline is not None:
+                            delay = min(delay, max(deadline - time.monotonic(), 0))
+                        if delay:
+                            await asyncio.sleep(delay)
+                        attempt += 1
+                        continue
+
+                    # No more retries wanted
+                    result.error = self._wrap_error(last_error, attempt, cfg)
                     result.attempts = attempt + 1
                     return result
 
-                # Error: decide on retry
-                last_error = result.error
-                if cfg.should_retry(attempt, error_str=result.error):
-                    delay = cfg.get_delay(attempt)
-                    # never overshoot the deadline
-                    if deadline is not None:
-                        delay = min(delay, max(deadline - time.monotonic(), 0))
-                    if delay:
-                        await asyncio.sleep(delay)
-                    attempt += 1
-                    continue
-
-                # No more retries wanted
-                result.error = self._wrap_error(last_error, attempt, cfg)
-                result.attempts = attempt + 1
-                return result
-
-            # ---------------------------------------------------------------- #
-            # Exception path
-            # ---------------------------------------------------------------- #
-            except Exception as exc:  # noqa: BLE001
-                err_str = str(exc)
-                last_error = err_str
-                if cfg.should_retry(attempt, error=exc):
-                    delay = cfg.get_delay(attempt)
-                    if deadline is not None:
-                        delay = min(delay, max(deadline - time.monotonic(), 0))
-                    if delay:
-                        await asyncio.sleep(delay)
-                    attempt += 1
-                    continue
-
-                end_time = datetime.now(UTC)
-                return ToolResult(
-                    tool=call.tool,
-                    result=None,
-                    error=self._wrap_error(err_str, attempt, cfg),
-                    start_time=start_time,
-                    end_time=end_time,
-                    machine=machine,
-                    pid=pid,
-                    attempts=attempt + 1,
-                )
+                # ---------------------------------------------------------------- #
+                # Exception path
+                # ---------------------------------------------------------------- #
+                except Exception as exc:  # noqa: BLE001
+                    err_str = str(exc)
+                    last_error = err_str
+                    if cfg.should_retry(attempt, error=exc, error_str=err_str):
+                        delay = cfg.get_delay(attempt)
+                        if deadline is not None:
+                            delay = min(delay, max(deadline - time.monotonic(), 0))
+                        if delay:
+                            await asyncio.sleep(delay)
+                        attempt += 1
+                        continue
+
+                    end_time = datetime.now(UTC)
+                    return ToolResult(
+                        tool=call.tool,
+                        result=None,
+                        error=self._wrap_error(err_str, attempt, cfg),
+                        start_time=start_time,
+                        end_time=end_time,
+                        machine=machine,
+                        pid=pid,
+                        attempts=attempt + 1,
+                    )
 
     # --------------------------------------------------------------------- #
     # Helpers

chuk_tool_processor/mcp/setup_mcp_http_streamable.py

@@ -110,10 +110,17 @@ async def setup_mcp_http_streamable(
 
     # Define OAuth error patterns that should NOT be retried at this level
     # These will be handled by the transport layer's OAuth refresh mechanism
+    # Based on RFC 6750 (Bearer Token Usage) and MCP OAuth spec
     oauth_error_patterns = [
-        "invalid_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",

chuk_tool_processor/mcp/setup_mcp_sse.py

@@ -89,10 +89,17 @@ async def setup_mcp_sse(  # noqa: C901 - long but just a config facade
 
     # Define OAuth error patterns that should NOT be retried at this level
     # These will be handled by the transport layer's OAuth refresh mechanism
+    # Based on RFC 6750 (Bearer Token Usage) and MCP OAuth spec
     oauth_error_patterns = [
-        "invalid_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",

chuk_tool_processor/mcp/transport/http_streamable_transport.py

@@ -519,16 +519,29 @@ class HTTPStreamableTransport(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/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/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",
+]