mirascope 1.16.9__py3-none-any.whl → 1.18.0__py3-none-any.whl

mirascope/core/google/stream.py

@@ -0,0 +1,128 @@
+"""The `GoogleStream` class for convenience around streaming LLM calls.
+
+usage docs: learn/streams.md
+"""
+
+from typing import cast
+
+from google.genai.types import (
+    Candidate,
+    Content,
+    ContentDict,
+    ContentListUnion,
+    ContentListUnionDict,
+    FinishReason,
+    FunctionCall,
+    GenerateContentResponse,
+    PartDict,
+    Tool,
+)
+
+from ..base.stream import BaseStream
+from ._utils import calculate_cost
+from .call_params import GoogleCallParams
+from .call_response import GoogleCallResponse
+from .call_response_chunk import GoogleCallResponseChunk
+from .dynamic_config import GoogleDynamicConfig
+from .tool import GoogleTool
+
+
+class GoogleStream(
+    BaseStream[
+        GoogleCallResponse,
+        GoogleCallResponseChunk,
+        ContentDict,
+        ContentDict,
+        ContentDict,
+        ContentListUnion | ContentListUnionDict,
+        GoogleTool,
+        Tool,
+        GoogleDynamicConfig,
+        GoogleCallParams,
+        FinishReason,
+    ]
+):
+    """A class for convenience around streaming Google LLM calls.
+
+    Example:
+
+    ```python
+    from mirascope.core import prompt_template
+    from mirascope.core.google import google_call
+
+
+    @google_call("google-1.5-flash", stream=True)
+    def recommend_book(genre: str) -> str:
+        return f"Recommend a {genre} book"
+
+    stream = recommend_book("fantasy")  # returns `GoogleStream` instance
+    for chunk, _ in stream:
+        print(chunk.content, end="", flush=True)
+    ```
+    """
+
+    _provider = "google"
+
+    @property
+    def cost(self) -> float | None:
+        """Returns the cost of the call."""
+        return calculate_cost(self.input_tokens, self.output_tokens, self.model)
+
+    def _construct_message_param(
+        self, tool_calls: list[FunctionCall] | None = None, content: str | None = None
+    ) -> ContentDict:
+        """Constructs the message parameter for the assistant."""
+        return {
+            "role": "model",
+            "parts": cast(
+                list[PartDict],
+                [{"text": content}]
+                + (
+                    [
+                        {"function_call": tool_call}
+                        for tool_call in (tool_calls or [])
+                        if tool_calls
+                    ]
+                    or []
+                ),
+            ),
+        }
+
+    def construct_call_response(self) -> GoogleCallResponse:
+        """Constructs the call response from a consumed GoogleStream.
+
+        Raises:
+            ValueError: if the stream has not yet been consumed.
+        """
+        if not hasattr(self, "message_param"):
+            raise ValueError(
+                "No stream response, check if the stream has been consumed."
+            )
+        response = GenerateContentResponse(
+            candidates=[
+                Candidate(
+                    finish_reason=self.finish_reasons[0]
+                    if self.finish_reasons
+                    else FinishReason.STOP,
+                    content=Content(
+                        role=self.message_param["role"],  # pyright: ignore [reportTypedDictNotRequiredAccess]
+                        parts=self.message_param["parts"],  # pyright: ignore [reportTypedDictNotRequiredAccess, reportArgumentType]
+                    ),
+                )
+            ]
+        )
+
+        return GoogleCallResponse(
+            metadata=self.metadata,
+            response=response,
+            tool_types=self.tool_types,
+            prompt_template=self.prompt_template,
+            fn_args=self.fn_args if self.fn_args else {},
+            dynamic_config=self.dynamic_config,
+            messages=self.messages,
+            call_params=self.call_params,
+            call_kwargs=self.call_kwargs,
+            user_message_param=self.user_message_param,
+            start_time=self.start_time,
+            end_time=self.end_time,
+        )

mirascope/core/google/tool.py

@@ -0,0 +1,104 @@
+"""The `GoogleTool` class for easy tool usage with Google's Google LLM calls.
+
+usage docs: learn/tools.md
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from google.genai.types import (
+    FunctionCall,
+    FunctionDeclaration,
+    Tool,
+)
+from pydantic.json_schema import SkipJsonSchema
+
+from ..base import BaseTool
+
+
+class GoogleTool(BaseTool):
+    """A class for defining tools for Google LLM calls.
+
+    Example:
+
+    ```python
+    from mirascope.core import prompt_template
+    from mirascope.core.google import google_call
+
+
+    def format_book(title: str, author: str) -> str:
+        return f"{title} by {author}"
+
+
+    @google_call("google-1.5-flash", tools=[format_book])
+    def recommend_book(genre: str) -> str:
+        return f"Recommend a {genre} book"
+
+
+    response = recommend_book("fantasy")
+    if tool := response.tool:  # returns an `GoogleTool` instance
+        print(tool.call())
+    ```
+    """
+
+    __provider__ = "google"
+
+    tool_call: SkipJsonSchema[FunctionCall]
+
+    @classmethod
+    def tool_schema(cls) -> Tool:
+        """Constructs a JSON Schema tool schema from the `BaseModel` schema defined.
+
+        Example:
+        ```python
+        from mirascope.core.google import GoogleTool
+
+
+        def format_book(title: str, author: str) -> str:
+            return f"{title} by {author}"
+
+
+        tool_type = GoogleTool.type_from_fn(format_book)
+        print(tool_type.tool_schema())  # prints the Google-specific tool schema
+        ```
+        """
+        model_schema = cls.model_json_schema()
+        fn: dict[str, Any] = {"name": cls._name(), "description": cls._description()}
+
+        if model_schema["properties"]:
+            fn["parameters"] = model_schema
+
+        if "parameters" in fn:
+            if "$defs" in fn["parameters"]:
+                raise ValueError(
+                    "Unfortunately Google's Google API cannot handle nested structures "
+                    "with $defs."
+                )
+
+            def handle_enum_schema(prop_schema: dict[str, Any]) -> dict[str, Any]:
+                if "enum" in prop_schema:
+                    prop_schema["format"] = "enum"
+                return prop_schema
+
+            fn["parameters"]["properties"] = {
+                prop: {
+                    key: value
+                    for key, value in handle_enum_schema(prop_schema).items()
+                    if key != "default"
+                }
+                for prop, prop_schema in fn["parameters"]["properties"].items()
+            }
+        return Tool(function_declarations=[FunctionDeclaration(**fn)])
+
+    @classmethod
+    def from_tool_call(cls, tool_call: FunctionCall) -> GoogleTool:
+        """Constructs an `GoogleTool` instance from a `tool_call`.
+
+        Args:
+            tool_call: The Google tool call from which to construct this tool instance.
+        """
+        model_json = {"tool_call": tool_call}
+        if tool_call.args:
+            model_json |= dict(tool_call.args.items())
+        return cls.model_validate(model_json)

mirascope/core/groq/_utils/_convert_message_params.py

@@ -45,6 +45,15 @@ def convert_message_params(
                             },
                         }
                     )
+                elif part.type == "image_url":
+                    converted_content.append(
+                        {
+                            "type": "image_url",
+                            "image_url": {
+                                "url": part.url,
+                            },
+                        }
+                    )
                 elif part.type == "tool_call":
                     converted_message_param = {
                         "role": "assistant",

mirascope/core/groq/_utils/_message_param_converter.py

@@ -8,7 +8,7 @@ from mirascope.core.base import TextPart, ToolResultPart
 from mirascope.core.base._utils._base_message_param_converter import (
     BaseMessageParamConverter,
 )
-from mirascope.core.base.message_param import ToolCallPart
+from mirascope.core.base.message_param import ImageURLPart, ToolCallPart
 from mirascope.core.groq._utils import convert_message_params
 
 
@@ -70,7 +70,14 @@ class GroqMessageParamConverter(BaseMessageParamConverter):
                 for part in content:
                     if "text" in part:
                         contents.append(TextPart(type="text", text=part["text"]))
-                    # TODO: add support for image parts here
+                    elif "image_url" in part:
+                        contents.append(
+                            ImageURLPart(
+                                type="image_url",
+                                url=part["image_url"]["url"],
+                                detail=part["image_url"].get("detail"),
+                            )
+                        )
             if contents:
                 converted.append(
                     BaseMessageParam(role=message_param["role"], content=contents)

mirascope/core/mistral/_utils/_convert_message_params.py

@@ -69,6 +69,13 @@ def convert_message_params(
                             )
                         )
                     )
+                elif part.type == "image_url":
+                    converted_content.append(
+                        {
+                            "type": "image_url",
+                            "image_url": part.url,
+                        }
+                    )
                 elif part.type == "tool_call":
                     converted_message_params.append(
                         AssistantMessage(

mirascope/core/mistral/_utils/_message_param_converter.py

@@ -19,7 +19,22 @@ from mirascope.core.base._utils._base_message_param_converter import (
 from mirascope.core.mistral._utils import convert_message_params
 
 from ...base import BaseMessageParam, ImagePart, TextPart, ToolResultPart
-from ...base.message_param import ToolCallPart
+from ...base.message_param import ImageURLPart, ToolCallPart
+
+
+def _create_image_part_from_data_url(image_url: str) -> ImagePart | None:
+    match = re.match(r"data:(image/\w+);base64,(.+)", image_url)
+    if not match:
+        return None
+    mime_type = match.group(1)
+    image_base64 = match.group(2)
+    image_data = base64.b64decode(image_base64)
+    return ImagePart(
+        type="image",
+        media_type=mime_type,
+        image=image_data,
+        detail=None,
+    )
 
 
 class MistralMessageParamConverter(BaseMessageParamConverter):
@@ -102,44 +117,35 @@ class MistralMessageParamConverter(BaseMessageParamConverter):
                     elif isinstance(chunk, ImageURLChunk):
                         image_url = chunk.image_url
                         if isinstance(image_url, str):
-                            # Extract data from the data URL
-                            match = re.match(r"data:(image/\w+);base64,(.+)", image_url)
-                            if not match:
-                                raise ValueError(
-                                    "ImageURLChunk image_url is not in a supported data URL format."
-                                )
-                            mime_type = match.group(1)
-                            image_base64 = match.group(2)
-                            image_data = base64.b64decode(image_base64)
-                            converted_parts.append(
-                                ImagePart(
-                                    type="image",
-                                    media_type=mime_type,
-                                    image=image_data,
-                                    detail=None,
+                            if image_part := _create_image_part_from_data_url(
+                                image_url
+                            ):
+                                converted_parts.append(image_part)
+                            else:
+                                converted_parts.append(
+                                    ImageURLPart(
+                                        type="image_url",
+                                        url=image_url,
+                                        detail=None,
+                                    )
                                 )
-                            )
+
                         else:
                             img_url_str = image_url.url  # type: ignore
-                            match = re.match(
-                                r"data:(image/\w+);base64,(.+)", img_url_str
-                            )
-                            if not match:
-                                raise ValueError(
-                                    "ImageURLChunk image_url is not in a supported data URL format."
-                                )
-                            mime_type = match.group(1)
-                            image_base64 = match.group(2)
-                            image_data = base64.b64decode(image_base64)
-                            converted_parts.append(
-                                ImagePart(
-                                    type="image",
-                                    media_type=mime_type,
-                                    image=image_data,
-                                    detail=None,
+                            if image_part := _create_image_part_from_data_url(
+                                img_url_str
+                            ):
+                                converted_parts.append(image_part)
+                            else:
+                                converted_parts.append(
+                                    ImageURLPart(
+                                        type="image_url",
+                                        url=img_url_str,
+                                        detail=image_url.detail
+                                        if isinstance(image_url.detail, str)
+                                        else None,
+                                    )
                                 )
-                            )
-
                     elif isinstance(chunk, ReferenceChunk):
                         raise ValueError(
                             "ReferenceChunk is not supported for conversion to BaseMessageParam."

mirascope/core/openai/_utils/_convert_message_params.py

@@ -6,6 +6,8 @@ import json
 from openai.types.chat import ChatCompletionMessageParam
 
 from ...base import BaseMessageParam
+from ...base._utils import get_audio_type
+from ...base._utils._parse_content_template import _load_media
 
 
 def convert_message_params(
@@ -44,6 +46,16 @@ def convert_message_params(
                             },
                         }
                     )
+                elif part.type == "image_url":
+                    converted_content.append(
+                        {
+                            "type": "image_url",
+                            "image_url": {
+                                "url": part.url,
+                                "detail": part.detail if part.detail else "auto",
+                            },
+                        }
+                    )
                 elif part.type == "audio":
                     if part.media_type not in [
                         "audio/wav",
@@ -53,11 +65,36 @@ def convert_message_params(
                             f"Unsupported audio media type: {part.media_type}. "
                             "OpenAI currently only supports WAV and MP3 audio file types."
                         )
+                    data = (
+                        part.audio
+                        if isinstance(part.audio, str)
+                        else base64.b64encode(part.audio).decode("utf-8")
+                    )
                     converted_content.append(
                         {
                             "input_audio": {
                                 "format": part.media_type.split("/")[-1],
-                                "data": base64.b64encode(part.audio).decode("utf-8"),
+                                "data": data,
+                            },
+                            "type": "input_audio",
+                        }
+                    )
+                elif part.type == "audio_url":
+                    audio = _load_media(part.url)
+                    audio_type = get_audio_type(audio)
+                    if audio_type not in [
+                        "audio/wav",
+                        "audio/mp3",
+                    ]:
+                        raise ValueError(
+                            f"Unsupported audio media type: {audio_type}. "
+                            "OpenAI currently only supports WAV and MP3 audio file types."
+                        )
+                    converted_content.append(
+                        {
+                            "input_audio": {
+                                "format": audio_type.split("/")[-1],
+                                "data": base64.b64encode(audio).decode("utf-8"),
                             },
                             "type": "input_audio",
                         }

mirascope/core/openai/_utils/_message_param_converter.py

@@ -1,12 +1,19 @@
 """This module contains the OpenAIMessageParamConverter class."""
 
 import json
+from collections.abc import Iterable
 from typing import cast
 
 from openai.types.chat import ChatCompletionMessageParam
 
 from mirascope.core import BaseMessageParam
-from mirascope.core.base import TextPart, ToolCallPart, ToolResultPart
+from mirascope.core.base import (
+    AudioPart,
+    ImageURLPart,
+    TextPart,
+    ToolCallPart,
+    ToolResultPart,
+)
 from mirascope.core.base._utils._base_message_param_converter import (
     BaseMessageParamConverter,
 )
@@ -57,12 +64,29 @@ class OpenAIMessageParamConverter(BaseMessageParamConverter):
                     BaseMessageParam(role=message_param["role"], content=content)
                 )
                 continue
-            elif isinstance(content, list):
+            elif isinstance(content, Iterable):
                 for part in content:
-                    if "text" in part:
+                    if part["type"] == "text":
                         contents.append(TextPart(type="text", text=part["text"]))
+                    elif part["type"] == "image_url":
+                        image_url = part["image_url"]
+                        contents.append(
+                            ImageURLPart(
+                                type="image_url",
+                                url=image_url["url"],
+                                detail=image_url.get("detail", None),
+                            )
+                        )
+                    elif part["type"] == "input_audio":
+                        input_audio = part["input_audio"]
+                        contents.append(
+                            AudioPart(
+                                type="audio",
+                                media_type=f"audio/{input_audio['format']}",
+                                audio=input_audio["data"],
+                            )
+                        )
                     else:
-                        # TODO: add support for image and audio parts here
                         raise ValueError(part["refusal"])  # pyright: ignore [reportGeneralTypeIssues]
             if tool_calls := message_param.get("tool_calls"):
                 for tool_call in tool_calls:

mirascope/core/vertex/__init__.py

@@ -1,5 +1,7 @@
 """The Mirascope Vertex Module."""
 
+import inspect
+import warnings
 from typing import TypeAlias
 
 from google.cloud.aiplatform_v1beta1.types import FunctionResponse
@@ -17,6 +19,19 @@ from .tool import VertexTool
 
 VertexMessageParam: TypeAlias = Content | FunctionResponse | BaseMessageParam
 
+warnings.warn(
+    inspect.cleandoc("""
+    The `mirascope.core.gemini` module is deprecated and will be removed in a future release.
+    Please use the `mirascope.core.google` module instead.
+                     
+    You can use Vertex AI by setting a custom `client` or environment variables.
+    See these docs for reference:
+        - Google AI SDK Custom Client: https://googleapis.github.io/python-genai/#create-a-client
+        - Mirascope Google Custom Client: https://mirascope.com/learn/calls/#__tabbed_39_5
+    """),
+    category=DeprecationWarning,
+)
+
 __all__ = [
     "call",
     "VertexCallParams",

mirascope/core/vertex/_utils/_convert_message_params.py

@@ -1,10 +1,16 @@
 """Utility for converting `BaseMessageParam` to `Content`"""
 
+import base64
+import io
+
+import PIL.Image
 from google.cloud.aiplatform_v1beta1.types import content as gapic_content_types
 from google.cloud.aiplatform_v1beta1.types import tool as gapic_tool_types
 from vertexai.generative_models import Content, Image, Part
 
 from ...base import BaseMessageParam
+from ...base._utils import get_audio_type
+from ...base._utils._parse_content_template import _load_media
 
 
 def convert_message_params(
@@ -22,15 +28,11 @@ def convert_message_params(
                 )  # pragma: no cover
             converted_message_params += [
                 Content(
-                    role="user",
+                    role="system",
                     parts=[
                         Part.from_text(content) if isinstance(content, str) else content
                     ],
                 ),
-                Content(
-                    role="model",
-                    parts=[Part.from_text("Ok! I will adhere to this system message.")],
-                ),
             ]
         elif isinstance((content := message_param.content), str):
             converted_message_params.append(
@@ -56,6 +58,29 @@ def convert_message_params(
                         )
                     image = Image.from_bytes(part.image)
                     converted_content.append(Part.from_image(image))
+                elif part.type == "image_url":
+                    # Should download the image to determine the media type
+                    image = PIL.Image.open(io.BytesIO(_load_media(part.url)))
+                    media_type = (
+                        PIL.Image.MIME[image.format]
+                        if image.format
+                        else "image/unknown"
+                    )
+                    if media_type not in [
+                        "image/jpeg",
+                        "image/png",
+                        "image/webp",
+                        "image/heic",
+                        "image/heif",
+                    ]:
+                        raise ValueError(
+                            f"Unsupported image media type: {media_type}. "
+                            "Gemini currently only supports JPEG, PNG, WebP, HEIC, "
+                            "and HEIF images."
+                        )
+                    converted_content.append(
+                        Part.from_uri(part.url, mime_type=media_type)
+                    )
                 elif part.type == "audio":
                     if part.media_type not in [
                         "audio/wav",
@@ -71,7 +96,32 @@ def convert_message_params(
                             "and FLAC audio file types."
                         )
                     converted_content.append(
-                        Part.from_data(mime_type=part.media_type, data=part.audio)
+                        Part.from_data(
+                            mime_type=part.media_type,
+                            data=part.audio
+                            if isinstance(part.audio, bytes)
+                            else base64.b64decode(part.audio),
+                        )
+                    )
+                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)
+                    if audio_type not in [
+                        "audio/wav",
+                        "audio/mp3",
+                        "audio/aiff",
+                        "audio/aac",
+                        "audio/ogg",
+                        "audio/flac",
+                    ]:
+                        raise ValueError(
+                            f"Unsupported audio media type: {audio_type}. "
+                            "Gemini currently only supports WAV, MP3, AIFF, AAC, OGG, "
+                            "and FLAC audio file types."
+                        )
+                    converted_content.append(
+                        Part.from_uri(part.url, mime_type=audio_type)
                     )
                 elif part.type == "tool_call":
                     if converted_content:

mirascope/core/vertex/_utils/_message_param_converter.py

@@ -7,7 +7,7 @@ from mirascope.core.base import DocumentPart, ImagePart, TextPart
 from mirascope.core.base._utils._base_message_param_converter import (
     BaseMessageParamConverter,
 )
-from mirascope.core.base.message_param import ToolCallPart, ToolResultPart
+from mirascope.core.base.message_param import ImageURLPart, ToolCallPart, ToolResultPart
 from mirascope.core.vertex._utils import convert_message_params
 
 
@@ -87,10 +87,18 @@ class VertexMessageParamConverter(BaseMessageParamConverter):
                         )
 
                 elif part.file_data:
-                    # part.file_data.file_uri has Google storage URI like "gs://bucket_name/file_name"
-                    raise ValueError(
-                        f"FileData.file_uri is not support: {part.file_data}. Cannot convert to BaseMessageParam."
-                    )
+                    if _is_image_mime(part.file_data.mime_type):
+                        contents.append(
+                            ImageURLPart(
+                                type="image_url",
+                                url=part.file_data.file_uri,
+                                detail=None,
+                            )
+                        )
+                    else:
+                        raise ValueError(
+                            f"FileData.file_uri is not support: {part.file_data}. Cannot convert to BaseMessageParam."
+                        )
                 elif part.function_call:
                     converted.append(
                         BaseMessageParam(