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

mirascope/core/openai/_utils/_calculate_cost.py

@@ -3,6 +3,7 @@
 
 def calculate_cost(
     input_tokens: int | float | None,
+    cached_tokens: int | float | None,
     output_tokens: int | float | None,
     model: str = "gpt-3.5-turbo-16k",
 ) -> float | None:
@@ -10,196 +11,236 @@ def calculate_cost(
 
     https://openai.com/pricing
 
-    Model                                     Input               Output
-    gpt-4o                                    $2.50 / 1M tokens   $10.00 / 1M tokens
-    gpt-4o-2024-11-20                         $2.50 / 1M tokens   $10.00 / 1M tokens
-    gpt-4o-2024-08-06                         $2.50 / 1M tokens   $10.00 / 1M tokens
-    gpt-4o-2024-05-13                         $5.00 / 1M tokens   $15.00 / 1M tokens
-    gpt-4o-audio-preview                      $2.50 / 1M tokens   $10.00 / 1M tokens
-    gpt-4o-audio-preview-2024-12-17           $2.50 / 1M tokens   $10.00 / 1M tokens
-    gpt-4o-audio-preview-2024-10-01           $2.50 / 1M tokens   $10.00 / 1M tokens
-    gpt-4o-realtime-preview                   $5.00 / 1M tokens   $20.00 / 1M tokens
-    gpt-4o-realtime-preview-2024-12-17        $5.00 / 1M tokens   $20.00 / 1M tokens
-    gpt-4o-realtime-preview-2024-10-01        $5.00 / 1M tokens   $20.00 / 1M tokens
-    gpt-4o-mini                               $0.15 / 1M tokens   $0.60  / 1M tokens
-    gpt-4o-mini-2024-07-18                    $0.15 / 1M tokens   $0.60  / 1M tokens
-    gpt-4o-mini-audio-preview                 $0.15 / 1M tokens   $0.60  / 1M tokens
-    gpt-4o-mini-audio-preview-2024-12-17      $0.15 / 1M tokens   $0.60  / 1M tokens
-    gpt-4o-mini-realtime-preview              $0.60 / 1M tokens   $2.40  / 1M tokens
-    gpt-4o-mini-realtime-preview-2024-12-17   $0.60 / 1M tokens   $2.40  / 1M tokens
-    o1                                        $15.00 / 1M tokens  $60.00 / 1M tokens
-    o1-2024-12-17                             $15.00 / 1M tokens  $60.00 / 1M tokens
-    o1-preview-2024-09-12                     $15.00 / 1M tokens  $60.00 / 1M tokens
-    o3-mini                                   $1.10 / 1M tokens   $4.40  / 1M tokens
-    o3-mini-2025-01-31                        $1.10 / 1M tokens   $4.40  / 1M tokens
-    o1-mini                                   $1.10 / 1M tokens   $4.40  / 1M tokens
-    o1-mini-2024-09-12                        $1.10 / 1M tokens   $4.40  / 1M tokens
-    gpt-4-turbo                               $10.00 / 1M tokens  $30.00 / 1M tokens
-    gpt-4-turbo-2024-04-09                    $10.00 / 1M tokens  $30.00 / 1M tokens
-    gpt-3.5-turbo-0125	                      $0.50 / 1M tokens	  $1.50 / 1M tokens
-    gpt-3.5-turbo-1106	                      $1.00 / 1M tokens	  $2.00 / 1M tokens
-    gpt-4-1106-preview	                      $10.00 / 1M tokens  $30.00 / 1M tokens
-    gpt-4	                                  $30.00 / 1M tokens  $60.00 / 1M tokens
-    text-embedding-3-small	                  $0.02 / 1M tokens
-    text-embedding-3-large	                  $0.13 / 1M tokens
-    text-embedding-ada-0002	                  $0.10 / 1M tokens
+    Model                                     Input               Cached               Output
+    gpt-4o                                    $2.50  / 1M tokens  $1.25 / 1M tokens   $10.00 / 1M tokens
+    gpt-4o-2024-11-20                         $2.50  / 1M tokens  $1.25 / 1M tokens   $10.00 / 1M tokens
+    gpt-4o-2024-08-06                         $2.50  / 1M tokens  $1.25 / 1M tokens   $10.00 / 1M tokens
+    gpt-4o-2024-05-13                         $5.00  / 1M tokens  $2.50 / 1M tokens   $15.00 / 1M tokens
+    gpt-4o-audio-preview                      $2.50  / 1M tokens  $1.25 / 1M tokens   $10.00 / 1M tokens
+    gpt-4o-audio-preview-2024-12-17           $2.50  / 1M tokens  $1.25 / 1M tokens   $10.00 / 1M tokens
+    gpt-4o-audio-preview-2024-10-01           $2.50  / 1M tokens  $1.25 / 1M tokens   $10.00 / 1M tokens
+    gpt-4o-realtime-preview                   $5.00  / 1M tokens  $2.50 / 1M tokens   $20.00 / 1M tokens
+    gpt-4o-realtime-preview-2024-12-17        $5.00  / 1M tokens  $2.50 / 1M tokens   $20.00 / 1M tokens
+    gpt-4o-realtime-preview-2024-10-01        $5.00  / 1M tokens  $2.50 / 1M tokens   $20.00 / 1M tokens
+    gpt-4o-mini                               $0.15  / 1M tokens  $0.08 / 1M tokens   $0.60  / 1M tokens
+    gpt-4o-mini-2024-07-18                    $0.15  / 1M tokens  $0.08 / 1M tokens   $0.60  / 1M tokens
+    gpt-4o-mini-audio-preview                 $0.15  / 1M tokens  $0.08 / 1M tokens   $0.60  / 1M tokens
+    gpt-4o-mini-audio-preview-2024-12-17      $0.15  / 1M tokens  $0.08 / 1M tokens   $0.60  / 1M tokens
+    gpt-4o-mini-realtime-preview              $0.60  / 1M tokens  $0.30 / 1M tokens   $2.40  / 1M tokens
+    gpt-4o-mini-realtime-preview-2024-12-17   $0.60  / 1M tokens  $0.30 / 1M tokens   $2.40  / 1M tokens
+    o1                                        $15.00 / 1M tokens  $7.50 / 1M tokens   $60.00 / 1M tokens
+    o1-2024-12-17                             $15.00 / 1M tokens  $7.50 / 1M tokens   $60.00 / 1M tokens
+    o1-preview-2024-09-12                     $15.00 / 1M tokens  $7.50 / 1M tokens   $60.00 / 1M tokens
+    o3-mini                                   $1.10  / 1M tokens  $0.55 / 1M tokens   $4.40  / 1M tokens
+    o3-mini-2025-01-31                        $1.10  / 1M tokens  $0.55 / 1M tokens   $4.40  / 1M tokens
+    o1-mini                                   $1.10  / 1M tokens  $0.55 / 1M tokens   $4.40  / 1M tokens
+    o1-mini-2024-09-12                        $1.10  / 1M tokens  $0.55 / 1M tokens   $4.40  / 1M tokens
+    gpt-4-turbo                               $10.00 / 1M tokens                      $30.00 / 1M tokens
+    gpt-4-turbo-2024-04-09                    $10.00 / 1M tokens                      $30.00 / 1M tokens
+    gpt-3.5-turbo-0125	                      $0.50  / 1M tokens	                  $1.50  / 1M tokens
+    gpt-3.5-turbo-1106	                      $1.00  / 1M tokens	                  $2.00  / 1M tokens
+    gpt-4-1106-preview	                      $10.00 / 1M tokens                      $30.00 / 1M tokens
+    gpt-4	                                  $30.00 / 1M tokens                      $60.00 / 1M tokens
+    text-embedding-3-small	                  $0.02  / 1M tokens
+    text-embedding-3-large	                  $0.13  / 1M tokens
+    text-embedding-ada-0002	                  $0.10  / 1M tokens
     """
     pricing = {
         "gpt-4o": {
             "prompt": 0.000_002_5,
+            "cached": 0.000_001_25,
             "completion": 0.000_01,
         },
         "gpt-4o-2024-11-20": {
             "prompt": 0.000_002_5,
+            "cached": 0.000_001_25,
             "completion": 0.000_01,
         },
         "gpt-4o-2024-08-06": {
             "prompt": 0.000_002_5,
+            "cached": 0.000_001_25,
             "completion": 0.000_01,
         },
         "gpt-4o-2024-05-13": {
             "prompt": 0.000_005,
+            "cached": 0.000_002_5,
             "completion": 0.000_015,
         },
         "gpt-4o-audio-preview": {
             "prompt": 0.000_002_5,
+            "cached": 0.000_001_25,
             "completion": 0.000_01,
         },
         "gpt-4o-audio-preview-2024-12-17": {
             "prompt": 0.000_002_5,
+            "cached": 0.000_001_25,
             "completion": 0.000_01,
         },
         "gpt-4o-audio-preview-2024-10-01": {
             "prompt": 0.000_002_5,
+            "cached": 0.000_001_25,
             "completion": 0.000_01,
         },
         "gpt-4o-realtime-preview": {
             "prompt": 0.000_005,
+            "cached": 0.000_002_5,
             "completion": 0.000_02,
         },
         "gpt-4o-realtime-preview-2024-12-17": {
             "prompt": 0.000_005,
+            "cached": 0.000_002_5,
             "completion": 0.000_02,
         },
         "gpt-4o-realtime-preview-2024-10-01": {
             "prompt": 0.000_005,
+            "cached": 0.000_002_5,
             "completion": 0.000_02,
         },
         "gpt-4o-mini": {
             "prompt": 0.000_000_15,
+            "cached": 0.000_000_08,
             "completion": 0.000_000_6,
         },
         "gpt-4o-mini-2024-07-18": {
             "prompt": 0.000_000_15,
+            "cached": 0.000_000_08,
             "completion": 0.000_000_6,
         },
         "gpt-4o-mini-audio-preview": {
             "prompt": 0.000_000_15,
+            "cached": 0.000_000_08,
             "completion": 0.000_000_6,
         },
         "gpt-4o-mini-audio-preview-2024-12-17": {
             "prompt": 0.000_000_15,
+            "cached": 0.000_000_08,
             "completion": 0.000_000_6,
         },
         "gpt-4o-mini-realtime-preview": {
             "prompt": 0.000_000_6,
+            "cached": 0.000_000_3,
             "completion": 0.000_002_4,
         },
         "gpt-4o-mini-realtime-preview-2024-12-17": {
             "prompt": 0.000_000_6,
+            "cached": 0.000_000_3,
             "completion": 0.000_002_4,
         },
         "o1": {
             "prompt": 0.000_015,
+            "cached": 0.000_007_5,
             "completion": 0.000_06,
         },
         "o1-2024-12-17": {
             "prompt": 0.000_015,
+            "cached": 0.000_007_5,
             "completion": 0.000_06,
         },
         "o1-preview-2024-09-12": {
             "prompt": 0.000_015,
+            "cached": 0.000_007_5,
             "completion": 0.000_06,
         },
         "o3-mini": {
             "prompt": 0.000_001_1,
+            "cached": 0.000_000_55,
             "completion": 0.000_004_4,
         },
         "o3-mini-2025-01-31": {
             "prompt": 0.000_001_1,
+            "cached": 0.000_000_55,
             "completion": 0.000_004_4,
         },
         "o1-mini": {
             "prompt": 0.000_001_1,
+            "cached": 0.000_000_55,
             "completion": 0.000_004_4,
         },
         "o1-mini-2024-09-12": {
             "prompt": 0.000_001_1,
+            "cached": 0.000_000_55,
             "completion": 0.000_004_4,
         },
         "gpt-4-turbo": {
             "prompt": 0.000_01,
+            "cached": 0,
             "completion": 0.000_03,
         },
         "gpt-4-turbo-2024-04-09": {
             "prompt": 0.000_01,
+            "cached": 0,
             "completion": 0.000_03,
         },
         "gpt-3.5-turbo-0125": {
             "prompt": 0.000_000_5,
+            "cached": 0,
             "completion": 0.000_001_5,
         },
         "gpt-3.5-turbo-1106": {
             "prompt": 0.000_001,
+            "cached": 0,
             "completion": 0.000_002,
         },
         "gpt-4-1106-preview": {
             "prompt": 0.000_01,
+            "cached": 0,
             "completion": 0.000_03,
         },
         "gpt-4": {
             "prompt": 0.000_003,
+            "cached": 0,
             "completion": 0.000_006,
         },
         "gpt-3.5-turbo-4k": {
             "prompt": 0.000_015,
+            "cached": 0,
             "completion": 0.000_02,
         },
         "gpt-3.5-turbo-16k": {
             "prompt": 0.000_003,
+            "cached": 0,
             "completion": 0.000_004,
         },
         "gpt-4-8k": {
             "prompt": 0.000_003,
+            "cached": 0,
             "completion": 0.000_006,
         },
         "gpt-4-32k": {
             "prompt": 0.000_006,
+            "cached": 0,
             "completion": 0.000_012,
         },
         "text-embedding-3-small": {
             "prompt": 0.000_000_02,
-            "completion": 0.000_000_02,
+            "cached": 0,
+            "completion": 0,
         },
         "text-embedding-ada-002": {
             "prompt": 0.000_000_1,
-            "completion": 0.000_000_1,
+            "cached": 0,
+            "completion": 0,
         },
         "text-embedding-3-large": {
             "prompt": 0.000_000_13,
-            "completion": 0.000_000_13,
+            "cached": 0,
+            "completion": 0,
         },
     }
     if input_tokens is None or output_tokens is None:
         return None
 
+    if cached_tokens is None:
+        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"]
-    total_cost = prompt_cost + completion_cost
+    total_cost = prompt_cost + cached_cost + completion_cost
 
     return total_cost

mirascope/core/openai/call_params.py

@@ -18,6 +18,9 @@ if TYPE_CHECKING:
         ChatCompletionAudioParam,
         ChatCompletionModality,  # pyright: ignore [reportAttributeAccessIssue]
     )
+    from openai.types.chat.chat_completion_reasoning_effort import (  # pyright: ignore [reportMissingImports]
+        ChatCompletionReasoningEffort,  # pyright: ignore [reportAttributeAccessIssue]
+    )
 else:
     try:
         from openai.types.chat.chat_completion_audio_param import (  # pyright: ignore [reportMissingImports]
@@ -30,6 +33,14 @@ else:
 
         class ChatCompletionModality: ...
 
+    try:
+        from openai.types.chat.chat_completion_reasoning_effort import (  # pyright: ignore [reportMissingImports]
+            ChatCompletionReasoningEffort,
+        )
+    except ImportError:
+
+        class ChatCompletionReasoningEffort: ...
+
 
 class OpenAICallParams(BaseCallParams):
     """The parameters to use when calling the OpenAI API.
@@ -46,6 +57,7 @@ class OpenAICallParams(BaseCallParams):
         n: ...
         parallel_tool_calls: ...
         presence_penalty: ...
+        reasoning_effort: ...
         response_format: ...
         seed: ...
         stop: ...
@@ -67,6 +79,7 @@ class OpenAICallParams(BaseCallParams):
     n: NotRequired[int | None]
     parallel_tool_calls: NotRequired[bool]
     presence_penalty: NotRequired[float | None]
+    reasoning_effort: NotRequired[ChatCompletionReasoningEffort | None]
     response_format: NotRequired[ResponseFormat]
     seed: NotRequired[int | None]
     stop: NotRequired[str | list[str] | None]

mirascope/core/openai/call_response.py

@@ -118,6 +118,17 @@ class OpenAICallResponse(
         """Returns the number of input tokens."""
         return self.usage.prompt_tokens if self.usage else None
 
+    @computed_field
+    @property
+    def cached_tokens(self) -> int | None:
+        """Returns the number of cached tokens."""
+        return (
+            details.cached_tokens
+            if self.usage
+            and (details := getattr(self.usage, "prompt_tokens_details", None))
+            else None
+        )
+
     @computed_field
     @property
     def output_tokens(self) -> int | None:
@@ -128,7 +139,9 @@ class OpenAICallResponse(
     @property
     def cost(self) -> float | None:
         """Returns the cost of the call."""
-        return calculate_cost(self.input_tokens, self.output_tokens, self.model)
+        return calculate_cost(
+            self.input_tokens, self.cached_tokens, self.output_tokens, self.model
+        )
 
     @computed_field
     @cached_property

mirascope/core/openai/call_response_chunk.py

@@ -79,6 +79,18 @@ class OpenAICallResponseChunk(BaseCallResponseChunk[ChatCompletionChunk, FinishR
             return self.chunk.usage
         return None
 
+    @computed_field
+    @property
+    def cached_tokens(self) -> int | None:
+        """Returns the number of cached tokens."""
+        return (
+            details.cached_tokens
+            if hasattr(self.chunk, "usage")
+            and self.usage
+            and (details := getattr(self.usage, "prompt_tokens_details", None))
+            else None
+        )
+
     @property
     def input_tokens(self) -> int | None:
         """Returns the number of input tokens."""

mirascope/core/openai/stream.py

@@ -87,9 +87,9 @@ class OpenAIStream(
     ) -> AsyncGenerator[tuple[OpenAICallResponseChunk, OpenAITool | None], None]:
         aiter = super().__aiter__()
 
-        async def generator() -> (
-            AsyncGenerator[tuple[OpenAICallResponseChunk, OpenAITool | None], None]
-        ):
+        async def generator() -> AsyncGenerator[
+            tuple[OpenAICallResponseChunk, OpenAITool | None], None
+        ]:
             async for chunk, tool in aiter:
                 if (
                     (choices := chunk.chunk.choices)
@@ -104,7 +104,9 @@ class OpenAIStream(
     @property
     def cost(self) -> float | None:
         """Returns the cost of the call."""
-        return calculate_cost(self.input_tokens, self.output_tokens, self.model)
+        return calculate_cost(
+            self.input_tokens, self.cached_tokens, self.output_tokens, self.model
+        )
 
     def _construct_message_param(
         self,

mirascope/core/vertex/__init__.py

@@ -33,7 +33,6 @@ warnings.warn(
 )
 
 __all__ = [
-    "call",
     "VertexCallParams",
     "VertexCallResponse",
     "VertexCallResponseChunk",
@@ -41,5 +40,6 @@ __all__ = [
     "VertexMessageParam",
     "VertexStream",
     "VertexTool",
+    "call",
     "vertex_call",
 ]

mirascope/core/vertex/_utils/_calculate_cost.py

@@ -3,6 +3,7 @@
 
 def calculate_cost(
     input_chars: int | float | None,
+    cached_chars: int | float | None,
     output_chars: int | float | None,
     model: str = "gemini-1.5-pro",
     context_length: int = 0,

mirascope/core/vertex/_utils/_convert_message_params.py

@@ -106,7 +106,7 @@ def convert_message_params(
                 elif part.type == "audio_url":
                     # Should download the audio to determine the media type
                     audio = _load_media(part.url)
-                    audio_type = get_audio_type(audio)
+                    audio_type = f"audio/{get_audio_type(audio)}"
                     if audio_type not in [
                         "audio/wav",
                         "audio/mp3",

mirascope/core/vertex/call_response.py

@@ -112,6 +112,12 @@ class VertexCallResponse(
         """Returns the number of input tokens."""
         return self.usage.prompt_token_count
 
+    @computed_field
+    @property
+    def cached_tokens(self) -> int:
+        """Returns the number of cached tokens."""
+        return 0
+
     @computed_field
     @property
     def output_tokens(self) -> int:
@@ -122,7 +128,9 @@ class VertexCallResponse(
     @property
     def cost(self) -> float | None:
         """Returns the cost of the call."""
-        return calculate_cost(self.input_tokens, self.output_tokens, self.model)
+        return calculate_cost(
+            self.input_tokens, self.cached_tokens, self.output_tokens, self.model
+        )
 
     @computed_field
     @cached_property

mirascope/core/vertex/call_response_chunk.py

@@ -76,6 +76,11 @@ class VertexCallResponseChunk(
         """Returns the number of input tokens."""
         return None
 
+    @property
+    def cached_tokens(self) -> None:
+        """Returns the number of cached tokens."""
+        return None
+
     @property
     def output_tokens(self) -> None:
         """Returns the number of output tokens."""

mirascope/core/vertex/stream.py

@@ -64,7 +64,9 @@ class VertexStream(
     @property
     def cost(self) -> float | None:
         """Returns the cost of the call."""
-        return calculate_cost(self.input_tokens, self.output_tokens, self.model)
+        return calculate_cost(
+            self.input_tokens, self.cached_tokens, self.output_tokens, self.model
+        )
 
     def _construct_message_param(
         self,

mirascope/core/xai/__init__.py

@@ -0,0 +1,28 @@
+"""The Mirascope xAI Module."""
+
+from typing import TypeAlias
+
+from ..openai import OpenAIMessageParam
+from ._call import xai_call
+from ._call import xai_call as call
+from .call_params import XAICallParams
+from .call_response import XAICallResponse
+from .call_response_chunk import XAICallResponseChunk
+from .dynamic_config import AsyncXAIDynamicConfig, XAIDynamicConfig
+from .stream import XAIStream
+from .tool import XAITool
+
+XAIMessageParam: TypeAlias = OpenAIMessageParam
+
+__all__ = [
+    "AsyncXAIDynamicConfig",
+    "XAICallParams",
+    "XAICallResponse",
+    "XAICallResponseChunk",
+    "XAIDynamicConfig",
+    "XAIMessageParam",
+    "XAIStream",
+    "XAITool",
+    "call",
+    "xai_call",
+]

mirascope/core/xai/_call.py

@@ -0,0 +1,67 @@
+"""The `xai_call` decorator for functions as LLM calls."""
+
+from ..base import call_factory
+from ..openai._utils import (
+    get_json_output,
+    handle_stream,
+    handle_stream_async,
+)
+from ._utils import setup_call
+from .call_params import XAICallParams
+from .call_response import XAICallResponse
+from .call_response_chunk import XAICallResponseChunk
+from .stream import XAIStream
+from .tool import XAITool
+
+xai_call = call_factory(
+    TCallResponse=XAICallResponse,
+    TCallResponseChunk=XAICallResponseChunk,
+    TToolType=XAITool,
+    TStream=XAIStream,
+    default_call_params=XAICallParams(),
+    setup_call=setup_call,  # pyright: ignore [reportArgumentType]
+    get_json_output=get_json_output,
+    handle_stream=handle_stream,  # pyright: ignore [reportArgumentType]
+    handle_stream_async=handle_stream_async,  # pyright: ignore [reportArgumentType]
+)
+"""A decorator for calling the xAI API with a typed function.
+
+usage docs: learn/calls.md
+
+This decorator is used to wrap a typed function that calls the xAI API. It parses
+the prompt template of the wrapped function as the messages array and templates the input
+arguments for the function into each message's template.
+
+Example:
+
+```python
+from mirascope.core import prompt_template
+from mirascope.core.xai import xai_call
+
+
+@xai_call("grok-2-latest")
+def recommend_book(genre: str) -> str:
+    return f"Recommend a {genre} book"
+
+response = recommend_book("fantasy")
+print(response.content)
+```
+
+Args:
+    model (str): The model to use in the API call.
+    stream (bool): Whether to stream the response from the API call.
+    tools (list[BaseTool | Callable]): The tools to use in the API call.
+    response_model (BaseModel | BaseType): The response model into which the response
+        should be structured.
+    output_parser (Callable[[OpenAICallResponse | ResponseModelT], Any]): A function for
+        parsing the call response whose value will be returned in place of the original
+        call response.
+    json_mode (bool): Whether to use JSON Mode.
+    client (None): xAI does not support a custom client.
+    call_params (OpenAICallParams): The `OpenAICallParams` call parameters to use in the
+        API call.
+
+Returns:
+    decorator (Callable): The decorator for turning a typed function into a xAI
+        routed LLM API call.
+"""

mirascope/core/xai/_utils/__init__.py

@@ -0,0 +1,6 @@
+"""xAI utilities for decorator factories."""
+
+from ._calculate_cost import calculate_cost
+from ._setup_call import setup_call
+
+__all__ = ["calculate_cost", "setup_call"]