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

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

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

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

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

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

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

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

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