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

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

@@ -0,0 +1,190 @@
+"""Cost calculation utilities for LLM instrumentation."""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from .....api._generated.token_cost import (
+    TokenCostCalculateRequestUsage,
+    TokenCostCalculateResponse,
+)
+from .....api.client import get_async_client, get_sync_client
+from .....llm.providers import get_provider_for_model
+from .....llm.providers.mirascope import MirascopeProvider
+from .....llm.responses.usage import Usage
+
+logger = logging.getLogger(__name__)
+
+
+def _is_via_router(model_id: str) -> bool:
+    """Check if the model_id routes through MirascopeProvider (Mirascope Router).
+
+    Args:
+        model_id: The full model ID (e.g., "openai/gpt-4o").
+
+    Returns:
+        True if the registered provider for this model is MirascopeProvider.
+    """
+    try:
+        provider = get_provider_for_model(model_id)
+        return isinstance(provider, MirascopeProvider)
+    except Exception:
+        return False
+
+
+def _normalize_model_id(model_id: str) -> str:
+    """Normalize model_id by stripping provider prefix and any :suffix.
+
+    Args:
+        model_id: The full model ID (e.g., "openai/gpt-4o:responses").
+
+    Returns:
+        The base model name (e.g., "gpt-4o").
+    """
+    # Strip provider prefix (e.g., "openai/gpt-4o" -> "gpt-4o")
+    if "/" in model_id:
+        model_id = model_id.split("/", 1)[1]
+    # Strip any :suffix (e.g., ":responses", ":completions")
+    return re.sub(r":.*$", "", model_id)
+
+
+def extract_cache_write_breakdown(usage: Usage) -> dict[str, float] | None:
+    """Extract cache write breakdown from Anthropic's raw usage data.
+
+    Returns a dict like {"ephemeral5m": 100, "ephemeral1h": 50} if available,
+    or None if the breakdown isn't available.
+    """
+    raw = usage.raw
+    if raw is None:
+        return None
+
+    # Check for Anthropic's cache_creation breakdown
+    cache_creation = getattr(raw, "cache_creation", None)
+    if cache_creation is None:
+        return None
+
+    ephemeral_5m = getattr(cache_creation, "ephemeral_5m_input_tokens", None)
+    ephemeral_1h = getattr(cache_creation, "ephemeral_1h_input_tokens", None)
+
+    if ephemeral_5m is None and ephemeral_1h is None:
+        return None
+
+    breakdown: dict[str, float] = {}
+    if ephemeral_5m is not None and ephemeral_5m > 0:
+        breakdown["ephemeral5m"] = float(ephemeral_5m)
+    if ephemeral_1h is not None and ephemeral_1h > 0:
+        breakdown["ephemeral1h"] = float(ephemeral_1h)
+
+    return breakdown if breakdown else None
+
+
+def calculate_cost_sync(
+    provider_id: str,
+    model_id: str,
+    usage: Usage,
+) -> TokenCostCalculateResponse | None:
+    """Calculate cost synchronously. Returns None on any failure."""
+    normalized_model = _normalize_model_id(model_id)
+    via_router = _is_via_router(model_id)
+    logger.debug(
+        "Calculating cost for provider=%s, model=%s (normalized=%s), "
+        "via_router=%s, usage=(input=%s, output=%s, cache_read=%s, cache_write=%s)",
+        provider_id,
+        model_id,
+        normalized_model,
+        via_router,
+        usage.input_tokens,
+        usage.output_tokens,
+        usage.cache_read_tokens,
+        usage.cache_write_tokens,
+    )
+    try:
+        client = get_sync_client()
+        logger.debug("Got sync client, making API request")
+        cache_breakdown = extract_cache_write_breakdown(usage)
+        if cache_breakdown:
+            logger.debug("Cache write breakdown: %s", cache_breakdown)
+        # Build usage kwargs, only including optional fields if they have values
+        usage_kwargs: dict[str, Any] = {
+            "input_tokens": usage.input_tokens,
+            "output_tokens": usage.output_tokens,
+        }
+        if usage.cache_read_tokens:
+            usage_kwargs["cache_read_tokens"] = usage.cache_read_tokens
+        if usage.cache_write_tokens:
+            usage_kwargs["cache_write_tokens"] = usage.cache_write_tokens
+        if cache_breakdown:
+            usage_kwargs["cache_write_breakdown"] = cache_breakdown
+        result = client.token_cost.calculate(
+            provider=provider_id,
+            model=normalized_model,
+            usage=TokenCostCalculateRequestUsage(**usage_kwargs),
+            via_router=via_router,
+        )
+        logger.debug(
+            "Cost calculation result: input=%s, output=%s, total=%s centicents",
+            result.input_cost_centicents,
+            result.output_cost_centicents,
+            result.total_cost_centicents,
+        )
+        return result
+    except Exception:
+        logger.debug("Failed to calculate cost", exc_info=True)
+        return None
+
+
+async def calculate_cost_async(
+    provider_id: str,
+    model_id: str,
+    usage: Usage,
+) -> TokenCostCalculateResponse | None:
+    """Calculate cost asynchronously. Returns None on any failure."""
+    normalized_model = _normalize_model_id(model_id)
+    via_router = _is_via_router(model_id)
+    logger.debug(
+        "Calculating cost (async) for provider=%s, model=%s (normalized=%s), "
+        "via_router=%s, usage=(input=%s, output=%s, cache_read=%s, cache_write=%s)",
+        provider_id,
+        model_id,
+        normalized_model,
+        via_router,
+        usage.input_tokens,
+        usage.output_tokens,
+        usage.cache_read_tokens,
+        usage.cache_write_tokens,
+    )
+    try:
+        client = get_async_client()
+        logger.debug("Got async client, making API request")
+        cache_breakdown = extract_cache_write_breakdown(usage)
+        if cache_breakdown:
+            logger.debug("Cache write breakdown: %s", cache_breakdown)
+        # Build usage kwargs, only including optional fields if they have values
+        usage_kwargs: dict[str, Any] = {
+            "input_tokens": usage.input_tokens,
+            "output_tokens": usage.output_tokens,
+        }
+        if usage.cache_read_tokens:
+            usage_kwargs["cache_read_tokens"] = usage.cache_read_tokens
+        if usage.cache_write_tokens:
+            usage_kwargs["cache_write_tokens"] = usage.cache_write_tokens
+        if cache_breakdown:
+            usage_kwargs["cache_write_breakdown"] = cache_breakdown
+        result = await client.token_cost.calculate(
+            provider=provider_id,
+            model=normalized_model,
+            usage=TokenCostCalculateRequestUsage(**usage_kwargs),
+            via_router=via_router,
+        )
+        logger.debug(
+            "Cost calculation result (async): input=%s, output=%s, total=%s centicents",
+            result.input_cost_centicents,
+            result.output_cost_centicents,
+            result.total_cost_centicents,
+        )
+        return result
+    except Exception:
+        logger.debug("Failed to calculate cost (async)", exc_info=True)
+        return None

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."""