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

mirascope/llm/providers/base/base_provider.py

@@ -3,18 +3,22 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from collections.abc import Sequence
-from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeAlias, overload
+from collections.abc import Callable, Generator, Mapping, Sequence
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeAlias, cast, overload
 from typing_extensions import TypeVar, Unpack
 
 from ...context import Context, DepsT
+from ...exceptions import APIError, MirascopeLLMError
 from ...formatting import Format, FormattableT
 from ...messages import Message, UserContent, user
 from ...responses import (
+    AsyncChunkIterator,
     AsyncContextResponse,
     AsyncContextStreamResponse,
     AsyncResponse,
     AsyncStreamResponse,
+    ChunkIterator,
     ContextResponse,
     ContextStreamResponse,
     Response,
@@ -33,6 +37,7 @@ from ...tools import (
 from .params import Params
 
 if TYPE_CHECKING:
+    from ...exceptions import MirascopeLLMError
     from ..provider_id import ProviderId
 
 ProviderClientT = TypeVar("ProviderClientT")
@@ -40,6 +45,18 @@ ProviderClientT = TypeVar("ProviderClientT")
 Provider: TypeAlias = "BaseProvider[Any]"
 """Type alias for `BaseProvider` with any client type."""
 
+ProviderErrorMap: TypeAlias = Mapping[
+    type[Exception],
+    "type[MirascopeLLMError] | Callable[[Exception], type[MirascopeLLMError]]",
+]
+"""Mapping from provider SDK exceptions to Mirascope error types.
+
+Keys are provider SDK exception types (e.g., OpenAIError, AnthropicError).
+Values can be:
+- Error type: Simple 1:1 mapping (e.g., RateLimitError)
+- Callable: Transform function returning error type based on exception details
+"""
+
 
 class BaseProvider(Generic[ProviderClientT], ABC):
     """Base abstract provider for LLM interactions.
@@ -59,8 +76,67 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     - ["anthropic/", "openai/"] - Multiple scopes (e.g., for AWS Bedrock)
     """
 
+    error_map: ClassVar[ProviderErrorMap]
+    """Mapping from provider SDK exceptions to Mirascope error types.
+
+    Values can be:
+    - Error type: Simple 1:1 mapping (e.g., AnthropicRateLimitError -> RateLimitError)
+    - Callable: Transform function returning error type based on exception details
+                (e.g., lambda e: NotFoundError if e.code == "model_not_found" else BadRequestError)
+
+    The mapping is walked via the exception's MRO, allowing both specific error handling
+    and fallback to base SDK error types (e.g., AnthropicError -> APIError).
+    """
+
     client: ProviderClientT
 
+    @contextmanager
+    def _wrap_errors(self) -> Generator[None, None, None]:
+        """Wrap provider API calls and convert errors to Mirascope exceptions.
+
+        Walks the exception's MRO to find the first matching error type in the
+        provider's error_map, allowing both specific error handling and fallback
+        to base SDK error types (e.g., AnthropicError -> APIError).
+        """
+        try:
+            yield
+        except Exception as e:
+            # Walk MRO to find first matching error type in provider's error_map
+            for error_class in type(e).__mro__:
+                if error_class in self.error_map:
+                    error_type_or_fn = self.error_map[error_class]
+
+                    if isinstance(error_type_or_fn, type):
+                        error_type = cast(type[MirascopeLLMError], error_type_or_fn)
+                    else:
+                        error_type = error_type_or_fn(e)
+
+                    # Construct Mirascope error with metadata
+                    error: MirascopeLLMError = error_type(str(e))
+                    if isinstance(error, APIError):
+                        error.status_code = self.get_error_status(e)
+                    error.provider = self.id
+                    error.original_exception = e
+                    raise error from e
+
+            # Not in error_map - not a provider error, re-raise as-is
+            raise
+
+    def _wrap_iterator_errors(self, iterator: ChunkIterator) -> ChunkIterator:
+        """Wrap sync chunk iterator to handle errors during iteration."""
+        # TODO: Consider moving this logic into BaseSyncStreamResponse if appropriate.
+        with self._wrap_errors():
+            yield from iterator
+
+    async def _wrap_async_iterator_errors(
+        self, iterator: AsyncChunkIterator
+    ) -> AsyncChunkIterator:
+        """Wrap async chunk iterator to handle errors during iteration."""
+        # TODO: Consider moving this logic into BaseAsyncStreamResponse if appropriate.
+        with self._wrap_errors():
+            async for chunk in iterator:
+                yield chunk
+
     @overload
     def call(
         self,
@@ -121,13 +197,14 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.Response` object containing the LLM-generated content.
         """
-        return self._call(
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            **params,
-        )
+        with self._wrap_errors():
+            return self._call(
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
 
     @abstractmethod
     def _call(
@@ -215,14 +292,15 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.ContextResponse` object containing the LLM-generated content.
         """
-        return self._context_call(
-            ctx=ctx,
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            **params,
-        )
+        with self._wrap_errors():
+            return self._context_call(
+                ctx=ctx,
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
 
     @abstractmethod
     def _context_call(
@@ -300,13 +378,14 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.AsyncResponse` object containing the LLM-generated content.
         """
-        return await self._call_async(
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            **params,
-        )
+        with self._wrap_errors():
+            return await self._call_async(
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
 
     @abstractmethod
     async def _call_async(
@@ -394,14 +473,15 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.AsyncContextResponse` object containing the LLM-generated content.
         """
-        return await self._context_call_async(
-            ctx=ctx,
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            **params,
-        )
+        with self._wrap_errors():
+            return await self._context_call_async(
+                ctx=ctx,
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
 
     @abstractmethod
     async def _context_call_async(
@@ -479,13 +559,18 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.StreamResponse` object for iterating over the LLM-generated content.
         """
-        return self._stream(
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            **params,
+        with self._wrap_errors():
+            stream_response = self._stream(
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
+        stream_response._chunk_iterator = self._wrap_iterator_errors(  # pyright: ignore[reportPrivateUsage]
+            stream_response._chunk_iterator  # pyright: ignore[reportPrivateUsage]
         )
+        return stream_response
 
     @abstractmethod
     def _stream(
@@ -577,14 +662,19 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.ContextStreamResponse` object for iterating over the LLM-generated content.
         """
-        return self._context_stream(
-            ctx=ctx,
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            **params,
+        with self._wrap_errors():
+            stream_response = self._context_stream(
+                ctx=ctx,
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
+        stream_response._chunk_iterator = self._wrap_iterator_errors(  # pyright: ignore[reportPrivateUsage]
+            stream_response._chunk_iterator  # pyright: ignore[reportPrivateUsage]
         )
+        return stream_response
 
     @abstractmethod
     def _context_stream(
@@ -664,13 +754,18 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.AsyncStreamResponse` object for asynchronously iterating over the LLM-generated content.
         """
-        return await self._stream_async(
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            **params,
+        with self._wrap_errors():
+            stream_response = await self._stream_async(
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
+        stream_response._chunk_iterator = self._wrap_async_iterator_errors(  # pyright: ignore[reportPrivateUsage]
+            stream_response._chunk_iterator  # pyright: ignore[reportPrivateUsage]
         )
+        return stream_response
 
     @abstractmethod
     async def _stream_async(
@@ -764,14 +859,19 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.AsyncContextStreamResponse` object for asynchronously iterating over the LLM-generated content.
         """
-        return await self._context_stream_async(
-            ctx=ctx,
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            **params,
+        with self._wrap_errors():
+            stream_response = await self._context_stream_async(
+                ctx=ctx,
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
+        stream_response._chunk_iterator = self._wrap_async_iterator_errors(  # pyright: ignore[reportPrivateUsage]
+            stream_response._chunk_iterator  # pyright: ignore[reportPrivateUsage]
         )
+        return stream_response
 
     @abstractmethod
     async def _context_stream_async(
@@ -1383,3 +1483,18 @@ class BaseProvider(Generic[ProviderClientT], ABC):
             format=response.format,
             **params,
         )
+
+    @abstractmethod
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from provider-specific exception.
+
+        Different SDKs store status codes differently (e.g., .status_code vs .code).
+        Each provider implements this to handle their SDK's convention.
+
+        Args:
+            e: The exception to extract status code from.
+
+        Returns:
+            The HTTP status code if available, None otherwise.
+        """
+        ...

mirascope/llm/providers/base/params.py

@@ -1,6 +1,58 @@
 """Base parameters for LLM providers."""
 
-from typing import TypedDict
+from typing import Literal, TypedDict
+from typing_extensions import Required
+
+ThinkingLevel = Literal["none", "default", "minimal", "low", "medium", "high", "max"]
+"""Level of effort/reasoning to apply to thinking."""
+
+
+class ThinkingConfig(TypedDict, total=False):
+    """Configuration for extended reasoning/thinking in LLM responses.
+
+    Thinking is a process where the model spends additional tokens reasoning about
+    the prompt before generating a response. Providing any `ThinkingConfig` will enable
+    thinking (unless it is specifically disabled via level="minimal"). Depending on
+    the provider and model, thinking may always be active regardless of user settings.
+    """
+
+    level: Required[ThinkingLevel]
+    """Level of effort/reasoning to apply to thinking.
+
+    - none: Disable thinking entirely. Minimizes cost and latency.
+    - default: Use the provider's default
+    - minimal: Use the provider's lowest setting for reasoning
+    - medium: Use a moderate amount of reasoning tokens 
+    - high: Allow extensive resources for thinking
+    - max: Uses as much thinking as allowed by the provider.
+
+    Mirascope makes a best effort to apply the chosen thinking level, but exact behavior
+    varies by provider and model. For example, some models may not support thinking,
+    while other models may not allow disabling it.
+    """
+
+    include_summaries: bool
+    """Whether to generate reasoning summaries (human readable Thoughts) from model output.
+    
+    Generally, providers do not return raw model thinking output, but may produce
+    thought summaries. When `include_summaries` is true, these will be requested from
+    the provider (if available). Otherwise, they will not be requested.
+    """
+
+    encode_thoughts_as_text: bool
+    """Re-encode Thought content as text for model consumption.
+
+    If `True`, when an `AssistantMessage` contains `Thoughts` and is passed back
+    to an LLM, those `Thoughts` will be encoded as `Text`, ensuring the assistant
+    can read its prior reasoning. This contrasts with provider defaults which may
+    ignore prior thoughts, particularly if tool calls are not involved.
+
+    When `True`, Mirascope will re-encode messages rather than reusing raw provider
+    response content, which may disable provider-specific optimizations like cached
+    reasoning tokens.
+
+    Defaults to `False` if unset.
+    """
 
 
 class Params(TypedDict, total=False):
@@ -55,39 +107,16 @@ class Params(TypedDict, total=False):
     response.
     """
 
-    thinking: bool
-    """Configures whether the model should use thinking.
-    
-    Thinking is a process where the model spends additional tokens thinking about the
-    prompt before generating a response. You may configure thinking either by passing
-    a bool to enable or disable it.
-
-    If `params.thinking` is `True`, then thinking and thought summaries will be enabled
-    (if supported by the model/provider), with a default budget for thinking tokens.
-
-    If `params.thinking` is `False`, then thinking will be wholly disabled, assuming
-    the model allows this (some models, e.g. `google:gemini-2.5-pro`, do not allow
-    disabling thinking).
-
-    If `params.thinking` is unset (or `None`), then we will use provider-specific default
-    behavior for the chosen model.
-    """
-
-    encode_thoughts_as_text: bool
-    """Configures whether `Thought` content should be re-encoded as text for model consumption.
-    
-    If `True`, then when an `AssistantMessage` contains `Thoughts` and is being passed back
-    to an LLM, those `Thoughts` will be encoded as `Text`, so that the assistant can read
-    those thoughts. That ensures the assistant has access to (at least the summarized output of)
-    its reasoning process, and contrasts with provider default behaviors which may ignore
-    prior thoughts, particularly if tool calls are not involved.
-
-    When `True`, we will always re-encode Mirascope messages being passed to the provider,
-    rather than reusing raw provider response content. This may disable provider-specific
-    behavior like cached reasoning tokens.
+    thinking: ThinkingConfig | None
+    """Configuration for extended reasoning/thinking.
 
-    If `False`, then `Thoughts` will not be encoded as text, and whether reasoning context
-    is available to the model depends entirely on the provider's behavior. 
+    Pass a `ThinkingConfig` to configure thinking behavior. The `level` field controls
+    whether thinking is enabled and how much reasoning to use. Level may be one of 
+    "minimal", "low", "medium", or "high". If level is unset, then thinking is enabled
+    with a provider-specific default level.
 
-    Defaults to `False` if unset.
+    `ThinkingConfig` can also include `encode_thoughts_as_text`, which is an advanced
+    feature for providing past thoughts back to the model as text content. This is
+    primarily useful for making thoughts transferable when passing a conversation
+    to a different model or provider than the one that generated the thinking.
     """

mirascope/llm/providers/google/__init__.py

@@ -1,21 +1,6 @@
 """Google client implementation."""
 
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from .model_id import GoogleModelId
-    from .provider import GoogleProvider
-else:
-    try:
-        from .model_id import GoogleModelId
-        from .provider import GoogleProvider
-    except ImportError:  # pragma: no cover
-        from .._missing_import_stubs import (
-            create_import_error_stub,
-            create_provider_stub,
-        )
-
-        GoogleProvider = create_provider_stub("google", "GoogleProvider")
-        GoogleModelId = str
+from .model_id import GoogleModelId
+from .provider import GoogleProvider
 
 __all__ = ["GoogleModelId", "GoogleProvider"]

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

@@ -4,8 +4,10 @@ from .decode import (
     decode_stream,
 )
 from .encode import encode_request
+from .errors import GOOGLE_ERROR_MAP
 
 __all__ = [
+    "GOOGLE_ERROR_MAP",
     "decode_async_stream",
     "decode_response",
     "decode_stream",

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

@@ -177,15 +177,19 @@ class _GoogleChunkProcessor:
             if self.current_content_type == "thought" and not part.thought:
                 yield ThoughtEndChunk()
                 self.current_content_type = None
-            elif self.current_content_type == "text" and not part.text:
-                yield TextEndChunk()  # pragma: no cover
-                self.current_content_type = None  # pragma: no cover
-            elif self.current_content_type == "tool_call" and not part.function_call:
+            elif (
+                self.current_content_type == "text" and not part.text
+            ):  # pragma: no cover
+                yield TextEndChunk()
+                self.current_content_type = None
+            elif (
+                self.current_content_type == "tool_call" and not part.function_call
+            ):  # pragma: no cover
                 # In testing, Gemini never emits tool calls and text in the same message
                 # (even when specifically asked in system and user prompt), so
                 # the following code is uncovered but included for completeness
-                yield ToolCallEndChunk()  # pragma: no cover
-                self.current_content_type = None  # pragma: no cover
+                yield ToolCallEndChunk(id=UNKNOWN_TOOL_ID)
+                self.current_content_type = None
 
             if part.thought:
                 if self.current_content_type is None:
@@ -210,17 +214,22 @@ class _GoogleChunkProcessor:
                         "Required name missing on Google function call"
                     )  # pragma: no cover
 
+                tool_id = function_call.id or UNKNOWN_TOOL_ID
+                self.current_content_type = "tool_call"
+
                 yield ToolCallStartChunk(
-                    id=function_call.id or UNKNOWN_TOOL_ID,
+                    id=tool_id,
                     name=function_call.name,
                 )
 
                 yield ToolCallChunk(
+                    id=tool_id,
                     delta=json.dumps(function_call.args)
                     if function_call.args
                     else "{}",
                 )
-                yield ToolCallEndChunk()
+                yield ToolCallEndChunk(id=tool_id)
+                self.current_content_type = None
 
         if candidate.finish_reason:
             if self.current_content_type == "text":