mirascope 1.19.0__py3-none-any.whl → 1.20.1__py3-none-any.whl

mirascope/__init__.py

@@ -17,7 +17,9 @@ from .core import (
     DocumentPart,
     ImagePart,
     ImageURLPart,
+    LocalProvider,
     Messages,
+    Provider,
     TextPart,
     ToolCallPart,
     ToolResultPart,
@@ -43,7 +45,9 @@ __all__ = [
     "DocumentPart",
     "ImagePart",
     "ImageURLPart",
+    "LocalProvider",
     "Messages",
+    "Provider",
     "TextPart",
     "ToolCallPart",
     "ToolResultPart",

mirascope/beta/openai/realtime/realtime.py

@@ -5,6 +5,7 @@ import base64
 import inspect
 import json
 import os
+from collections import defaultdict
 from collections.abc import Callable
 from functools import lru_cache
 from io import BytesIO
@@ -17,23 +18,21 @@ from typing import (
 )
 
 import websockets
-from black.trans import defaultdict
 from pydantic import BaseModel
 from pydub import AudioSegment
 from typing_extensions import NotRequired, overload
 from websockets.asyncio.client import ClientConnection, connect
 
-from mirascope.beta.openai.realtime._utils._audio import (
+from ....core import BaseTool
+from ....core.base._utils import (
+    convert_base_model_to_base_tool,
+    convert_function_to_base_tool,
+)
+from ._utils._audio import (
     async_audio_input_audio_buffer_append_event,
     async_audio_to_item_create_event,
     audio_chunk_to_audio_segment,
 )
-from mirascope.core import BaseTool
-from mirascope.core.base._utils import (
-    convert_base_model_to_base_tool,
-    convert_function_to_base_tool,
-)
-
 from ._utils._protocols import FunctionCallHandlerFunc, ReceiverFunc, SenderFunc
 from .tool import FunctionCallArguments, OpenAIRealtimeTool, RealtimeToolParam
 

mirascope/beta/openai/realtime/tool.py

@@ -6,8 +6,8 @@ import jiter
 from pydantic.json_schema import SkipJsonSchema
 from typing_extensions import NotRequired, TypedDict
 
-from mirascope.core import BaseTool
-from mirascope.core.base import GenerateJsonSchemaNoTitles, ToolConfig
+from ....core import BaseTool
+from ....core.base import GenerateJsonSchemaNoTitles, ToolConfig
 
 
 class OpenAIRealtimeToolConfig(ToolConfig, total=False):

mirascope/core/__init__.py

@@ -2,7 +2,7 @@
 
 from contextlib import suppress
 
-from . import base
+from . import base, costs
 from .base import (
     AudioPart,
     AudioURLPart,
@@ -14,11 +14,14 @@ from .base import (
     BaseTool,
     BaseToolKit,
     CacheControlPart,
+    CostMetadata,
     DocumentPart,
     FromCallArgs,
     ImagePart,
     ImageURLPart,
+    LocalProvider,
     Messages,
+    Provider,
     ResponseModelConfigDict,
     TextPart,
     ToolCallPart,
@@ -28,6 +31,7 @@ from .base import (
     prompt_template,
     toolkit_tool,
 )
+from .costs import calculate_cost
 
 with suppress(ImportError):
     from . import anthropic as anthropic
@@ -71,11 +75,14 @@ __all__ = [
     "BaseTool",
     "BaseToolKit",
     "CacheControlPart",
+    "CostMetadata",
     "DocumentPart",
     "FromCallArgs",
     "ImagePart",
     "ImageURLPart",
+    "LocalProvider",
     "Messages",
+    "Provider",
     "ResponseModelConfigDict",
     "TextPart",
     "ToolCallPart",
@@ -83,7 +90,9 @@ __all__ = [
     "anthropic",
     "azure",
     "base",
+    "calculate_cost",
     "cohere",
+    "costs",
     "gemini",
     "google",
     "groq",

mirascope/core/anthropic/_utils/__init__.py

@@ -1,6 +1,5 @@
 """Anthropic utilities for decorator factories."""
 
-from ._calculate_cost import calculate_cost
 from ._convert_common_call_params import convert_common_call_params
 from ._convert_message_params import convert_message_params
 from ._get_json_output import get_json_output
@@ -8,7 +7,6 @@ from ._handle_stream import handle_stream, handle_stream_async
 from ._setup_call import setup_call
 
 __all__ = [
-    "calculate_cost",
     "convert_common_call_params",
     "convert_message_params",
     "get_json_output",

mirascope/core/anthropic/_utils/_convert_message_params.py

@@ -5,7 +5,6 @@ import base64
 from anthropic.types import MessageParam
 
 from ...base import BaseMessageParam
-from ...base._utils._parse_content_template import _load_media, get_image_type
 
 
 def convert_message_params(
@@ -47,15 +46,10 @@ def convert_message_params(
                         }
                     )
                 elif part.type == "image_url":
-                    image = _load_media(part.url)
                     converted_content.append(
                         {
                             "type": "image",
-                            "source": {
-                                "data": base64.b64encode(image).decode("utf-8"),
-                                "media_type": f"image/{get_image_type(image)}",
-                                "type": "base64",
-                            },
+                            "source": {"url": part.url, "type": "url"},
                         }
                     )
                 elif part.type == "document":

mirascope/core/anthropic/_utils/_message_param_converter.py

@@ -6,7 +6,13 @@ from anthropic.types import MessageParam
 
 from mirascope.core import BaseMessageParam
 from mirascope.core.anthropic._utils import convert_message_params
-from mirascope.core.base import ImagePart, TextPart, ToolCallPart, ToolResultPart
+from mirascope.core.base import (
+    ImagePart,
+    ImageURLPart,
+    TextPart,
+    ToolCallPart,
+    ToolResultPart,
+)
 from mirascope.core.base._utils._base_message_param_converter import (
     BaseMessageParamConverter,
 )
@@ -53,41 +59,52 @@ class AnthropicMessageParamConverter(BaseMessageParamConverter):
 
                 elif block["type"] == "image":
                     source = block.get("source")
-                    if not source or source.get("type") != "base64":
-                        raise ValueError(
-                            "ImageBlockParam must have a 'source' with type='base64'."
-                        )
-                    image_data = source.get("data")
-                    media_type = source.get("media_type")
-                    if not image_data or not media_type:
+                    source_type = source.get("type") if source else None
+                    if not source or source_type not in ["base64", "url"]:
                         raise ValueError(
-                            "ImageBlockParam source must have 'data' and 'media_type'."
+                            "ImageBlockParam must have a 'source' with type='base64' or type='url'."
                         )
-                    if media_type not in [
-                        "image/jpeg",
-                        "image/png",
-                        "image/gif",
-                        "image/webp",
-                    ]:
-                        raise ValueError(
-                            f"Unsupported image media type: {media_type}. "
-                            "BaseMessageParam currently only supports JPEG, PNG, GIF, and WebP images."
+                    if source_type == "url":
+                        url = source.get("url")
+                        if not url:
+                            raise ValueError(
+                                "ImageBlockParam source with type='url' must have a 'url'."
+                            )
+                        converted_content.append(
+                            ImageURLPart(type="image_url", url=url, detail=None)
                         )
-                    if isinstance(image_data, str):
-                        decoded_image_data = base64.b64decode(image_data)
-                    elif isinstance(image_data, PathLike):
-                        with open(image_data, "rb") as image_data:
-                            decoded_image_data = image_data.read()
                     else:
-                        decoded_image_data = image_data.read()
-                    converted_content.append(
-                        ImagePart(
-                            type="image",
-                            media_type=media_type,
-                            image=decoded_image_data,
-                            detail=None,
+                        image_data = source.get("data")
+                        media_type = source.get("media_type")
+                        if not image_data or not media_type:
+                            raise ValueError(
+                                "ImageBlockParam source with type='base64' must have 'data' and 'media_type'."
+                            )
+                        if media_type not in [
+                            "image/jpeg",
+                            "image/png",
+                            "image/gif",
+                            "image/webp",
+                        ]:
+                            raise ValueError(
+                                f"Unsupported image media type: {media_type}. "
+                                "BaseMessageParam currently only supports JPEG, PNG, GIF, and WebP images."
+                            )
+                        if isinstance(image_data, str):
+                            decoded_image_data = base64.b64decode(image_data)
+                        elif isinstance(image_data, PathLike):
+                            with open(image_data, "rb") as image_data:
+                                decoded_image_data = image_data.read()
+                        else:
+                            decoded_image_data = image_data.read()
+                        converted_content.append(
+                            ImagePart(
+                                type="image",
+                                media_type=media_type,
+                                image=decoded_image_data,
+                                detail=None,
+                            )
                         )
-                    )
 
                 elif block["type"] == "tool_use":
                     if converted_content:

mirascope/core/anthropic/call_response.py

@@ -16,7 +16,7 @@ from pydantic import SerializeAsAny, computed_field
 
 from .. import BaseMessageParam
 from ..base import BaseCallResponse, transform_tool_outputs, types
-from ._utils import calculate_cost
+from ..base.types import CostMetadata
 from ._utils._convert_finish_reason_to_common_finish_reasons import (
     _convert_finish_reasons_to_common_finish_reasons,
 )
@@ -112,14 +112,6 @@ class AnthropicCallResponse(
         """Returns the number of output tokens."""
         return self.usage.output_tokens
 
-    @computed_field
-    @property
-    def cost(self) -> float | None:
-        """Returns the cost of the call."""
-        return calculate_cost(
-            self.input_tokens, self.cached_tokens, self.output_tokens, self.model
-        )
-
     @computed_field
     @cached_property
     def message_param(self) -> SerializeAsAny[MessageParam]:
@@ -202,3 +194,9 @@ class AnthropicCallResponse(
         return AnthropicMessageParamConverter.from_provider(
             [(self.user_message_param)]
         )[0]
+
+    @computed_field
+    @property
+    def cost_metadata(self) -> CostMetadata:
+        """Get metadata required for cost calculation."""
+        return super().cost_metadata

mirascope/core/anthropic/call_response_chunk.py

@@ -16,6 +16,7 @@ from anthropic.types import (
 )
 
 from ..base import BaseCallResponseChunk, types
+from ..base.types import CostMetadata
 from ._utils._convert_finish_reason_to_common_finish_reasons import (
     _convert_finish_reasons_to_common_finish_reasons,
 )
@@ -114,6 +115,15 @@ class AnthropicCallResponseChunk(
             return self.usage.output_tokens
         return None
 
+    @property
+    def cost_metadata(self) -> CostMetadata:
+        """Returns the cost metadata."""
+        return CostMetadata(
+            input_tokens=self.input_tokens,
+            output_tokens=self.output_tokens,
+            cached_tokens=self.cached_tokens,
+        )
+
     @property
     def common_finish_reasons(self) -> list[types.FinishReason] | None:
         """Provider-agnostic finish reasons."""

mirascope/core/anthropic/stream.py

@@ -17,7 +17,7 @@ from anthropic.types.tool_use_block_param import ToolUseBlockParam
 from pydantic import BaseModel
 
 from ..base.stream import BaseStream
-from ._utils import calculate_cost
+from ..base.types import CostMetadata
 from .call_params import AnthropicCallParams
 from .call_response import AnthropicCallResponse
 from .call_response_chunk import AnthropicCallResponseChunk
@@ -64,13 +64,6 @@ class AnthropicStream(
 
     _provider = "anthropic"
 
-    @property
-    def cost(self) -> float | None:
-        """Returns the cost of the call."""
-        return calculate_cost(
-            self.input_tokens, self.cached_tokens, self.output_tokens, self.model
-        )
-
     def _construct_message_param(
         self, tool_calls: list[ToolUseBlock] | None = None, content: str | None = None
     ) -> MessageParam:
@@ -147,3 +140,8 @@ class AnthropicStream(
             start_time=self.start_time,
             end_time=self.end_time,
         )
+
+    @property
+    def cost_metadata(self) -> CostMetadata:
+        """Get metadata required for cost calculation."""
+        return super().cost_metadata

mirascope/core/azure/_utils/__init__.py

@@ -1,13 +1,11 @@
 """Azure utilities for decorator factories."""
 
-from ._calculate_cost import calculate_cost
 from ._convert_message_params import convert_message_params
 from ._get_json_output import get_json_output
 from ._handle_stream import handle_stream, handle_stream_async
 from ._setup_call import setup_call
 
 __all__ = [
-    "calculate_cost",
     "convert_message_params",
     "get_json_output",
     "handle_stream",

mirascope/core/azure/call_response.py

@@ -19,8 +19,7 @@ from pydantic import SerializeAsAny, SkipValidation, computed_field
 
 from .. import BaseMessageParam
 from ..base import BaseCallResponse, transform_tool_outputs
-from ..base.types import FinishReason
-from ._utils import calculate_cost
+from ..base.types import CostMetadata, FinishReason
 from ._utils._convert_finish_reason_to_common_finish_reasons import (
     _convert_finish_reasons_to_common_finish_reasons,
 )
@@ -116,14 +115,6 @@ class AzureCallResponse(
         """Returns the number of output tokens."""
         return self.usage.completion_tokens if self.usage else None
 
-    @computed_field
-    @property
-    def cost(self) -> float | None:
-        """Returns the cost of the call."""
-        return calculate_cost(
-            self.input_tokens, self.cached_tokens, self.output_tokens, self.model
-        )
-
     @computed_field
     @cached_property
     def message_param(self) -> SerializeAsAny[AssistantMessage]:
@@ -213,3 +204,9 @@ class AzureCallResponse(
         if not self.user_message_param:
             return None
         return AzureMessageParamConverter.from_provider([self.user_message_param])[0]
+
+    @computed_field
+    @property
+    def cost_metadata(self) -> CostMetadata:
+        """Get metadata required for cost calculation."""
+        return super().cost_metadata

mirascope/core/azure/call_response_chunk.py

@@ -13,7 +13,7 @@ from azure.ai.inference.models import (
 from pydantic import SkipValidation
 
 from ..base import BaseCallResponseChunk
-from ..base.types import FinishReason
+from ..base.types import CostMetadata, FinishReason
 
 
 class AzureCallResponseChunk(
@@ -94,6 +94,11 @@ class AzureCallResponseChunk(
         """Returns the number of output tokens."""
         return self.usage.completion_tokens
 
+    @property
+    def cost_metadata(self) -> CostMetadata:
+        """Returns the cost metadata."""
+        return super().cost_metadata
+
     @property
     def common_finish_reasons(self) -> list[FinishReason] | None:
         """Provider-agnostic finish reasons."""

mirascope/core/azure/stream.py

@@ -21,7 +21,7 @@ from azure.ai.inference.models import (
 )
 
 from ..base.stream import BaseStream
-from ._utils import calculate_cost
+from ..base.types import CostMetadata
 from .call_params import AzureCallParams
 from .call_response import AzureCallResponse
 from .call_response_chunk import AzureCallResponseChunk
@@ -66,13 +66,6 @@ class AzureStream(
 
     _provider = "azure"
 
-    @property
-    def cost(self) -> float | None:
-        """Returns the cost of the call."""
-        return calculate_cost(
-            self.input_tokens, self.cached_tokens, self.output_tokens, self.model
-        )
-
     def _construct_message_param(
         self,
         tool_calls: list[ChatCompletionsToolCall] | None = None,
@@ -147,3 +140,8 @@ class AzureStream(
             start_time=self.start_time,
             end_time=self.end_time,
         )
+
+    @property
+    def cost_metadata(self) -> CostMetadata:
+        """Get metadata required for cost calculation."""
+        return super().cost_metadata

mirascope/core/base/__init__.py

@@ -30,7 +30,14 @@ from .stream import BaseStream
 from .structured_stream import BaseStructuredStream
 from .tool import BaseTool, GenerateJsonSchemaNoTitles, ToolConfig
 from .toolkit import BaseToolKit, toolkit_tool
-from .types import AudioSegment, JsonableType, Usage
+from .types import (
+    AudioSegment,
+    CostMetadata,
+    JsonableType,
+    LocalProvider,
+    Provider,
+    Usage,
+)
 
 __all__ = [
     "AudioPart",
@@ -50,12 +57,14 @@ __all__ = [
     "BaseType",
     "CacheControlPart",
     "CommonCallParams",
+    "CostMetadata",
     "DocumentPart",
     "FromCallArgs",
     "GenerateJsonSchemaNoTitles",
     "ImagePart",
     "ImageURLPart",
     "JsonableType",
+    "LocalProvider",
     "Messages",
     "Metadata",
     "ResponseModelConfigDict",

mirascope/core/base/_utils/__init__.py

@@ -14,6 +14,7 @@ from ._get_create_fn_or_async_create_fn import get_async_create_fn, get_create_f
 from ._get_document_type import get_document_type
 from ._get_dynamic_configuration import get_dynamic_configuration
 from ._get_fn_args import get_fn_args
+from ._get_image_dimensions import get_image_dimensions
 from ._get_image_type import get_image_type
 from ._get_metadata import get_metadata
 from ._get_possible_user_message_param import get_possible_user_message_param
@@ -68,6 +69,7 @@ __all__ = [
     "get_document_type",
     "get_dynamic_configuration",
     "get_fn_args",
+    "get_image_dimensions",
     "get_image_type",
     "get_metadata",
     "get_possible_user_message_param",

mirascope/core/base/_utils/_get_image_dimensions.py

@@ -0,0 +1,39 @@
+import base64
+import io
+import re
+
+from ...base.types import Image, ImageMetadata, has_pil_module
+from ._parse_content_template import _load_media
+
+
+def get_image_dimensions(data_url: str) -> ImageMetadata | None:
+    """
+    Extract width and height from a base64 encoded image.
+
+    Args:
+        data_url: The data URL containing base64 encoded image data or External URL
+
+    Returns:
+        Dictionary with width and height, or None if extraction failed
+    """
+    try:
+        if data_url.startswith("http"):
+            binary_data = _load_media(data_url)
+        else:
+            # Extract the base64 data part from the URL
+            # Format is: data:[<media type>][;base64],<data>
+            pattern = r"data:image/[^;]+;base64,"
+            base64_data = re.sub(pattern, "", data_url)
+
+            # Decode the base64 data
+            binary_data = base64.b64decode(base64_data)
+
+        # Use PIL to open the image and get dimensions
+        if not has_pil_module:  # pragma: no cover
+            raise ImportError("PIL module is not available")
+        with Image.open(io.BytesIO(binary_data)) as image:
+            width, height = image.size
+
+        return ImageMetadata(width=width, height=height)
+    except Exception:
+        return None

mirascope/core/base/call_response.py

@@ -7,7 +7,7 @@ import json
 from abc import ABC, abstractmethod
 from collections.abc import Callable
 from functools import cached_property, wraps
-from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar, cast
 
 from pydantic import (
     BaseModel,
@@ -18,13 +18,14 @@ from pydantic import (
     field_serializer,
 )
 
+from ..costs import calculate_cost
 from ._utils import BaseType, get_common_usage
 from .call_kwargs import BaseCallKwargs
 from .call_params import BaseCallParams
 from .dynamic_config import BaseDynamicConfig
 from .metadata import Metadata
 from .tool import BaseTool
-from .types import FinishReason, JsonableType, Usage
+from .types import CostMetadata, FinishReason, JsonableType, Provider, Usage
 
 if TYPE_CHECKING:
     from ...llm.tool import Tool
@@ -225,12 +226,41 @@ class BaseCallResponse(
     @computed_field
     @property
     @abstractmethod
-    def cost(self) -> float | None:
-        """Should return the cost of the response in dollars.
+    def cost_metadata(self) -> CostMetadata:
+        """Get metadata required for cost calculation.
 
-        If there is no cost, this method must return None.
+        Returns:
+            Metadata relevant to cost calculation
         """
-        ...
+
+        return CostMetadata(
+            input_tokens=self.input_tokens,
+            output_tokens=self.output_tokens,
+            cached_tokens=self.cached_tokens,
+        )
+
+    @computed_field
+    @property
+    def cost(self) -> float | None:
+        """Calculate the cost of this API call using the unified calculate_cost function."""
+
+        model = self.model
+        if not model:
+            return None
+
+        if self.input_tokens is None or self.output_tokens is None:
+            return None
+
+        return calculate_cost(
+            provider=self.provider,
+            model=model,
+            metadata=self.cost_metadata,
+        )
+
+    @property
+    def provider(self) -> Provider:
+        """Get the provider used for this API call."""
+        return cast(Provider, self._provider)
 
     @computed_field
     @cached_property

mirascope/core/base/call_response_chunk.py

@@ -11,7 +11,7 @@ from typing import Any, Generic, TypeVar
 from pydantic import BaseModel, ConfigDict
 
 from mirascope.core.base._utils import get_common_usage
-from mirascope.core.base.types import FinishReason, Usage
+from mirascope.core.base.types import CostMetadata, FinishReason, Usage
 
 _ChunkT = TypeVar("_ChunkT", bound=Any)
 _FinishReasonT = TypeVar("_FinishReasonT", bound=Any)
@@ -102,6 +102,20 @@ class BaseCallResponseChunk(BaseModel, Generic[_ChunkT, _FinishReasonT], ABC):
         """
         ...
 
+    @property
+    @abstractmethod
+    def cost_metadata(self) -> CostMetadata:
+        """Get metadata required for cost calculation.
+
+        Returns:
+            A CostMetadata object with information relevant to cost calculation
+        """
+        return CostMetadata(
+            input_tokens=self.input_tokens,
+            output_tokens=self.output_tokens,
+            cached_tokens=self.cached_tokens,
+        )
+
     @property
     @abstractmethod
     def common_finish_reasons(self) -> list[FinishReason] | None: