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

mirascope/core/base/stream.py

@@ -14,6 +14,7 @@ from typing import (
     overload,
 )
 
+from ..costs import calculate_cost
 from ._utils import (
     HandleStream,
     HandleStreamAsync,
@@ -35,6 +36,7 @@ from .messages import Messages
 from .metadata import Metadata
 from .prompt import prompt_template
 from .tool import BaseTool
+from .types import CostMetadata, Provider
 
 _BaseCallResponseT = TypeVar("_BaseCallResponseT", bound=BaseCallResponse)
 _BaseCallResponseChunkT = TypeVar(
@@ -211,10 +213,30 @@ class BaseStream(
             self.finish_reasons = chunk.finish_reasons
 
     @property
-    @abstractmethod
+    def provider(self) -> Provider:
+        return cast(Provider, self._provider)
+
+    @property
+    def cost_metadata(self) -> CostMetadata:
+        """Returns metadata needed for cost calculation."""
+        return CostMetadata(
+            input_tokens=self.input_tokens,
+            output_tokens=self.output_tokens,
+            cached_tokens=self.cached_tokens,
+        )
+
+    @property
     def cost(self) -> float | None:
-        """Returns the cost of the stream."""
-        ...
+        """Calculate the cost of this streaming API call."""
+
+        if self.input_tokens is None or self.output_tokens is None:
+            return None
+
+        return calculate_cost(
+            provider=self.provider,
+            model=self.model,
+            metadata=self.cost_metadata,
+        )
 
     @abstractmethod
     def _construct_message_param(

mirascope/core/base/types.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Literal, TypeAlias
+from typing import TYPE_CHECKING, Annotated, Literal, TypeAlias
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict, Field
 
 if TYPE_CHECKING:
     from PIL import Image
@@ -68,3 +68,277 @@ JsonableType: TypeAlias = (
     | dict[str, "JsonableType"]
     | BaseModel
 )
+
+
+class VideoMetadata(BaseModel):
+    """Metadata for a video for cost calculation"""
+
+    duration_seconds: Annotated[
+        float,
+        Field(description="Duration of the video in seconds"),
+    ]
+
+    with_audio: Annotated[
+        bool | None,
+        Field(
+            default=False,
+            description="Whether the video includes audio that should be processed",
+        ),
+    ] = False
+
+    tokens: Annotated[
+        int | None,
+        Field(default=None, description="Precalculated token count for this video"),
+    ] = None
+
+
+class AudioMetadata(BaseModel):
+    """Metadata for an audio file for cost calculation"""
+
+    duration_seconds: Annotated[
+        float,
+        Field(description="Duration of the audio in seconds"),
+    ]
+
+    with_timestamps: Annotated[
+        bool | None,
+        Field(default=False, description="Whether timestamps should be included"),
+    ] = False
+
+    tokens: Annotated[
+        int | None,
+        Field(default=None, description="Precalculated token count for this audio"),
+    ] = None
+
+
+class ImageMetadata(BaseModel):
+    """Metadata for an image for cost calculation"""
+
+    width: Annotated[
+        int,
+        Field(description="Width of the image in pixels"),
+    ]
+
+    height: Annotated[
+        int,
+        Field(description="Height of the image in pixels"),
+    ]
+
+    tokens: Annotated[
+        int | None,
+        Field(default=None, description="Precalculated token count for this image"),
+    ] = None
+
+    detail: Annotated[
+        str | None,
+        Field(default=None, description="Detail level of the image"),
+    ] = None
+
+
+class GoogleMetadata(BaseModel):
+    """Google API specific metadata for cost calculation"""
+
+    use_vertex_ai: Annotated[
+        bool | None,
+        Field(
+            default=False,
+            description="Whether to use Vertex AI pricing (vs. direct Gemini API)",
+        ),
+    ] = False
+
+    grounding_requests: Annotated[
+        int | None,
+        Field(default=None, description="Number of Google Search grounding requests"),
+    ] = None
+
+
+class PDFImageMetadata(BaseModel):
+    """Metadata for an image extracted from a PDF page"""
+
+    width: Annotated[
+        int,
+        Field(description="Width of the image in pixels"),
+    ]
+
+    height: Annotated[
+        int,
+        Field(description="Height of the image in pixels"),
+    ]
+
+    tokens: Annotated[
+        int | None,
+        Field(default=None, description="Precalculated token count for this image"),
+    ] = None
+
+
+class PDFMetadata(BaseModel):
+    """Metadata specific to PDF documents for cost calculation"""
+
+    page_count: Annotated[
+        int | None,
+        Field(default=None, description="Number of pages in the PDF"),
+    ] = None
+
+    text_tokens: Annotated[
+        int | None,
+        Field(
+            default=None, description="Number of tokens from text content in the PDF"
+        ),
+    ] = None
+
+    images: Annotated[
+        list[PDFImageMetadata] | None,
+        Field(
+            default=None,
+            description="List of images extracted from PDF with width and height information",
+        ),
+    ] = None
+
+    cached: Annotated[
+        bool | None,
+        Field(
+            default=None,
+            description="Whether this PDF was cached for reduced token costs",
+        ),
+    ] = None
+
+
+class CostMetadata(BaseModel):
+    """Metadata required for accurate LLM API cost calculation across all providers."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    # Common fields
+    input_tokens: Annotated[
+        int | float | None,
+        Field(default=None, description="Input tokens"),
+    ] = None
+    output_tokens: Annotated[
+        int | float | None,
+        Field(default=None, description="Output tokens"),
+    ] = None
+    cached_tokens: Annotated[
+        int | float | None,
+        Field(default=None, description="Cached tokens"),
+    ] = None
+    streaming_mode: Annotated[
+        bool | None,
+        Field(default=None, description="Whether streaming API was used"),
+    ] = None
+    cached_response: Annotated[
+        bool | None,
+        Field(default=None, description="Whether response was served from cache"),
+    ] = None
+    context_length: Annotated[
+        int | None,
+        Field(default=None, description="Total context window length in tokens"),
+    ] = None
+    realtime_mode: Annotated[
+        bool | None,
+        Field(default=None, description="Whether realtime processing was used"),
+    ] = None
+    region: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Cloud region for request (affects pricing in some providers)",
+        ),
+    ] = None
+    tier: Annotated[
+        str | None,
+        Field(default=None, description="Service tier (e.g. standard, enterprise)"),
+    ] = None
+    batch_mode: Annotated[
+        bool | None,
+        Field(
+            default=False,
+            description="Whether batch mode is used (discount usually applies)",
+        ),
+    ] = None
+
+    # Media-related fields
+    images: Annotated[
+        list[ImageMetadata] | None,
+        Field(default=None, description="List of images with their metadata"),
+    ] = None
+    videos: Annotated[
+        list[VideoMetadata] | None,
+        Field(default=None, description="List of videos with their metadata"),
+    ] = None
+    audio: Annotated[
+        list[AudioMetadata] | None,
+        Field(default=None, description="List of audio clips with their metadata"),
+    ] = None
+    audio_output: Annotated[
+        list[AudioMetadata] | None,
+        Field(
+            default=None, description="List of audio output clips with their metadata"
+        ),
+    ] = None
+    # PDF-related fields
+    pdf: Annotated[
+        PDFMetadata | None,
+        Field(default=None, description="Metadata for PDF documents"),
+    ] = None
+
+    # Context caching related fields
+    context_cache_tokens: Annotated[
+        int | None,
+        Field(default=None, description="Number of cached context tokens"),
+    ] = None
+    context_cache_hours: Annotated[
+        float | None,
+        Field(default=None, description="Number of hours to keep context in cache"),
+    ] = None
+
+    # Provider-specific fields
+    google: Annotated[
+        GoogleMetadata | None,
+        Field(
+            default=None,
+            description="Google/Gemini-specific metadata for cost calculation",
+        ),
+    ] = None
+    realtime_tokens: Annotated[
+        int | None,
+        Field(
+            default=None,
+            description="[OpenAI] Number of realtime tokens in the request",
+        ),
+    ] = None
+
+    # Anthropic-specific fields
+    cache_write: Annotated[
+        bool | None,
+        Field(default=None, description="[Anthropic] Whether cache write occurred"),
+    ] = None
+    tool_use_tokens: Annotated[
+        int | None,
+        Field(default=None, description="[Anthropic] Tokens used for tool calls"),
+    ] = None
+
+    # If the provider happens to provide the cost, we should just use that.
+    cost: Annotated[
+        float | None,
+        Field(default=None, description="Cost provided by the API response"),
+    ] = None
+
+
+Provider: TypeAlias = Literal[
+    "anthropic",
+    "azure",
+    "bedrock",
+    "cohere",
+    "gemini",
+    "google",
+    "groq",
+    "litellm",
+    "mistral",
+    "openai",
+    "vertex",
+    "xai",
+]
+LocalProvider: TypeAlias = Literal[
+    "ollama",
+    "vllm",
+]

mirascope/core/bedrock/_utils/__init__.py

@@ -1,13 +1,11 @@
 """Bedrock 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/bedrock/call_response.py

@@ -19,7 +19,7 @@ from ..base import (
     BaseCallResponse,
     transform_tool_outputs,
 )
-from ..base.types import FinishReason
+from ..base.types import CostMetadata, FinishReason
 from ._call_kwargs import BedrockCallKwargs
 from ._types import (
     AssistantMessageTypeDef,
@@ -33,7 +33,6 @@ from ._types import (
     ToolUseBlockContentTypeDef,
     UserMessageTypeDef,
 )
-from ._utils import calculate_cost
 from ._utils._convert_finish_reason_to_common_finish_reasons import (
     _convert_finish_reasons_to_common_finish_reasons,
 )
@@ -140,14 +139,6 @@ class BedrockCallResponse(
         """Returns the number of output tokens."""
         return self.usage["outputTokens"] 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[AssistantMessageTypeDef]:
@@ -245,3 +236,9 @@ class BedrockCallResponse(
         if not self.user_message_param:
             return None
         return BedrockMessageParamConverter.from_provider([self.user_message_param])[0]  # pyright: ignore [reportArgumentType]
+
+    @computed_field
+    @property
+    def cost_metadata(self) -> CostMetadata:
+        """Get metadata required for cost calculation."""
+        return super().cost_metadata

mirascope/core/bedrock/call_response_chunk.py

@@ -9,6 +9,7 @@ from pydantic import SkipValidation
 from types_aiobotocore_bedrock_runtime.literals import StopReasonType as FinishReason
 
 from ..base import BaseCallResponseChunk, types
+from ..base.types import CostMetadata
 from ._types import AsyncStreamOutputChunk, StreamOutputChunk, TokenUsageTypeDef
 from ._utils._convert_finish_reason_to_common_finish_reasons import (
     _convert_finish_reasons_to_common_finish_reasons,
@@ -98,6 +99,11 @@ class BedrockCallResponseChunk(
             return self.usage["outputTokens"]
         return None
 
+    @property
+    def cost_metadata(self) -> CostMetadata:
+        """Returns the cost metadata."""
+        return super().cost_metadata
+
     @property
     def common_finish_reasons(self) -> list[types.FinishReason] | None:
         return _convert_finish_reasons_to_common_finish_reasons(

mirascope/core/bedrock/stream.py

@@ -20,6 +20,7 @@ from types_aiobotocore_bedrock_runtime.type_defs import (
 )
 
 from ..base.stream import BaseStream
+from ..base.types import CostMetadata
 from ._types import (
     AssistantMessageTypeDef,
     InternalBedrockMessageParam,
@@ -28,9 +29,6 @@ from ._types import (
     ToolUseBlockMessageTypeDef,
     UserMessageTypeDef,
 )
-from ._utils import (
-    calculate_cost,
-)
 from .call_params import BedrockCallParams
 from .call_response import BedrockCallResponse
 from .call_response_chunk import BedrockCallResponseChunk
@@ -91,13 +89,6 @@ class BedrockStream(
             ResponseMetadataTypeDef | AsyncResponseMetadataTypeDef
         ) = _DEFAULT_RESPONSE_METADATA
 
-    @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[ToolUseBlockContentTypeDef] | None = None,
@@ -156,3 +147,8 @@ class BedrockStream(
             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/cohere/_utils/__init__.py

@@ -1,13 +1,11 @@
 """Cohere 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/cohere/call_response.py

@@ -16,8 +16,7 @@ from pydantic import 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,
 )
@@ -119,14 +118,6 @@ class CohereCallResponse(
             return self.usage.output_tokens
         return None
 
-    @computed_field
-    @property
-    def cost(self) -> float | None:
-        """Returns the cost of the response."""
-        return calculate_cost(
-            self.input_tokens, self.cached_tokens, self.output_tokens, self.model
-        )
-
     @computed_field
     @cached_property
     def message_param(self) -> ChatMessage:
@@ -202,3 +193,9 @@ class CohereCallResponse(
         if not self.user_message_param:
             return None
         return CohereMessageParamConverter.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/cohere/call_response_chunk.py

@@ -13,6 +13,7 @@ from cohere.types import (
 from pydantic import SkipValidation
 
 from ..base import BaseCallResponseChunk, types
+from ..base.types import CostMetadata
 from ._types import (
     StreamEndStreamedChatResponse,
     StreamStartStreamedChatResponse,
@@ -112,6 +113,11 @@ class CohereCallResponseChunk(
             return self.usage.output_tokens
         return None
 
+    @property
+    def cost_metadata(self) -> CostMetadata:
+        """Returns the cost metadata."""
+        return super().cost_metadata
+
     @property
     def common_finish_reasons(self) -> list[types.FinishReason] | None:
         return _convert_finish_reasons_to_common_finish_reasons(

mirascope/core/cohere/stream.py

@@ -14,7 +14,7 @@ from cohere.types import (
 )
 
 from ..base.stream import BaseStream
-from ._utils import calculate_cost
+from ..base.types import CostMetadata
 from .call_params import CohereCallParams
 from .call_response import CohereCallResponse
 from .call_response_chunk import CohereCallResponseChunk
@@ -59,13 +59,6 @@ class CohereStream(
 
     _provider = "cohere"
 
-    @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[ToolCall] | None = None, content: str | None = None
     ) -> ChatMessage:
@@ -114,3 +107,7 @@ class CohereStream(
             start_time=self.start_time,
             end_time=self.end_time,
         )
+
+    @property
+    def cost_metadata(self) -> CostMetadata:
+        return super().cost_metadata

mirascope/core/costs/__init__.py

@@ -0,0 +1,5 @@
+"""Cost calculation module for LLM API calls."""
+
+from .calculate_cost import calculate_cost
+
+__all__ = ["calculate_cost"]

mirascope/core/{anthropic/_utils/_calculate_cost.py → costs/_anthropic_calculate_cost.py}

@@ -1,10 +1,10 @@
 """Calculate the cost of a completion using the Anthropic API."""
 
+from ..base.types import CostMetadata
+
 
 def calculate_cost(
-    input_tokens: int | float | None,
-    cached_tokens: int | float | None,
-    output_tokens: int | float | None,
+    metadata: CostMetadata,
     model: str = "claude-3-haiku-20240229",
 ) -> float | None:
     """Calculate the cost of a completion using the Anthropic API.
@@ -14,6 +14,8 @@ def calculate_cost(
     Model                                      Input                 Cached                Output
     claude-3-5-haiku                           $0.80  / 1M tokens    $0.08  / 1M tokens    $4.00  / 1M tokens
     claude-3-5-haiku-20241022                  $0.80  / 1M tokens    $0.08  / 1M tokens    $4.00  / 1M tokens
+    claude-3-7-sonnet                          $3.00  / 1M tokens    $0.30  / 1M tokens    $15.00 / 1M tokens
+    claude-3-7-sonnet-20250219                 $3.00  / 1M tokens    $0.30  / 1M tokens    $15.00 / 1M tokens
     claude-3-5-sonnet                          $3.00  / 1M tokens    $0.30  / 1M tokens    $15.00 / 1M tokens
     claude-3-5-sonnet-20241022                 $3.00  / 1M tokens    $0.30  / 1M tokens    $15.00 / 1M tokens
     claude-3-5-sonnet-20240620                 $3.00  / 1M tokens    $0.30  / 1M tokens    $15.00 / 1M tokens
@@ -40,7 +42,7 @@ def calculate_cost(
     """
     pricing = {
         # Anthropic models
-        "claude-3-5-haiku": {
+        "claude-3-5-haiku-latest": {
             "prompt": 0.000_000_8,
             "completion": 0.000_004,
             "cached": 0.000_000_08,
@@ -50,7 +52,17 @@ def calculate_cost(
             "completion": 0.000_004,
             "cached": 0.000_000_08,
         },
-        "claude-3-5-sonnet": {
+        "claude-3-7-sonnet-latest": {
+            "prompt": 0.000_003,
+            "completion": 0.000_015,
+            "cached": 0.000_000_3,
+        },
+        "claude-3-7-sonnet-20250219": {
+            "prompt": 0.000_003,
+            "completion": 0.000_015,
+            "cached": 0.000_000_3,
+        },
+        "claude-3-5-sonnet-latest": {
             "prompt": 0.000_003,
             "completion": 0.000_015,
             "cached": 0.000_000_3,
@@ -65,7 +77,7 @@ def calculate_cost(
             "completion": 0.000_015,
             "cached": 0.000_000_3,
         },
-        "claude-3-haiku": {
+        "claude-3-haiku-latest": {
             "prompt": 0.000_000_8,
             "completion": 0.000_004,
             "cached": 0.000_000_08,
@@ -75,7 +87,7 @@ def calculate_cost(
             "completion": 0.000_004,
             "cached": 0.000_000_08,
         },
-        "claude-3-sonnet": {
+        "claude-3-sonnet-latest": {
             "prompt": 0.000_003,
             "completion": 0.000_015,
             "cached": 0.000_000_3,
@@ -85,7 +97,7 @@ def calculate_cost(
             "completion": 0.000_015,
             "cached": 0.000_000_3,
         },
-        "claude-3-opus": {
+        "claude-3-opus-latest": {
             "prompt": 0.000_015,
             "completion": 0.000_075,
             "cached": 0.000_001_5,
@@ -111,6 +123,11 @@ def calculate_cost(
             "cached": 0,
         },
         # Bedrock models
+        "anthropic.claude-3-7-sonnet-20250219-v1:0": {
+            "prompt": 0.000_003,
+            "completion": 0.000_015,
+            "cached": 0.000_000_3,
+        },
         "anthropic.claude-3-5-sonnet-20241022-v2:0": {
             "prompt": 0.000_003,
             "completion": 0.000_015,
@@ -142,6 +159,11 @@ def calculate_cost(
             "cached": 0.000_001_5,
         },
         # Vertex AI models
+        "claude-3-7-sonnet@20250219": {
+            "prompt": 0.000_003,
+            "completion": 0.000_015,
+            "cached": 0.000_000_3,
+        },
         "claude-3-5-sonnet@20241022": {
             "prompt": 0.000_003,
             "completion": 0.000_015,
@@ -169,20 +191,29 @@ def calculate_cost(
         },
     }
 
-    if input_tokens is None or output_tokens is None:
+    if metadata.input_tokens is None or metadata.output_tokens is None:
         return None
 
-    if cached_tokens is None:
-        cached_tokens = 0
+    if metadata.cached_tokens is None:
+        metadata.cached_tokens = 0
 
     try:
         model_pricing = pricing[model]
     except KeyError:
         return None
 
-    prompt_cost = input_tokens * model_pricing["prompt"]
-    cached_cost = cached_tokens * model_pricing["cached"]
-    completion_cost = output_tokens * model_pricing["completion"]
+    # Calculate cost for text tokens
+    prompt_cost = metadata.input_tokens * model_pricing["prompt"]
+    cached_cost = metadata.cached_tokens * model_pricing["cached"]
+    completion_cost = metadata.output_tokens * model_pricing["completion"]
+
+    # Image tokens are in response tokens
+    # https://docs.anthropic.com/en/docs/build-with-claude/vision#calculate-image-costs
+
+    # PDF documents  tokens are in response tokens
+    # https://docs.anthropic.com/en/docs/build-with-claude/pdf-support#estimate-your-costs
+
+    # Sum all costs
     total_cost = prompt_cost + cached_cost + completion_cost
 
     return total_cost