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

chuk_tool_processor/observability/tracing.py

@@ -0,0 +1,345 @@
+"""
+OpenTelemetry tracing integration for chuk-tool-processor.
+
+Provides drop-in distributed tracing with standardized span names and attributes.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+from chuk_tool_processor.logging import get_logger
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import Span, Tracer  # type: ignore[import-not-found]
+
+logger = get_logger("chuk_tool_processor.observability.tracing")
+
+# Global tracer instance
+_tracer: Tracer | None = None
+_tracing_enabled = False
+
+
+def init_tracer(service_name: str = "chuk-tool-processor") -> Tracer | NoOpTracer:
+    """
+    Initialize OpenTelemetry tracer with best-practice configuration.
+
+    Args:
+        service_name: Service name for tracing
+
+    Returns:
+        Configured OpenTelemetry tracer or NoOpTracer if initialization fails
+    """
+    global _tracer, _tracing_enabled
+
+    try:
+        from opentelemetry import trace  # type: ignore[import-not-found]
+        from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (  # type: ignore[import-not-found]
+            OTLPSpanExporter,
+        )
+        from opentelemetry.sdk.resources import Resource  # type: ignore[import-not-found]
+        from opentelemetry.sdk.trace import TracerProvider  # type: ignore[import-not-found]
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor  # type: ignore[import-not-found]
+
+        # Create resource with service name
+        resource = Resource.create({"service.name": service_name})
+
+        # Create tracer provider
+        provider = TracerProvider(resource=resource)
+
+        # Add OTLP exporter (exports to OTEL collector)
+        otlp_exporter = OTLPSpanExporter()
+        provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
+
+        # Set as global tracer provider
+        trace.set_tracer_provider(provider)
+
+        _tracer = trace.get_tracer(__name__)
+        _tracing_enabled = True
+
+        logger.info(f"OpenTelemetry tracing initialized for service: {service_name}")
+        return _tracer
+
+    except ImportError as e:
+        logger.warning(f"OpenTelemetry packages not installed: {e}. Tracing disabled.")
+        _tracing_enabled = False
+        return NoOpTracer()
+
+
+def get_tracer() -> Tracer | NoOpTracer:
+    """
+    Get the current tracer instance.
+
+    Returns:
+        OpenTelemetry tracer or no-op tracer if not initialized
+    """
+    if _tracer is None:
+        return NoOpTracer()
+    return _tracer
+
+
+def is_tracing_enabled() -> bool:
+    """Check if tracing is enabled."""
+    return _tracing_enabled
+
+
+@contextmanager
+def trace_tool_execution(
+    tool: str,
+    namespace: str | None = None,
+    attributes: dict[str, Any] | None = None,
+):
+    """
+    Context manager for tracing tool execution.
+
+    Creates a span with name "tool.execute" and standard attributes.
+
+    Args:
+        tool: Tool name
+        namespace: Optional tool namespace
+        attributes: Additional span attributes
+
+    Example:
+        with trace_tool_execution("calculator", attributes={"operation": "add"}):
+            result = await tool.execute(a=5, b=3)
+    """
+    if not _tracing_enabled or _tracer is None:
+        yield None
+        return
+
+    span_name = "tool.execute"
+    span_attributes: dict[str, str | int | float | bool] = {
+        "tool.name": tool,
+    }
+
+    if namespace:
+        span_attributes["tool.namespace"] = namespace
+
+    if attributes:
+        # Flatten attributes with "tool." prefix
+        for key, value in attributes.items():
+            # Convert value to string for OTEL compatibility
+            if isinstance(value, (str, int, float, bool)):
+                span_attributes[f"tool.{key}"] = value
+            else:
+                span_attributes[f"tool.{key}"] = str(value)
+
+    with _tracer.start_as_current_span(span_name, attributes=span_attributes) as span:
+        yield span
+
+
+@contextmanager
+def trace_cache_operation(
+    operation: str,
+    tool: str,
+    hit: bool | None = None,
+    attributes: dict[str, Any] | None = None,
+):
+    """
+    Context manager for tracing cache operations.
+
+    Args:
+        operation: Cache operation (lookup, set, invalidate)
+        tool: Tool name
+        hit: Whether cache hit (for lookup operations)
+        attributes: Additional span attributes
+
+    Example:
+        with trace_cache_operation("lookup", "calculator", hit=True):
+            result = await cache.get(tool, key)
+    """
+    if not _tracing_enabled or _tracer is None:
+        yield None
+        return
+
+    span_name = f"tool.cache.{operation}"
+    span_attributes: dict[str, str | int | float | bool] = {
+        "tool.name": tool,
+        "cache.operation": operation,
+    }
+
+    if hit is not None:
+        span_attributes["cache.hit"] = hit
+
+    if attributes:
+        for key, value in attributes.items():
+            if isinstance(value, (str, int, float, bool)):
+                span_attributes[f"cache.{key}"] = value
+            else:
+                span_attributes[f"cache.{key}"] = str(value)
+
+    with _tracer.start_as_current_span(span_name, attributes=span_attributes) as span:
+        yield span
+
+
+@contextmanager
+def trace_retry_attempt(
+    tool: str,
+    attempt: int,
+    max_retries: int,
+    attributes: dict[str, Any] | None = None,
+):
+    """
+    Context manager for tracing retry attempts.
+
+    Args:
+        tool: Tool name
+        attempt: Current attempt number (0-indexed)
+        max_retries: Maximum retry attempts
+        attributes: Additional span attributes
+
+    Example:
+        with trace_retry_attempt("api_tool", attempt=1, max_retries=3):
+            result = await executor.execute([call])
+    """
+    if not _tracing_enabled or _tracer is None:
+        yield None
+        return
+
+    span_name = "tool.retry.attempt"
+    span_attributes: dict[str, str | int | float | bool] = {
+        "tool.name": tool,
+        "retry.attempt": attempt,
+        "retry.max_attempts": max_retries,
+    }
+
+    if attributes:
+        for key, value in attributes.items():
+            if isinstance(value, (str, int, float, bool)):
+                span_attributes[f"retry.{key}"] = value
+            else:
+                span_attributes[f"retry.{key}"] = str(value)
+
+    with _tracer.start_as_current_span(span_name, attributes=span_attributes) as span:
+        yield span
+
+
+@contextmanager
+def trace_circuit_breaker(
+    tool: str,
+    state: str,
+    attributes: dict[str, Any] | None = None,
+):
+    """
+    Context manager for tracing circuit breaker operations.
+
+    Args:
+        tool: Tool name
+        state: Circuit breaker state (CLOSED, OPEN, HALF_OPEN)
+        attributes: Additional span attributes
+
+    Example:
+        with trace_circuit_breaker("api_tool", state="OPEN"):
+            can_execute = await breaker.can_execute()
+    """
+    if not _tracing_enabled or _tracer is None:
+        yield None
+        return
+
+    span_name = "tool.circuit_breaker.check"
+    span_attributes: dict[str, str | int | float | bool] = {
+        "tool.name": tool,
+        "circuit.state": state,
+    }
+
+    if attributes:
+        for key, value in attributes.items():
+            if isinstance(value, (str, int, float, bool)):
+                span_attributes[f"circuit.{key}"] = value
+            else:
+                span_attributes[f"circuit.{key}"] = str(value)
+
+    with _tracer.start_as_current_span(span_name, attributes=span_attributes) as span:
+        yield span
+
+
+@contextmanager
+def trace_rate_limit(
+    tool: str,
+    allowed: bool,
+    attributes: dict[str, Any] | None = None,
+):
+    """
+    Context manager for tracing rate limiting.
+
+    Args:
+        tool: Tool name
+        allowed: Whether request was allowed
+        attributes: Additional span attributes
+
+    Example:
+        with trace_rate_limit("api_tool", allowed=True):
+            await rate_limiter.acquire()
+    """
+    if not _tracing_enabled or _tracer is None:
+        yield None
+        return
+
+    span_name = "tool.rate_limit.check"
+    span_attributes: dict[str, str | int | float | bool] = {
+        "tool.name": tool,
+        "rate_limit.allowed": allowed,
+    }
+
+    if attributes:
+        for key, value in attributes.items():
+            if isinstance(value, (str, int, float, bool)):
+                span_attributes[f"rate_limit.{key}"] = value
+            else:
+                span_attributes[f"rate_limit.{key}"] = str(value)
+
+    with _tracer.start_as_current_span(span_name, attributes=span_attributes) as span:
+        yield span
+
+
+def add_span_event(span: Span | None, name: str, attributes: dict[str, Any] | None = None) -> None:
+    """
+    Add an event to the current span.
+
+    Args:
+        span: Span to add event to (can be None)
+        name: Event name
+        attributes: Event attributes
+    """
+    if span is None or not _tracing_enabled:
+        return
+
+    try:
+        span.add_event(name, attributes=attributes or {})
+    except Exception as e:
+        logger.debug(f"Error adding span event: {e}")
+
+
+def set_span_error(span: Span | None, error: Exception | str) -> None:
+    """
+    Mark span as error and record exception details.
+
+    Args:
+        span: Span to mark as error (can be None)
+        error: Error to record
+    """
+    if span is None or not _tracing_enabled:
+        return
+
+    try:
+        from opentelemetry.trace import Status, StatusCode
+
+        span.set_status(Status(StatusCode.ERROR, str(error)))
+
+        if isinstance(error, Exception):
+            span.record_exception(error)
+        else:
+            span.add_event("error", {"error.message": str(error)})
+
+    except Exception as e:
+        logger.debug(f"Error setting span error: {e}")
+
+
+class NoOpTracer:
+    """No-op tracer when OpenTelemetry is not available."""
+
+    @contextmanager
+    def start_as_current_span(self, _name: str, **_kwargs):
+        """No-op span context manager."""
+        yield None

chuk_tool_processor/plugins/__init__.py

@@ -1 +1 @@
-# chuk_tool_processor/plugins/parsers__init__.py
+# chuk_tool_processor/plugins/parsers__init__.py

chuk_tool_processor/plugins/discovery.py

@@ -8,10 +8,10 @@ import inspect
 import logging
 import pkgutil
 from types import ModuleType
-from typing import Any, Dict, List, Optional, Set, Type
+from typing import Any
 
-from chuk_tool_processor.plugins.parsers.base import ParserPlugin
 from chuk_tool_processor.models.execution_strategy import ExecutionStrategy
+from chuk_tool_processor.plugins.parsers.base import ParserPlugin
 
 __all__ = [
     "plugin_registry",
@@ -33,7 +33,7 @@ class PluginRegistry:
 
     def __init__(self) -> None:
         # category → {name → object}
-        self._plugins: Dict[str, Dict[str, Any]] = {}
+        self._plugins: dict[str, dict[str, Any]] = {}
 
     # --------------------------------------------------------------------- #
     # Public API
@@ -42,10 +42,10 @@ class PluginRegistry:
         self._plugins.setdefault(category, {})[name] = plugin
         logger.debug("Registered plugin %s.%s", category, name)
 
-    def get_plugin(self, category: str, name: str) -> Optional[Any]:  # noqa: D401
+    def get_plugin(self, category: str, name: str) -> Any | None:  # noqa: D401
         return self._plugins.get(category, {}).get(name)
 
-    def list_plugins(self, category: str | None = None) -> Dict[str, List[str]]:
+    def list_plugins(self, category: str | None = None) -> dict[str, list[str]]:
         if category is not None:
             return {category: sorted(self._plugins.get(category, {}))}
         return {cat: sorted(names) for cat, names in self._plugins.items()}
@@ -70,10 +70,10 @@ class PluginDiscovery:
     # ------------------------------------------------------------------ #
     def __init__(self, registry: PluginRegistry) -> None:
         self._registry = registry
-        self._seen_modules: Set[str] = set()
+        self._seen_modules: set[str] = set()
 
     # ------------------------------------------------------------------ #
-    def discover_plugins(self, package_paths: List[str]) -> None:
+    def discover_plugins(self, package_paths: list[str]) -> None:
         """Import every package in *package_paths* and walk its subtree."""
         for pkg_path in package_paths:
             self._walk(pkg_path)
@@ -113,7 +113,7 @@ class PluginDiscovery:
                 self._maybe_register(attr)
 
     # ------------------------------------------------------------------ #
-    def _maybe_register(self, cls: Type) -> None:
+    def _maybe_register(self, cls: type) -> None:
         """Register *cls* in all matching plugin categories."""
         if inspect.isabstract(cls):
             return
@@ -121,7 +121,7 @@ class PluginDiscovery:
         # ------------------- Parser plugins -------------------------
         if issubclass(cls, ParserPlugin) and cls is not ParserPlugin:
             if not inspect.iscoroutinefunction(getattr(cls, "try_parse", None)):
-                logger.warning("Skipping parser plugin %s: try_parse is not async", cls.__qualname__)
+                logger.debug("Skipping parser plugin %s: try_parse is not async", cls.__qualname__)
             else:
                 try:
                     self._registry.register_plugin("parser", cls.__name__, cls())
@@ -133,7 +133,7 @@ class PluginDiscovery:
             self._registry.register_plugin("execution_strategy", cls.__name__, cls)
 
         # ------------- Explicit @plugin decorator ------------------
-        meta: Optional[dict] = getattr(cls, "_plugin_meta", None)
+        meta: dict | None = getattr(cls, "_plugin_meta", None)
         if meta:
             category = meta.get("category", "unknown")
             name = meta.get("name", cls.__name__)
@@ -178,6 +178,6 @@ def discover_default_plugins() -> None:
     PluginDiscovery(plugin_registry).discover_plugins(["chuk_tool_processor.plugins"])
 
 
-def discover_plugins(package_paths: List[str]) -> None:
+def discover_plugins(package_paths: list[str]) -> None:
     """Discover plugins from arbitrary external *package_paths*."""
     PluginDiscovery(plugin_registry).discover_plugins(package_paths)

chuk_tool_processor/plugins/parsers/__init__.py

@@ -1 +1 @@
-# chuk_tool_processor/plugins/parsers/__init__.py
+# chuk_tool_processor/plugins/parsers/__init__.py

chuk_tool_processor/plugins/parsers/base.py

@@ -4,7 +4,6 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import List
 
 from chuk_tool_processor.models.tool_call import ToolCall
 
@@ -21,6 +20,6 @@ class ParserPlugin(ABC):
     """
 
     @abstractmethod
-    async def try_parse(self, raw: str | object) -> List[ToolCall]:  # noqa: D401
+    async def try_parse(self, raw: str | object) -> list[ToolCall]:  # noqa: D401
         """Attempt to parse *raw* into one or more :class:`ToolCall` objects."""
         ...

chuk_tool_processor/plugins/parsers/function_call_tool.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 
 import json
 import re
-from typing import Any, Dict, List
+from typing import Any
 
 from pydantic import ValidationError
 
@@ -26,8 +26,7 @@ class PluginMeta:
 
     name: str = "function_call"
     description: str = (
-        "Parses a single OpenAI-style `function_call` JSON object (including "
-        "strings that embed such an object)."
+        "Parses a single OpenAI-style `function_call` JSON object (including strings that embed such an object)."
     )
     version: str = "1.0.0"
     author: str = "chuk_tool_processor"
@@ -40,19 +39,25 @@ class FunctionCallPlugin(ParserPlugin):
     # Public API
     # --------------------------------------------------------------------- #
 
-    async def try_parse(self, raw: str | Dict[str, Any]) -> List[ToolCall]:
-        payload: Dict[str, Any] | None
+    async def try_parse(self, raw: Any) -> list[ToolCall]:
+        # Handle non-string, non-dict inputs gracefully
+        if not isinstance(raw, str | dict):
+            return []
+
+        payload: dict[str, Any] | None
 
         # 1️⃣  Primary path ─ whole payload is JSON
         if isinstance(raw, dict):
             payload = raw
-        else:
+        elif isinstance(raw, str):
             try:
                 payload = json.loads(raw)
             except json.JSONDecodeError:
                 payload = None
+        else:
+            return []
 
-        calls: List[ToolCall] = []
+        calls: list[ToolCall] = []
 
         if isinstance(payload, dict):
             calls.extend(self._extract_from_payload(payload))
@@ -72,7 +77,7 @@ class FunctionCallPlugin(ParserPlugin):
     # Helpers
     # ------------------------------------------------------------------ #
 
-    def _extract_from_payload(self, payload: Dict[str, Any]) -> List[ToolCall]:
+    def _extract_from_payload(self, payload: dict[str, Any]) -> list[ToolCall]:
         fc = payload.get("function_call")
         if not isinstance(fc, dict):
             return []

chuk_tool_processor/plugins/parsers/json_tool.py

@@ -4,7 +4,7 @@
 from __future__ import annotations
 
 import json
-from typing import Any, List
+from typing import Any
 
 from pydantic import ValidationError
 
@@ -19,6 +19,7 @@ logger = get_logger(__name__)
 
 class PluginMeta:
     """Optional self-description consumed by the plugin-discovery subsystem."""
+
     name: str = "json_tool_calls"
     description: str = "Parses a JSON object containing a `tool_calls` array."
     version: str = "1.0.0"
@@ -28,7 +29,7 @@ class PluginMeta:
 class JsonToolPlugin(ParserPlugin):
     """Extracts a *list* of :class:`ToolCall` objects from a `tool_calls` array."""
 
-    async def try_parse(self, raw: str | Any) -> List[ToolCall]:  # noqa: D401
+    async def try_parse(self, raw: str | Any) -> list[ToolCall]:  # noqa: D401
         # Decode JSON if we were given a string
         try:
             data = json.loads(raw) if isinstance(raw, str) else raw
@@ -39,7 +40,7 @@ class JsonToolPlugin(ParserPlugin):
         if not isinstance(data, dict):
             return []
 
-        calls: List[ToolCall] = []
+        calls: list[ToolCall] = []
         for entry in data.get("tool_calls", []):
             try:
                 calls.append(ToolCall(**entry))

chuk_tool_processor/plugins/parsers/openai_tool.py

@@ -4,7 +4,7 @@
 from __future__ import annotations
 
 import json
-from typing import Any, List
+from typing import Any
 
 from pydantic import ValidationError
 
@@ -19,6 +19,7 @@ logger = get_logger(__name__)
 
 class PluginMeta:
     """Optional descriptor consumed by the plugin-discovery system."""
+
     name: str = "openai_tool_calls"
     description: str = "Parses Chat-Completions responses containing `tool_calls`."
     version: str = "1.0.0"
@@ -43,7 +44,7 @@ class OpenAIToolPlugin(ParserPlugin):
         }
     """
 
-    async def try_parse(self, raw: str | Any) -> List[ToolCall]:  # noqa: D401
+    async def try_parse(self, raw: str | Any) -> list[ToolCall]:  # noqa: D401
         # ------------------------------------------------------------------ #
         # 1. Decode JSON when the input is a string
         # ------------------------------------------------------------------ #
@@ -59,8 +60,14 @@ class OpenAIToolPlugin(ParserPlugin):
         # ------------------------------------------------------------------ #
         # 2. Build ToolCall objects
         # ------------------------------------------------------------------ #
-        calls: List[ToolCall] = []
-        for entry in data["tool_calls"]:
+        calls: list[ToolCall] = []
+
+        # Ensure tool_calls is a list
+        tool_calls = data.get("tool_calls", [])
+        if not isinstance(tool_calls, list):
+            return []
+
+        for entry in tool_calls:
             fn = entry.get("function", {})
             name = fn.get("name")
             args = fn.get("arguments", {})
@@ -76,9 +83,7 @@ class OpenAIToolPlugin(ParserPlugin):
                 continue
 
             try:
-                calls.append(
-                    ToolCall(tool=name, arguments=args if isinstance(args, dict) else {})
-                )
+                calls.append(ToolCall(tool=name, arguments=args if isinstance(args, dict) else {}))
             except ValidationError:
                 logger.debug(
                     "openai_tool_plugin: validation error while building ToolCall for %s",

chuk_tool_processor/plugins/parsers/xml_tool.py

@@ -17,7 +17,6 @@ from __future__ import annotations
 
 import json
 import re
-from typing import List
 
 from pydantic import ValidationError
 
@@ -32,6 +31,7 @@ logger = get_logger(__name__)
 
 class PluginMeta:
     """Optional descriptor that can be used by the plugin-discovery mechanism."""
+
     name: str = "xml_tool_tag"
     description: str = "Parses <tool …/> XML tags into ToolCall objects."
     version: str = "1.0.0"
@@ -49,11 +49,11 @@ class XmlToolPlugin(ParserPlugin):
     )
 
     # ------------------------------------------------------------------ #
-    async def try_parse(self, raw: str | object) -> List[ToolCall]:  # noqa: D401
+    async def try_parse(self, raw: str | object) -> list[ToolCall]:  # noqa: D401
         if not isinstance(raw, str):
             return []
 
-        calls: List[ToolCall] = []
+        calls: list[ToolCall] = []
 
         for match in self._TAG.finditer(raw):
             name = match.group("tool")
@@ -92,7 +92,7 @@ class XmlToolPlugin(ParserPlugin):
         # 3️⃣ Last resort - naive unescaping of \" → "
         if parsed is None:
             try:
-                parsed = json.loads(raw_args.replace(r"\"", "\""))
+                parsed = json.loads(raw_args.replace(r"\"", '"'))
             except json.JSONDecodeError:
                 parsed = {}