mirascope 2.0.0__py3-none-any.whl → 2.0.0a0__py3-none-any.whl

mirascope/ops/_internal/configuration.py

@@ -1,177 +0,0 @@
-"""Configuration utilities for Mirascope ops module initialization and setup."""
-
-from __future__ import annotations
-
-import logging
-from collections.abc import Iterator
-from contextlib import contextmanager
-from typing import TYPE_CHECKING
-
-from opentelemetry import trace as otel_trace
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor
-
-from ...api.client import Mirascope
-from ...api.settings import update_settings
-from .exporters import MirascopeOTLPExporter
-
-if TYPE_CHECKING:
-    from opentelemetry.trace import Tracer
-
-DEFAULT_TRACER_NAME = "mirascope.llm"
-
-logger = logging.getLogger(__name__)
-
-_tracer_provider: TracerProvider | None = None
-_tracer_name: str = DEFAULT_TRACER_NAME
-_tracer_version: str | None = None
-_tracer: Tracer | None = None
-
-
-def _create_mirascope_cloud_provider(
-    api_key: str | None = None, base_url: str | None = None
-) -> TracerProvider:
-    """Create a TracerProvider configured for Mirascope Cloud.
-
-    Args:
-        api_key: Optional API key. If not provided, uses MIRASCOPE_API_KEY env var.
-
-    Returns:
-        Configured TracerProvider with MirascopeOTLPExporter.
-
-    Raises:
-        RuntimeError: If API key is not available.
-    """
-    try:
-        client = Mirascope(api_key=api_key, base_url=base_url)
-    except (ValueError, RuntimeError) as e:
-        raise RuntimeError(
-            "Failed to create Mirascope Cloud client. "
-            "Set MIRASCOPE_API_KEY environment variable or pass api_key parameter."
-        ) from e
-
-    exporter = MirascopeOTLPExporter(client=client)
-    provider = TracerProvider()
-    provider.add_span_processor(BatchSpanProcessor(exporter))
-
-    return provider
-
-
-def configure(
-    *,
-    api_key: str | None = None,
-    base_url: str | None = None,
-    tracer_provider: TracerProvider | None = None,
-    tracer_name: str = DEFAULT_TRACER_NAME,
-    tracer_version: str | None = None,
-) -> None:
-    """Configure the ops module for tracing.
-
-    When called without arguments, automatically configures Mirascope Cloud
-    using the MIRASCOPE_API_KEY environment variable.
-
-    Args:
-        tracer_provider: Optional custom TracerProvider. If provided, this takes
-            precedence over automatic Mirascope Cloud configuration.
-        api_key: Optional Mirascope Cloud API key. If not provided, uses
-            MIRASCOPE_API_KEY environment variable.
-        tracer_name: Tracer name to use when creating a tracer.
-            Defaults to "mirascope.llm".
-        tracer_version: Optional tracer version.
-
-    Raises:
-        RuntimeError: If no tracer_provider is given and Mirascope Cloud
-            cannot be configured (missing API key).
-
-    Example:
-        Simple Mirascope Cloud configuration (recommended):
-        ```python
-        import os
-        os.environ["MIRASCOPE_API_KEY"] = "your-api-key"
-
-        from mirascope import ops
-
-        ops.configure()  # Automatically uses Mirascope Cloud
-        ```
-
-        With explicit API key:
-        ```python
-        from mirascope import ops
-
-        ops.configure(api_key="your-api-key")
-        ```
-
-        With custom tracer provider:
-        ```python
-        from mirascope import ops
-        from opentelemetry.sdk.trace import TracerProvider
-
-        provider = TracerProvider()
-        ops.configure(tracer_provider=provider)
-        ```
-    """
-    global _tracer_provider, _tracer_name, _tracer_version, _tracer
-
-    # Update settings so get_sync_client/get_async_client can use these values
-    if api_key is not None or base_url is not None:
-        update_settings(api_key=api_key, base_url=base_url)
-
-    # If no tracer_provider given, auto-configure Mirascope Cloud
-    if tracer_provider is None:
-        tracer_provider = _create_mirascope_cloud_provider(
-            api_key=api_key, base_url=base_url
-        )
-
-    _tracer_provider = tracer_provider
-    otel_trace.set_tracer_provider(tracer_provider)
-
-    _tracer_name = tracer_name
-    _tracer_version = tracer_version
-
-    _tracer = tracer_provider.get_tracer(_tracer_name, _tracer_version)
-
-
-def set_tracer(tracer: Tracer | None) -> None:
-    """Set the configured tracer instance."""
-    global _tracer
-    _tracer = tracer
-
-
-def get_tracer() -> Tracer | None:
-    """Return the configured tracer instance."""
-    return _tracer
-
-
-@contextmanager
-def tracer_context(tracer: Tracer | None) -> Iterator[Tracer | None]:
-    """Context manager for temporarily setting a tracer.
-
-    Temporarily sets the tracer for the duration of the context and restores
-    the previous tracer when the context exits.
-
-    Args:
-        tracer: The tracer to use within the context.
-
-    Yields:
-        The tracer that was set.
-
-    Example:
-        ```python
-        from mirascope import ops
-        from opentelemetry.sdk.trace import TracerProvider
-
-        provider = TracerProvider()
-        tracer = provider.get_tracer("my-tracer")
-
-        with ops.tracer_context(tracer):
-            # Use the tracer within this context
-            ...
-        # Previous tracer is restored here
-        ```
-    """
-    previous_tracer = get_tracer()
-    set_tracer(tracer)
-    try:
-        yield tracer
-    finally:
-        set_tracer(previous_tracer)

mirascope/ops/_internal/context.py

@@ -1,76 +0,0 @@
-"""Context management utilities for distributed tracing."""
-
-from __future__ import annotations
-
-from collections.abc import Iterator, Mapping
-from contextlib import ExitStack, contextmanager
-from typing import Any
-
-from opentelemetry import context as otel_context
-from opentelemetry.context import Context
-
-from .propagation import extract_context
-from .session import extract_session_id, session
-
-
-@contextmanager
-def propagated_context(
-    *,
-    parent: Context | None = None,
-    extract_from: Mapping[str, Any] | None = None,
-) -> Iterator[None]:
-    """Attach a parent context or extract context from carrier headers.
-
-    This context manager is used to establish trace context continuity,
-    typically on the server side when receiving requests. It either extracts
-    context from incoming headers or attaches a pre-existing context.
-
-    Args:
-        parent: Pre-existing OTEL context to attach. Mutually exclusive with extract_from.
-        extract_from: Dictionary of headers to extract context from (e.g., request.headers).
-            Mutually exclusive with parent.
-
-    Raises:
-        ValueError: If both parent and extract_from are provided, or if neither is provided.
-
-    Example:
-        Server-side context extraction from FastAPI request:
-
-        ```python
-        @app.post("/endpoint")
-        async def endpoint(request: Request):
-            with propagated_context(extract_from=dict(request.headers)):
-                result = process_request()
-            return result
-        ```
-
-        Using a pre-existing context:
-
-        ```python
-        with propagated_context(parent=existing_context):
-            do_work()
-        ```
-    """
-    if parent is not None and extract_from is not None:
-        raise ValueError("Cannot specify both 'parent' and 'extract_from' parameters")
-
-    if parent is None and extract_from is None:
-        raise ValueError("Must specify either 'parent' or 'extract_from' parameter")
-
-    if extract_from is not None:
-        with ExitStack() as stack:
-            session_id = extract_session_id(extract_from)
-            if session_id:
-                stack.enter_context(session(id=session_id))
-
-            extracted_context = extract_context(extract_from)
-            token = otel_context.attach(extracted_context)
-            stack.callback(otel_context.detach, token)
-
-            yield
-    elif parent is not None:
-        token = otel_context.attach(parent)
-        try:
-            yield
-        finally:
-            otel_context.detach(token)

mirascope/ops/_internal/exporters/__init__.py

@@ -1,26 +0,0 @@
-"""Mirascope OpenTelemetry exporters for two-phase telemetry.
-
-This package provides a two-phase export system for OpenTelemetry tracing:
-1. Immediate start event transmission for real-time visibility
-2. Batched end event transmission for efficiency
-"""
-
-from .exporters import MirascopeOTLPExporter
-from .processors import MirascopeSpanProcessor
-from .types import (
-    Link,
-    SpanContextDict,
-    SpanEvent,
-    SpanEventType,
-    Status,
-)
-
-__all__ = [
-    "Link",
-    "MirascopeOTLPExporter",
-    "MirascopeSpanProcessor",
-    "SpanContextDict",
-    "SpanEvent",
-    "SpanEventType",
-    "Status",
-]

mirascope/ops/_internal/exporters/exporters.py

@@ -1,395 +0,0 @@
-"""Exporter implementation for OpenTelemetry exporters.
-
-This module provides the export layer for sending OpenTelemetry span
-events to the Mirascope ingestion endpoint. It wraps the Fern-generated
-Mirascope client to provide the interface needed by OpenTelemetry exporters.
-"""
-
-from __future__ import annotations
-
-import logging
-import time
-from collections.abc import Sequence
-
-from opentelemetry.sdk.trace import ReadableSpan
-from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
-from opentelemetry.util.types import AttributeValue
-
-from ....api._generated.traces.types import (
-    TracesCreateRequestResourceSpansItem,
-    TracesCreateRequestResourceSpansItemResource,
-    TracesCreateRequestResourceSpansItemResourceAttributesItem,
-    TracesCreateRequestResourceSpansItemResourceAttributesItemValue,
-    TracesCreateRequestResourceSpansItemScopeSpansItem,
-    TracesCreateRequestResourceSpansItemScopeSpansItemScope,
-    TracesCreateRequestResourceSpansItemScopeSpansItemSpansItem,
-    TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItem,
-    TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue,
-    TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemStatus,
-)
-from ....api.client import Mirascope
-
-logger = logging.getLogger(__name__)
-
-
-class MirascopeOTLPExporter(SpanExporter):
-    """OTLP/HTTP exporter for completed spans.
-
-    This exporter implements the OpenTelemetry SpanExporter interface
-    for exporting completed spans in OTLP format over HTTP. It's
-    designed to work with BatchSpanProcessor for efficient batching.
-
-    This uses the Fern auto-generated client for sending converted spans.
-
-    Attributes:
-        exporter: Export client for sending events.
-        timeout: Request timeout in seconds.
-    """
-
-    def __init__(
-        self,
-        client: Mirascope,
-        timeout: float = 30.0,
-        max_retry_attempts: int = 3,
-    ) -> None:
-        """Initialize the telemetry exporter.
-
-        Args:
-            client: The Fern-generated Mirascope client instance.
-                In the future, this will accept the enhanced client from
-                mirascope.api.client that provides error handling and caching
-                capabilities.
-            timeout: Request timeout in seconds for telemetry operations.
-            max_retry_attempts: Maximum number of retry attempts for failed exports.
-        """
-        self.client = client
-        self.timeout = timeout
-        self.max_retry_attempts = max_retry_attempts
-        self._shutdown = False
-
-    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
-        """Export a batch of spans to the telemetry endpoint.
-
-        This is the standard OpenTelemetry export interface.
-
-        Args:
-            spans: Sequence of ReadableSpan objects to export.
-
-        Returns:
-            SpanExportResult indicating success or failure.
-        """
-        if self._shutdown:
-            return SpanExportResult.FAILURE
-
-        if not spans:
-            return SpanExportResult.SUCCESS
-
-        exceptions: list[Exception] = []
-        delay = 0.1
-
-        for i in range(self.max_retry_attempts):
-            if i > 0:
-                time.sleep(delay)
-                delay = min(delay * 2, 5.0)
-
-            try:
-                otlp_data = self._convert_spans_to_otlp(spans)
-                response = self.client.traces.create(resource_spans=otlp_data)
-
-                if (
-                    response
-                    and hasattr(response, "partial_success")
-                    and response.partial_success
-                ):
-                    partial_success = response.partial_success
-                    if hasattr(partial_success, "rejected_spans"):
-                        rejected = partial_success.rejected_spans
-                        if rejected is not None and rejected > 0:
-                            return SpanExportResult.FAILURE
-
-                return SpanExportResult.SUCCESS
-
-            except Exception as e:
-                exceptions.append(e)
-                logger.warning(
-                    f"Export attempt {i + 1} failed, retrying in {delay}s: {e}"
-                )
-
-        logger.error(
-            f"Failed to export spans after {self.max_retry_attempts} attempts: {exceptions}"
-        )
-
-        return SpanExportResult.FAILURE
-
-    def _convert_spans_to_otlp(
-        self, spans: Sequence[ReadableSpan]
-    ) -> list[TracesCreateRequestResourceSpansItem]:
-        """Convert OpenTelemetry spans to OTLP format.
-
-        Args:
-            spans: Sequence of ReadableSpan objects.
-
-        Returns:
-            List of ResourceSpans in OTLP format.
-        """
-        resource_spans_map = {}
-
-        for span in spans:
-            try:
-                otlp_span = self._convert_span(span)
-            except ValueError as e:
-                logger.warning(f"Skipping span due to error: {e}")
-                continue
-
-            resource_key = id(span.resource) if span.resource else "default"
-
-            if resource_key not in resource_spans_map:
-                resource = None
-                if span.resource:
-                    resource_attrs = []
-                    for key, value in span.resource.attributes.items():
-                        attr_value = self._convert_resource_attribute_value(value)
-                        resource_attrs.append(
-                            TracesCreateRequestResourceSpansItemResourceAttributesItem(
-                                key=key,
-                                value=attr_value,
-                            )
-                        )
-                    resource = TracesCreateRequestResourceSpansItemResource(
-                        attributes=resource_attrs
-                    )
-
-                resource_spans_map[resource_key] = {
-                    "resource": resource,
-                    "scope_spans": {},
-                }
-
-            scope_key = (
-                span.instrumentation_scope.name
-                if span.instrumentation_scope
-                else "unknown"
-            )
-
-            if scope_key not in resource_spans_map[resource_key]["scope_spans"]:
-                scope = None
-                if span.instrumentation_scope:
-                    scope = TracesCreateRequestResourceSpansItemScopeSpansItemScope(
-                        name=span.instrumentation_scope.name,
-                        version=span.instrumentation_scope.version,
-                    )
-
-                resource_spans_map[resource_key]["scope_spans"][scope_key] = {
-                    "scope": scope,
-                    "spans": [],
-                }
-
-            resource_spans_map[resource_key]["scope_spans"][scope_key]["spans"].append(
-                otlp_span
-            )
-
-        result = []
-        for resource_data in resource_spans_map.values():
-            scope_spans = []
-            for scope_data in resource_data["scope_spans"].values():
-                scope_spans.append(
-                    TracesCreateRequestResourceSpansItemScopeSpansItem(
-                        scope=scope_data["scope"],
-                        spans=scope_data["spans"],
-                    )
-                )
-
-            result.append(
-                TracesCreateRequestResourceSpansItem(
-                    resource=resource_data["resource"],
-                    scope_spans=scope_spans,
-                )
-            )
-
-        return result
-
-    def _convert_span(
-        self, span: ReadableSpan
-    ) -> TracesCreateRequestResourceSpansItemScopeSpansItemSpansItem:
-        """Convert a single ReadableSpan to OTLP format."""
-        context = span.get_span_context()
-        if not context or not context.is_valid:
-            raise ValueError(f"Cannot export span without valid context: {span.name}")
-
-        attributes = []
-        if span.attributes:
-            for key, value in span.attributes.items():
-                attr_value = self._convert_attribute_value(value)
-                attributes.append(
-                    TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItem(
-                        key=key,
-                        value=attr_value,
-                    )
-                )
-
-        status = None
-        if span.status:
-            status = TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemStatus(
-                code=span.status.status_code.value,
-                message=span.status.description or "",
-            )
-
-        # Convert events
-        events = None
-        if span.events:
-            events = []
-            for event in span.events:
-                event_attrs: list[dict[str, object]] = []
-                if event.attributes:
-                    for key, value in event.attributes.items():
-                        # Convert to OTLP attribute format with typed values
-                        attr_value = self._convert_event_attribute_value(value)
-                        event_attrs.append({"key": key, "value": attr_value})
-                events.append(
-                    {
-                        "name": event.name,
-                        "timeUnixNano": str(event.timestamp)
-                        if event.timestamp
-                        else None,
-                        "attributes": event_attrs if event_attrs else None,
-                    }
-                )
-
-        trace_id = format(context.trace_id, "032x")
-        span_id = format(context.span_id, "016x")
-
-        # Build kwargs, only including events if present (to avoid sending null)
-        kwargs: dict[str, object] = {
-            "trace_id": trace_id,
-            "span_id": span_id,
-            "parent_span_id": (
-                format(span.parent.span_id, "016x")
-                if span.parent and span.parent.span_id
-                else None
-            ),
-            "name": span.name,
-            "kind": span.kind.value if span.kind else 0,
-            "start_time_unix_nano": str(span.start_time) if span.start_time else "0",
-            "end_time_unix_nano": str(span.end_time) if span.end_time else "0",
-            "attributes": attributes or None,
-            "status": status,
-        }
-        # Only include events if present (omit entirely to avoid sending null)
-        if events:
-            kwargs["events"] = events
-
-        return TracesCreateRequestResourceSpansItemScopeSpansItemSpansItem(**kwargs)  # type: ignore[arg-type]
-
-    def _convert_attribute_value(
-        self, value: AttributeValue
-    ) -> TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue:
-        """Convert OpenTelemetry AttributeValue to Mirascope API's KeyValueValue.
-
-        This conversion is necessary because the Fern-generated API client
-        expects KeyValueValue objects, not OpenTelemetry's AttributeValue types.
-
-        Args:
-            value: An OpenTelemetry AttributeValue (bool, int, float, str, or Sequence)
-
-        Returns:
-            A KeyValueValue object for the Mirascope API
-        """
-        match value:
-            case str():
-                return TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue(
-                    string_value=value
-                )
-            case bool():
-                return TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue(
-                    bool_value=value
-                )
-            case int():
-                return TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue(
-                    int_value=str(value)
-                )
-            case float():
-                return TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue(
-                    double_value=value
-                )
-            case _:
-                return TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue(
-                    string_value=str(list(value))
-                )
-
-    def _convert_event_attribute_value(
-        self, value: AttributeValue
-    ) -> dict[str, object]:
-        """Convert OpenTelemetry AttributeValue to OTLP event attribute value format.
-
-        This uses the OTLP JSON format with typed value wrappers (e.g., stringValue, intValue).
-
-        Args:
-            value: An OpenTelemetry AttributeValue (bool, int, float, str, or Sequence)
-
-        Returns:
-            A dict with the typed value (e.g., {"stringValue": "..."})
-        """
-        match value:
-            case str():
-                return {"stringValue": value}
-            case bool():
-                return {"boolValue": value}
-            case int():
-                return {"intValue": str(value)}
-            case float():
-                return {"doubleValue": value}
-            case _:
-                # Sequences - convert to string representation
-                return {"stringValue": str(list(value))}
-
-    def _convert_resource_attribute_value(
-        self, value: AttributeValue
-    ) -> TracesCreateRequestResourceSpansItemResourceAttributesItemValue:
-        """Convert OpenTelemetry AttributeValue to Mirascope API's resource KeyValueValue.
-
-        This conversion is necessary because the Fern-generated API client
-        expects KeyValueValue objects, not OpenTelemetry's AttributeValue types.
-
-        Args:
-            value: An OpenTelemetry AttributeValue (bool, int, float, str, or Sequence)
-
-        Returns:
-            A KeyValueValue object for the Mirascope API resource attributes
-        """
-        match value:
-            case str():
-                return TracesCreateRequestResourceSpansItemResourceAttributesItemValue(
-                    string_value=value
-                )
-            case bool():
-                return TracesCreateRequestResourceSpansItemResourceAttributesItemValue(
-                    bool_value=value
-                )
-            case int():
-                return TracesCreateRequestResourceSpansItemResourceAttributesItemValue(
-                    int_value=str(value)
-                )
-            case float():
-                return TracesCreateRequestResourceSpansItemResourceAttributesItemValue(
-                    double_value=value
-                )
-            case _:
-                return TracesCreateRequestResourceSpansItemResourceAttributesItemValue(
-                    string_value=str(list(value))
-                )
-
-    def shutdown(self) -> None:
-        """Shutdown the exporter. Subsequent exports will return FAILURE."""
-        self._shutdown = True
-
-    def force_flush(self, timeout_millis: int = 30000) -> bool:
-        """Force flush any pending data.
-
-        No-op since this exporter does not buffer data internally.
-
-        Args:
-            timeout_millis: Maximum time to wait in milliseconds (unused).
-
-        Returns:
-            Always True since there is no internal buffer to flush.
-        """
-        return True