mirascope 1.0.5__py3-none-any.whl → 2.1.1__py3-none-any.whl

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.result,
+                }
+                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."""

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

@@ -0,0 +1,161 @@
+"""OpenTelemetry GenAI instrumentation for `mirascope.llm`.
+
+This module provides the public instrument_llm() and uninstrument_llm() functions
+that enable/disable instrumentation for Model calls and Response.resume methods.
+"""
+
+from __future__ import annotations
+
+import os
+
+from opentelemetry import trace as otel_trace
+
+from ...configuration import get_tracer
+from .model import (
+    unwrap_model_call,
+    unwrap_model_call_async,
+    unwrap_model_context_call,
+    unwrap_model_context_call_async,
+    unwrap_model_context_resume,
+    unwrap_model_context_resume_async,
+    unwrap_model_context_resume_stream,
+    unwrap_model_context_resume_stream_async,
+    unwrap_model_context_stream,
+    unwrap_model_context_stream_async,
+    unwrap_model_resume,
+    unwrap_model_resume_async,
+    unwrap_model_resume_stream,
+    unwrap_model_resume_stream_async,
+    unwrap_model_stream,
+    unwrap_model_stream_async,
+    wrap_model_call,
+    wrap_model_call_async,
+    wrap_model_context_call,
+    wrap_model_context_call_async,
+    wrap_model_context_resume,
+    wrap_model_context_resume_async,
+    wrap_model_context_resume_stream,
+    wrap_model_context_resume_stream_async,
+    wrap_model_context_stream,
+    wrap_model_context_stream_async,
+    wrap_model_resume,
+    wrap_model_resume_async,
+    wrap_model_resume_stream,
+    wrap_model_resume_stream_async,
+    wrap_model_stream,
+    wrap_model_stream_async,
+)
+from .response import (
+    unwrap_async_context_response_resume,
+    unwrap_async_context_stream_response_resume,
+    unwrap_async_response_resume,
+    unwrap_async_stream_response_resume,
+    unwrap_context_response_resume,
+    unwrap_context_stream_response_resume,
+    unwrap_response_resume,
+    unwrap_stream_response_resume,
+    wrap_async_context_response_resume,
+    wrap_async_context_stream_response_resume,
+    wrap_async_response_resume,
+    wrap_async_stream_response_resume,
+    wrap_context_response_resume,
+    wrap_context_stream_response_resume,
+    wrap_response_resume,
+    wrap_stream_response_resume,
+)
+
+
+def instrument_llm() -> None:
+    """Enable GenAI 1.38 span emission for future `llm.Model` calls and streams.
+
+    Uses the tracer provider configured via `ops.configure()`. If no provider
+    was configured, uses the global OpenTelemetry tracer provider.
+
+    Example:
+
+        Enable instrumentation with a custom provider:
+        ```python
+        from mirascope import ops
+        from opentelemetry.sdk.trace import TracerProvider
+
+        provider = TracerProvider()
+        ops.configure(tracer_provider=provider)
+        ops.instrument_llm()
+        ```
+    """
+    if otel_trace is None:  # pragma: no cover
+        raise ImportError(
+            "OpenTelemetry is not installed. Run `pip install mirascope[otel]` "
+            "and ensure `opentelemetry-api` is available before calling "
+            "`instrument_llm`."
+        )
+
+    os.environ.setdefault("OTEL_SEMCONV_STABILITY_OPT_IN", "gen_ai_latest_experimental")
+
+    if get_tracer() is None:  # pragma: no cover
+        raise RuntimeError(
+            "You must call `configure()` before calling `instrument_llm()`."
+        )
+
+    # Model call methods
+    wrap_model_call()
+    wrap_model_call_async()
+    wrap_model_context_call()
+    wrap_model_context_call_async()
+    wrap_model_stream()
+    wrap_model_stream_async()
+    wrap_model_context_stream()
+    wrap_model_context_stream_async()
+
+    # Model resume methods
+    wrap_model_resume()
+    wrap_model_resume_async()
+    wrap_model_context_resume()
+    wrap_model_context_resume_async()
+    wrap_model_resume_stream()
+    wrap_model_resume_stream_async()
+    wrap_model_context_resume_stream()
+    wrap_model_context_resume_stream_async()
+
+    # Response resume methods (Mirascope-specific spans)
+    wrap_response_resume()
+    wrap_async_response_resume()
+    wrap_context_response_resume()
+    wrap_async_context_response_resume()
+    wrap_stream_response_resume()
+    wrap_async_stream_response_resume()
+    wrap_context_stream_response_resume()
+    wrap_async_context_stream_response_resume()
+
+
+def uninstrument_llm() -> None:
+    """Disable previously configured instrumentation."""
+    # Model call methods
+    unwrap_model_call()
+    unwrap_model_call_async()
+    unwrap_model_context_call()
+    unwrap_model_context_call_async()
+    unwrap_model_stream()
+    unwrap_model_stream_async()
+    unwrap_model_context_stream()
+    unwrap_model_context_stream_async()
+
+    # Model resume methods
+    unwrap_model_resume()
+    unwrap_model_resume_async()
+    unwrap_model_context_resume()
+    unwrap_model_context_resume_async()
+    unwrap_model_resume_stream()
+    unwrap_model_resume_stream_async()
+    unwrap_model_context_resume_stream()
+    unwrap_model_context_resume_stream_async()
+
+    # Response resume methods (Mirascope-specific spans)
+    unwrap_response_resume()
+    unwrap_async_response_resume()
+    unwrap_context_response_resume()
+    unwrap_async_context_response_resume()
+    unwrap_stream_response_resume()
+    unwrap_async_stream_response_resume()
+    unwrap_context_stream_response_resume()
+    unwrap_async_context_stream_response_resume()