mirascope 2.0.0a5__py3-none-any.whl → 2.0.1__py3-none-any.whl

mirascope/llm/providers/google/_utils/encode.py

@@ -1,10 +1,12 @@
 """Google message encoding and request preparation."""
 
+from __future__ import annotations
+
 import base64
 import json
 from collections.abc import Sequence
 from functools import lru_cache
-from typing import Any, TypedDict, cast
+from typing import TYPE_CHECKING, Any, TypedDict, cast
 from typing_extensions import Required
 
 from google.genai import types as genai_types
@@ -14,17 +16,109 @@ from ....exceptions import FeatureNotSupportedError
 from ....formatting import (
     Format,
     FormattableT,
-    _utils as _formatting_utils,
+    OutputParser,
     resolve_format,
 )
 from ....messages import AssistantMessage, Message, UserMessage
 from ....tools import FORMAT_TOOL_NAME, AnyToolSchema, BaseToolkit
-from ...base import Params, _utils as _base_utils
+from ...base import _utils as _base_utils
 from ..model_id import GoogleModelId, model_name
 from ..model_info import MODELS_WITHOUT_STRUCTURED_OUTPUT_AND_TOOLS_SUPPORT
 
+if TYPE_CHECKING:
+    from ....models import Params, ThinkingConfig, ThinkingLevel
+
 UNKNOWN_TOOL_ID = "google_unknown_tool_id"
 
+# Thinking level to a float multiplier % of max tokens (for 2.5 models using budget)
+THINKING_LEVEL_TO_BUDGET_MULTIPLIER: dict[ThinkingLevel, float] = {
+    "none": 0,
+    "minimal": 0.1,
+    "low": 0.2,
+    "medium": 0.4,
+    "high": 0.6,
+    "max": 0.8,
+}
+
+# Gemini 3 Pro supports only LOW or HIGH
+# https://ai.google.dev/gemini-api/docs/gemini-3#thinking_level
+THINKING_LEVEL_FOR_GEMINI_3_PRO: dict[ThinkingLevel, genai_types.ThinkingLevel] = {
+    "default": genai_types.ThinkingLevel.THINKING_LEVEL_UNSPECIFIED,
+    "none": genai_types.ThinkingLevel.LOW,
+    "minimal": genai_types.ThinkingLevel.LOW,
+    "low": genai_types.ThinkingLevel.LOW,
+    "medium": genai_types.ThinkingLevel.HIGH,
+    "high": genai_types.ThinkingLevel.HIGH,
+    "max": genai_types.ThinkingLevel.HIGH,
+}
+
+# Gemini 3 Flash supports MINIMAL, LOW, MEDIUM, HIGH
+# https://ai.google.dev/gemini-api/docs/gemini-3#thinking_level
+THINKING_LEVEL_FOR_GEMINI_3_FLASH: dict[ThinkingLevel, genai_types.ThinkingLevel] = {
+    "default": genai_types.ThinkingLevel.THINKING_LEVEL_UNSPECIFIED,
+    "none": genai_types.ThinkingLevel.MINIMAL,
+    "minimal": genai_types.ThinkingLevel.MINIMAL,
+    "low": genai_types.ThinkingLevel.LOW,
+    "medium": genai_types.ThinkingLevel.MEDIUM,
+    "high": genai_types.ThinkingLevel.HIGH,
+    "max": genai_types.ThinkingLevel.HIGH,
+}
+
+
+def google_thinking_config(
+    thinking_config: ThinkingConfig,
+    max_tokens: int | None,
+    model_id: GoogleModelId,
+) -> genai_types.ThinkingConfigDict:
+    """Compute Google thinking configuration based on model version.
+
+    Args:
+        thinking_config: The ThinkingConfig from params
+        max_tokens: Max output tokens (used to compute budget for 2.5 models)
+        model_id: The Google model ID to determine version
+
+    Returns:
+        ThinkingConfigDict with either thinking_level or thinking_budget set.
+
+    Notes:
+        - Gemini 2.5 models use thinking_budget (token count)
+        - Gemini 3.0 Pro supports thinking_level "low" or "high"
+        - Gemini 3.0 Flash supports thinking_level "minimal", "low", "medium", "high"
+
+    See: https://ai.google.dev/gemini-api/docs/gemini-3#thinking_level
+    """
+    level: ThinkingLevel = thinking_config.get("level", "default")
+    include_thoughts = thinking_config.get("include_thoughts")
+
+    result = genai_types.ThinkingConfigDict()
+
+    if "gemini-3-flash" in model_id:
+        result["thinking_level"] = THINKING_LEVEL_FOR_GEMINI_3_FLASH.get(
+            level, genai_types.ThinkingLevel.THINKING_LEVEL_UNSPECIFIED
+        )
+    elif "gemini-3-pro" in model_id:
+        result["thinking_level"] = THINKING_LEVEL_FOR_GEMINI_3_PRO.get(
+            level, genai_types.ThinkingLevel.THINKING_LEVEL_UNSPECIFIED
+        )
+    else:  # Fall back to 2.5-style budgets
+        # 2.5 models use thinking_budget
+        if level == "default":
+            budget = -1  # Dynamic budget
+        elif level == "none":
+            budget = 0  # Disable thinking
+        else:
+            # Compute budget as percentage of max_tokens
+            if max_tokens is None:
+                max_tokens = 16000
+            multiplier = THINKING_LEVEL_TO_BUDGET_MULTIPLIER.get(level, 0.4)
+            budget = int(multiplier * max_tokens)
+
+        result["thinking_budget"] = budget
+    if include_thoughts is not None:
+        result["include_thoughts"] = include_thoughts
+
+    return result
+
 
 class GoogleKwargs(TypedDict, total=False):
     """Kwargs for Google's generate_content method."""
@@ -105,7 +199,7 @@ def _encode_content(
                     function_response=genai_types.FunctionResponseDict(
                         id=part.id if part.id != UNKNOWN_TOOL_ID else None,
                         name=part.name,
-                        response={"output": str(part.value)},
+                        response={"output": str(part.result)},
                     )
                 )
             )
@@ -177,7 +271,10 @@ def encode_request(
     model_id: GoogleModelId,
     messages: Sequence[Message],
     tools: Sequence[AnyToolSchema] | BaseToolkit[AnyToolSchema] | None,
-    format: type[FormattableT] | Format[FormattableT] | None,
+    format: type[FormattableT]
+    | Format[FormattableT]
+    | OutputParser[FormattableT]
+    | None,
     params: Params,
 ) -> tuple[Sequence[Message], Format[FormattableT] | None, GoogleKwargs]:
     """Prepares a request for the genai `Client.models.generate_content` method."""
@@ -187,7 +284,7 @@ def encode_request(
     google_config: genai_types.GenerateContentConfigDict = (
         genai_types.GenerateContentConfigDict()
     )
-    encode_thoughts = False
+    encode_thoughts_as_text = False
     google_model_name = model_name(model_id)
 
     with _base_utils.ensure_all_params_accessed(
@@ -206,19 +303,28 @@ def encode_request(
         if param_accessor.stop_sequences is not None:
             google_config["stop_sequences"] = param_accessor.stop_sequences
         if param_accessor.thinking is not None:
-            if param_accessor.thinking:
-                google_config["thinking_config"] = genai_types.ThinkingConfigDict(
-                    thinking_budget=-1,  # automatic budget
-                    include_thoughts=True,
-                )
-            else:
-                google_config["thinking_config"] = genai_types.ThinkingConfigDict(
-                    include_thoughts=False, thinking_budget=0
-                )
-        if param_accessor.encode_thoughts_as_text:
-            encode_thoughts = True
+            thinking_config = param_accessor.thinking
+
+            # Compute thinking config based on model version
+            google_config["thinking_config"] = google_thinking_config(
+                thinking_config, param_accessor.max_tokens, model_id
+            )
+
+            # Handle encode_thoughts_as_text from ThinkingConfig
+            if thinking_config.get("encode_thoughts_as_text"):
+                encode_thoughts_as_text = True
 
     tools = tools.tools if isinstance(tools, BaseToolkit) else tools or []
+
+    if _base_utils.has_strict_tools(tools):
+        raise FeatureNotSupportedError(
+            feature="strict tools",
+            provider_id="google",
+            model_id=model_id,
+            message="Google does not support strict mode for tools. "
+            "Set strict=False on your tools or omit the strict parameter.",
+        )
+
     google_tools: list[genai_types.ToolDict] = []
 
     allows_strict_mode_with_tools = (
@@ -244,7 +350,7 @@ def encode_request(
             google_config["response_mime_type"] = "application/json"
             google_config["response_schema"] = format.schema
         elif format.mode == "tool":
-            format_tool_schema = _formatting_utils.create_tool_schema(format)
+            format_tool_schema = format.create_tool_schema()
             format_tool = _convert_tool_to_function_declaration(format_tool_schema)
             google_tools.append(
                 genai_types.ToolDict(function_declarations=[format_tool])
@@ -286,7 +392,9 @@ def encode_request(
 
     kwargs = GoogleKwargs(
         model=model_name(model_id),
-        contents=_encode_messages(remaining_messages, model_id, encode_thoughts),
+        contents=_encode_messages(
+            remaining_messages, model_id, encode_thoughts_as_text
+        ),
         config=google_config,
     )
 

mirascope/llm/providers/google/_utils/errors.py

@@ -11,20 +11,21 @@ from ....exceptions import (
     BadRequestError,
     NotFoundError,
     PermissionError,
+    ProviderError,
     RateLimitError,
     ServerError,
 )
 from ...base import ProviderErrorMap
 
 
-def map_google_error(e: Exception) -> type[APIError]:
+def map_google_error(e: Exception) -> type[ProviderError]:
     """Map Google error to appropriate Mirascope error type.
 
     Google only provides ClientError (4xx) and ServerError (5xx) with status codes,
     so we map based on status code and message patterns.
     """
     if not isinstance(e, GoogleClientError | GoogleServerError):
-        return APIError
+        return ProviderError
 
     # Authentication errors (401) or 400 with "API key not valid"
     if e.code == 401 or (e.code == 400 and "API key not valid" in str(e)):

mirascope/llm/providers/google/model_info.py

@@ -21,6 +21,7 @@ GoogleKnownModels = Literal[
     "google/gemini-2.5-flash-lite-preview-09-2025",
     "google/gemini-2.5-flash-preview-09-2025",
     "google/gemini-2.5-pro",
+    "google/gemini-3-flash-preview",
     "google/gemini-3-pro-image-preview",
     "google/gemini-3-pro-preview",
     "google/gemini-flash-latest",

mirascope/llm/providers/google/provider.py

@@ -1,13 +1,16 @@
 """Google provider implementation."""
 
+from __future__ import annotations
+
 from collections.abc import Sequence
+from typing import TYPE_CHECKING
 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 ...formatting import Format, FormattableT, OutputParser
 from ...messages import Message
 from ...responses import (
     AsyncContextResponse,
@@ -29,10 +32,13 @@ from ...tools import (
     Tool,
     Toolkit,
 )
-from ..base import BaseProvider, Params
+from ..base import BaseProvider
 from . import _utils
 from .model_id import GoogleModelId, model_name
 
+if TYPE_CHECKING:
+    from ...models import Params
+
 
 class GoogleProvider(BaseProvider[Client]):
     """The client for the Google LLM model."""
@@ -47,7 +53,10 @@ class GoogleProvider(BaseProvider[Client]):
         """Initialize the Google client."""
         http_options = None
         if base_url:
-            http_options = HttpOptions(base_url=base_url)
+            http_options = HttpOptions(
+                base_url=base_url,
+                headers={"Authorization": f"Bearer {api_key}"},
+            )
 
         self.client = Client(api_key=api_key, http_options=http_options)
 
@@ -61,7 +70,10 @@ class GoogleProvider(BaseProvider[Client]):
         model_id: GoogleModelId,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> Response | Response[FormattableT]:
         """Generate an `llm.Response` by synchronously calling the Google GenAI API.
@@ -85,8 +97,9 @@ class GoogleProvider(BaseProvider[Client]):
         )
         google_response = self.client.models.generate_content(**kwargs)
 
+        include_thoughts = _utils.get_include_thoughts(params)
         assistant_message, finish_reason, usage = _utils.decode_response(
-            google_response, model_id
+            google_response, model_id, include_thoughts=include_thoughts
         )
 
         return Response(
@@ -112,7 +125,10 @@ class GoogleProvider(BaseProvider[Client]):
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
         """Generate an `llm.ContextResponse` by synchronously calling the Google GenAI API.
@@ -137,8 +153,9 @@ class GoogleProvider(BaseProvider[Client]):
         )
         google_response = self.client.models.generate_content(**kwargs)
 
+        include_thoughts = _utils.get_include_thoughts(params)
         assistant_message, finish_reason, usage = _utils.decode_response(
-            google_response, model_id
+            google_response, model_id, include_thoughts=include_thoughts
         )
 
         return ContextResponse(
@@ -161,7 +178,10 @@ class GoogleProvider(BaseProvider[Client]):
         model_id: GoogleModelId,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Generate an `llm.AsyncResponse` by asynchronously calling the Google GenAI API.
@@ -185,8 +205,9 @@ class GoogleProvider(BaseProvider[Client]):
         )
         google_response = await self.client.aio.models.generate_content(**kwargs)
 
+        include_thoughts = _utils.get_include_thoughts(params)
         assistant_message, finish_reason, usage = _utils.decode_response(
-            google_response, model_id
+            google_response, model_id, include_thoughts=include_thoughts
         )
 
         return AsyncResponse(
@@ -212,7 +233,10 @@ class GoogleProvider(BaseProvider[Client]):
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
         """Generate an `llm.AsyncContextResponse` by asynchronously calling the Google GenAI API.
@@ -237,8 +261,9 @@ class GoogleProvider(BaseProvider[Client]):
         )
         google_response = await self.client.aio.models.generate_content(**kwargs)
 
+        include_thoughts = _utils.get_include_thoughts(params)
         assistant_message, finish_reason, usage = _utils.decode_response(
-            google_response, model_id
+            google_response, model_id, include_thoughts=include_thoughts
         )
 
         return AsyncContextResponse(
@@ -261,7 +286,10 @@ class GoogleProvider(BaseProvider[Client]):
         model_id: GoogleModelId,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Generate an `llm.StreamResponse` by synchronously streaming from the Google GenAI API.
@@ -286,7 +314,10 @@ class GoogleProvider(BaseProvider[Client]):
 
         google_stream = self.client.models.generate_content_stream(**kwargs)
 
-        chunk_iterator = _utils.decode_stream(google_stream)
+        include_thoughts = _utils.get_include_thoughts(params)
+        chunk_iterator = _utils.decode_stream(
+            google_stream, include_thoughts=include_thoughts
+        )
 
         return StreamResponse(
             provider_id="google",
@@ -308,7 +339,10 @@ class GoogleProvider(BaseProvider[Client]):
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> ContextStreamResponse[DepsT] | ContextStreamResponse[DepsT, FormattableT]:
         """Generate an `llm.ContextStreamResponse` by synchronously streaming from the Google GenAI API.
@@ -334,7 +368,10 @@ class GoogleProvider(BaseProvider[Client]):
 
         google_stream = self.client.models.generate_content_stream(**kwargs)
 
-        chunk_iterator = _utils.decode_stream(google_stream)
+        include_thoughts = _utils.get_include_thoughts(params)
+        chunk_iterator = _utils.decode_stream(
+            google_stream, include_thoughts=include_thoughts
+        )
 
         return ContextStreamResponse(
             provider_id="google",
@@ -353,7 +390,10 @@ class GoogleProvider(BaseProvider[Client]):
         model_id: GoogleModelId,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
         """Generate an `llm.AsyncStreamResponse` by asynchronously streaming from the Google GenAI API.
@@ -378,7 +418,10 @@ class GoogleProvider(BaseProvider[Client]):
 
         google_stream = await self.client.aio.models.generate_content_stream(**kwargs)
 
-        chunk_iterator = _utils.decode_async_stream(google_stream)
+        include_thoughts = _utils.get_include_thoughts(params)
+        chunk_iterator = _utils.decode_async_stream(
+            google_stream, include_thoughts=include_thoughts
+        )
 
         return AsyncStreamResponse(
             provider_id="google",
@@ -400,7 +443,10 @@ class GoogleProvider(BaseProvider[Client]):
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> (
         AsyncContextStreamResponse[DepsT]
@@ -429,7 +475,10 @@ class GoogleProvider(BaseProvider[Client]):
 
         google_stream = await self.client.aio.models.generate_content_stream(**kwargs)
 
-        chunk_iterator = _utils.decode_async_stream(google_stream)
+        include_thoughts = _utils.get_include_thoughts(params)
+        chunk_iterator = _utils.decode_async_stream(
+            google_stream, include_thoughts=include_thoughts
+        )
 
         return AsyncContextStreamResponse(
             provider_id="google",

mirascope/llm/providers/mirascope/__init__.py

@@ -0,0 +1,5 @@
+"""Mirascope Router provider for routing LLM requests."""
+
+from .provider import MirascopeProvider
+
+__all__ = ["MirascopeProvider"]

mirascope/llm/providers/mirascope/_utils.py

@@ -0,0 +1,73 @@
+"""Utility functions for Mirascope Router provider."""
+
+import os
+from typing import cast
+
+from ..base import Provider
+from ..provider_id import ProviderId
+
+
+def extract_model_scope(model_id: str) -> str | None:
+    """Extract model scope from model ID.
+
+    Args:
+        model_id: Model identifier in the format "scope/model-name"
+                  e.g., "openai/gpt-4", "anthropic/claude-3", "google/gemini-pro"
+
+    Returns:
+        The model scope (e.g., "openai", "anthropic", "google") or None if invalid format.
+    """
+    if "/" not in model_id:
+        return None
+    return model_id.split("/", 1)[0]
+
+
+def get_default_router_base_url() -> str:
+    """Get the default router base URL from environment or use default.
+
+    Returns:
+        The router base URL (without trailing provider path).
+    """
+    return os.environ.get(
+        "MIRASCOPE_ROUTER_BASE_URL", "https://mirascope.com/router/v2"
+    )
+
+
+def create_underlying_provider(
+    model_scope: str, api_key: str, router_base_url: str
+) -> Provider:
+    """Create and cache an underlying provider instance using provider_singleton.
+
+    This function constructs the appropriate router URL for the provider and
+    delegates to provider_singleton for caching and instantiation.
+
+    Args:
+        model_scope: The model scope (e.g., "openai", "anthropic", "google")
+        api_key: The API key to use for authentication
+        router_base_url: The base router URL (e.g., "http://mirascope.com/router/v2")
+
+    Returns:
+        A cached provider instance configured for the Mirascope Router.
+
+    Raises:
+        ValueError: If the provider is unsupported.
+    """
+    if model_scope not in ["anthropic", "google", "openai"]:
+        raise ValueError(
+            f"Unsupported provider: {model_scope}. "
+            f"Mirascope Router currently supports: anthropic, google, openai"
+        )
+
+    base_url = f"{router_base_url}/{model_scope}"
+    if model_scope == "openai":  # OpenAI expects /v1, which their SDK doesn't add
+        base_url = f"{base_url}/v1"
+
+    # Lazy import to avoid circular dependencies
+    from ..provider_registry import provider_singleton
+
+    # Use provider_singleton which provides caching
+    return provider_singleton(
+        cast(ProviderId, model_scope),
+        api_key=api_key,
+        base_url=base_url,
+    )