mirascope 2.0.0a1__py3-none-any.whl → 2.0.0a3__py3-none-any.whl

mirascope/ops/_internal/exporters/types.py

@@ -0,0 +1,165 @@
+"""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

@@ -0,0 +1,29 @@
+"""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

@@ -0,0 +1,8 @@
+"""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

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

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

@@ -0,0 +1,238 @@
+"""Utilities for encoding Mirascope messages into GenAI semconv payloads."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from . import gen_ai_types
+
+if TYPE_CHECKING:
+    from typing import TypeAlias
+
+    MessagePart: TypeAlias = (
+        gen_ai_types.TextPart
+        | gen_ai_types.ToolCallRequestPart
+        | gen_ai_types.ToolCallResponsePart
+        | gen_ai_types.BlobPart
+        | gen_ai_types.FilePart
+        | gen_ai_types.UriPart
+        | gen_ai_types.ReasoningPart
+        | gen_ai_types.GenericPart
+    )
+
+
+from .....llm.content import (
+    Audio,
+    Base64ImageSource,
+    Document,
+    Image,
+    Text,
+    Thought,
+    ToolCall,
+    ToolOutput,
+)
+from .....llm.formatting import FormattableT
+from .....llm.messages import AssistantMessage, Message, SystemMessage
+from .....llm.responses.finish_reason import FinishReason
+from .....llm.responses.root_response import RootResponse
+from .....llm.tools import ToolkitT
+from .....llm.types import Jsonable
+
+
+@dataclass(frozen=True, slots=True)
+class OTelMessageSnapshot:
+    """Structured view of system, input, and output messages."""
+
+    system_instructions: gen_ai_types.SystemInstructions
+    """Instructions to be executed prior to the conversation."""
+
+    inputs: gen_ai_types.InputMessages
+    """Messages to be sent to the model."""
+
+    outputs: gen_ai_types.OutputMessages
+    """Messages received from the model."""
+
+
+def _serialize_message_parts(
+    parts: Sequence[
+        Text | ToolCall | ToolOutput[Jsonable] | Thought | Image | Audio | Document
+    ],
+) -> list[MessagePart]:
+    """Serialize message content parts into GenAI-compliant dictionaries.
+
+    Handles Text, ToolCall, ToolOutput, Thought, Image, Audio, Document,
+    and str types.
+    """
+    serialized: list[MessagePart] = []
+    for part in parts:
+        match part:
+            case Text():
+                text_part: gen_ai_types.TextPart = {
+                    "type": "text",
+                    "content": part.text,
+                }
+                serialized.append(text_part)
+            case ToolCall():
+                try:
+                    arguments = json.loads(part.args)
+                except json.JSONDecodeError:  # pragma: no cover
+                    arguments = ""
+                tool_call_part: gen_ai_types.ToolCallRequestPart = {
+                    "type": "tool_call",
+                    "id": part.id,
+                    "name": part.name,
+                    "arguments": arguments,
+                }
+                serialized.append(tool_call_part)
+            case ToolOutput():
+                tool_output_part: gen_ai_types.ToolCallResponsePart = {
+                    "type": "tool_call_response",
+                    "id": part.id,
+                    "response": part.value,
+                }
+                serialized.append(tool_output_part)
+            case Thought():
+                serialized.append(
+                    gen_ai_types.ReasoningPart(type="reasoning", content=part.thought)
+                )
+            case Image():
+                if isinstance(part.source, Base64ImageSource):
+                    image = gen_ai_types.BlobPart(
+                        type="blob",
+                        modality="image",
+                        mime_type=part.source.mime_type,
+                        content=part.source.data,
+                    )
+                else:
+                    image = gen_ai_types.UriPart(
+                        type="uri", modality="image", uri=part.source.url
+                    )
+                serialized.append(image)
+            case Audio():
+                serialized.append(
+                    gen_ai_types.BlobPart(
+                        type="blob",
+                        modality="audio",
+                        mime_type=part.source.mime_type,
+                        content=part.source.data,
+                    )
+                )
+            case Document():  # pragma: no cover
+                raise NotImplementedError(
+                    "Document serialization is not yet supported by any provider. "
+                    "This will be implemented when provider support is added."
+                )
+    return serialized
+
+
+def _serialize_message(message: Message) -> gen_ai_types.ChatMessage:
+    """Serialize a Mirascope message into a GenAI ChatMessage."""
+    content_parts = _serialize_message_parts(
+        message.content if not isinstance(message, SystemMessage) else [message.content]
+    )
+    serialized: gen_ai_types.ChatMessage = {
+        "role": message.role,
+        "parts": content_parts,
+    }
+    name = getattr(message, "name", None)
+    if name:
+        serialized["name"] = name
+    return serialized
+
+
+def map_finish_reason(
+    reason: FinishReason | None,
+) -> gen_ai_types.FinishReason:
+    """Map a finish reason to a GenAI finish reason."""
+    if reason is None:
+        return "stop"
+    elif reason == FinishReason.MAX_TOKENS:
+        return "length"
+    elif reason == FinishReason.REFUSAL:  # pragma: no cover
+        return "content_filter"
+    raise ValueError(f"Unknown finish reason: {reason}")  # pragma: no cover
+
+
+def _serialize_output_message(
+    message: AssistantMessage, finish_reason: FinishReason | None
+) -> gen_ai_types.OutputMessage:
+    """Serialize an assistant message into a GenAI OutputMessage with finish_reason."""
+    chat_message = _serialize_message(message)
+    output_message: gen_ai_types.OutputMessage = {
+        "role": chat_message["role"],
+        "parts": chat_message["parts"],
+        "finish_reason": map_finish_reason(finish_reason),
+    }
+    if "name" in chat_message:
+        output_message["name"] = chat_message["name"]
+    return output_message
+
+
+def split_request_messages(
+    messages: Sequence[Message],
+) -> tuple[gen_ai_types.SystemInstructions, gen_ai_types.InputMessages]:
+    """Return serialized system instructions and non-system input messages.
+
+    System messages are flattened into a list of parts (not wrapped in message objects),
+    while other messages are serialized as complete ChatMessage objects.
+    """
+    system_instructions: gen_ai_types.SystemInstructions = []
+    inputs: gen_ai_types.InputMessages = []
+    for message in messages:
+        if message.role == "system":
+            # System messages contribute only their parts (flattened)
+            parts = _serialize_message_parts(
+                [message.content]
+                if isinstance(message, SystemMessage)
+                else message.content
+            )
+            system_instructions.extend(parts)
+        else:
+            # Non-system messages are serialized as full ChatMessage objects
+            serialized = _serialize_message(message)
+            inputs.append(serialized)
+    return system_instructions, inputs
+
+
+def snapshot_from_response_messages(
+    *,
+    request_messages: Sequence[Message],
+    assistant_message: AssistantMessage,
+    finish_reason: FinishReason | None,
+) -> OTelMessageSnapshot:
+    """Build a snapshot using the request/response boundary for a call."""
+
+    system_instructions, inputs = split_request_messages(request_messages)
+    outputs = [_serialize_output_message(assistant_message, finish_reason)]
+    return OTelMessageSnapshot(
+        system_instructions=system_instructions,
+        inputs=inputs,
+        outputs=outputs,
+    )
+
+
+def snapshot_from_root_response(
+    response: RootResponse[ToolkitT, FormattableT | None],
+    *,
+    request_messages: Sequence[Message] | None = None,
+) -> OTelMessageSnapshot:
+    """Build a snapshot directly from a `RootResponse`.
+
+    Args:
+        response: The response that includes the entire conversation history.
+        request_messages: Optional explicit request message sequence. Defaults to all
+            but the final assistant message inside `response.messages`.
+    """
+
+    assistant_message = response.messages[-1]
+    if not isinstance(assistant_message, AssistantMessage):  # pragma: no cover
+        raise TypeError("Final response message must be an AssistantMessage")
+
+    return snapshot_from_response_messages(
+        request_messages=request_messages or response.messages[:-1],
+        assistant_message=assistant_message,
+        finish_reason=response.finish_reason,
+    )

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

@@ -0,0 +1,38 @@
+"""OpenTelemetry Gen AI Semantic Conventions types."""
+
+from __future__ import annotations
+
+from .gen_ai_input_messages import ChatMessage, InputMessages
+from .gen_ai_output_messages import FinishReason, OutputMessage, OutputMessages
+from .gen_ai_system_instructions import SystemInstructions
+from .shared import (
+    BlobPart,
+    FilePart,
+    GenericPart,
+    Modality,
+    ReasoningPart,
+    Role,
+    TextPart,
+    ToolCallRequestPart,
+    ToolCallResponsePart,
+    UriPart,
+)
+
+__all__ = [
+    "BlobPart",
+    "ChatMessage",
+    "FilePart",
+    "FinishReason",
+    "GenericPart",
+    "InputMessages",
+    "Modality",
+    "OutputMessage",
+    "OutputMessages",
+    "ReasoningPart",
+    "Role",
+    "SystemInstructions",
+    "TextPart",
+    "ToolCallRequestPart",
+    "ToolCallResponsePart",
+    "UriPart",
+]

mirascope/ops/_internal/instrumentation/llm/gen_ai_types/gen_ai_input_messages.py

@@ -0,0 +1,31 @@
+"""OpenTelemetry Gen AI Semantic Conventions types."""
+
+from __future__ import annotations
+
+from typing import TypeAlias, TypedDict
+from typing_extensions import NotRequired
+
+from . import shared
+
+
+class ChatMessage(TypedDict):
+    role: shared.Role | str
+    """Role of the entity that created the message."""
+
+    parts: list[
+        shared.TextPart
+        | shared.ToolCallRequestPart
+        | shared.ToolCallResponsePart
+        | shared.BlobPart
+        | shared.FilePart
+        | shared.UriPart
+        | shared.ReasoningPart
+        | shared.GenericPart
+    ]
+    """List of message parts that make up the message content."""
+
+    name: NotRequired[str | None]
+    """The name of the participant."""
+
+
+InputMessages: TypeAlias = list[ChatMessage]

mirascope/ops/_internal/instrumentation/llm/gen_ai_types/gen_ai_output_messages.py

@@ -0,0 +1,38 @@
+"""OpenTelemetry Gen AI Semantic Conventions types."""
+
+from __future__ import annotations
+
+from typing import Literal, TypeAlias, TypedDict
+from typing_extensions import NotRequired
+
+from . import shared
+
+FinishReason: TypeAlias = Literal[
+    "stop", "length", "content_filter", "tool_call", "error"
+]
+
+
+class OutputMessage(TypedDict):
+    role: shared.Role | str
+    """Role of the entity that created the message."""
+
+    parts: list[
+        shared.TextPart
+        | shared.ToolCallRequestPart
+        | shared.ToolCallResponsePart
+        | shared.BlobPart
+        | shared.FilePart
+        | shared.UriPart
+        | shared.ReasoningPart
+        | shared.GenericPart
+    ]
+    """List of message parts that make up the message content."""
+
+    name: NotRequired[str | None]
+    """The name of the participant."""
+
+    finish_reason: FinishReason | str
+    """Reason for finishing the generation."""
+
+
+OutputMessages: TypeAlias = list[OutputMessage]

mirascope/ops/_internal/instrumentation/llm/gen_ai_types/gen_ai_system_instructions.py

@@ -0,0 +1,18 @@
+"""OpenTelemetry Gen AI Semantic Conventions types."""
+
+from __future__ import annotations
+
+from typing import TypeAlias
+
+from . import shared
+
+SystemInstructions: TypeAlias = list[
+    shared.TextPart
+    | shared.ToolCallRequestPart
+    | shared.ToolCallResponsePart
+    | shared.BlobPart
+    | shared.FilePart
+    | shared.UriPart
+    | shared.ReasoningPart
+    | shared.GenericPart
+]

mirascope/ops/_internal/instrumentation/llm/gen_ai_types/shared.py

@@ -0,0 +1,100 @@
+"""OpenTelemetry Gen AI Semantic Conventions types."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypeAlias, TypedDict
+from typing_extensions import NotRequired
+
+
+class BlobPart(TypedDict):
+    type: Literal["blob"]
+    """The type of the content captured in this part."""
+
+    mime_type: NotRequired[str | None]
+    """The IANA MIME type of the attached data."""
+
+    modality: Modality | str
+    """The general modality of the data if it is known. Instrumentations SHOULD also set the mimeType field if the specific type is known."""
+
+    content: str
+    """Raw bytes of the attached data. This field SHOULD be encoded as a base64 string when transmitted as JSON."""
+
+
+class FilePart(TypedDict):
+    type: Literal["file"]
+    """The type of the content captured in this part."""
+
+    mime_type: NotRequired[str | None]
+    """The IANA MIME type of the attached data."""
+
+    modality: Modality | str
+    """The general modality of the data if it is known. Instrumentations SHOULD also set the mimeType field if the specific type is known."""
+
+    file_id: str
+    """An identifier referencing a file that was pre-uploaded to the provider."""
+
+
+class GenericPart(TypedDict):
+    type: str
+    """The type of the content captured in this part."""
+
+
+Modality: TypeAlias = Literal["image", "video", "audio"]
+
+
+class ReasoningPart(TypedDict):
+    type: Literal["reasoning"]
+    """The type of the content captured in this part."""
+
+    content: str
+    """Reasoning/thinking content received from the model."""
+
+
+Role: TypeAlias = Literal["system", "user", "assistant", "tool"]
+
+
+class TextPart(TypedDict):
+    type: Literal["text"]
+    """The type of the content captured in this part."""
+
+    content: str
+    """Text content sent to or received from the model."""
+
+
+class ToolCallRequestPart(TypedDict):
+    type: Literal["tool_call"]
+    """The type of the content captured in this part."""
+
+    id: NotRequired[str | None]
+    """Unique identifier for the tool call."""
+
+    name: str
+    """Name of the tool."""
+
+    arguments: NotRequired[Any]
+    """Arguments for the tool call."""
+
+
+class ToolCallResponsePart(TypedDict):
+    type: Literal["tool_call_response"]
+    """The type of the content captured in this part."""
+
+    id: NotRequired[str | None]
+    """Unique tool call identifier."""
+
+    response: Any
+    """Tool call response."""
+
+
+class UriPart(TypedDict):
+    type: Literal["uri"]
+    """The type of the content captured in this part."""
+
+    mime_type: NotRequired[str | None]
+    """The IANA MIME type of the attached data."""
+
+    modality: Modality | str
+    """The general modality of the data if it is known. Instrumentations SHOULD also set the mimeType field if the specific type is known."""
+
+    uri: str
+    """A URI referencing attached data. It should not be a base64 data URL, which should use the `blob` part instead. The URI may use a scheme known to the provider api (e.g. `gs://bucket/object.png`), or be a publicly accessible location."""