mirascope 2.0.1__py3-none-any.whl → 2.1.0__py3-none-any.whl

mirascope/ops/_internal/instrumentation/providers/anthropic.py

@@ -0,0 +1,78 @@
+"""OpenTelemetry instrumentation for Anthropic SDK."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
+
+from .base import BaseInstrumentation, ContentCaptureMode
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import TracerProvider
+
+
+class AnthropicInstrumentation(BaseInstrumentation[AnthropicInstrumentor]):
+    """Manages OpenTelemetry instrumentation lifecycle for the Anthropic SDK."""
+
+    def _create_instrumentor(self) -> AnthropicInstrumentor:
+        """Create a new Anthropic instrumentor instance."""
+        return AnthropicInstrumentor()
+
+    def _configure_capture_content(self, capture_content: ContentCaptureMode) -> None:
+        """Configure environment variables for Anthropic content capture."""
+        if capture_content == "enabled":
+            self._set_env_var("TRACELOOP_TRACE_CONTENT", "true")
+        elif capture_content == "disabled":
+            self._set_env_var("TRACELOOP_TRACE_CONTENT", "false")
+
+
+def instrument_anthropic(
+    *,
+    tracer_provider: TracerProvider | None = None,
+    capture_content: ContentCaptureMode = "default",
+) -> None:
+    """Enable OpenTelemetry instrumentation for the Anthropic Python SDK.
+
+    Uses the provided tracer_provider or the global OpenTelemetry tracer provider.
+
+    Args:
+        tracer_provider: Optional tracer provider to use. If not provided,
+            uses the global OpenTelemetry tracer provider.
+        capture_content: Controls whether to capture message content in spans.
+            - "enabled": Capture message content
+            - "disabled": Do not capture message content
+            - "default": Use the library's default behavior
+
+    Example:
+
+        Enable instrumentation with Mirascope Cloud:
+        ```python
+        from mirascope import ops
+
+        ops.configure()
+        ops.instrument_anthropic()
+        ```
+
+        Enable instrumentation with content capture:
+        ```python
+        from mirascope import ops
+
+        ops.configure()
+        ops.instrument_anthropic(capture_content="enabled")
+        ```
+    """
+    AnthropicInstrumentation().instrument(
+        tracer_provider=tracer_provider,
+        capture_content=capture_content,
+    )
+
+
+def uninstrument_anthropic() -> None:
+    """Disable previously configured Anthropic instrumentation."""
+    AnthropicInstrumentation().uninstrument()
+
+
+def is_anthropic_instrumented() -> bool:
+    """Return whether Anthropic instrumentation is currently active."""
+    return AnthropicInstrumentation().is_instrumented

mirascope/ops/_internal/instrumentation/providers/base.py

@@ -0,0 +1,179 @@
+"""Base class for OpenTelemetry SDK instrumentation."""
+
+from __future__ import annotations
+
+import os
+import threading
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Generic, Literal, Protocol, TypeVar
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import TracerProvider
+
+ContentCaptureMode = Literal["enabled", "disabled", "default"]
+
+# OpenTelemetry semantic conventions environment variable
+OTEL_SEMCONV_STABILITY_OPT_IN = "OTEL_SEMCONV_STABILITY_OPT_IN"
+OTEL_SEMCONV_STABILITY_VALUE = "gen_ai_latest_experimental"
+
+
+class Instrumentor(Protocol):
+    """Protocol for OpenTelemetry instrumentors."""
+
+    def instrument(self, *, tracer_provider: TracerProvider | None = None) -> None:
+        """Enable instrumentation."""
+        ...
+
+    def uninstrument(self) -> None:
+        """Disable instrumentation."""
+        ...
+
+
+InstrumentorT = TypeVar("InstrumentorT", bound=Instrumentor)
+
+
+class BaseInstrumentation(ABC, Generic[InstrumentorT]):
+    """Base class for managing OpenTelemetry instrumentation lifecycle.
+
+    This class provides a thread-safe singleton pattern for SDK instrumentation.
+    Subclasses must implement `_create_instrumentor()` and `_configure_capture_content()`.
+
+    Each subclass gets its own `_instance` and `_instance_lock` via `__init_subclass__`,
+    ensuring that different providers can be initialized independently without blocking.
+    """
+
+    _instance: BaseInstrumentation[InstrumentorT] | None = None
+    _instance_lock: threading.Lock
+    _lock: threading.Lock
+    _instrumentor: InstrumentorT | None
+    _original_env: dict[str, str | None]
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        """Initialize subclass with its own singleton instance and lock."""
+        super().__init_subclass__(**kwargs)
+        cls._instance = None
+        cls._instance_lock = threading.Lock()
+
+    def __new__(cls) -> BaseInstrumentation[InstrumentorT]:
+        """Create or return the singleton instance."""
+        if cls._instance is None:
+            with cls._instance_lock:
+                if cls._instance is None:
+                    instance = super().__new__(cls)
+                    instance._lock = threading.Lock()
+                    instance._instrumentor = None
+                    instance._original_env = {}
+                    cls._instance = instance
+        return cls._instance
+
+    @property
+    def is_instrumented(self) -> bool:
+        """Return whether instrumentation is currently active."""
+        return self._instrumentor is not None
+
+    @abstractmethod
+    def _create_instrumentor(self) -> InstrumentorT:
+        """Create and return a new instrumentor instance.
+
+        Returns:
+            A new instance of the SDK-specific instrumentor.
+        """
+        ...
+
+    @abstractmethod
+    def _configure_capture_content(self, capture_content: ContentCaptureMode) -> None:
+        """Configure environment variables for content capture.
+
+        Args:
+            capture_content: The capture content mode to configure.
+        """
+        ...
+
+    def instrument(
+        self,
+        *,
+        tracer_provider: TracerProvider | None = None,
+        capture_content: ContentCaptureMode = "default",
+    ) -> None:
+        """Enable OpenTelemetry instrumentation for the SDK.
+
+        Args:
+            tracer_provider: Optional tracer provider to use. If not provided,
+                uses the global OpenTelemetry tracer provider.
+            capture_content: Controls whether to capture message content in spans.
+        """
+        with self._lock:
+            if self.is_instrumented:
+                return
+
+            self._set_env_var(
+                OTEL_SEMCONV_STABILITY_OPT_IN,
+                OTEL_SEMCONV_STABILITY_VALUE,
+                use_setdefault=True,
+            )
+
+            self._configure_capture_content(capture_content)
+
+            instrumentor = self._create_instrumentor()
+            try:
+                if tracer_provider is not None:
+                    instrumentor.instrument(tracer_provider=tracer_provider)
+                else:
+                    instrumentor.instrument()
+            except Exception:
+                self._restore_env_vars()
+                raise
+
+            self._instrumentor = instrumentor
+
+    def uninstrument(self) -> None:
+        """Disable previously configured instrumentation."""
+        with self._lock:
+            if self._instrumentor is None:
+                return
+
+            self._instrumentor.uninstrument()
+            self._instrumentor = None
+            self._restore_env_vars()
+
+    def _set_env_var(
+        self, key: str, value: str, *, use_setdefault: bool = False
+    ) -> None:
+        """Set an environment variable and track the original value.
+
+        Args:
+            key: The environment variable name.
+            value: The value to set.
+            use_setdefault: If True, only set if not already present.
+        """
+        if key not in self._original_env:
+            self._original_env[key] = os.environ.get(key)
+
+        if use_setdefault:
+            os.environ.setdefault(key, value)
+        else:
+            os.environ[key] = value
+
+    def _restore_env_vars(self) -> None:
+        """Restore all environment variables to their original values."""
+        for key, value in self._original_env.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+        self._original_env.clear()
+
+    @classmethod
+    def reset_for_testing(cls) -> None:
+        """Reset singleton instance for testing.
+
+        This properly cleans up the instrumentor and restores environment variables
+        before resetting the instance.
+        """
+        with cls._instance_lock:
+            if cls._instance is not None:
+                if cls._instance._instrumentor is not None:
+                    cls._instance._instrumentor.uninstrument()
+                    cls._instance._instrumentor = None
+                cls._instance._restore_env_vars()
+            cls._instance = None

mirascope/ops/_internal/instrumentation/providers/google_genai.py

@@ -0,0 +1,85 @@
+"""OpenTelemetry instrumentation for Google GenAI SDK."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from opentelemetry.instrumentation.google_genai import GoogleGenAiSdkInstrumentor
+
+from .base import BaseInstrumentation, ContentCaptureMode
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import TracerProvider
+
+
+class GoogleGenAIInstrumentation(BaseInstrumentation[GoogleGenAiSdkInstrumentor]):
+    """Manages OpenTelemetry instrumentation lifecycle for the Google GenAI SDK."""
+
+    def _create_instrumentor(self) -> GoogleGenAiSdkInstrumentor:
+        """Create a new Google GenAI instrumentor instance."""
+        return GoogleGenAiSdkInstrumentor()
+
+    def _configure_capture_content(self, capture_content: ContentCaptureMode) -> None:
+        """Configure environment variables for Google GenAI content capture."""
+        # Google GenAI uses ContentCapturingMode enum instead of true/false.
+        # Valid values: NO_CONTENT, SPAN_ONLY, EVENT_ONLY, SPAN_AND_EVENT
+        if capture_content == "enabled":
+            self._set_env_var(
+                "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT",
+                "SPAN_AND_EVENT",
+            )
+        elif capture_content == "disabled":
+            self._set_env_var(
+                "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "NO_CONTENT"
+            )
+
+
+def instrument_google_genai(
+    *,
+    tracer_provider: TracerProvider | None = None,
+    capture_content: ContentCaptureMode = "default",
+) -> None:
+    """Enable OpenTelemetry instrumentation for the Google GenAI Python SDK.
+
+    Uses the provided tracer_provider or the global OpenTelemetry tracer provider.
+
+    Args:
+        tracer_provider: Optional tracer provider to use. If not provided,
+            uses the global OpenTelemetry tracer provider.
+        capture_content: Controls whether to capture message content in spans.
+            - "enabled": Capture message content
+            - "disabled": Do not capture message content
+            - "default": Use the library's default behavior
+
+    Example:
+
+        Enable instrumentation with Mirascope Cloud:
+        ```python
+        from mirascope import ops
+
+        ops.configure()
+        ops.instrument_google_genai()
+        ```
+
+        Enable instrumentation with content capture:
+        ```python
+        from mirascope import ops
+
+        ops.configure()
+        ops.instrument_google_genai(capture_content="enabled")
+        ```
+    """
+    GoogleGenAIInstrumentation().instrument(
+        tracer_provider=tracer_provider,
+        capture_content=capture_content,
+    )
+
+
+def uninstrument_google_genai() -> None:
+    """Disable previously configured Google GenAI instrumentation."""
+    GoogleGenAIInstrumentation().uninstrument()
+
+
+def is_google_genai_instrumented() -> bool:
+    """Return whether Google GenAI instrumentation is currently active."""
+    return GoogleGenAIInstrumentation().is_instrumented

mirascope/ops/_internal/instrumentation/providers/openai.py

@@ -0,0 +1,82 @@
+"""OpenTelemetry instrumentation for OpenAI SDK."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
+
+from .base import BaseInstrumentation, ContentCaptureMode
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import TracerProvider
+
+
+class OpenAIInstrumentation(BaseInstrumentation[OpenAIInstrumentor]):
+    """Manages OpenTelemetry instrumentation lifecycle for the OpenAI SDK."""
+
+    def _create_instrumentor(self) -> OpenAIInstrumentor:
+        """Create a new OpenAI instrumentor instance."""
+        return OpenAIInstrumentor()
+
+    def _configure_capture_content(self, capture_content: ContentCaptureMode) -> None:
+        """Configure environment variables for OpenAI content capture."""
+        if capture_content == "enabled":
+            self._set_env_var(
+                "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "true"
+            )
+        elif capture_content == "disabled":
+            self._set_env_var(
+                "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "false"
+            )
+
+
+def instrument_openai(
+    *,
+    tracer_provider: TracerProvider | None = None,
+    capture_content: ContentCaptureMode = "default",
+) -> None:
+    """Enable OpenTelemetry instrumentation for the OpenAI Python SDK.
+
+    Uses the provided tracer_provider or the global OpenTelemetry tracer provider.
+
+    Args:
+        tracer_provider: Optional tracer provider to use. If not provided,
+            uses the global OpenTelemetry tracer provider.
+        capture_content: Controls whether to capture message content in spans.
+            - "enabled": Capture message content
+            - "disabled": Do not capture message content
+            - "default": Use the library's default behavior
+
+    Example:
+
+        Enable instrumentation with Mirascope Cloud:
+        ```python
+        from mirascope import ops
+
+        ops.configure()
+        ops.instrument_openai()
+        ```
+
+        Enable instrumentation with content capture:
+        ```python
+        from mirascope import ops
+
+        ops.configure()
+        ops.instrument_openai(capture_content="enabled")
+        ```
+    """
+    OpenAIInstrumentation().instrument(
+        tracer_provider=tracer_provider,
+        capture_content=capture_content,
+    )
+
+
+def uninstrument_openai() -> None:
+    """Disable previously configured OpenAI instrumentation."""
+    OpenAIInstrumentation().uninstrument()
+
+
+def is_openai_instrumented() -> bool:
+    """Return whether OpenAI instrumentation is currently active."""
+    return OpenAIInstrumentation().is_instrumented

mirascope/ops/_internal/traced_calls.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass, field
 from typing import Any, Generic, TypeVar
 from typing_extensions import TypeIs
 
+from ..._utils import copy_function_metadata
 from ...llm.calls import AsyncCall, AsyncContextCall, Call, ContextCall
 from ...llm.context import Context, DepsT
 from ...llm.formatting import FormattableT
@@ -35,6 +36,7 @@ from .traced_functions import (
     TracedContextFunction,
     TracedFunction,
 )
+from .utils import get_original_fn
 
 CallT = TypeVar(
     "CallT",
@@ -106,6 +108,14 @@ class _BaseTracedCall(Generic[CallT]):
     metadata: dict[str, str] = field(default_factory=dict)
     """Arbitrary key-value pairs for additional metadata."""
 
+    __name__: str = field(init=False, repr=False, default="")
+    """The name of the underlying function (preserved for decorator stacking)."""
+
+    def __post_init__(self) -> None:
+        """Preserve standard function attributes for decorator stacking."""
+        original_fn = get_original_fn(self._call.prompt.fn)
+        copy_function_metadata(self, original_fn)
+
 
 @dataclass(kw_only=True)
 class TracedCall(_BaseTracedCall[Call[P, FormattableT]]):
@@ -153,6 +163,7 @@ class TracedCall(_BaseTracedCall[Call[P, FormattableT]]):
 
     def __post_init__(self) -> None:
         """Initialize TracedFunction wrappers for call and stream methods."""
+        super().__post_init__()
         self.call = TracedFunction(
             fn=self._call.call, tags=self.tags, metadata=self.metadata
         )
@@ -213,6 +224,7 @@ class TracedAsyncCall(_BaseTracedCall[AsyncCall[P, FormattableT]]):
 
     def __post_init__(self) -> None:
         """Initialize AsyncTracedFunction wrappers for call and stream methods."""
+        super().__post_init__()
         self.call = AsyncTracedFunction(
             fn=self._call.call, tags=self.tags, metadata=self.metadata
         )
@@ -276,6 +288,7 @@ class TracedContextCall(_BaseTracedCall[ContextCall[P, DepsT, FormattableT]]):
 
     def __post_init__(self) -> None:
         """Initialize TracedContextFunction wrappers for call and stream methods."""
+        super().__post_init__()
         self.call = TracedContextFunction(
             fn=self._call.call, tags=self.tags, metadata=self.metadata
         )
@@ -344,6 +357,7 @@ class TracedAsyncContextCall(_BaseTracedCall[AsyncContextCall[P, DepsT, Formatta
 
     def __post_init__(self) -> None:
         """Initialize AsyncTracedContextFunction wrappers for call and stream methods."""
+        super().__post_init__()
         self.call = AsyncTracedContextFunction(
             fn=self._call.call, tags=self.tags, metadata=self.metadata
         )

mirascope/ops/_internal/traced_functions.py

@@ -10,6 +10,7 @@ from typing import Any, Generic, Literal, TypeVar
 
 from opentelemetry.util.types import AttributeValue
 
+from ..._utils import copy_function_metadata
 from ...api.client import get_async_client, get_sync_client
 from ...llm.context import Context, DepsT
 from ...llm.responses.root_response import RootResponse
@@ -175,11 +176,15 @@ class _BaseFunction(Generic[P, R, FunctionT], ABC):
     _is_async: bool = field(init=False)
     """Whether the wrapped function is asynchronous."""
 
+    __name__: str = field(init=False, repr=False, default="")
+    """The name of the underlying function (preserved for decorator stacking)."""
+
     def __post_init__(self) -> None:
         """Initialize additional attributes after dataclass init."""
         self._qualified_name = get_qualified_name(self.fn)
         original_fn = get_original_fn(self.fn)
         self._module_name = getattr(original_fn, "__module__", "")
+        copy_function_metadata(self, original_fn)
 
 
 @dataclass(kw_only=True)
@@ -200,7 +205,7 @@ class _BaseTracedFunction(_BaseFunction[P, R, FunctionT]):
                 "mirascope.trace.arg_values": json_dumps(arg_values),
             }
             if self.tags:
-                attributes["mirascope.trace.tags"] = self.tags
+                attributes["mirascope.trace.tags"] = list(self.tags)
             if self.metadata:
                 attributes["mirascope.trace.metadata"] = json_dumps(self.metadata)
             span.set(**attributes)
@@ -314,7 +319,7 @@ class _BaseTracedContextFunction(
                 "mirascope.trace.arg_values": json_dumps(arg_values),
             }
             if self.tags:
-                attributes["mirascope.trace.tags"] = self.tags
+                attributes["mirascope.trace.tags"] = list(self.tags)
             if self.metadata:
                 attributes["mirascope.trace.metadata"] = json_dumps(self.metadata)
             span.set(**attributes)

mirascope/ops/_internal/utils.py

@@ -33,15 +33,23 @@ def _is_call_method(fn: Callable[..., Any]) -> bool:
 
 
 def get_original_fn(fn: Callable[..., Any]) -> Callable[..., Any]:
-    """Get the original function from a Call method or return fn as-is.
+    """Get the original unwrapped function.
 
-    When fn is a bound method of a Call object (e.g., Call.call or Call.stream),
-    returns the original decorated function from prompt.fn. Otherwise returns fn.
+    Follows the __wrapped__ chain set by copy_function_metadata() to find the
+    original function. Falls back to checking for Call methods for bound methods.
     """
+    # Follow __wrapped__ chain if available (set by copy_function_metadata)
+    # In practice, get_original_fn is called with original functions or bound methods,
+    # so this loop is defensive code for edge cases like @functools.wraps chains.
+    while hasattr(fn, "__wrapped__"):
+        fn = fn.__wrapped__  # pyright: ignore[reportFunctionMemberAccess] # pragma: no cover
+
+    # Handle bound methods of Call objects (e.g., Call.call or Call.stream)
     if _is_call_method(fn):
         prompt = fn.__self__.prompt  # pyright: ignore[reportFunctionMemberAccess]
         if hasattr(prompt, "fn"):
-            return prompt.fn
+            return get_original_fn(prompt.fn)
+
     return fn
 
 

mirascope/ops/_internal/versioned_functions.py

@@ -196,7 +196,7 @@ class _BaseVersionedFunction(_BaseTracedFunction[P, R, Any]):
             if self.name:
                 span.set(**{"mirascope.version.name": self.name})
             if self.tags:
-                span.set(**{"mirascope.version.tags": self.tags})
+                span.set(**{"mirascope.version.tags": list(self.tags)})
             if self.metadata:
                 for key, value in self.metadata.items():
                     span.set(**{f"mirascope.version.meta.{key}": value})