mirascope 1.20.0__py3-none-any.whl → 1.21.0__py3-none-any.whl

mirascope/core/__init__.py

@@ -14,6 +14,7 @@ from .base import (
     BaseTool,
     BaseToolKit,
     CacheControlPart,
+    CostMetadata,
     DocumentPart,
     FromCallArgs,
     ImagePart,
@@ -74,6 +75,7 @@ __all__ = [
     "BaseTool",
     "BaseToolKit",
     "CacheControlPart",
+    "CostMetadata",
     "DocumentPart",
     "FromCallArgs",
     "ImagePart",

mirascope/core/anthropic/call_response.py

@@ -20,9 +20,7 @@ from ..base.types import CostMetadata
 from ._utils._convert_finish_reason_to_common_finish_reasons import (
     _convert_finish_reasons_to_common_finish_reasons,
 )
-from ._utils._message_param_converter import (
-    AnthropicMessageParamConverter,
-)
+from ._utils._message_param_converter import AnthropicMessageParamConverter
 from .call_params import AnthropicCallParams
 from .dynamic_config import AnthropicDynamicConfig, AsyncAnthropicDynamicConfig
 from .tool import AnthropicTool
@@ -37,6 +35,7 @@ class AnthropicCallResponse(
         MessageParam,
         AnthropicCallParams,
         MessageParam,
+        AnthropicMessageParamConverter,
     ]
 ):
     """A convenience wrapper around the Anthropic `Message` response.
@@ -62,6 +61,10 @@ class AnthropicCallResponse(
     ```
     """
 
+    _message_converter: type[AnthropicMessageParamConverter] = (
+        AnthropicMessageParamConverter
+    )
+
     _provider = "anthropic"
 
     @computed_field

mirascope/core/azure/call_response.py

@@ -38,6 +38,7 @@ class AzureCallResponse(
         ChatRequestMessage,
         AzureCallParams,
         UserMessage,
+        AzureMessageParamConverter,
     ]
 ):
     """A convenience wrapper around the Azure `ChatCompletion` response.
@@ -64,6 +65,7 @@ class AzureCallResponse(
     """
 
     response: SkipValidation[ChatCompletions]
+    _message_converter: type[AzureMessageParamConverter] = AzureMessageParamConverter
 
     _provider = "azure"
 

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, LocalProvider, Provider, Usage
+from .types import (
+    AudioSegment,
+    CostMetadata,
+    JsonableType,
+    LocalProvider,
+    Provider,
+    Usage,
+)
 
 __all__ = [
     "AudioPart",
@@ -50,6 +57,7 @@ __all__ = [
     "BaseType",
     "CacheControlPart",
     "CommonCallParams",
+    "CostMetadata",
     "DocumentPart",
     "FromCallArgs",
     "GenerateJsonSchemaNoTitles",

mirascope/core/base/_create.py

@@ -187,7 +187,7 @@ def create_factory(  # noqa: ANN202
                 start_time = datetime.datetime.now().timestamp() * 1000
                 response = await create(stream=False, **call_kwargs)
                 end_time = datetime.datetime.now().timestamp() * 1000
-                output = TCallResponse(
+                output = TCallResponse(  # pyright: ignore [reportCallIssue]
                     metadata=get_metadata(fn, dynamic_config),
                     response=response,
                     tool_types=tool_types,  # pyright: ignore [reportArgumentType]
@@ -231,7 +231,7 @@ def create_factory(  # noqa: ANN202
                 start_time = datetime.datetime.now().timestamp() * 1000
                 response = create(stream=False, **call_kwargs)
                 end_time = datetime.datetime.now().timestamp() * 1000
-                output = TCallResponse(
+                output = TCallResponse(  # pyright: ignore [reportCallIssue]
                     metadata=get_metadata(fn, dynamic_config),
                     response=response,
                     tool_types=tool_types,  # pyright: ignore [reportArgumentType]

mirascope/core/base/_utils/__init__.py

@@ -1,5 +1,6 @@
 """Internal Utilities."""
 
+from ._base_message_param_converter import BaseMessageParamConverter
 from ._base_type import BaseType, is_base_type
 from ._convert_base_model_to_base_tool import convert_base_model_to_base_tool
 from ._convert_base_type_to_base_tool import convert_base_type_to_base_tool
@@ -46,8 +47,10 @@ from ._setup_extract_tool import setup_extract_tool
 __all__ = [
     "DEFAULT_TOOL_DOCSTRING",
     "AsyncCreateFn",
+    "BaseMessageParamConverter",
     "BaseType",
     "CalculateCost",
+    "CallDecorator",
     "CreateFn",
     "GetJsonOutput",
     "HandleStream",

mirascope/core/base/_utils/_base_message_param_converter.py

@@ -3,7 +3,7 @@
 from abc import ABC, abstractmethod
 from typing import Any
 
-from mirascope.core import BaseMessageParam
+from mirascope.core.base.message_param import BaseMessageParam
 
 
 class BaseMessageParamConverter(ABC):

mirascope/core/base/call_response.py

@@ -19,7 +19,7 @@ from pydantic import (
 )
 
 from ..costs import calculate_cost
-from ._utils import BaseType, get_common_usage
+from ._utils import BaseMessageParamConverter, BaseType, get_common_usage
 from .call_kwargs import BaseCallKwargs
 from .call_params import BaseCallParams
 from .dynamic_config import BaseDynamicConfig
@@ -40,6 +40,9 @@ _ToolMessageParamT = TypeVar("_ToolMessageParamT", bound=Any)
 _CallParamsT = TypeVar("_CallParamsT", bound=BaseCallParams)
 _UserMessageParamT = TypeVar("_UserMessageParamT", bound=Any)
 _BaseCallResponseT = TypeVar("_BaseCallResponseT", bound="BaseCallResponse")
+_BaseMessageParamConverterT = TypeVar(
+    "_BaseMessageParamConverterT", bound=BaseMessageParamConverter
+)
 
 
 def transform_tool_outputs(
@@ -97,6 +100,7 @@ class BaseCallResponse(
         _MessageParamT,
         _CallParamsT,
         _UserMessageParamT,
+        _BaseMessageParamConverterT,
     ],
     ABC,
 ):
@@ -131,6 +135,7 @@ class BaseCallResponse(
     start_time: float
     end_time: float
 
+    _message_converter: type[_BaseMessageParamConverterT]
     _provider: ClassVar[str] = "NO PROVIDER"
     _model: str = "NO MODEL"
 
@@ -313,6 +318,11 @@ class BaseCallResponse(
         """Provider-agnostic user message param."""
         ...
 
+    @property
+    def common_messages(self) -> list[BaseMessageParam]:
+        """Provider-agnostic list of messages."""
+        return self._message_converter.from_provider(self.messages)
+
     @property
     def common_tools(self) -> list[Tool] | None:
         """Provider-agnostic tools."""

mirascope/core/bedrock/call_response.py

@@ -51,6 +51,7 @@ class BedrockCallResponse(
         InternalBedrockMessageParam,
         BedrockCallParams,
         UserMessageTypeDef,
+        BedrockMessageParamConverter,
     ]
 ):
     """A convenience wrapper around the Bedrock `ChatCompletion` response.
@@ -78,6 +79,9 @@ class BedrockCallResponse(
     """
 
     response: SkipValidation[SyncConverseResponseTypeDef | AsyncConverseResponseTypeDef]
+    _message_converter: type[BedrockMessageParamConverter] = (
+        BedrockMessageParamConverter
+    )
 
     _provider = "bedrock"
 

mirascope/core/cohere/call_response.py

@@ -35,6 +35,7 @@ class CohereCallResponse(
         SkipValidation[ChatMessage],
         CohereCallParams,
         SkipValidation[ChatMessage],
+        CohereMessageParamConverter,
     ]
 ):
     """A convenience wrapper around the Cohere `ChatCompletion` response.
@@ -60,6 +61,8 @@ class CohereCallResponse(
     ```
     """
 
+    _message_converter: type[CohereMessageParamConverter] = CohereMessageParamConverter
+
     _provider = "cohere"
 
     @computed_field

mirascope/core/gemini/call_response.py

@@ -36,6 +36,7 @@ class GeminiCallResponse(
         ContentsType,
         GeminiCallParams,
         ContentDict,
+        GeminiMessageParamConverter,
     ]
 ):
     """A convenience wrapper around the Gemini API response.
@@ -62,6 +63,8 @@ class GeminiCallResponse(
     ```
     """
 
+    _message_converter: type[GeminiMessageParamConverter] = GeminiMessageParamConverter
+
     _provider = "gemini"
 
     @computed_field

mirascope/core/google/call_response.py

@@ -40,6 +40,7 @@ class GoogleCallResponse(
         ContentListUnion | ContentListUnionDict,
         GoogleCallParams,
         ContentDict,
+        GoogleMessageParamConverter,
     ]
 ):
     """A convenience wrapper around the Google API response.
@@ -66,6 +67,8 @@ class GoogleCallResponse(
     ```
     """
 
+    _message_converter: type[GoogleMessageParamConverter] = GoogleMessageParamConverter
+
     _provider = "google"
 
     @computed_field

mirascope/core/google/tool.py

@@ -70,17 +70,48 @@ class GoogleTool(BaseTool):
             fn["parameters"] = model_schema
 
         if "parameters" in fn:
+            # Resolve $defs and $ref
             if "$defs" in fn["parameters"]:
-                raise ValueError(
-                    "Unfortunately Google's Google API cannot handle nested structures "
-                    "with $defs."
-                )
+                defs = fn["parameters"].pop("$defs")
+
+                def resolve_refs(schema: dict[str, Any]) -> dict[str, Any]:
+                    """Recursively resolve $ref references using the $defs dictionary."""
+                    # If this is a reference, resolve it
+                    if "$ref" in schema:
+                        ref = schema["$ref"]
+                        if ref.startswith("#/$defs/"):
+                            ref_key = ref.replace("#/$defs/", "")
+                            if ref_key in defs:
+                                # Merge the definition with the current schema (excluding $ref)
+                                resolved = {
+                                    **{k: v for k, v in schema.items() if k != "$ref"},
+                                    **resolve_refs(defs[ref_key]),
+                                }
+                                return resolved
+
+                    # Process all other keys recursively
+                    result = {}
+                    for key, value in schema.items():
+                        if isinstance(value, dict):
+                            result[key] = resolve_refs(value)
+                        elif isinstance(value, list):
+                            result[key] = [
+                                resolve_refs(item) if isinstance(item, dict) else item
+                                for item in value
+                            ]
+                        else:
+                            result[key] = value
+                    return result
+
+                # Resolve all references in the parameters
+                fn["parameters"] = resolve_refs(fn["parameters"])
 
             def handle_enum_schema(prop_schema: dict[str, Any]) -> dict[str, Any]:
                 if "enum" in prop_schema:
                     prop_schema["format"] = "enum"
                 return prop_schema
 
+            # Process properties after resolving references
             fn["parameters"]["properties"] = {
                 prop: {
                     key: value

mirascope/core/groq/call_response.py

@@ -35,6 +35,7 @@ class GroqCallResponse(
         ChatCompletionMessageParam,
         GroqCallParams,
         ChatCompletionUserMessageParam,
+        GroqMessageParamConverter,
     ]
 ):
     """A convenience wrapper around the Groq `ChatCompletion` response.
@@ -59,6 +60,8 @@ class GroqCallResponse(
     ```
     """
 
+    _message_converter: type[GroqMessageParamConverter] = GroqMessageParamConverter
+
     _provider = "groq"
 
     @computed_field

mirascope/core/mistral/call_response.py

@@ -38,6 +38,7 @@ class MistralCallResponse(
         AssistantMessage | SystemMessage | ToolMessage | UserMessage,
         MistralCallParams,
         UserMessage,
+        MistralMessageParamConverter,
     ]
 ):
     """A convenience wrapper around the Mistral `ChatCompletion` response.
@@ -62,6 +63,10 @@ class MistralCallResponse(
     ```
     """
 
+    _message_converter: type[MistralMessageParamConverter] = (
+        MistralMessageParamConverter
+    )
+
     _provider = "mistral"
 
     @property

mirascope/core/openai/call_response.py

@@ -58,6 +58,7 @@ class OpenAICallResponse(
         ChatCompletionMessageParam,
         OpenAICallParams,
         ChatCompletionUserMessageParam,
+        OpenAIMessageParamConverter,
     ]
 ):
     """A convenience wrapper around the OpenAI `ChatCompletion` response.
@@ -84,6 +85,7 @@ class OpenAICallResponse(
     """
 
     response: SkipValidation[ChatCompletion]
+    _message_converter: type[OpenAIMessageParamConverter] = OpenAIMessageParamConverter
 
     _provider = "openai"
 

mirascope/core/vertex/call_response.py

@@ -30,6 +30,7 @@ class VertexCallResponse(
         Content,
         VertexCallParams,
         Content,
+        VertexMessageParamConverter,
     ]
 ):
     """A convenience wrapper around the Vertex AI `GenerateContentResponse`.
@@ -55,6 +56,8 @@ class VertexCallResponse(
     ```
     """
 
+    _message_converter: type[VertexMessageParamConverter] = VertexMessageParamConverter
+
     _provider = "vertex"
 
     @computed_field

mirascope/llm/__init__.py

@@ -1,13 +1,18 @@
-from ..core import LocalProvider, Provider, calculate_cost
+from ..core import CostMetadata, LocalProvider, Provider, calculate_cost
+from ._call import call
+from ._context import context
+from ._override import override
 from .call_response import CallResponse
-from .llm_call import call
-from .llm_override import override
+from .stream import Stream
 
 __all__ = [
     "CallResponse",
+    "CostMetadata",
     "LocalProvider",
     "Provider",
+    "Stream",
     "calculate_cost",
     "call",
+    "context",
     "override",
 ]

mirascope/llm/{llm_call.py → _call.py}

@@ -20,6 +20,7 @@ from ..core.base import (
 from ..core.base._utils import fn_is_async
 from ..core.base.stream_config import StreamConfig
 from ..core.base.types import LocalProvider, Provider
+from ._context import CallArgs, apply_context_overrides_to_call_args
 from ._protocols import (
     AsyncLLMFunctionDecorator,
     CallDecorator,
@@ -193,13 +194,9 @@ def _call(
     ]
 ):
     """Decorator for defining a function that calls a language model."""
-    if provider in get_args(LocalProvider):
-        provider_call, client = _get_local_provider_call(
-            cast(LocalProvider, provider), client
-        )
-    else:
-        provider_call = _get_provider_call(cast(Provider, provider))
-    _original_args = {
+    # Store original call args that will be used for each function call
+    original_call_args: CallArgs = {
+        "provider": provider,
         "model": model,
         "stream": stream,
         "tools": tools,
@@ -214,36 +211,112 @@ def _call(
         fn: Callable[_P, _R | Awaitable[_R]],
     ) -> Callable[
         _P,
-        CallResponse | Stream | Awaitable[CallResponse | Stream],
+        CallResponse
+        | Stream
+        | _ResponseModelT
+        | _ParsedOutputT
+        | (_ResponseModelT | CallResponse)
+        | Awaitable[CallResponse]
+        | Awaitable[Stream]
+        | Awaitable[_ResponseModelT]
+        | Awaitable[_ParsedOutputT]
+        | Awaitable[(_ResponseModelT | CallResponse)],
     ]:
-        decorated = provider_call(**_original_args)(fn)
+        if fn_is_async(fn):
 
-        if fn_is_async(decorated):
-
-            @wraps(decorated)
+            @wraps(fn)
             async def inner_async(
                 *args: _P.args, **kwargs: _P.kwargs
-            ) -> CallResponse | Stream:
+            ) -> (
+                CallResponse
+                | Stream
+                | _ResponseModelT
+                | _ParsedOutputT
+                | (_ResponseModelT | CallResponse)
+            ):
+                # Apply any context overrides to the original call args
+                effective_call_args = apply_context_overrides_to_call_args(
+                    original_call_args
+                )
+
+                # Get the appropriate provider call function with the possibly overridden provider
+                effective_provider = effective_call_args["provider"]
+                effective_client = effective_call_args["client"]
+
+                if effective_provider in get_args(LocalProvider):
+                    provider_call, effective_client = _get_local_provider_call(
+                        cast(LocalProvider, effective_provider), effective_client
+                    )
+                    effective_call_args["client"] = effective_client
+                else:
+                    provider_call = _get_provider_call(
+                        cast(Provider, effective_provider)
+                    )
+
+                # Use the provider-specific call function with overridden args
+                call_kwargs = dict(effective_call_args)
+                del call_kwargs[
+                    "provider"
+                ]  # Remove provider as it's not a parameter to provider_call
+
+                # Get decorated function using provider_call
+                decorated = provider_call(**call_kwargs)(fn)
+
+                # Call the decorated function and wrap the result
                 result = await decorated(*args, **kwargs)
                 return _wrap_result(result)
 
-            inner_async._original_args = _original_args  # pyright: ignore [reportAttributeAccessIssue]
-            inner_async._original_provider_call = provider_call  # pyright: ignore [reportAttributeAccessIssue]
+            inner_async._original_call_args = original_call_args  # pyright: ignore [reportAttributeAccessIssue]
             inner_async._original_fn = fn  # pyright: ignore [reportAttributeAccessIssue]
-            inner_async._original_provider = provider  # pyright: ignore [reportAttributeAccessIssue]
 
             return inner_async
         else:
 
-            @wraps(decorated)
-            def inner(*args: _P.args, **kwargs: _P.kwargs) -> CallResponse | Stream:
+            @wraps(fn)
+            def inner(
+                *args: _P.args, **kwargs: _P.kwargs
+            ) -> (
+                CallResponse
+                | Stream
+                | _ResponseModelT
+                | _ParsedOutputT
+                | (_ResponseModelT | CallResponse)
+            ):
+                # Apply any context overrides to the original call args
+                effective_call_args = apply_context_overrides_to_call_args(
+                    original_call_args
+                )
+
+                # Get the appropriate provider call function with the possibly overridden provider
+                effective_provider = effective_call_args["provider"]
+                effective_client = effective_call_args["client"]
+
+                if effective_provider in get_args(LocalProvider):
+                    provider_call, effective_client = _get_local_provider_call(
+                        cast(LocalProvider, effective_provider), effective_client
+                    )
+                    effective_call_args["client"] = effective_client
+                else:
+                    provider_call = _get_provider_call(
+                        cast(Provider, effective_provider)
+                    )
+
+                # Use the provider-specific call function with overridden args
+                call_kwargs = dict(effective_call_args)
+                del call_kwargs[
+                    "provider"
+                ]  # Remove provider as it's not a parameter to provider_call
+
+                # Get decorated function using provider_call
+                decorated = provider_call(**call_kwargs)(fn)
+
+                # Call the decorated function and wrap the result
                 result = decorated(*args, **kwargs)
                 return _wrap_result(result)
 
-            inner._original_args = _original_args  # pyright: ignore [reportAttributeAccessIssue]
-            inner._original_provider_call = provider_call  # pyright: ignore [reportAttributeAccessIssue]
+            inner._original_call_args = original_call_args  # pyright: ignore [reportAttributeAccessIssue]
             inner._original_fn = fn  # pyright: ignore [reportAttributeAccessIssue]
-            inner._original_provider = provider  # pyright: ignore [reportAttributeAccessIssue]
+
             return inner
 
     return wrapper  # pyright: ignore [reportReturnType]