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

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
@@ -50,6 +51,10 @@ class GoogleProvider(BaseProvider[Client]):
 
         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 +83,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 +135,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 +183,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 +235,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/mlx/_utils.py

@@ -2,14 +2,21 @@ from collections.abc import Callable
 from typing import TypeAlias, TypedDict
 
 import mlx.core as mx
+from huggingface_hub.errors import LocalEntryNotFoundError
 from mlx_lm.generate import GenerationResponse
 from mlx_lm.sample_utils import make_sampler
 
+from ...exceptions import NotFoundError
 from ...responses import FinishReason, Usage
-from ..base import Params, _utils as _base_utils
+from ..base import Params, ProviderErrorMap, _utils as _base_utils
 
 Sampler: TypeAlias = Callable[[mx.array], mx.array]
 
+# Error mapping for MLX provider
+MLX_ERROR_MAP: ProviderErrorMap = {
+    LocalEntryNotFoundError: NotFoundError,
+}
+
 
 class MakeSamplerKwargs(TypedDict, total=False):
     """Keyword arguments to be used for `mlx_lm`-s `make_sampler` function.

mirascope/llm/providers/mlx/provider.py

@@ -70,6 +70,14 @@ class MLXProvider(BaseProvider[None]):
 
     id = "mlx"
     default_scope = "mlx-community/"
+    error_map = _utils.MLX_ERROR_MAP
+
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from MLX exception.
+
+        MLX/HuggingFace Hub exceptions don't have status codes.
+        """
+        return None
 
     def _call(
         self,

mirascope/llm/providers/openai/__init__.py

@@ -1,6 +1,15 @@
 """OpenAI client implementation."""
 
+from .completions.base_provider import BaseOpenAICompletionsProvider
+from .completions.provider import OpenAICompletionsProvider
 from .model_id import OpenAIModelId
 from .provider import OpenAIProvider
+from .responses.provider import OpenAIResponsesProvider
 
-__all__ = ["OpenAIModelId", "OpenAIProvider"]
+__all__ = [
+    "BaseOpenAICompletionsProvider",
+    "OpenAICompletionsProvider",
+    "OpenAIModelId",
+    "OpenAIProvider",
+    "OpenAIResponsesProvider",
+]

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

@@ -0,0 +1,5 @@
+"""Shared OpenAI utilities."""
+
+from .errors import OPENAI_ERROR_MAP
+
+__all__ = ["OPENAI_ERROR_MAP"]

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

@@ -0,0 +1,46 @@
+"""OpenAI error handling utilities."""
+
+from openai import (
+    APIConnectionError as OpenAIAPIConnectionError,
+    APIResponseValidationError as OpenAIAPIResponseValidationError,
+    APITimeoutError as OpenAIAPITimeoutError,
+    AuthenticationError as OpenAIAuthenticationError,
+    BadRequestError as OpenAIBadRequestError,
+    ConflictError as OpenAIConflictError,
+    InternalServerError as OpenAIInternalServerError,
+    NotFoundError as OpenAINotFoundError,
+    OpenAIError,
+    PermissionDeniedError as OpenAIPermissionDeniedError,
+    RateLimitError as OpenAIRateLimitError,
+    UnprocessableEntityError as OpenAIUnprocessableEntityError,
+)
+
+from ....exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ResponseValidationError,
+    ServerError,
+    TimeoutError,
+)
+from ...base import ProviderErrorMap
+
+# Shared error mapping used by OpenAI Responses and Completions providers
+OPENAI_ERROR_MAP: ProviderErrorMap = {
+    OpenAIAuthenticationError: AuthenticationError,
+    OpenAIPermissionDeniedError: PermissionError,
+    OpenAINotFoundError: NotFoundError,
+    OpenAIBadRequestError: BadRequestError,
+    OpenAIUnprocessableEntityError: BadRequestError,
+    OpenAIConflictError: BadRequestError,
+    OpenAIRateLimitError: RateLimitError,
+    OpenAIInternalServerError: ServerError,
+    OpenAIAPITimeoutError: TimeoutError,
+    OpenAIAPIConnectionError: ConnectionError,
+    OpenAIAPIResponseValidationError: ResponseValidationError,
+    OpenAIError: APIError,  # Catch-all for unknown OpenAI errors
+}

mirascope/llm/providers/openai/completions/base_provider.py

@@ -31,6 +31,7 @@ from ....tools import (
     Toolkit,
 )
 from ...base import BaseProvider, Params
+from .. import _utils as _shared_utils
 from ..model_id import model_name as openai_model_name
 from . import _utils
 
@@ -44,6 +45,7 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
     api_key_env_var: ClassVar[str]
     api_key_required: ClassVar[bool] = True
     provider_name: ClassVar[str | None] = None
+    error_map = _shared_utils.OPENAI_ERROR_MAP
 
     def __init__(
         self,
@@ -77,6 +79,10 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             base_url=resolved_base_url,
         )
 
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from OpenAI exception."""
+        return getattr(e, "status_code", None)
+
     def _model_name(self, model_id: str) -> str:
         """Extract the model name to send to the API."""
         return openai_model_name(model_id, None)
@@ -114,7 +120,6 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             params=params,
         )
         kwargs["model"] = self._model_name(model_id)
-
         openai_response = self.client.chat.completions.create(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(
@@ -171,7 +176,6 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             params=params,
         )
         kwargs["model"] = self._model_name(model_id)
-
         openai_response = self.client.chat.completions.create(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(
@@ -224,7 +228,6 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             format=format,
         )
         kwargs["model"] = self._model_name(model_id)
-
         openai_response = await self.async_client.chat.completions.create(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(
@@ -281,7 +284,6 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             format=format,
         )
         kwargs["model"] = self._model_name(model_id)
-
         openai_response = await self.async_client.chat.completions.create(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(
@@ -334,7 +336,6 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             params=params,
         )
         kwargs["model"] = self._model_name(model_id)
-
         openai_stream = self.client.chat.completions.create(
             **kwargs,
             stream=True,
@@ -436,7 +437,6 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             params=params,
         )
         kwargs["model"] = self._model_name(model_id)
-
         openai_stream = await self.async_client.chat.completions.create(
             **kwargs,
             stream=True,

mirascope/llm/providers/openai/provider.py

@@ -3,9 +3,10 @@
 from collections.abc import Sequence
 from typing_extensions import Unpack
 
-from openai import OpenAI
+from openai import BadRequestError as OpenAIBadRequestError, OpenAI
 
 from ...context import Context, DepsT
+from ...exceptions import BadRequestError, NotFoundError
 from ...formatting import Format, FormattableT
 from ...messages import Message
 from ...responses import (
@@ -29,6 +30,7 @@ from ...tools import (
     Toolkit,
 )
 from ..base import BaseProvider, Params
+from . import _utils
 from .completions import OpenAICompletionsProvider
 from .model_id import OPENAI_KNOWN_MODELS, OpenAIModelId
 from .responses import OpenAIResponsesProvider
@@ -107,6 +109,13 @@ class OpenAIProvider(BaseProvider[OpenAI]):
 
     id = "openai"
     default_scope = "openai/"
+    # Include special handling for model_not_found from Responses API
+    error_map = {
+        **_utils.OPENAI_ERROR_MAP,
+        OpenAIBadRequestError: lambda e: NotFoundError
+        if hasattr(e, "code") and e.code == "model_not_found"  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
+        else BadRequestError,
+    }
 
     def __init__(
         self, *, api_key: str | None = None, base_url: str | None = None
@@ -121,6 +130,10 @@ class OpenAIProvider(BaseProvider[OpenAI]):
         # Use completions client's underlying OpenAI client as the main one
         self.client = self._completions_provider.client
 
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from OpenAI exception."""
+        return getattr(e, "status_code", None)  # pragma: no cover
+
     def _choose_subprovider(
         self, model_id: OpenAIModelId, messages: Sequence[Message]
     ) -> OpenAICompletionsProvider | OpenAIResponsesProvider:

mirascope/llm/providers/openai/responses/provider.py

@@ -3,9 +3,10 @@
 from collections.abc import Sequence
 from typing_extensions import Unpack
 
-from openai import AsyncOpenAI, OpenAI
+from openai import AsyncOpenAI, BadRequestError as OpenAIBadRequestError, OpenAI
 
 from ....context import Context, DepsT
+from ....exceptions import BadRequestError, NotFoundError
 from ....formatting import Format, FormattableT
 from ....messages import Message
 from ....responses import (
@@ -29,6 +30,7 @@ from ....tools import (
     Toolkit,
 )
 from ...base import BaseProvider, Params
+from .. import _utils as _shared_utils
 from ..model_id import OpenAIModelId, model_name
 from . import _utils
 
@@ -38,6 +40,12 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
 
     id = "openai:responses"
     default_scope = "openai/"
+    error_map = {
+        **_shared_utils.OPENAI_ERROR_MAP,
+        OpenAIBadRequestError: lambda e: NotFoundError
+        if hasattr(e, "code") and e.code == "model_not_found"  # pyright: ignore[reportAttributeAccessIssue,reportUnknownMemberType]
+        else BadRequestError,
+    }
 
     def __init__(
         self,
@@ -49,6 +57,10 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
         self.client = OpenAI(api_key=api_key, base_url=base_url)
         self.async_client = AsyncOpenAI(api_key=api_key, base_url=base_url)
 
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from OpenAI exception."""
+        return getattr(e, "status_code", None)
+
     def _call(
         self,
         *,
@@ -77,7 +89,6 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
             format=format,
             params=params,
         )
-
         openai_response = self.client.responses.create(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(
@@ -127,7 +138,6 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
             format=format,
             params=params,
         )
-
         openai_response = await self.async_client.responses.create(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(
@@ -177,7 +187,6 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
             format=format,
             params=params,
         )
-
         openai_stream = self.client.responses.create(
             **kwargs,
             stream=True,
@@ -227,7 +236,6 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
             format=format,
             params=params,
         )
-
         openai_stream = await self.async_client.responses.create(
             **kwargs,
             stream=True,
@@ -281,7 +289,6 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
             format=format,
             params=params,
         )
-
         openai_response = self.client.responses.create(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(
@@ -335,7 +342,6 @@ class OpenAIResponsesProvider(BaseProvider[OpenAI]):
             format=format,
             params=params,
         )
-
         openai_response = await self.async_client.responses.create(**kwargs)
 
         assistant_message, finish_reason, usage = _utils.decode_response(

mirascope/llm/providers/provider_registry.py

@@ -1,16 +1,31 @@
 """Provider registry for managing provider instances and scopes."""
 
+from functools import lru_cache
 from typing import overload
 
 from ..exceptions import NoRegisteredProviderError
+from .anthropic import AnthropicProvider
 from .base import Provider
-from .load_provider import load_provider
+from .google import GoogleProvider
+from .mlx import MLXProvider
+from .ollama import OllamaProvider
+from .openai import OpenAIProvider
+from .openai.completions.provider import OpenAICompletionsProvider
+from .openai.responses.provider import OpenAIResponsesProvider
 from .provider_id import ProviderId
+from .together import TogetherProvider
 
 # Global registry mapping scopes to providers
 # Scopes are matched by prefix (longest match wins)
 PROVIDER_REGISTRY: dict[str, Provider] = {}
 
+
+def reset_provider_registry() -> None:
+    """Resets the provider registry, clearing all registered providers."""
+    PROVIDER_REGISTRY.clear()
+    provider_singleton.cache_clear()
+
+
 # Default auto-registration mapping for built-in providers
 # These providers will be automatically registered on first use
 DEFAULT_AUTO_REGISTER_SCOPES: dict[str, ProviderId] = {
@@ -23,6 +38,44 @@ DEFAULT_AUTO_REGISTER_SCOPES: dict[str, ProviderId] = {
 }
 
 
+@lru_cache(maxsize=256)
+def provider_singleton(
+    provider_id: ProviderId, *, api_key: str | None = None, base_url: str | None = None
+) -> Provider:
+    """Create a cached provider instance for the specified provider id.
+
+    Args:
+        provider_id: The provider name ("openai", "anthropic", or "google").
+        api_key: API key for authentication. If None, uses provider-specific env var.
+        base_url: Base URL for the API. If None, uses provider-specific env var.
+
+    Returns:
+        A cached provider instance for the specified provider with the given parameters.
+
+    Raises:
+        ValueError: If the provider_id is not supported.
+    """
+    match provider_id:
+        case "anthropic":
+            return AnthropicProvider(api_key=api_key, base_url=base_url)
+        case "google":
+            return GoogleProvider(api_key=api_key, base_url=base_url)
+        case "mlx":  # pragma: no cover (MLX is only available on macOS)
+            return MLXProvider()
+        case "ollama":
+            return OllamaProvider(api_key=api_key, base_url=base_url)
+        case "openai":
+            return OpenAIProvider(api_key=api_key, base_url=base_url)
+        case "openai:completions":
+            return OpenAICompletionsProvider(api_key=api_key, base_url=base_url)
+        case "openai:responses":
+            return OpenAIResponsesProvider(api_key=api_key, base_url=base_url)
+        case "together":
+            return TogetherProvider(api_key=api_key, base_url=base_url)
+        case _:  # pragma: no cover
+            raise ValueError(f"Unknown provider: '{provider_id}'")
+
+
 @overload
 def register_provider(
     provider: Provider,
@@ -100,7 +153,7 @@ def register_provider(
     """
 
     if isinstance(provider, str):
-        provider = load_provider(provider, api_key=api_key, base_url=base_url)
+        provider = provider_singleton(provider, api_key=api_key, base_url=base_url)
 
     if scope is None:
         scope = provider.default_scope
@@ -160,7 +213,7 @@ def get_provider_for_model(model_id: str) -> Provider:
     if matching_defaults:
         best_scope = max(matching_defaults, key=len)
         provider_id = DEFAULT_AUTO_REGISTER_SCOPES[best_scope]
-        provider = load_provider(provider_id)
+        provider = provider_singleton(provider_id)
         # Auto-register for future calls
         PROVIDER_REGISTRY[best_scope] = provider
         return provider

mirascope/ops/_internal/closure.py

@@ -50,6 +50,55 @@ def _is_third_party(module: ModuleType, site_packages: set[str]) -> bool:
     )
 
 
+class _RemoveVersionDecoratorTransformer(cst.CSTTransformer):
+    """CST transformer to remove @ops.version and @version decorators."""
+
+    @classmethod
+    def _is_version_decorator(cls, decorator: cst.Decorator) -> bool:
+        """Returns True if the decorator is @version or @ops.version."""
+        decorator_node = decorator.decorator
+
+        if isinstance(decorator_node, cst.Name) and decorator_node.value == "version":
+            return True
+        if (
+            isinstance(decorator_node, cst.Call)
+            and isinstance(decorator_node.func, cst.Name)
+            and decorator_node.func.value == "version"
+        ):
+            return True
+
+        if (
+            isinstance(decorator_node, cst.Attribute)
+            and isinstance(decorator_node.value, cst.Name)
+            and decorator_node.value.value == "ops"
+            and decorator_node.attr.value == "version"
+        ):
+            return True
+        if isinstance(decorator_node, cst.Call) and isinstance(
+            decorator_node.func, cst.Attribute
+        ):
+            func_attribute = decorator_node.func
+            if (
+                isinstance(func_attribute.value, cst.Name)
+                and func_attribute.value.value == "ops"
+                and func_attribute.attr.value == "version"
+            ):
+                return True
+
+        return False
+
+    def leave_FunctionDef(
+        self, original_node: cst.FunctionDef, updated_node: cst.FunctionDef
+    ) -> cst.FunctionDef:
+        """Returns function definition with @version/@ops.version decorators removed."""
+        new_decorators = [
+            decorator
+            for decorator in updated_node.decorators
+            if not self._is_version_decorator(decorator)
+        ]
+        return updated_node.with_changes(decorators=new_decorators)
+
+
 class _RemoveDocstringTransformer(cst.CSTTransformer):
     """CST transformer to remove docstrings from functions and classes."""
 
@@ -125,14 +174,9 @@ def _clean_source_code(
     if docstr_flag in ("1", "true", "yes"):
         return source.rstrip()
     module = cst.parse_module(source)
-
-    transformer = _RemoveDocstringTransformer(exclude_fn_body=exclude_fn_body)
-    new_module = module.visit(transformer)
-
-    code = new_module.code
-    code = code.rstrip()
-
-    return code
+    module = module.visit(_RemoveVersionDecoratorTransformer())
+    module = module.visit(_RemoveDocstringTransformer(exclude_fn_body=exclude_fn_body))
+    return module.code.rstrip()
 
 
 @dataclass(frozen=True)
@@ -596,9 +640,9 @@ def _clean_source_from_string(source: str, exclude_fn_body: bool = False) -> str
     """Returns cleaned source code string with optional docstring removal."""
     source = dedent(source)
     module = cst.parse_module(source)
-    transformer = _RemoveDocstringTransformer(exclude_fn_body=exclude_fn_body)
-    new_module = module.visit(transformer)
-    return new_module.code.rstrip()
+    module = module.visit(_RemoveVersionDecoratorTransformer())
+    module = module.visit(_RemoveDocstringTransformer(exclude_fn_body=exclude_fn_body))
+    return module.code.rstrip()
 
 
 def _get_class_source_from_method(method: Callable[..., Any]) -> str:
@@ -694,6 +738,13 @@ class _DependencyCollector:
             # For Python 3.13+
             return definition.func  # pyright: ignore[reportFunctionMemberAccess] # pragma: no cover
 
+        if (
+            (wrapped_function := getattr(definition, "fn", None)) is not None
+            and not hasattr(definition, "__qualname__")
+            and callable(wrapped_function)
+        ):
+            return wrapped_function
+
         return definition
 
     def _get_source_code(self, definition: Callable[..., Any] | type) -> str | None:

{mirascope-2.0.0a4.dist-info → mirascope-2.0.0a5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mirascope
-Version: 2.0.0a4
+Version: 2.0.0a5
 Summary: LLM abstractions that aren't obstructions
 Project-URL: Homepage, https://mirascope.com
 Project-URL: Documentation, https://mirascope.com/docs/mirascope/v2