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

mirascope/core/google/_utils/_message_param_converter.py

@@ -0,0 +1,153 @@
+from typing import cast
+
+from google.genai import Client
+from google.genai.types import (
+    Content,
+    ContentDict,
+    ContentOrDict,
+)
+
+from mirascope.core import BaseMessageParam
+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 (
+    AudioURLPart,
+    ImageURLPart,
+    ToolCallPart,
+    ToolResultPart,
+)
+from mirascope.core.gemini._utils._message_param_converter import _is_audio_mime
+from mirascope.core.google._utils import convert_message_params
+
+
+def _is_image_mime(mime_type: str) -> bool:
+    return mime_type in ["image/jpeg", "image/png", "image/gif", "image/webp"]
+
+
+def _to_image_part(mime_type: str, data: bytes) -> ImagePart:
+    if not _is_image_mime(mime_type):
+        raise ValueError(
+            f"Unsupported image media type: {mime_type}. "
+            "Expected one of: image/jpeg, image/png, image/gif, image/webp."
+        )
+    return ImagePart(type="image", media_type=mime_type, image=data, detail=None)
+
+
+def _to_document_part(mime_type: str, data: bytes) -> DocumentPart:
+    if mime_type != "application/pdf":
+        raise ValueError(
+            f"Unsupported document media type: {mime_type}. "
+            "Only application/pdf is supported."
+        )
+    return DocumentPart(type="document", media_type=mime_type, document=data)
+
+
+class GoogleMessageParamConverter(BaseMessageParamConverter):
+    """Converts between Google `ContentDict` and Mirascope `BaseMessageParam`."""
+
+    @staticmethod
+    def to_provider(
+        message_params: list[BaseMessageParam], client: Client | None = None
+    ) -> list[ContentDict]:
+        """
+        Convert from Mirascope `BaseMessageParam` to Google `ContentDict`.
+        """
+        return convert_message_params(
+            cast(list[BaseMessageParam | ContentDict], message_params),
+            client or Client(),
+        )
+
+    @staticmethod
+    def from_provider(message_params: list[ContentOrDict]) -> list[BaseMessageParam]:
+        """
+        Convert from Google's `ContentDict` to Mirascope `BaseMessageParam`.
+        """
+        converted: list[BaseMessageParam] = []
+        for message_param in message_params:
+            if isinstance(message_param, dict):
+                message_param = Content.model_validate(message_param)
+            role: str = "assistant"
+            content_list = []
+            for part in message_param.parts or []:
+                if part.text:
+                    content_list.append(TextPart(type="text", text=part.text))
+
+                elif part.inline_data:
+                    blob = part.inline_data
+                    mime = blob.mime_type or ""
+                    data = blob.data or b""
+                    if _is_image_mime(mime or ""):
+                        content_list.append(_to_image_part(mime, data))
+                    elif mime == "application/pdf":
+                        content_list.append(_to_document_part(mime, data))
+                    else:
+                        raise ValueError(
+                            f"Unsupported inline_data mime type: {mime}. Cannot convert to BaseMessageParam."
+                        )
+
+                elif part.file_data:
+                    if _is_image_mime(cast(str, part.file_data.mime_type)):
+                        content_list.append(
+                            ImageURLPart(
+                                type="image_url",
+                                url=cast(str, part.file_data.file_uri),
+                                detail=None,
+                            )
+                        )
+                    elif _is_audio_mime(cast(str, part.file_data.mime_type)):
+                        content_list.append(
+                            AudioURLPart(
+                                type="audio_url",
+                                url=cast(str, part.file_data.file_uri),
+                            )
+                        )
+                    else:
+                        raise ValueError(
+                            f"Unsupported file_data mime type: {part.file_data.mime_type}. Cannot convert to BaseMessageParam."
+                        )
+                elif part.function_call:
+                    converted.append(
+                        BaseMessageParam(
+                            role=role,
+                            content=[
+                                ToolCallPart(
+                                    type="tool_call",
+                                    name=part.function_call.name,  # pyright: ignore [reportArgumentType]
+                                    args=part.function_call.args,
+                                )
+                            ],
+                        )
+                    )
+                elif part.function_response:
+                    converted.append(
+                        BaseMessageParam(
+                            role=role,
+                            content=[
+                                ToolResultPart(
+                                    type="tool_result",
+                                    name=part.function_response.name,  # pyright: ignore [reportArgumentType]
+                                    content=part.function_response.response[  # pyright: ignore [reportArgumentType, reportOptionalSubscript]
+                                        "result"
+                                    ],
+                                    id=None,
+                                    is_error=False,
+                                )
+                            ],
+                        )
+                    )
+                else:
+                    raise ValueError(
+                        "Part does not contain any supported content (text, image, or document)."
+                    )
+
+            if len(content_list) == 1 and isinstance(content_list[0], TextPart):
+                converted.append(
+                    BaseMessageParam(role=role, content=content_list[0].text)
+                )
+            else:
+                if content_list:
+                    converted.append(BaseMessageParam(role=role, content=content_list))
+
+        return converted

mirascope/core/google/_utils/_setup_call.py

@@ -0,0 +1,180 @@
+"""This module contains the setup_call function, which is used to set up the"""
+
+import contextlib
+from collections.abc import Awaitable, Callable, Generator
+from typing import Any, cast, overload
+
+from google.genai import Client
+from google.genai.types import (
+    ContentDict,
+    FunctionCallingConfig,
+    FunctionCallingConfigMode,
+    GenerateContentConfig,
+    GenerateContentConfigDict,
+    GenerateContentResponse,
+    Part,
+    PartDict,
+    ToolConfig,
+    ToolListUnion,
+)
+from pydantic import BaseModel
+
+from ...base import BaseMessageParam, BaseTool, _utils
+from ...base._utils import (
+    AsyncCreateFn,
+    CreateFn,
+    fn_is_async,
+    get_async_create_fn,
+    get_create_fn,
+)
+from ...base.call_params import CommonCallParams
+from ...base.stream_config import StreamConfig
+from .._call_kwargs import GoogleCallKwargs
+from ..call_params import GoogleCallParams
+from ..dynamic_config import GoogleDynamicConfig
+from ..tool import GoogleTool
+from ._convert_common_call_params import convert_common_call_params
+from ._convert_message_params import convert_message_params
+
+
+def _get_generate_content_config(
+    config: GenerateContentConfig | GenerateContentConfigDict,
+) -> GenerateContentConfig:
+    if isinstance(config, dict):
+        return GenerateContentConfig.model_validate(config)
+    return config
+
+
+@contextlib.contextmanager
+def _generate_content_config_context(
+    call_kwargs: GoogleCallKwargs,
+) -> Generator[GenerateContentConfig, None, None]:
+    config = call_kwargs.get("config", {})
+    config = _get_generate_content_config(config)
+    yield config
+    call_kwargs["config"] = config
+
+
+@overload
+def setup_call(
+    *,
+    model: str,
+    client: Client | None,
+    fn: Callable[..., Awaitable[GoogleDynamicConfig]],
+    fn_args: dict[str, Any],
+    dynamic_config: GoogleDynamicConfig,
+    tools: list[type[BaseTool] | Callable] | None,
+    json_mode: bool,
+    call_params: GoogleCallParams | CommonCallParams,
+    response_model: type[BaseModel] | None,
+    stream: bool | StreamConfig,
+) -> tuple[
+    AsyncCreateFn[GenerateContentResponse, GenerateContentResponse],
+    str | None,
+    list[ContentDict],
+    list[type[GoogleTool]] | None,
+    GoogleCallKwargs,
+]: ...
+
+
+@overload
+def setup_call(
+    *,
+    model: str,
+    client: Client | None,
+    fn: Callable[..., GoogleDynamicConfig],
+    fn_args: dict[str, Any],
+    dynamic_config: GoogleDynamicConfig,
+    tools: list[type[BaseTool] | Callable] | None,
+    json_mode: bool,
+    call_params: GoogleCallParams | CommonCallParams,
+    response_model: type[BaseModel] | None,
+    stream: bool | StreamConfig,
+) -> tuple[
+    CreateFn[GenerateContentResponse, GenerateContentResponse],
+    str | None,
+    list[ContentDict],
+    list[type[GoogleTool]] | None,
+    GoogleCallKwargs,
+]: ...
+
+
+def setup_call(
+    *,
+    model: str,
+    client: Client | None,
+    fn: Callable[..., GoogleDynamicConfig | Awaitable[GoogleDynamicConfig]],
+    fn_args: dict[str, Any],
+    dynamic_config: GoogleDynamicConfig,
+    tools: list[type[BaseTool] | Callable] | None,
+    json_mode: bool,
+    call_params: GoogleCallParams | CommonCallParams,
+    response_model: type[BaseModel] | None,
+    stream: bool | StreamConfig,
+) -> tuple[
+    CreateFn[GenerateContentResponse, GenerateContentResponse]
+    | AsyncCreateFn[GenerateContentResponse, GenerateContentResponse],
+    str | None,
+    list[ContentDict],
+    list[type[GoogleTool]] | None,
+    GoogleCallKwargs,
+]:
+    prompt_template, messages, tool_types, base_call_kwargs = _utils.setup_call(
+        fn,
+        fn_args,
+        dynamic_config,
+        tools,
+        GoogleTool,
+        call_params,
+        convert_common_call_params,
+    )
+    call_kwargs = cast(GoogleCallKwargs, base_call_kwargs)
+    messages = cast(list[BaseMessageParam | ContentDict], messages)
+
+    if client is None:
+        client = Client()
+
+    messages = convert_message_params(messages, client)
+
+    if messages[0] and messages[0].get("role") == "system":
+        with _generate_content_config_context(call_kwargs) as config:
+            config.system_instruction = [
+                Part.model_validate(part)
+                for part in (messages.pop(0).get("parts") or [])
+            ]
+
+    if json_mode:
+        with _generate_content_config_context(call_kwargs) as config:
+            if not tools:
+                config.response_mime_type = "application/json"
+        messages[-1]["parts"].append(  # pyright: ignore [reportTypedDictNotRequiredAccess, reportOptionalMemberAccess, reportArgumentType]
+            PartDict(text=_utils.json_mode_content(response_model))
+        )  # pyright: ignore [reportTypedDictNotRequiredAccess, reportOptionalMemberAccess, reportArgumentType]
+    elif response_model:
+        assert tool_types, "At least one tool must be provided for extraction."
+        with _generate_content_config_context(call_kwargs) as config:
+            config.tool_config = ToolConfig(
+                function_calling_config=FunctionCallingConfig(
+                    mode=FunctionCallingConfigMode.ANY,
+                    allowed_function_names=[tool_types[0]._name()],
+                )
+            )
+    config_tools = call_kwargs.pop("tools", None)
+    if config_tools:
+        with _generate_content_config_context(call_kwargs) as config:
+            config.tools = cast(ToolListUnion, config_tools)
+
+    call_kwargs |= {"model": model, "contents": messages}
+
+    create = (
+        get_async_create_fn(
+            client.aio.models.generate_content,
+            client.aio.models.generate_content_stream,
+        )
+        if fn_is_async(fn)
+        else get_create_fn(
+            client.models.generate_content, client.models.generate_content_stream
+        )
+    )
+
+    return create, prompt_template, messages, tool_types, call_kwargs

mirascope/core/google/call_params.py

@@ -0,0 +1,22 @@
+"""usage docs: learn/calls.md#provider-specific-parameters"""
+
+from __future__ import annotations
+
+from google.genai.types import (
+    GenerateContentConfigOrDict,
+)
+from typing_extensions import NotRequired
+
+from ..base import BaseCallParams
+
+
+class GoogleCallParams(BaseCallParams):
+    """The parameters to use when calling the Google API.
+
+    [Google API Reference](https://ai.google.dev/google-api/docs/text-generation?lang=python)
+
+    Attributes:
+        config: ...
+    """
+
+    config: NotRequired[GenerateContentConfigOrDict]

mirascope/core/google/call_response.py

@@ -0,0 +1,202 @@
+"""This module contains the `GoogleCallResponse` class.
+
+usage docs: learn/calls.md#handling-responses
+"""
+
+from functools import cached_property
+
+from google.genai.types import (
+    ContentDict,
+    ContentListUnion,
+    ContentListUnionDict,
+    FunctionResponseDict,
+    GenerateContentResponse,
+    PartDict,
+    # Import manually SchemaDict to avoid Pydantic error
+    SchemaDict,  # noqa: F401
+    Tool,
+)
+from pydantic import computed_field
+
+from .. import BaseMessageParam
+from ..base import BaseCallResponse, transform_tool_outputs
+from ..base.types import FinishReason
+from ._utils import calculate_cost
+from ._utils._convert_finish_reason_to_common_finish_reasons import (
+    _convert_finish_reasons_to_common_finish_reasons,
+)
+from ._utils._message_param_converter import GoogleMessageParamConverter
+from .call_params import GoogleCallParams
+from .dynamic_config import GoogleDynamicConfig
+from .tool import GoogleTool
+
+
+class GoogleCallResponse(
+    BaseCallResponse[
+        GenerateContentResponse,
+        GoogleTool,
+        Tool,
+        GoogleDynamicConfig,
+        ContentListUnion | ContentListUnionDict,
+        GoogleCallParams,
+        ContentDict,
+    ]
+):
+    """A convenience wrapper around the Google API response.
+
+    When calling the Google API using a function decorated with `google_call`, the
+    response will be a `GoogleCallResponse` instance with properties that allow for
+    more convenient access to commonly used attributes.
+
+
+    Example:
+
+    ```python
+    from mirascope.core import prompt_template
+    from mirascope.core.google import google_call
+
+
+    @google_call("google-1.5-flash")
+    def recommend_book(genre: str) -> str:
+        return f"Recommend a {genre} book"
+
+
+    response = recommend_book("fantasy")  # response is an `GoogleCallResponse` instance
+    print(response.content)
+    ```
+    """
+
+    _provider = "google"
+
+    @property
+    def content(self) -> str:
+        """Returns the contained string content for the 0th choice."""
+        return self.response.candidates[0].content.parts[0].text  # pyright: ignore [reportOptionalSubscript, reportReturnType, reportOptionalMemberAccess, reportOptionalIterable]
+
+    @property
+    def finish_reasons(self) -> list[str]:
+        """Returns the finish reasons of the response."""
+
+        return [
+            candidate.finish_reason.value
+            for candidate in (self.response.candidates or [])
+            if candidate and candidate.finish_reason is not None
+        ]
+
+    @property
+    def model(self) -> str:
+        """Returns the model name.
+
+        google.generativeai does not return model, so we return the model provided by
+        the user.
+        """
+        return self._model
+
+    @property
+    def id(self) -> str | None:
+        """Returns the id of the response.
+
+        google.generativeai does not return an id
+        """
+        return None
+
+    @property
+    def usage(self) -> None:
+        """Returns the usage of the chat completion.
+
+        google.generativeai does not have Usage, so we return None
+        """
+        return None
+
+    @property
+    def input_tokens(self) -> None:
+        """Returns the number of input tokens."""
+        return None
+
+    @property
+    def output_tokens(self) -> None:
+        """Returns the number of output tokens."""
+        return None
+
+    @property
+    def cost(self) -> float | None:
+        """Returns the cost of the call."""
+        return calculate_cost(self.input_tokens, self.output_tokens, self.model)
+
+    @computed_field
+    @cached_property
+    def message_param(self) -> ContentDict:
+        """Returns the models's response as a message parameter."""
+        return {"role": "model", "parts": self.response.candidates[0].content.parts}  # pyright: ignore [reportReturnType, reportOptionalSubscript, reportOptionalMemberAccess]
+
+    @computed_field
+    @cached_property
+    def tools(self) -> list[GoogleTool] | None:
+        """Returns the list of tools for the 0th candidate's 0th content part."""
+        if self.tool_types is None:
+            return None
+
+        extracted_tools = []
+        for part in self.response.candidates[0].content.parts:  # pyright: ignore [reportReturnType, reportOptionalSubscript, reportOptionalMemberAccess, reportOptionalIterable]
+            tool_call = part.function_call
+            for tool_type in self.tool_types:
+                if tool_call.name == tool_type._name():  # pyright: ignore [reportOptionalMemberAccess]
+                    extracted_tools.append(tool_type.from_tool_call(tool_call))  # pyright: ignore [reportArgumentType]
+                    break
+
+        return extracted_tools
+
+    @computed_field
+    @cached_property
+    def tool(self) -> GoogleTool | None:
+        """Returns the 0th tool for the 0th candidate's 0th content part.
+
+        Raises:
+            ValidationError: if the tool call doesn't match the tool's schema.
+        """
+        tools = self.tools
+        if tools:
+            return tools[0]
+        return None
+
+    @classmethod
+    @transform_tool_outputs
+    def tool_message_params(
+        cls, tools_and_outputs: list[tuple[GoogleTool, str]]
+    ) -> list[ContentDict]:
+        """Returns the tool message parameters for tool call results.
+
+        Args:
+            tools_and_outputs: The list of tools and their outputs from which the tool
+                message parameters should be constructed.
+
+        Returns:
+            The list of constructed `FunctionResponse` parameters.
+        """
+        return [
+            {
+                "role": "user",
+                "parts": [
+                    PartDict(
+                        function_response=FunctionResponseDict(
+                            name=tool._name(), response={"result": output}
+                        )
+                    )
+                    for tool, output in tools_and_outputs
+                ],
+            }
+        ]
+
+    @property
+    def common_finish_reasons(self) -> list[FinishReason] | None:
+        return _convert_finish_reasons_to_common_finish_reasons(self.finish_reasons)
+
+    @property
+    def common_message_param(self) -> BaseMessageParam:
+        return GoogleMessageParamConverter.from_provider([self.message_param])[0]
+
+    @property
+    def common_user_message_param(self) -> BaseMessageParam | None:
+        if not self.user_message_param:
+            return None
+        return GoogleMessageParamConverter.from_provider([self.user_message_param])[0]

mirascope/core/google/call_response_chunk.py

@@ -0,0 +1,97 @@
+"""This module contains the `GoogleCallResponseChunk` class.
+
+usage docs: learn/streams.md#handling-streamed-responses
+"""
+
+from typing import cast
+
+from google.genai.types import FinishReason as GoogleFinishReason
+from google.genai.types import GenerateContentResponse
+
+from mirascope.core.base.types import FinishReason
+
+from ..base import BaseCallResponseChunk
+from ._utils._convert_finish_reason_to_common_finish_reasons import (
+    _convert_finish_reasons_to_common_finish_reasons,
+)
+
+
+class GoogleCallResponseChunk(
+    BaseCallResponseChunk[GenerateContentResponse, GoogleFinishReason]
+):
+    """A convenience wrapper around the Google API streamed response chunks.
+
+    When calling the Google API using a function decorated with `google_call` and
+    `stream` set to `True`, the stream will contain `GoogleCallResponseChunk` instances
+
+    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")  # response is an `GoogleStream`
+    for chunk, _ in stream:
+        print(chunk.content, end="", flush=True)
+    ```
+    """
+
+    @property
+    def content(self) -> str:
+        """Returns the chunk content for the 0th choice."""
+        return self.chunk.candidates[0].content.parts[0].text  # pyright: ignore [reportOptionalMemberAccess, reportOptionalSubscript, reportReturnType]
+
+    @property
+    def finish_reasons(self) -> list[GoogleFinishReason]:
+        """Returns the finish reasons of the response."""
+        return [
+            candidate.finish_reason
+            for candidate in (self.chunk.candidates or [])
+            if candidate.finish_reason is not None
+        ]
+
+    @property
+    def model(self) -> None:
+        """Returns the model name.
+
+        google.generativeai does not return model, so we return None
+        """
+        return None
+
+    @property
+    def id(self) -> str | None:
+        """Returns the id of the response.
+
+        google.generativeai does not return an id
+        """
+        return None
+
+    @property
+    def usage(self) -> None:
+        """Returns the usage of the chat completion.
+
+        google.generativeai does not have Usage, so we return None
+        """
+        return None
+
+    @property
+    def input_tokens(self) -> None:
+        """Returns the number of input tokens."""
+        return None
+
+    @property
+    def output_tokens(self) -> None:
+        """Returns the number of output tokens."""
+        return None
+
+    @property
+    def common_finish_reasons(self) -> list[FinishReason] | None:
+        return _convert_finish_reasons_to_common_finish_reasons(
+            cast(list[str], self.finish_reasons)
+        )

mirascope/core/google/dynamic_config.py

@@ -0,0 +1,26 @@
+"""This module defines the function return type for functions as LLM calls."""
+
+from google.genai import Client
+from google.genai.types import ContentListUnion, ContentListUnionDict
+
+from ..base import BaseDynamicConfig, BaseMessageParam
+from .call_params import GoogleCallParams
+
+GoogleDynamicConfig = BaseDynamicConfig[
+    ContentListUnion | ContentListUnionDict | BaseMessageParam, GoogleCallParams, Client
+]
+"""The function return type for functions wrapped with the `google_call` decorator.
+
+Example:
+
+```python
+from mirascope.core import prompt_template
+from mirascope.core.google import GoogleDynamicConfig, google_call
+
+
+@google_call("google-1.5-flash")
+@prompt_template("Recommend a {capitalized_genre} book")
+def recommend_book(genre: str) -> GoogleDynamicConfig:
+    return {"computed_fields": {"capitalized_genre": genre.capitalize()}}
+```
+"""