mirascope 2.0.0__py3-none-any.whl → 2.0.0a0__py3-none-any.whl

mirascope/llm/{providers/base/base_provider.py → clients/base/client.py}

@@ -3,22 +3,20 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-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 collections.abc import Sequence
+from contextvars import ContextVar, Token
+from types import TracebackType
+from typing import Generic, overload
+from typing_extensions import Self, TypeVar, Unpack
 
 from ...context import Context, DepsT
-from ...exceptions import APIError, ProviderError
-from ...formatting import Format, FormattableT, OutputParser
+from ...formatting import Format, FormattableT
 from ...messages import Message, UserContent, user
 from ...responses import (
-    AsyncChunkIterator,
     AsyncContextResponse,
     AsyncContextStreamResponse,
     AsyncResponse,
     AsyncStreamResponse,
-    ChunkIterator,
     ContextResponse,
     ContextStreamResponse,
     Response,
@@ -34,121 +32,53 @@ from ...tools import (
     Tool,
     Toolkit,
 )
+from .params import Params
 
-if TYPE_CHECKING:
-    from ...models import Params
-    from ..provider_id import ProviderId
-
+ModelIdT = TypeVar("ModelIdT", bound=str)
 ProviderClientT = TypeVar("ProviderClientT")
 
-Provider: TypeAlias = "BaseProvider[Any]"
-"""Type alias for `BaseProvider` with any client type."""
-
-ProviderErrorMap: TypeAlias = Mapping[
-    type[Exception],
-    "type[ProviderError] | Callable[[Exception], type[ProviderError]]",
-]
-"""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
-"""
+ClientT = TypeVar("ClientT", bound="BaseClient")
+"""Type variable for an LLM client."""
 
 
-class BaseProvider(Generic[ProviderClientT], ABC):
-    """Base abstract provider for LLM interactions.
+class BaseClient(Generic[ModelIdT, ProviderClientT], ABC):
+    """Base abstract client for provider-specific implementations.
 
     This class defines explicit methods for each type of call, eliminating
     the need for complex overloads in provider implementations.
     """
 
-    id: ClassVar[ProviderId]
-    """Provider identifier (e.g., "anthropic", "openai")."""
-
-    default_scope: ClassVar[str | list[str]]
-    """Default scope(s) for this provider when explicitly registered.
-
-    Can be a single scope string or a list of scopes. For example:
-    - "anthropic/" - Single scope
-    - ["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 -> ProviderError).
-    """
-
     client: ProviderClientT
+    _token: Token | None = None
 
-    @contextmanager
-    def _wrap_errors(self) -> Generator[None, None, None]:
-        """Wrap provider API calls and convert errors to Mirascope exceptions.
+    @property
+    @abstractmethod
+    def _context_var(self) -> ContextVar:
+        """The ContextVar for this client type."""
+        ...
 
-        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 -> ProviderError).
-        """
-        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[ProviderError], error_type_or_fn)
-                    else:
-                        error_type = error_type_or_fn(e)
-
-                    # Construct Mirascope error with metadata
-                    if issubclass(error_type, APIError):
-                        error: ProviderError = error_type(
-                            str(e),
-                            provider=self.id,
-                            status_code=self.get_error_status(e),
-                            original_exception=e,
-                        )
-                    else:
-                        error = error_type(
-                            str(e),
-                            provider=self.id,
-                            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
+    def __enter__(self) -> Self:
+        """Sets the client context and stores the token."""
+        self._token = self._context_var.set(self)
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Restores the client context to the token from the last setting."""
+        if self._token is not None:
+            self._context_var.reset(self._token)
+            self._token = None
 
     @overload
+    @abstractmethod
     def call(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
         format: None = None,
@@ -158,10 +88,11 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     def call(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
         format: type[FormattableT] | Format[FormattableT],
@@ -171,31 +102,27 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     def call(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        format: type[FormattableT] | Format[FormattableT] | None,
         **params: Unpack[Params],
     ) -> Response | Response[FormattableT]:
         """Generate an `llm.Response` with an optional response format."""
         ...
 
+    @abstractmethod
     def call(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> Response | Response[FormattableT]:
         """Generate an `llm.Response` by synchronously calling this client's LLM provider.
@@ -210,37 +137,15 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.Response` object containing the LLM-generated content.
         """
-        with self._wrap_errors():
-            return self._call(
-                model_id=model_id,
-                messages=messages,
-                tools=tools,
-                format=format,
-                **params,
-            )
-
-    @abstractmethod
-    def _call(
-        self,
-        *,
-        model_id: str,
-        messages: Sequence[Message],
-        tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
-        **params: Unpack[Params],
-    ) -> Response | Response[FormattableT]:
-        """Implementation for call(). Subclasses override this method."""
         ...
 
     @overload
+    @abstractmethod
     def context_call(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
@@ -252,11 +157,12 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     def context_call(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
@@ -268,37 +174,33 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     def context_call(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        format: type[FormattableT] | Format[FormattableT] | None,
         **params: Unpack[Params],
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
         """Generate an `llm.ContextResponse` with an optional response format."""
         ...
 
+    @abstractmethod
     def context_call(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
         """Generate an `llm.ContextResponse` by synchronously calling this client's LLM provider.
@@ -314,40 +216,14 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.ContextResponse` object containing the LLM-generated content.
         """
-        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(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: str,
-        messages: Sequence[Message],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
-        **params: Unpack[Params],
-    ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
-        """Implementation for context_call(). Subclasses override this method."""
         ...
 
     @overload
+    @abstractmethod
     async def call_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: None = None,
@@ -357,10 +233,11 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     async def call_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: type[FormattableT] | Format[FormattableT],
@@ -370,31 +247,27 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     async def call_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        format: type[FormattableT] | Format[FormattableT] | None,
         **params: Unpack[Params],
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Generate an `llm.AsyncResponse` with an optional response format."""
         ...
 
+    @abstractmethod
     async def call_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Generate an `llm.AsyncResponse` by asynchronously calling this client's LLM provider.
@@ -409,37 +282,15 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.AsyncResponse` object containing the LLM-generated content.
         """
-        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(
-        self,
-        *,
-        model_id: str,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
-        **params: Unpack[Params],
-    ) -> AsyncResponse | AsyncResponse[FormattableT]:
-        """Implementation for call_async(). Subclasses override this method."""
         ...
 
     @overload
+    @abstractmethod
     async def context_call_async(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
@@ -451,11 +302,12 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     async def context_call_async(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
@@ -467,37 +319,33 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     async def context_call_async(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        format: type[FormattableT] | Format[FormattableT] | None,
         **params: Unpack[Params],
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
         """Generate an `llm.AsyncContextResponse` with an optional response format."""
         ...
 
+    @abstractmethod
     async def context_call_async(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
         """Generate an `llm.AsyncContextResponse` by asynchronously calling this client's LLM provider.
@@ -513,40 +361,14 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.AsyncContextResponse` object containing the LLM-generated content.
         """
-        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(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: str,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
-        **params: Unpack[Params],
-    ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
-        """Implementation for context_call_async(). Subclasses override this method."""
         ...
 
     @overload
+    @abstractmethod
     def stream(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
         format: None = None,
@@ -556,10 +378,11 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     def stream(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
         format: type[FormattableT] | Format[FormattableT],
@@ -569,31 +392,27 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     def stream(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        format: type[FormattableT] | Format[FormattableT] | None,
         **params: Unpack[Params],
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Stream an `llm.StreamResponse` with an optional response format."""
         ...
 
+    @abstractmethod
     def stream(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Generate an `llm.StreamResponse` by synchronously streaming from this client's LLM provider.
@@ -608,41 +427,15 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.StreamResponse` object for iterating over the LLM-generated content.
         """
-        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(
-        self,
-        *,
-        model_id: str,
-        messages: Sequence[Message],
-        tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
-        **params: Unpack[Params],
-    ) -> StreamResponse | StreamResponse[FormattableT]:
-        """Implementation for stream(). Subclasses override this method."""
         ...
 
     @overload
+    @abstractmethod
     def context_stream(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
@@ -654,11 +447,12 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     def context_stream(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
@@ -670,19 +464,17 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     def context_stream(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        format: type[FormattableT] | Format[FormattableT] | None,
         **params: Unpack[Params],
     ) -> (
         ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
@@ -690,19 +482,17 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         """Stream an `llm.ContextStreamResponse` with an optional response format."""
         ...
 
+    @abstractmethod
     def context_stream(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> (
         ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
@@ -720,46 +510,14 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.ContextStreamResponse` object for iterating over the LLM-generated content.
         """
-        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(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: str,
-        messages: Sequence[Message],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
-        **params: Unpack[Params],
-    ) -> (
-        ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
-    ):
-        """Implementation for context_stream(). Subclasses override this method."""
         ...
 
     @overload
+    @abstractmethod
     async def stream_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: None = None,
@@ -769,10 +527,11 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     async def stream_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: type[FormattableT] | Format[FormattableT],
@@ -782,31 +541,27 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     async def stream_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        format: type[FormattableT] | Format[FormattableT] | None,
         **params: Unpack[Params],
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
         """Stream an `llm.AsyncStreamResponse` with an optional response format."""
         ...
 
+    @abstractmethod
     async def stream_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
         """Generate an `llm.AsyncStreamResponse` by asynchronously streaming from this client's LLM provider.
@@ -821,41 +576,15 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.AsyncStreamResponse` object for asynchronously iterating over the LLM-generated content.
         """
-        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(
-        self,
-        *,
-        model_id: str,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
-        **params: Unpack[Params],
-    ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
-        """Implementation for stream_async(). Subclasses override this method."""
         ...
 
     @overload
+    @abstractmethod
     async def context_stream_async(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
@@ -867,11 +596,12 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     async def context_stream_async(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
@@ -883,19 +613,17 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         ...
 
     @overload
+    @abstractmethod
     async def context_stream_async(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        format: type[FormattableT] | Format[FormattableT] | None,
         **params: Unpack[Params],
     ) -> (
         AsyncContextStreamResponse[DepsT, None]
@@ -904,19 +632,17 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         """Stream an `llm.AsyncContextStreamResponse` with an optional response format."""
         ...
 
+    @abstractmethod
     async def context_stream_async(
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> (
         AsyncContextStreamResponse[DepsT, None]
@@ -935,47 +661,13 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         Returns:
             An `llm.AsyncContextStreamResponse` object for asynchronously iterating over the LLM-generated content.
         """
-        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(
-        self,
-        *,
-        ctx: Context[DepsT],
-        model_id: str,
-        messages: Sequence[Message],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
-        **params: Unpack[Params],
-    ) -> (
-        AsyncContextStreamResponse[DepsT, None]
-        | AsyncContextStreamResponse[DepsT, FormattableT]
-    ):
-        """Implementation for context_stream_async(). Subclasses override this method."""
         ...
 
     @overload
     def resume(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: Response,
         content: UserContent,
         **params: Unpack[Params],
@@ -987,7 +679,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     def resume(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: Response[FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -999,7 +691,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     def resume(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: Response | Response[FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1010,7 +702,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     def resume(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: Response | Response[FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1044,7 +736,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     async def resume_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncResponse,
         content: UserContent,
         **params: Unpack[Params],
@@ -1056,7 +748,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     async def resume_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncResponse[FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1068,7 +760,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     async def resume_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncResponse | AsyncResponse[FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1079,7 +771,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     async def resume_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncResponse | AsyncResponse[FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1114,7 +806,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: ContextResponse[DepsT, None],
         content: UserContent,
         **params: Unpack[Params],
@@ -1127,7 +819,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: ContextResponse[DepsT, FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1140,7 +832,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1152,7 +844,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1189,7 +881,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncContextResponse[DepsT, None],
         content: UserContent,
         **params: Unpack[Params],
@@ -1202,7 +894,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncContextResponse[DepsT, FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1215,7 +907,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncContextResponse[DepsT, None]
         | AsyncContextResponse[DepsT, FormattableT],
         content: UserContent,
@@ -1228,7 +920,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncContextResponse[DepsT, None]
         | AsyncContextResponse[DepsT, FormattableT],
         content: UserContent,
@@ -1265,7 +957,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     def resume_stream(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: StreamResponse,
         content: UserContent,
         **params: Unpack[Params],
@@ -1277,7 +969,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     def resume_stream(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: StreamResponse[FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1289,7 +981,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     def resume_stream(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: StreamResponse | StreamResponse[FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1300,7 +992,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     def resume_stream(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: StreamResponse | StreamResponse[FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1334,7 +1026,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     async def resume_stream_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncStreamResponse,
         content: UserContent,
         **params: Unpack[Params],
@@ -1346,7 +1038,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     async def resume_stream_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncStreamResponse[FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1358,7 +1050,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     async def resume_stream_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncStreamResponse | AsyncStreamResponse[FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1369,7 +1061,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
     async def resume_stream_async(
         self,
         *,
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncStreamResponse | AsyncStreamResponse[FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1404,7 +1096,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: ContextStreamResponse[DepsT, None],
         content: UserContent,
         **params: Unpack[Params],
@@ -1417,7 +1109,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: ContextStreamResponse[DepsT, FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1430,7 +1122,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: ContextStreamResponse[DepsT, None]
         | ContextStreamResponse[DepsT, FormattableT],
         content: UserContent,
@@ -1445,7 +1137,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: ContextStreamResponse[DepsT, None]
         | ContextStreamResponse[DepsT, FormattableT],
         content: UserContent,
@@ -1485,7 +1177,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncContextStreamResponse[DepsT, None],
         content: UserContent,
         **params: Unpack[Params],
@@ -1498,7 +1190,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncContextStreamResponse[DepsT, FormattableT],
         content: UserContent,
         **params: Unpack[Params],
@@ -1511,7 +1203,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncContextStreamResponse[DepsT, None]
         | AsyncContextStreamResponse[DepsT, FormattableT],
         content: UserContent,
@@ -1527,7 +1219,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         self,
         *,
         ctx: Context[DepsT],
-        model_id: str,
+        model_id: ModelIdT,
         response: AsyncContextStreamResponse[DepsT, None]
         | AsyncContextStreamResponse[DepsT, FormattableT],
         content: UserContent,
@@ -1562,18 +1254,3 @@ 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.
-        """
-        ...