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

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-2.0.2.dist-info → mirascope-2.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mirascope
-Version: 2.0.2
+Version: 2.1.0
 Summary: Every frontier LLM. One unified interface.
 Project-URL: Homepage, https://mirascope.com
 Project-URL: Documentation, https://mirascope.com/docs/mirascope/v2
@@ -60,6 +60,9 @@ Requires-Dist: mlx-lm<1,>=0.28.4; extra == 'all'
 Requires-Dist: openai<3,>=2.15.0; extra == 'all'
 Requires-Dist: opentelemetry-api<2,>=1.38.0; extra == 'all'
 Requires-Dist: opentelemetry-exporter-otlp<2,>=1.38.0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-anthropic<1,>=0.50.0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-google-genai<1,>=0.3b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-openai-v2<3,>=2.0b0; extra == 'all'
 Requires-Dist: opentelemetry-instrumentation<1,>=0.59b0; extra == 'all'
 Requires-Dist: opentelemetry-propagator-b3<2,>=1.38.0; extra == 'all'
 Requires-Dist: opentelemetry-propagator-b3>=1.38.0; extra == 'all'
@@ -88,6 +91,9 @@ Provides-Extra: ops
 Requires-Dist: libcst>=1.8.6; extra == 'ops'
 Requires-Dist: opentelemetry-api<2,>=1.38.0; extra == 'ops'
 Requires-Dist: opentelemetry-exporter-otlp<2,>=1.38.0; extra == 'ops'
+Requires-Dist: opentelemetry-instrumentation-anthropic<1,>=0.50.0; extra == 'ops'
+Requires-Dist: opentelemetry-instrumentation-google-genai<1,>=0.3b0; extra == 'ops'
+Requires-Dist: opentelemetry-instrumentation-openai-v2<3,>=2.0b0; extra == 'ops'
 Requires-Dist: opentelemetry-instrumentation<1,>=0.59b0; extra == 'ops'
 Requires-Dist: opentelemetry-propagator-b3<2,>=1.38.0; extra == 'ops'
 Requires-Dist: opentelemetry-propagator-b3>=1.38.0; extra == 'ops'
@@ -97,9 +103,66 @@ Requires-Dist: orjson>=3.11.4; extra == 'ops'
 Requires-Dist: packaging>=25.0; extra == 'ops'
 Description-Content-Type: text/markdown
 
-## Mirascope v2 Python
+# Mirascope Python
 
-This directory contains the Python implementation of Mirascope.
+This directory contains the Python implementation of Mirascope: The LLM Anti-Framework. It's intended as a "Goldilocks API" that affords the fine-grained control you'd get from using raw provider APIs, as well as the type safety and easy ergonomics that are offered by higher-level agent frameworks. Think of Mirascope as the "React" of LLM development, where provider native APIs are HTML/CSS, and the agent frameworks are Angular.
+
+## Documentation 
+
+- [Why use Mirascope?](https://mirascope.com/docs/why)
+- [Mirascope Quickstart](https://mirascope.com/docs/quickstart)
+- [Mirascope Concepts](https://mirascope.com/docs/learn/llm)
+
+## Installation
+
+```bash
+# using uv, with all provider deps
+uv add "mirascope[all]"
+
+# using uv, with just Anthropic
+uv add "mirascope[anthropic]"
+
+# using pip, with all deps 
+pip install "mirascope[all]"
+
+# using pip, just OpenAI
+pip install "mirascope[openai]"
+```
+
+## Usage
+
+Here's an example of creating a simple agent, with tool-calling and streaming, using Mirascope. For many more examples, [read the docs](https://mirascope.com/docs).
+
+```python
+from mirascope import llm
+
+@llm.tool
+def exp(a: float, b: float) -> float:
+   """Compute an exponent"""
+   return a ** b
+
+@llm.tool
+def add(a: float, b: float) -> float:
+   """Add two numbers"""
+   return a + b
+
+model = llm.Model("anthropic/claude-haiku-4-5")
+response = model.stream("What is 42 ** 4 + 37 ** 3?", tools=[exp, add])
+
+while True:
+   for stream in response.streams():
+         if stream.content_type == "text":
+            for delta in stream:
+               print(delta, end="", flush=True)
+         elif stream.content_type == "tool_call":
+            stream.collect()  # consume the stream
+            print(f"\n> Calling {stream.tool_name}({stream.partial_args})")
+   print()
+   if response.tool_calls:
+         response = response.resume(response.execute_tools())
+   else:
+         break
+```
 
 ## Development Setup
 
@@ -107,97 +170,62 @@ This directory contains the Python implementation of Mirascope.
    ```bash
    cp .env.example .env
    # Edit .env with your API keys
+   # Necessary for updating e2e snapshot tests
    ```
 
 2. **Install Dependencies**:
 
    ```bash
+   cd python
    uv sync --all-extras --dev
    ```
 
-3. **Run Tests**:
-   ```bash
-   uv run pytest
-   ```
+## Helpful Commands:
 
-## `ops.span` and Session Tracing
+Here are helpful development commands. All must be run from within the `python` directory.
 
-`mirascope.ops` provides tracing helpers to trace any Python function, not just
-`llm.Model` calls.
+- `uv run pyright .`
 
-1. Install the OTEL extra and set up a tracer provider exactly as shown above.
-   `ops.span` automatically reuses the active provider, so spans from manual
-   instrumentation and GenAI instrumentation end up in the same trace tree.
-2. Use `ops.session` to group related spans and attach metadata:
-   ```python
-   from mirascope import ops
+Run typechecking.
 
-   with ops.session(id="req-42", attributes={"team": "core"}):
-       with ops.span("load-data") as span:
-           span.set(stage="ingest")
-           # expensive work here
-   ```
-3. The span exposes `span_id`/`trace_id`, logging helpers, and graceful no-op
-   behavior when OTEL is not configured. When OTEL is active, session metadata is
-   attached to every span, and additional tools like `ops.trace`/`ops.version`
-   (planned) can build on the same context.
+- `uv run ruff check --fix .`
 
-## `ops.trace` Decorator
+Check ruff linter (fixing issues where possible).
 
-`@ops.trace` adds span instrumentation to any Python callable (including
-`llm.Model` helpers) so you can capture argument/return metadata alongside the
-GenAI spans emitted by `llm.instrument_opentelemetry`.
+- `uv run ruff format .`
 
-```python
-from mirascope import ops
+Run ruff formatter.
 
-@ops.trace(tags=["ingest"])
-def normalize(record: dict[str, str]) -> dict[str, str]:
-    return {k: v.strip() for k, v in record.items()}
+- `uv run pytest`
 
-result = normalize({"foo": " bar "})
-wrapped = normalize.wrapped({"foo": " bar "})
-print(wrapped.span_id, wrapped.trace_id)
-```
+Run all Python unit tests.
 
-- The decorator automatically handles sync/async functions and reuses `ops.span`
-  serialization logic for arguments/results.
-- Combine with `ops.session` to tag spans with contextual metadata, and with
-  `ops.instrument_opentelemetry` to obtain both model-level GenAI spans
-  and method-level spans like `recommend_book.__call__`.
-- For now we focus on Mirascope-layer entry points (e.g., decorated functions or
-  `llm.Model` wrappers) and do not auto-instrument underlying provider SDK calls.
+- `uv run pytest --cov --cov-config=.coverargc --cov-report=term-missing`
 
-## Testing
+Run all Python unit tests, and report code coverage. (We require 100% coverage in CI.)
 
-### VCR Cassettes
+- `uv run pytest --fix`
 
-The project uses [VCR.py](https://vcrpy.readthedocs.io/) to record and replay HTTP interactions with LLM APIs. This allows tests to run quickly and consistently without making actual API calls.
+Run all Python unit tests, and update any changed snapshots.
 
-- **Cassettes Location**: Test cassettes are stored in `tests/llm/clients/*/cassettes/`
-- **Recording Mode**: Tests use `"once"` mode - records new interactions if no cassette exists, replays existing cassettes otherwise
-- **CI/CD**: In CI environments, tests use existing cassettes and never make real API calls
+- `uvx codespell --config ../.codespellrc`
 
-### Inline Snapshots
+Run codespell, identifying many common spelling mistakes.
 
-The project uses [inline-snapshot](https://15r10nk.github.io/inline-snapshot/) to capture expected test outputs directly in the test code.
+## Typechecking
 
-- **Update Snapshots**: Run `uv run pytest --inline-snapshot=fix` to update all snapshots with actual values
-- **Review Changes**: Run `uv run pytest --inline-snapshot=review` to preview what would change
-- **Formatted Output**: Snapshots are automatically formatted with `ruff` for consistency
+We prize type safety, both on the API surface and internally. You can run typechecking via `uv run pyright .` within this `python/` directory. (We're looking into supporting `ty` so as to speed up our typechecking.)
 
-Example:
-```python
-def test_api_response():
-    response = client.call(messages=[user("Hello")])
-    assert response.content == snapshot([Text(text="Hi there!")])
-```
+## Testing
+
+This project makes extensive use of e2e tests, which replay real interactions with various LLM providers to ensure that Mirascope truly works on the providers' APIs. We use [VCR.py](https://vcrpy.readthedocs.io/) and [inline-snapshot](https://15r10nk.github.io/inline-snapshot/) to maintain these e2e tests. For more details, read [tests/e2e/README.md](./tests/e2e/README.md).
+
+If you make changes to Mirascope that require new snapshots, you should manually delete the outdated cassette files, and then run `uv run pytest python/tests/e2e --fix`. Note that doing so requires real API keys in your `.env` file.
+
+We require 100% code coverage in CI. You can get a code coverage report via:
 
-### Recording New Test Interactions
+`uv run pytest --cov --cov-config=.coverargc --cov-report=term-missing`
 
-To record new test interactions:
+## Read More
 
-1. Ensure your API keys are set in `.env`
-2. Delete the relevant cassette file (if updating an existing test)
-3. Run the specific test: `uv run pytest tests/path/to/test.py::test_name`
-4. The cassette will be automatically created/updated
+For more info on contributing, read [the contributing page in our docs](https://mirascope.com/docs/contributing).