mirascope 2.0.0__py3-none-any.whl → 2.0.0a1__py3-none-any.whl

mirascope/llm/clients/google/clients.py

@@ -0,0 +1,853 @@
+"""Google client implementation."""
+
+import os
+from collections.abc import Sequence
+from contextvars import ContextVar
+from functools import lru_cache
+from typing import overload
+from typing_extensions import Unpack
+
+from google.genai import Client
+from google.genai.types import HttpOptions
+
+from ...context import Context, DepsT
+from ...formatting import Format, FormattableT
+from ...messages import Message
+from ...responses import (
+    AsyncContextResponse,
+    AsyncContextStreamResponse,
+    AsyncResponse,
+    AsyncStreamResponse,
+    ContextResponse,
+    ContextStreamResponse,
+    Response,
+    StreamResponse,
+)
+from ...tools import (
+    AsyncContextTool,
+    AsyncContextToolkit,
+    AsyncTool,
+    AsyncToolkit,
+    ContextTool,
+    ContextToolkit,
+    Tool,
+    Toolkit,
+)
+from ..base import BaseClient, Params
+from . import _utils
+from .model_ids import GoogleModelId
+
+GOOGLE_CLIENT_CONTEXT: ContextVar["GoogleClient | None"] = ContextVar(
+    "GOOGLE_CLIENT_CONTEXT", default=None
+)
+
+
+@lru_cache(maxsize=256)
+def _google_singleton(api_key: str | None, base_url: str | None) -> "GoogleClient":
+    """Return a cached Google client instance for the given parameters."""
+    return GoogleClient(api_key=api_key, base_url=base_url)
+
+
+def client(
+    *, api_key: str | None = None, base_url: str | None = None
+) -> "GoogleClient":
+    """Create or retrieve a Google client with the given parameters.
+
+    If a client has already been created with these parameters, it will be
+    retrieved from cache and returned.
+
+    Args:
+        api_key: API key for authentication. If None, uses GOOGLE_API_KEY env var.
+        base_url: Base URL for the API. If None, uses GOOGLE_BASE_URL env var.
+
+    Returns:
+        A Google client instance.
+    """
+    api_key = api_key or os.getenv("GOOGLE_API_KEY")
+    base_url = base_url or os.getenv("GOOGLE_BASE_URL")
+    return _google_singleton(api_key, base_url)
+
+
+def get_client() -> "GoogleClient":
+    """Retrieve the current Google client from context, or a global default.
+
+    Returns:
+        The current Google client from context if available, otherwise
+        a global default client based on environment variables.
+    """
+    ctx_client = GOOGLE_CLIENT_CONTEXT.get()
+    return ctx_client or client()
+
+
+class GoogleClient(BaseClient[GoogleModelId, Client]):
+    """The client for the Google LLM model."""
+
+    @property
+    def _context_var(self) -> ContextVar["GoogleClient | None"]:
+        return GOOGLE_CLIENT_CONTEXT
+
+    def __init__(
+        self, *, api_key: str | None = None, base_url: str | None = None
+    ) -> None:
+        """Initialize the Google client."""
+        http_options = None
+        if base_url:
+            http_options = HttpOptions(base_url=base_url)
+
+        self.client = Client(api_key=api_key, http_options=http_options)
+
+    @overload
+    def call(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: None = None,
+        **params: Unpack[Params],
+    ) -> Response:
+        """Generate an `llm.Response` without a response format."""
+        ...
+
+    @overload
+    def call(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT],
+        **params: Unpack[Params],
+    ) -> Response[FormattableT]:
+        """Generate an `llm.Response` with a response format."""
+        ...
+
+    @overload
+    def call(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None,
+        **params: Unpack[Params],
+    ) -> Response | Response[FormattableT]:
+        """Generate an `llm.Response` with an optional response format."""
+        ...
+
+    def call(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> Response | Response[FormattableT]:
+        """Generate an `llm.Response` by synchronously calling the Google GenAI API.
+
+        Args:
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            An `llm.Response` object containing the LLM-generated content.
+        """
+        input_messages, format, contents, config = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        google_response = self.client.models.generate_content(
+            model=model_id,
+            contents=contents,
+            config=config,
+        )
+
+        assistant_message, finish_reason = _utils.decode_response(
+            google_response, model_id
+        )
+
+        return Response(
+            raw=google_response,
+            provider="google",
+            model_id=model_id,
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            format=format,
+        )
+
+    @overload
+    def context_call(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: None = None,
+        **params: Unpack[Params],
+    ) -> ContextResponse[DepsT, None]:
+        """Generate an `llm.ContextResponse` without a response format."""
+        ...
+
+    @overload
+    def context_call(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT],
+        **params: Unpack[Params],
+    ) -> ContextResponse[DepsT, FormattableT]:
+        """Generate an `llm.ContextResponse` with a response format."""
+        ...
+
+    @overload
+    def context_call(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None,
+        **params: Unpack[Params],
+    ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
+        """Generate an `llm.ContextResponse` with an optional response format."""
+        ...
+
+    def context_call(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
+        """Generate an `llm.ContextResponse` by synchronously calling the Google GenAI API.
+
+        Args:
+            ctx: Context object with dependencies for tools.
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            An `llm.ContextResponse` object containing the LLM-generated content.
+        """
+        input_messages, format, contents, config = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        google_response = self.client.models.generate_content(
+            model=model_id,
+            contents=contents,
+            config=config,
+        )
+
+        assistant_message, finish_reason = _utils.decode_response(
+            google_response, model_id
+        )
+
+        return ContextResponse(
+            raw=google_response,
+            provider="google",
+            model_id=model_id,
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            format=format,
+        )
+
+    @overload
+    async def call_async(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: None = None,
+        **params: Unpack[Params],
+    ) -> AsyncResponse:
+        """Generate an `llm.AsyncResponse` without a response format."""
+        ...
+
+    @overload
+    async def call_async(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT],
+        **params: Unpack[Params],
+    ) -> AsyncResponse[FormattableT]:
+        """Generate an `llm.AsyncResponse` with a response format."""
+        ...
+
+    @overload
+    async def call_async(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None,
+        **params: Unpack[Params],
+    ) -> AsyncResponse | AsyncResponse[FormattableT]:
+        """Generate an `llm.AsyncResponse` with an optional response format."""
+        ...
+
+    async def call_async(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncResponse | AsyncResponse[FormattableT]:
+        """Generate an `llm.AsyncResponse` by asynchronously calling the Google GenAI API.
+
+        Args:
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            An `llm.AsyncResponse` object containing the LLM-generated content.
+        """
+        input_messages, format, contents, config = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        google_response = await self.client.aio.models.generate_content(
+            model=model_id,
+            contents=contents,
+            config=config,
+        )
+
+        assistant_message, finish_reason = _utils.decode_response(
+            google_response, model_id
+        )
+
+        return AsyncResponse(
+            raw=google_response,
+            provider="google",
+            model_id=model_id,
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            format=format,
+        )
+
+    @overload
+    async def context_call_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: None = None,
+        **params: Unpack[Params],
+    ) -> AsyncContextResponse[DepsT, None]:
+        """Generate an `llm.AsyncContextResponse` without a response format."""
+        ...
+
+    @overload
+    async def context_call_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT],
+        **params: Unpack[Params],
+    ) -> AsyncContextResponse[DepsT, FormattableT]:
+        """Generate an `llm.AsyncContextResponse` with a response format."""
+        ...
+
+    @overload
+    async def context_call_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None,
+        **params: Unpack[Params],
+    ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
+        """Generate an `llm.AsyncContextResponse` with an optional response format."""
+        ...
+
+    async def context_call_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
+        """Generate an `llm.AsyncContextResponse` by asynchronously calling the Google GenAI API.
+
+        Args:
+            ctx: Context object with dependencies for tools.
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            An `llm.AsyncContextResponse` object containing the LLM-generated content.
+        """
+        input_messages, format, contents, config = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        google_response = await self.client.aio.models.generate_content(
+            model=model_id,
+            contents=contents,
+            config=config,
+        )
+
+        assistant_message, finish_reason = _utils.decode_response(
+            google_response, model_id
+        )
+
+        return AsyncContextResponse(
+            raw=google_response,
+            provider="google",
+            model_id=model_id,
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            format=format,
+        )
+
+    @overload
+    def stream(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: None = None,
+        **params: Unpack[Params],
+    ) -> StreamResponse:
+        """Stream an `llm.StreamResponse` without a response format."""
+        ...
+
+    @overload
+    def stream(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT],
+        **params: Unpack[Params],
+    ) -> StreamResponse[FormattableT]:
+        """Stream an `llm.StreamResponse` with a response format."""
+        ...
+
+    @overload
+    def stream(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None,
+        **params: Unpack[Params],
+    ) -> StreamResponse | StreamResponse[FormattableT]:
+        """Stream an `llm.StreamResponse` with an optional response format."""
+        ...
+
+    def stream(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> StreamResponse | StreamResponse[FormattableT]:
+        """Generate an `llm.StreamResponse` by synchronously streaming from the Google GenAI API.
+
+        Args:
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            An `llm.StreamResponse` object for iterating over the LLM-generated content.
+        """
+        input_messages, format, contents, config = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        google_stream = self.client.models.generate_content_stream(
+            model=model_id,
+            contents=contents,
+            config=config,
+        )
+
+        chunk_iterator = _utils.decode_stream(google_stream)
+
+        return StreamResponse(
+            provider="google",
+            model_id=model_id,
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )
+
+    @overload
+    def context_stream(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: None = None,
+        **params: Unpack[Params],
+    ) -> ContextStreamResponse[DepsT]:
+        """Stream an `llm.ContextStreamResponse` without a response format."""
+        ...
+
+    @overload
+    def context_stream(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT],
+        **params: Unpack[Params],
+    ) -> ContextStreamResponse[DepsT, FormattableT]:
+        """Stream an `llm.ContextStreamResponse` with a response format."""
+        ...
+
+    @overload
+    def context_stream(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None,
+        **params: Unpack[Params],
+    ) -> ContextStreamResponse[DepsT] | ContextStreamResponse[DepsT, FormattableT]:
+        """Stream an `llm.ContextStreamResponse` with an optional response format."""
+        ...
+
+    def context_stream(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> ContextStreamResponse[DepsT] | ContextStreamResponse[DepsT, FormattableT]:
+        """Generate an `llm.ContextStreamResponse` by synchronously streaming from the Google GenAI API.
+
+        Args:
+            ctx: Context object with dependencies for tools.
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            An `llm.ContextStreamResponse` object for iterating over the LLM-generated content.
+        """
+        input_messages, format, contents, config = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        google_stream = self.client.models.generate_content_stream(
+            model=model_id,
+            contents=contents,
+            config=config,
+        )
+
+        chunk_iterator = _utils.decode_stream(google_stream)
+
+        return ContextStreamResponse(
+            provider="google",
+            model_id=model_id,
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )
+
+    @overload
+    async def stream_async(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: None = None,
+        **params: Unpack[Params],
+    ) -> AsyncStreamResponse:
+        """Stream an `llm.AsyncStreamResponse` without a response format."""
+        ...
+
+    @overload
+    async def stream_async(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT],
+        **params: Unpack[Params],
+    ) -> AsyncStreamResponse[FormattableT]:
+        """Stream an `llm.AsyncStreamResponse` with a response format."""
+        ...
+
+    @overload
+    async def stream_async(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None,
+        **params: Unpack[Params],
+    ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
+        """Stream an `llm.AsyncStreamResponse` with an optional response format."""
+        ...
+
+    async def stream_async(
+        self,
+        *,
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
+        """Generate an `llm.AsyncStreamResponse` by asynchronously streaming from the Google GenAI API.
+
+        Args:
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            An `llm.AsyncStreamResponse` object for asynchronously iterating over the LLM-generated content.
+        """
+        input_messages, format, contents, config = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        google_stream = await self.client.aio.models.generate_content_stream(
+            model=model_id,
+            contents=contents,
+            config=config,
+        )
+
+        chunk_iterator = _utils.decode_async_stream(google_stream)
+
+        return AsyncStreamResponse(
+            provider="google",
+            model_id=model_id,
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )
+
+    @overload
+    async def context_stream_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: None = None,
+        **params: Unpack[Params],
+    ) -> AsyncContextStreamResponse[DepsT]:
+        """Stream an `llm.AsyncContextStreamResponse` without a response format."""
+        ...
+
+    @overload
+    async def context_stream_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT],
+        **params: Unpack[Params],
+    ) -> AsyncContextStreamResponse[DepsT, FormattableT]:
+        """Stream an `llm.AsyncContextStreamResponse` with a response format."""
+        ...
+
+    @overload
+    async def context_stream_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None,
+        **params: Unpack[Params],
+    ) -> AsyncContextStreamResponse | AsyncContextStreamResponse[DepsT, FormattableT]:
+        """Stream an `llm.AsyncContextStreamResponse` with an optional response format."""
+        ...
+
+    async def context_stream_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: GoogleModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncContextStreamResponse | AsyncContextStreamResponse[DepsT, FormattableT]:
+        """Generate an `llm.AsyncContextStreamResponse` by asynchronously streaming from the Google GenAI API.
+
+        Args:
+            ctx: Context object with dependencies for tools.
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            An `llm.AsyncContextStreamResponse` object for asynchronously iterating over the LLM-generated content.
+        """
+        input_messages, format, contents, config = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        google_stream = await self.client.aio.models.generate_content_stream(
+            model=model_id,
+            contents=contents,
+            config=config,
+        )
+
+        chunk_iterator = _utils.decode_async_stream(google_stream)
+
+        return AsyncContextStreamResponse(
+            provider="google",
+            model_id=model_id,
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )