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

mirascope/ops/_internal/exporters/processors.py

@@ -1,104 +0,0 @@
-"""Span processors for two-phase export system.
-
-This module implements a custom SpanProcessor that sends immediate
-start events and batches end events for efficient export.
-"""
-
-from concurrent.futures import ThreadPoolExecutor
-
-from opentelemetry.context import Context
-from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor
-from opentelemetry.sdk.trace.export import BatchSpanProcessor
-
-from .exporters import MirascopeOTLPExporter
-
-
-class MirascopeSpanProcessor(SpanProcessor):
-    """Two-phase span processor for Mirascope telemetry.
-
-    This processor implements a two-phase export strategy:
-    1. Immediate transmission of minimal start events for real-time visibility
-    2. Batched transmission of complete events for efficiency
-
-    The processor uses a thread pool to ensure start events don't block
-    the application while maintaining compatibility with OpenTelemetry's
-    synchronous SDK.
-
-    Attributes:
-        start_exporter: Exporter for immediate start events.
-        batch_processor: Standard batch processor for completed spans.
-        executor: Thread pool for non-blocking start event transmission.
-    """
-
-    def __init__(
-        self,
-        otlp_exporter: MirascopeOTLPExporter,
-        batch_processor: BatchSpanProcessor | None = None,
-        executor: ThreadPoolExecutor | None = None,
-    ) -> None:
-        """Initialize the two-phase processor.
-
-        Args:
-            start_exporter: Exporter for immediate start events.
-            batch_processor: Optional batch processor for end events.
-            executor: Optional thread pool executor (creates default if None).
-        """
-        self.otlp_exporter = otlp_exporter
-        self.batch_processor = batch_processor
-        self.executor = executor or ThreadPoolExecutor(
-            max_workers=2, thread_name_prefix="mirascope-span-processor"
-        )
-        self._shutdown = False
-
-    def on_start(
-        self, span: ReadableSpan, parent_context: Context | None = None
-    ) -> None:
-        """Handle span start by sending immediate start event.
-
-        This method extracts minimal span data and sends it immediately
-        via the start exporter in a non-blocking manner.
-
-        Args:
-            span: The span that just started.
-            parent_context: Optional parent context for the span.
-        """
-        if self._shutdown:
-            return
-
-        self.executor.submit(self.otlp_exporter.export, [span])
-
-    def on_end(self, span: ReadableSpan) -> None:
-        """Handle span end by delegating to batch processor.
-
-        Args:
-            span: The span that just ended.
-        """
-        if self.batch_processor and not self._shutdown:
-            self.batch_processor.on_end(span)
-
-    def shutdown(self) -> None:
-        """Gracefully shutdown the processor.
-
-        This ensures all pending start events are sent and the
-        batch processor is properly shutdown.
-        """
-        self._shutdown = True
-
-        if self.batch_processor:
-            self.batch_processor.shutdown()
-
-        self.executor.shutdown(wait=True)
-        self.otlp_exporter.shutdown()
-
-    def force_flush(self, timeout_millis: int = 30000) -> bool:
-        """Force flush all pending data.
-
-        Args:
-            timeout_millis: Maximum time to wait in milliseconds.
-
-        Returns:
-            True if flush completed successfully.
-        """
-        if self.batch_processor:
-            return self.batch_processor.force_flush(timeout_millis)
-        return True

mirascope/ops/_internal/exporters/types.py

@@ -1,165 +0,0 @@
-"""Type definitions for the two-phase export system.
-
-This module defines the event types and data structures used for
-immediate start event transmission and batched end event export.
-"""
-
-from enum import Enum
-from typing import Literal, TypedDict
-
-from opentelemetry.util.types import AttributeValue
-
-# TODO: unify/DRY types in the _internal package
-
-SpanKind = Literal["CLIENT", "SERVER", "PRODUCER", "CONSUMER", "INTERNAL"]
-StatusCode = Literal["UNSET", "OK", "ERROR"]
-
-
-class SpanEventType(str, Enum):
-    """Event types for span lifecycle tracking."""
-
-    SPAN_STARTED = "span_started"
-    SPAN_UPDATED = "span_updated"
-    SPAN_COMPLETED = "span_completed"
-
-
-class SpanEvent(TypedDict):
-    """Individual event within a span."""
-
-    name: str
-    """The name of the event."""
-
-    timestamp: int
-    """Nanoseconds since epoch (OTel standard)."""
-
-    attributes: dict[str, AttributeValue]
-    """Event-specific attributes."""
-
-
-class Status(TypedDict):
-    """Status representation for serialization."""
-
-    code: StatusCode
-    """The status code: UNSET, OK, or ERROR."""
-
-    description: str | None
-    """Optional human-readable description of the status."""
-
-
-class SpanContextDict(TypedDict):
-    """Span context for links and parent references."""
-
-    trace_id: str
-    """The trace ID as a 32-character hex string."""
-
-    span_id: str
-    """The span ID as a 16-character hex string."""
-
-    trace_flags: int
-    """Trace flags (e.g., for sampling decisions)."""
-
-    trace_state: str | None
-    """Optional vendor-specific trace state."""
-
-
-class Link(TypedDict):
-    """Link representation for span relationships."""
-
-    context: SpanContextDict
-    """The linked span's context."""
-
-    attributes: dict[str, AttributeValue]
-    """Attributes describing the link."""
-
-
-class SpanStartEvent(TypedDict):
-    """Minimal span data for immediate transmission.
-
-    This event is sent immediately when a span starts to provide
-    real-time visibility into long-running operations.
-    """
-
-    trace_id: str
-    """The trace ID as a 32-character hex string."""
-
-    span_id: str
-    """The span ID as a 16-character hex string."""
-
-    parent_span_id: str | None
-    """The parent span ID if this is a child span."""
-
-    name: str
-    """The name of the span."""
-
-    start_time: int
-    """Nanoseconds since epoch."""
-
-    kind: SpanKind
-    """The span kind: CLIENT, SERVER, PRODUCER, CONSUMER, or INTERNAL."""
-
-    attributes: dict[str, AttributeValue]
-    """Minimal required attributes only."""
-
-
-class SpanUpdateEvent(TypedDict, total=False):
-    """Incremental updates to span data.
-
-    These events are batched and sent periodically to update
-    span attributes or add events without waiting for completion.
-    """
-
-    trace_id: str
-    """The trace ID as a 32-character hex string."""
-
-    span_id: str
-    """The span ID as a 16-character hex string."""
-
-    timestamp: int
-    """Nanoseconds since epoch."""
-
-    attributes: dict[str, AttributeValue]
-    """Additional or updated attributes."""
-
-    events: list[SpanEvent]
-    """New events to add to the span."""
-
-
-class SpanCompleteEvent(TypedDict):
-    """Complete span data for batch export.
-
-    This event contains all span data and is sent when the span
-    completes, typically in batches for efficiency.
-    """
-
-    trace_id: str
-    """The trace ID as a 32-character hex string."""
-
-    span_id: str
-    """The span ID as a 16-character hex string."""
-
-    parent_span_id: str | None
-    """The parent span ID if this is a child span."""
-
-    name: str
-    """The name of the span."""
-
-    kind: SpanKind
-    """The span kind: CLIENT, SERVER, PRODUCER, CONSUMER, or INTERNAL."""
-
-    start_time: int
-    """Nanoseconds since epoch."""
-
-    end_time: int
-    """Nanoseconds since epoch."""
-
-    status: Status
-    """The final status of the span."""
-
-    attributes: dict[str, AttributeValue]
-    """All span attributes."""
-
-    events: list[SpanEvent]
-    """All events that occurred during the span."""
-
-    links: list[Link]
-    """Links to other spans."""

mirascope/ops/_internal/exporters/utils.py

@@ -1,29 +0,0 @@
-"""Utility functions for OpenTelemetry exporters.
-
-This module provides helper functions for formatting and converting
-OpenTelemetry data types for export.
-"""
-
-
-def format_trace_id(trace_id: int) -> str:
-    """Format a trace ID as a 32-character hex string.
-
-    Args:
-        trace_id: The trace ID as an integer.
-
-    Returns:
-        32-character hexadecimal string representation of the trace ID.
-    """
-    return format(trace_id, "032x")
-
-
-def format_span_id(span_id: int) -> str:
-    """Format a span ID as a 16-character hex string.
-
-    Args:
-        span_id: The span ID as an integer.
-
-    Returns:
-        16-character hexadecimal string representation of the span ID.
-    """
-    return format(span_id, "016x")

mirascope/ops/_internal/instrumentation/__init__.py

@@ -1,8 +0,0 @@
-"""Instrumentation modules for various frameworks and libraries."""
-
-from .llm import instrument_llm, uninstrument_llm
-
-__all__ = [
-    "instrument_llm",
-    "uninstrument_llm",
-]

mirascope/ops/_internal/instrumentation/llm/__init__.py

@@ -1,8 +0,0 @@
-"""Instrumentation llm modules for various frameworks and libraries."""
-
-from .llm import instrument_llm, uninstrument_llm
-
-__all__ = [
-    "instrument_llm",
-    "uninstrument_llm",
-]