mirascope 2.0.0a4__py3-none-any.whl → 2.0.0a6__py3-none-any.whl

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

@@ -14,17 +14,105 @@ from ....exceptions import FeatureNotSupportedError
 from ....formatting import (
     Format,
     FormattableT,
-    _utils as _formatting_utils,
     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 Params, ThinkingConfig, ThinkingLevel, _utils as _base_utils
 from ..model_id import GoogleModelId, model_name
 from ..model_info import MODELS_WITHOUT_STRUCTURED_OUTPUT_AND_TOOLS_SUPPORT
 
 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_summaries = thinking_config.get("include_summaries")
+
+    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_summaries is not None:
+        result["include_thoughts"] = include_summaries
+
+    return result
+
 
 class GoogleKwargs(TypedDict, total=False):
     """Kwargs for Google's generate_content method."""
@@ -187,7 +275,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,17 +294,16 @@ 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 []
     google_tools: list[genai_types.ToolDict] = []
@@ -244,7 +331,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 +373,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

@@ -0,0 +1,49 @@
+"""Google error handling utilities."""
+
+from google.genai.errors import (
+    ClientError as GoogleClientError,
+    ServerError as GoogleServerError,
+)
+
+from ....exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ServerError,
+)
+from ...base import ProviderErrorMap
+
+
+def map_google_error(e: Exception) -> type[APIError]:
+    """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
+
+    # 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)):
+        return AuthenticationError
+    if e.code == 403:
+        return PermissionError
+    if e.code == 404:
+        return NotFoundError
+    if e.code == 429:
+        return RateLimitError
+    if e.code in (400, 422):
+        return BadRequestError
+    if isinstance(e, GoogleServerError) and e.code >= 500:
+        return ServerError
+    return APIError
+
+
+# Shared error mapping for Google provider
+GOOGLE_ERROR_MAP: ProviderErrorMap = {
+    GoogleClientError: map_google_error,
+    GoogleServerError: map_google_error,
+}

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

@@ -39,6 +39,7 @@ class GoogleProvider(BaseProvider[Client]):
 
     id = "google"
     default_scope = "google/"
+    error_map = _utils.GOOGLE_ERROR_MAP
 
     def __init__(
         self, *, api_key: str | None = None, base_url: str | None = None
@@ -46,10 +47,17 @@ 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)
 
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from Google exception."""
+        return getattr(e, "code", None)
+
     def _call(
         self,
         *,
@@ -78,7 +86,6 @@ class GoogleProvider(BaseProvider[Client]):
             format=format,
             params=params,
         )
-
         google_response = self.client.models.generate_content(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(
@@ -131,7 +138,6 @@ class GoogleProvider(BaseProvider[Client]):
             format=format,
             params=params,
         )
-
         google_response = self.client.models.generate_content(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(
@@ -180,7 +186,6 @@ class GoogleProvider(BaseProvider[Client]):
             format=format,
             params=params,
         )
-
         google_response = await self.client.aio.models.generate_content(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(
@@ -233,7 +238,6 @@ class GoogleProvider(BaseProvider[Client]):
             format=format,
             params=params,
         )
-
         google_response = await self.client.aio.models.generate_content(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(

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,77 @@
+"""Utility functions for Mirascope Router provider."""
+
+import os
+from typing import cast
+
+from ..base import Provider
+from ..provider_id import ProviderId
+
+
+def extract_provider_prefix(model_id: str) -> str | None:
+    """Extract provider prefix from model ID.
+
+    Args:
+        model_id: Model identifier in the format "provider/model-name"
+                  e.g., "openai/gpt-4", "anthropic/claude-3", "google/gemini-pro"
+
+    Returns:
+        The provider prefix (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/v0"
+    )
+
+
+def create_underlying_provider(
+    provider_prefix: 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:
+        provider_prefix: The provider name (e.g., "openai", "anthropic", "google",
+                         "openai:completions", "openai:responses")
+        api_key: The API key to use for authentication
+        router_base_url: The base router URL (e.g., "http://mirascope.com/router/v0")
+
+    Returns:
+        A cached provider instance configured for the Mirascope Router.
+
+    Raises:
+        ValueError: If the provider is unsupported.
+    """
+    # Extract base provider name (handles variants like "openai:completions")
+    base_provider = provider_prefix.split(":")[0]
+
+    if base_provider not in ["anthropic", "google", "openai"]:
+        raise ValueError(
+            f"Unsupported provider: {provider_prefix}. "
+            f"Mirascope Router currently supports: anthropic, google, openai"
+        )
+
+    base_url = f"{router_base_url}/{base_provider}"
+    if base_provider == "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, provider_prefix),
+        api_key=api_key,
+        base_url=base_url,
+    )

mirascope/llm/providers/mirascope/provider.py

@@ -0,0 +1,318 @@
+"""Mirascope Router provider that routes requests through the Mirascope Router API."""
+
+import os
+from collections.abc import Sequence
+from typing_extensions import Unpack
+
+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 BaseProvider, Params, Provider
+from . import _utils
+
+
+class MirascopeProvider(BaseProvider[None]):
+    """Provider that routes LLM requests through the Mirascope Router API.
+
+    The Mirascope Router provides a unified API for multiple LLM providers
+    (Anthropic, Google, OpenAI) with usage tracking and cost calculation.
+
+    This provider:
+    - Takes model IDs in the format "provider/model-name" (e.g., "openai/gpt-4")
+    - Routes requests to the Mirascope Router endpoint
+    - Delegates to the appropriate underlying provider (Anthropic, Google, or OpenAI)
+    - Uses MIRASCOPE_API_KEY for authentication
+
+    Environment Variables:
+        MIRASCOPE_API_KEY: Required API key for Mirascope Router authentication
+        MIRASCOPE_ROUTER_BASE_URL: Optional base URL override (default: https://mirascope.com/router/v0)
+
+    Example:
+        ```python
+        import os
+        from mirascope import llm
+
+        os.environ["MIRASCOPE_API_KEY"] = "mk..."
+
+        # Register the Mirascope provider
+        llm.register_provider(
+            "mirascope",
+            scope=["anthropic/", "google/", "openai/"],
+        )
+
+        # Use with llm.call decorator
+        @llm.call("openai/gpt-4")
+        def recommend_book(genre: str):
+            return f"Recommend a {genre} book"
+
+        response = recommend_book("fantasy")
+        print(response.content)
+        ```
+    """
+
+    id = "mirascope"
+    default_scope = ["anthropic/", "google/", "openai/"]
+    error_map = {}
+    """Empty error map since MirascopeProvider delegates to underlying providers.
+
+    Error handling is performed by the underlying provider instances (Anthropic,
+    Google, OpenAI), which have their own error maps. Any exceptions that bubble
+    up from underlying providers are already converted to Mirascope exceptions.
+    """
+
+    def __init__(
+        self, *, api_key: str | None = None, base_url: str | None = None
+    ) -> None:
+        """Initialize the Mirascope provider.
+
+        Args:
+            api_key: Mirascope API key. If not provided, reads from MIRASCOPE_API_KEY
+                environment variable.
+            base_url: Optional base URL override for the Mirascope Router. If not
+                provided, reads from MIRASCOPE_ROUTER_BASE_URL environment variable
+                or defaults to https://mirascope.com/router/v0
+        """
+        api_key = api_key or os.environ.get("MIRASCOPE_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "Mirascope API key not found. "
+                "Set MIRASCOPE_API_KEY environment variable or pass api_key parameter."
+            )
+
+        self.api_key = api_key
+        self.router_base_url = base_url or _utils.get_default_router_base_url()
+        self.client = None  # No single client; we create per-provider clients
+
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from exception.
+
+        Since MirascopeProvider delegates to underlying providers, this method
+        is not used for direct error extraction. Underlying providers handle
+        their own status code extraction.
+
+        Args:
+            e: The exception to extract status code from.
+
+        Returns:
+            None, as status extraction is handled by underlying providers.
+        """
+        return None
+
+    def _get_underlying_provider(self, model_id: str) -> Provider:
+        """Get the underlying provider for a model ID.
+
+        Args:
+            model_id: Model identifier in format "provider/model-name"
+
+        Returns:
+            The appropriate cached provider instance (Anthropic, Google, or OpenAI)
+
+        Raises:
+            ValueError: If the model ID format is invalid or provider is unsupported
+        """
+        provider_prefix = _utils.extract_provider_prefix(model_id)
+        if not provider_prefix:
+            raise ValueError(
+                f"Invalid model ID format: {model_id}. "
+                f"Expected format 'provider/model-name' (e.g., 'openai/gpt-4')"
+            )
+
+        # Use the cached function to get/create the provider
+        return _utils.create_underlying_provider(
+            provider_prefix=provider_prefix,
+            api_key=self.api_key,
+            router_base_url=self.router_base_url,
+        )
+
+    def _call(
+        self,
+        *,
+        model_id: str,
+        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 calling through the Mirascope Router."""
+        provider = self._get_underlying_provider(model_id)
+        return provider.call(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    def _context_call(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: str,
+        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 calling through the Mirascope Router."""
+        provider = self._get_underlying_provider(model_id)
+        return provider.context_call(
+            ctx=ctx,
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    async def _call_async(
+        self,
+        *,
+        model_id: str,
+        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 calling through the Mirascope Router."""
+        provider = self._get_underlying_provider(model_id)
+        return await provider.call_async(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    async def _context_call_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: str,
+        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 calling through the Mirascope Router."""
+        provider = self._get_underlying_provider(model_id)
+        return await provider.context_call_async(
+            ctx=ctx,
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    def _stream(
+        self,
+        *,
+        model_id: str,
+        messages: Sequence[Message],
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> StreamResponse | StreamResponse[FormattableT]:
+        """Stream an `llm.StreamResponse` by calling through the Mirascope Router."""
+        provider = self._get_underlying_provider(model_id)
+        return provider.stream(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    def _context_stream(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: str,
+        messages: Sequence[Message],
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> (
+        ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
+    ):
+        """Stream an `llm.ContextStreamResponse` by calling through the Mirascope Router."""
+        provider = self._get_underlying_provider(model_id)
+        return provider.context_stream(
+            ctx=ctx,
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    async def _stream_async(
+        self,
+        *,
+        model_id: str,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
+        """Stream an `llm.AsyncStreamResponse` by calling through the Mirascope Router."""
+        provider = self._get_underlying_provider(model_id)
+        return await provider.stream_async(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    async def _context_stream_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: str,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> (
+        AsyncContextStreamResponse[DepsT, None]
+        | AsyncContextStreamResponse[DepsT, FormattableT]
+    ):
+        """Stream an `llm.AsyncContextStreamResponse` by calling through the Mirascope Router."""
+        provider = self._get_underlying_provider(model_id)
+        return await provider.context_stream_async(
+            ctx=ctx,
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )