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

mirascope/llm/__init__.py

@@ -92,8 +92,8 @@ from .providers import (
     Params,
     Provider,
     ProviderId,
-    load_provider,
     register_provider,
+    reset_provider_registry,
 )
 from .responses import (
     AsyncChunkIterator,
@@ -232,7 +232,6 @@ __all__ = [
     "exceptions",
     "format",
     "formatting",
-    "load_provider",
     "mcp",
     "messages",
     "model",
@@ -242,6 +241,7 @@ __all__ = [
     "prompts",
     "providers",
     "register_provider",
+    "reset_provider_registry",
     "responses",
     "tool",
     "tools",

mirascope/llm/exceptions.py

@@ -11,6 +11,7 @@ class MirascopeLLMError(Exception):
     """Base exception for all Mirascope LLM errors."""
 
     original_exception: Exception | None
+    provider: "ProviderId | None"
 
 
 class APIError(MirascopeLLMError):
@@ -18,6 +19,10 @@ class APIError(MirascopeLLMError):
 
     status_code: int | None
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
 
 class ConnectionError(MirascopeLLMError):
     """Raised when unable to connect to the API (network issues, timeouts)."""
@@ -26,18 +31,30 @@ class ConnectionError(MirascopeLLMError):
 class AuthenticationError(APIError):
     """Raised for authentication failures (401, invalid API keys)."""
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message, status_code=status_code or 401)
+
 
 class PermissionError(APIError):
     """Raised for permission/authorization failures (403)."""
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message, status_code=status_code or 403)
+
 
 class BadRequestError(APIError):
     """Raised for malformed requests (400, 422)."""
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message, status_code=status_code or 400)
+
 
 class NotFoundError(APIError):
     """Raised when requested resource is not found (404)."""
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message, status_code=status_code or 404)
+
 
 class ToolNotFoundError(MirascopeLLMError):
     """Raised if a tool_call cannot be converted to any corresponding tool."""
@@ -96,15 +113,26 @@ class FormattingModeNotSupportedError(FeatureNotSupportedError):
 class RateLimitError(APIError):
     """Raised when rate limits are exceeded (429)."""
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message, status_code=status_code or 429)
+
 
 class ServerError(APIError):
     """Raised for server-side errors (500+)."""
 
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message, status_code=status_code or 500)
+
 
 class TimeoutError(MirascopeLLMError):
     """Raised when requests timeout or deadline exceeded."""
 
 
+# This wraps the APIResponseValidationErrors that OpenAI and Anthropic both return.
+class ResponseValidationError(MirascopeLLMError):
+    """Raised when API response fails validation."""
+
+
 class NoRegisteredProviderError(MirascopeLLMError):
     """Raised when no provider is registered for a given model_id."""
 

mirascope/llm/providers/__init__.py

@@ -6,7 +6,6 @@ from .anthropic import (
 )
 from .base import BaseProvider, Params, Provider
 from .google import GoogleModelId, GoogleProvider
-from .load_provider import load, load_provider
 from .mlx import MLXModelId, MLXProvider
 from .model_id import ModelId
 from .ollama import OllamaProvider
@@ -16,7 +15,11 @@ from .openai import (
 )
 from .openai.completions import BaseOpenAICompletionsProvider
 from .provider_id import KNOWN_PROVIDER_IDS, ProviderId
-from .provider_registry import get_provider_for_model, register_provider
+from .provider_registry import (
+    get_provider_for_model,
+    register_provider,
+    reset_provider_registry,
+)
 from .together import TogetherProvider
 
 __all__ = [
@@ -38,7 +41,6 @@ __all__ = [
     "ProviderId",
     "TogetherProvider",
     "get_provider_for_model",
-    "load",
-    "load_provider",
     "register_provider",
+    "reset_provider_registry",
 ]

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

@@ -9,8 +9,10 @@ from .encode import (
     encode_request,
     process_params,
 )
+from .errors import ANTHROPIC_ERROR_MAP
 
 __all__ = [
+    "ANTHROPIC_ERROR_MAP",
     "DEFAULT_FORMAT_MODE",
     "DEFAULT_MAX_TOKENS",
     "AnthropicImageMimeType",

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

@@ -0,0 +1,46 @@
+"""Anthropic error handling utilities."""
+
+from anthropic import (
+    AnthropicError,
+    APIConnectionError as AnthropicAPIConnectionError,
+    APIResponseValidationError as AnthropicAPIResponseValidationError,
+    APITimeoutError as AnthropicAPITimeoutError,
+    AuthenticationError as AnthropicAuthenticationError,
+    BadRequestError as AnthropicBadRequestError,
+    ConflictError as AnthropicConflictError,
+    InternalServerError as AnthropicInternalServerError,
+    NotFoundError as AnthropicNotFoundError,
+    PermissionDeniedError as AnthropicPermissionDeniedError,
+    RateLimitError as AnthropicRateLimitError,
+    UnprocessableEntityError as AnthropicUnprocessableEntityError,
+)
+
+from ....exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ResponseValidationError,
+    ServerError,
+    TimeoutError,
+)
+from ...base import ProviderErrorMap
+
+# Shared error mapping used by both AnthropicProvider and AnthropicBetaProvider
+ANTHROPIC_ERROR_MAP: ProviderErrorMap = {
+    AnthropicAuthenticationError: AuthenticationError,
+    AnthropicPermissionDeniedError: PermissionError,
+    AnthropicBadRequestError: BadRequestError,
+    AnthropicUnprocessableEntityError: BadRequestError,
+    AnthropicNotFoundError: NotFoundError,
+    AnthropicConflictError: BadRequestError,
+    AnthropicRateLimitError: RateLimitError,
+    AnthropicInternalServerError: ServerError,
+    AnthropicAPITimeoutError: TimeoutError,
+    AnthropicAPIConnectionError: ConnectionError,
+    AnthropicAPIResponseValidationError: ResponseValidationError,
+    AnthropicError: APIError,  # Catch-all for unknown Anthropic errors
+}

mirascope/llm/providers/anthropic/beta_provider.py

@@ -29,6 +29,7 @@ from ...tools import (
     Toolkit,
 )
 from ..base import BaseProvider, Params
+from . import _utils
 from ._utils import beta_decode, beta_encode
 from .model_id import model_name
 
@@ -38,6 +39,7 @@ class AnthropicBetaProvider(BaseProvider[Anthropic]):
 
     id = "anthropic-beta"
     default_scope = "anthropic-beta/"
+    error_map = _utils.ANTHROPIC_ERROR_MAP
 
     def __init__(
         self, *, api_key: str | None = None, base_url: str | None = None
@@ -46,6 +48,10 @@ class AnthropicBetaProvider(BaseProvider[Anthropic]):
         self.client = Anthropic(api_key=api_key, base_url=base_url)
         self.async_client = AsyncAnthropic(api_key=api_key, base_url=base_url)
 
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from Anthropic exception."""
+        return getattr(e, "status_code", None)
+
     def _call(
         self,
         *,

mirascope/llm/providers/anthropic/provider.py

@@ -55,6 +55,7 @@ class AnthropicProvider(BaseProvider[Anthropic]):
 
     id = "anthropic"
     default_scope = "anthropic/"
+    error_map = _utils.ANTHROPIC_ERROR_MAP
     _beta_provider: AnthropicBetaProvider
 
     def __init__(
@@ -65,6 +66,10 @@ class AnthropicProvider(BaseProvider[Anthropic]):
         self.async_client = AsyncAnthropic(api_key=api_key, base_url=base_url)
         self._beta_provider = AnthropicBetaProvider(api_key=api_key, base_url=base_url)
 
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from Anthropic exception."""
+        return getattr(e, "status_code", None)
+
     def _call(
         self,
         *,

mirascope/llm/providers/base/__init__.py

@@ -1,7 +1,7 @@
 """Base client interfaces and types."""
 
 from . import _utils
-from .base_provider import BaseProvider, Provider
+from .base_provider import BaseProvider, Provider, ProviderErrorMap
 from .kwargs import BaseKwargs, KwargsT
 from .params import Params
 
@@ -11,5 +11,6 @@ __all__ = [
     "KwargsT",
     "Params",
     "Provider",
+    "ProviderErrorMap",
     "_utils",
 ]

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/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/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,
+}