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

mirascope/llm/models/models.py

@@ -2,21 +2,16 @@
 
 from __future__ import annotations
 
-from collections.abc import Sequence
-from contextvars import ContextVar, Token
-from types import TracebackType
-from typing import overload
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, overload
 from typing_extensions import Unpack
 
+from ..clients import PROVIDERS, get_client
 from ..context import Context, DepsT
-from ..formatting import Format, FormattableT, OutputParser
-from ..messages import Message, UserContent, promote_to_messages
-from ..providers import (
-    ModelId,
-    Provider,
-    ProviderId,
-    get_provider_for_model,
-)
+from ..formatting import Format, FormattableT
+from ..messages import Message, UserContent
 from ..responses import (
     AsyncContextResponse,
     AsyncContextStreamResponse,
@@ -37,12 +32,19 @@ from ..tools import (
     Tool,
     Toolkit,
 )
-from .params import Params
+
+if TYPE_CHECKING:
+    from ..clients import (
+        ModelId,
+        Params,
+        Provider,
+    )
+
 
 MODEL_CONTEXT: ContextVar[Model | None] = ContextVar("MODEL_CONTEXT", default=None)
 
 
-def model_from_context() -> Model | None:
+def get_model_from_context() -> Model | None:
     """Get the LLM currently set via context, if any."""
     return MODEL_CONTEXT.get()
 
@@ -66,14 +68,15 @@ class Model:
 
         def recommend_book(genre: str) -> llm.Response:
             # Uses context model if available, otherwise creates default
-            model = llm.use_model("openai/gpt-5-mini")
-            return model.call(f"Please recommend a book in {genre}.")
+            model = llm.use_model(provider="openai", model_id="gpt-4o-mini")
+            message = llm.messages.user(f"Please recommend a book in {genre}.")
+            return model.call(messages=[message])
 
         # Uses default model
         response = recommend_book("fantasy")
 
         # Override with different model
-        with llm.model(provider="anthropic", model_id="anthropic/claude-sonnet-4-5"):
+        with llm.model(provider="anthropic", model_id="claude-sonnet-4-0"):
             response = recommend_book("fantasy")  # Uses Claude
         ```
 
@@ -84,78 +87,39 @@ class Model:
 
         def recommend_book(genre: str) -> llm.Response:
             # Hardcoded model, cannot be overridden by context
-            model = llm.Model("openai/gpt-5-mini")
-            return model.call(f"Please recommend a book in {genre}.")
+            model = llm.Model(provider="openai", model_id="gpt-4o-mini")
+            message = llm.messages.user(f"Please recommend a book in {genre}.")
+            return model.call(messages=[message])
         ```
     """
 
+    provider: Provider
+    """The provider being used (e.g. `openai`)."""
+
     model_id: ModelId
-    """The model being used (e.g. `"openai/gpt-4o-mini"`)."""
+    """The model being used (e.g. `gpt-4o-mini`)."""
 
     params: Params
     """The default parameters for the model (temperature, max_tokens, etc.)."""
 
     def __init__(
         self,
+        provider: Provider,
         model_id: ModelId,
         **params: Unpack[Params],
     ) -> None:
-        """Initialize the Model with model_id and optional params."""
-        if "/" not in model_id:
-            raise ValueError(
-                "Invalid model_id format. Expected format: 'provider/model-name' "
-                f"(e.g., 'openai/gpt-4'). Got: '{model_id}'"
-            )
+        """Initialize the Model with provider, model_id, and optional params."""
+        if provider not in PROVIDERS:
+            raise ValueError(f"Unknown provider: {provider}")
+        self.provider = provider
         self.model_id = model_id
         self.params = params
-        self._token_stack: list[Token[Model | None]] = []
-
-    @property
-    def provider(self) -> Provider:
-        """The provider being used (e.g. an `OpenAIProvider`).
-
-        This property dynamically looks up the provider from the registry based on
-        the current model_id. This allows provider overrides via `llm.register_provider()`
-        to take effect even after the model instance is created.
-
-        Raises:
-            NoRegisteredProviderError: If no provider is available for the model_id
-        """
-        return get_provider_for_model(self.model_id)
-
-    @property
-    def provider_id(self) -> ProviderId:
-        """The string id of the provider being used (e.g. `"openai"`).
-
-        This property returns the `id` field of the dynamically resolved provider.
-
-        Raises:
-            NoRegisteredProviderError: If no provider is available for the model_id
-        """
-        return self.provider.id
-
-    def __enter__(self) -> Model:
-        """Enter the context manager, setting this model in context."""
-        token = MODEL_CONTEXT.set(self)
-        self._token_stack.append(token)
-        return self
-
-    def __exit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc_val: BaseException | None,
-        exc_tb: TracebackType | None,
-    ) -> None:
-        """Exit the context manager, resetting the model context."""
-        if self._token_stack:
-            token = self._token_stack.pop()
-            MODEL_CONTEXT.reset(token)
 
     @overload
     def call(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
         format: None = None,
     ) -> Response:
@@ -165,8 +129,8 @@ class Model:
     @overload
     def call(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> Response[FormattableT]:
@@ -176,41 +140,32 @@ class Model:
     @overload
     def call(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        format: type[FormattableT] | Format[FormattableT] | None,
     ) -> Response | Response[FormattableT]:
         """Generate an `llm.Response` with an optional response format."""
         ...
 
     def call(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        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,
     ) -> Response | Response[FormattableT]:
         """Generate an `llm.Response` by synchronously calling this model's LLM provider.
 
         Args:
-            content: Content to send to the LLM. Can be a string (converted to user
-                message), UserContent, a sequence of UserContent, or a sequence of
-                Messages for full control.
+            messages: Messages to send to the LLM.
             tools: Optional tools that the model may invoke.
             format: Optional response format specifier.
 
         Returns:
             An `llm.Response` object containing the LLM-generated content.
         """
-        messages = promote_to_messages(content)
-        return self.provider.call(
+        return get_client(self.provider).call(
             model_id=self.model_id,
             messages=messages,
             tools=tools,
@@ -221,8 +176,8 @@ class Model:
     @overload
     async def call_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: None = None,
     ) -> AsyncResponse:
@@ -232,8 +187,8 @@ class Model:
     @overload
     async def call_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> AsyncResponse[FormattableT]:
@@ -243,41 +198,32 @@ class Model:
     @overload
     async def call_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        format: type[FormattableT] | Format[FormattableT] | None,
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Generate an `llm.AsyncResponse` with an optional response format."""
         ...
 
     async def call_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        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,
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Generate an `llm.AsyncResponse` by asynchronously calling this model's LLM provider.
 
         Args:
-            content: Content to send to the LLM. Can be a string (converted to user
-                message), UserContent, a sequence of UserContent, or a sequence of
-                Messages for full control.
+            messages: Messages to send to the LLM.
             tools: Optional tools that the model may invoke.
             format: Optional response format specifier.
 
         Returns:
             An `llm.AsyncResponse` object containing the LLM-generated content.
         """
-        messages = promote_to_messages(content)
-        return await self.provider.call_async(
+        return await get_client(self.provider).call_async(
             model_id=self.model_id,
             messages=messages,
             tools=tools,
@@ -288,8 +234,8 @@ class Model:
     @overload
     def stream(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
         format: None = None,
     ) -> StreamResponse:
@@ -299,8 +245,8 @@ class Model:
     @overload
     def stream(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> StreamResponse[FormattableT]:
@@ -310,41 +256,32 @@ class Model:
     @overload
     def stream(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        format: type[FormattableT] | Format[FormattableT] | None,
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Stream an `llm.StreamResponse` with an optional response format."""
         ...
 
     def stream(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        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,
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Generate an `llm.StreamResponse` by synchronously streaming from this model's LLM provider.
 
         Args:
-            content: Content to send to the LLM. Can be a string (converted to user
-                message), UserContent, a sequence of UserContent, or a sequence of
-                Messages for full control.
+            messages: Messages to send to the LLM.
             tools: Optional tools that the model may invoke.
             format: Optional response format specifier.
 
         Returns:
             An `llm.StreamResponse` object for iterating over the LLM-generated content.
         """
-        messages = promote_to_messages(content)
-        return self.provider.stream(
+        return get_client(self.provider).stream(
             model_id=self.model_id,
             messages=messages,
             tools=tools,
@@ -355,8 +292,8 @@ class Model:
     @overload
     async def stream_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        messages: list[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: None = None,
     ) -> AsyncStreamResponse:
@@ -366,8 +303,8 @@ class Model:
     @overload
     async def stream_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        messages: list[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> AsyncStreamResponse[FormattableT]:
@@ -377,41 +314,32 @@ class Model:
     @overload
     async def stream_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        messages: list[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        format: type[FormattableT] | Format[FormattableT] | None,
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
         """Stream an `llm.AsyncStreamResponse` with an optional response format."""
         ...
 
     async def stream_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
+        messages: list[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
         """Generate an `llm.AsyncStreamResponse` by asynchronously streaming from this model's LLM provider.
 
         Args:
-            content: Content to send to the LLM. Can be a string (converted to user
-                message), UserContent, a sequence of UserContent, or a sequence of
-                Messages for full control.
+            messages: Messages to send to the LLM.
             tools: Optional tools that the model may invoke.
             format: Optional response format specifier.
 
         Returns:
             An `llm.AsyncStreamResponse` object for asynchronously iterating over the LLM-generated content.
         """
-        messages = promote_to_messages(content)
-        return await self.provider.stream_async(
+        return await get_client(self.provider).stream_async(
             model_id=self.model_id,
             messages=messages,
             tools=tools,
@@ -422,9 +350,9 @@ class Model:
     @overload
     def context_call(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        messages: Sequence[Message],
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
@@ -436,9 +364,9 @@ class Model:
     @overload
     def context_call(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        messages: Sequence[Message],
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
@@ -450,48 +378,39 @@ class Model:
     @overload
     def context_call(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        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,
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
         """Generate an `llm.ContextResponse` with an optional response format."""
         ...
 
     def context_call(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        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,
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
         """Generate an `llm.ContextResponse` by synchronously calling this model's LLM provider.
 
         Args:
-            content: Content to send to the LLM. Can be a string (converted to user
-                message), UserContent, a sequence of UserContent, or a sequence of
-                Messages for full control.
             ctx: Context object with dependencies for tools.
+            messages: Messages to send to the LLM.
             tools: Optional tools that the model may invoke.
             format: Optional response format specifier.
 
         Returns:
             An `llm.ContextResponse` object containing the LLM-generated content.
         """
-        messages = promote_to_messages(content)
-        return self.provider.context_call(
+        return get_client(self.provider).context_call(
             ctx=ctx,
             model_id=self.model_id,
             messages=messages,
@@ -503,9 +422,9 @@ class Model:
     @overload
     async def context_call_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
@@ -517,9 +436,9 @@ class Model:
     @overload
     async def context_call_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
@@ -531,48 +450,39 @@ class Model:
     @overload
     async def context_call_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        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,
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
         """Generate an `llm.AsyncContextResponse` with an optional response format."""
         ...
 
     async def context_call_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        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,
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
         """Generate an `llm.AsyncContextResponse` by asynchronously calling this model's LLM provider.
 
         Args:
-            content: Content to send to the LLM. Can be a string (converted to user
-                message), UserContent, a sequence of UserContent, or a sequence of
-                Messages for full control.
             ctx: Context object with dependencies for tools.
+            messages: Messages to send to the LLM.
             tools: Optional tools that the model may invoke.
             format: Optional response format specifier.
 
         Returns:
             An `llm.AsyncContextResponse` object containing the LLM-generated content.
         """
-        messages = promote_to_messages(content)
-        return await self.provider.context_call_async(
+        return await get_client(self.provider).context_call_async(
             ctx=ctx,
             model_id=self.model_id,
             messages=messages,
@@ -584,9 +494,9 @@ class Model:
     @overload
     def context_stream(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        messages: Sequence[Message],
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
@@ -598,9 +508,9 @@ class Model:
     @overload
     def context_stream(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        messages: Sequence[Message],
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
@@ -612,16 +522,13 @@ class Model:
     @overload
     def context_stream(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        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,
     ) -> (
         ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
     ):
@@ -630,34 +537,28 @@ class Model:
 
     def context_stream(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        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,
     ) -> (
         ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
     ):
         """Generate an `llm.ContextStreamResponse` by synchronously streaming from this model's LLM provider.
 
         Args:
-            content: Content to send to the LLM. Can be a string (converted to user
-                message), UserContent, a sequence of UserContent, or a sequence of
-                Messages for full control.
             ctx: Context object with dependencies for tools.
+            messages: Messages to send to the LLM.
             tools: Optional tools that the model may invoke.
             format: Optional response format specifier.
 
         Returns:
             An `llm.ContextStreamResponse` object for iterating over the LLM-generated content.
         """
-        messages = promote_to_messages(content)
-        return self.provider.context_stream(
+        return get_client(self.provider).context_stream(
             ctx=ctx,
             model_id=self.model_id,
             messages=messages,
@@ -669,9 +570,9 @@ class Model:
     @overload
     async def context_stream_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        messages: list[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
@@ -683,9 +584,9 @@ class Model:
     @overload
     async def context_stream_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        messages: list[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
@@ -697,16 +598,13 @@ class Model:
     @overload
     async def context_stream_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        messages: list[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        format: type[FormattableT] | Format[FormattableT] | None,
     ) -> (
         AsyncContextStreamResponse[DepsT, None]
         | AsyncContextStreamResponse[DepsT, FormattableT]
@@ -716,16 +614,13 @@ class Model:
 
     async def context_stream_async(
         self,
-        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
+        messages: list[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,
     ) -> (
         AsyncContextStreamResponse[DepsT, None]
         | AsyncContextStreamResponse[DepsT, FormattableT]
@@ -733,18 +628,15 @@ class Model:
         """Generate an `llm.AsyncContextStreamResponse` by asynchronously streaming from this model's LLM provider.
 
         Args:
-            content: Content to send to the LLM. Can be a string (converted to user
-                message), UserContent, a sequence of UserContent, or a sequence of
-                Messages for full control.
             ctx: Context object with dependencies for tools.
+            messages: Messages to send to the LLM.
             tools: Optional tools that the model may invoke.
             format: Optional response format specifier.
 
         Returns:
             An `llm.AsyncContextStreamResponse` object for asynchronously iterating over the LLM-generated content.
         """
-        messages = promote_to_messages(content)
-        return await self.provider.context_stream_async(
+        return await get_client(self.provider).context_stream_async(
             ctx=ctx,
             model_id=self.model_id,
             messages=messages,
@@ -804,7 +696,7 @@ class Model:
         Returns:
             A new `llm.Response` object containing the extended conversation.
         """
-        return self.provider.resume(
+        return get_client(self.provider).resume(
             model_id=self.model_id,
             response=response,
             content=content,
@@ -862,7 +754,7 @@ class Model:
         Returns:
             A new `llm.AsyncResponse` object containing the extended conversation.
         """
-        return await self.provider.resume_async(
+        return await get_client(self.provider).resume_async(
             model_id=self.model_id,
             response=response,
             content=content,
@@ -925,7 +817,7 @@ class Model:
         Returns:
             A new `llm.ContextResponse` object containing the extended conversation.
         """
-        return self.provider.context_resume(
+        return get_client(self.provider).context_resume(
             ctx=ctx,
             model_id=self.model_id,
             response=response,
@@ -991,7 +883,7 @@ class Model:
         Returns:
             A new `llm.AsyncContextResponse` object containing the extended conversation.
         """
-        return await self.provider.context_resume_async(
+        return await get_client(self.provider).context_resume_async(
             ctx=ctx,
             model_id=self.model_id,
             response=response,
@@ -1050,7 +942,7 @@ class Model:
         Returns:
             A new `llm.StreamResponse` object for streaming the extended conversation.
         """
-        return self.provider.resume_stream(
+        return get_client(self.provider).resume_stream(
             model_id=self.model_id,
             response=response,
             content=content,
@@ -1108,7 +1000,7 @@ class Model:
         Returns:
             A new `llm.AsyncStreamResponse` object for asynchronously streaming the extended conversation.
         """
-        return await self.provider.resume_stream_async(
+        return await get_client(self.provider).resume_stream_async(
             model_id=self.model_id,
             response=response,
             content=content,
@@ -1177,7 +1069,7 @@ class Model:
         Returns:
             A new `llm.ContextStreamResponse` object for streaming the extended conversation.
         """
-        return self.provider.context_resume_stream(
+        return get_client(self.provider).context_resume_stream(
             ctx=ctx,
             model_id=self.model_id,
             response=response,
@@ -1249,7 +1141,7 @@ class Model:
         Returns:
             A new `llm.AsyncContextStreamResponse` object for asynchronously streaming the extended conversation.
         """
-        return await self.provider.context_resume_stream_async(
+        return await get_client(self.provider).context_resume_stream_async(
             ctx=ctx,
             model_id=self.model_id,
             response=response,
@@ -1258,138 +1150,71 @@ class Model:
         )
 
 
+@contextmanager
 def model(
+    *,
+    provider: Provider,
     model_id: ModelId,
     **params: Unpack[Params],
-) -> Model:
-    """Helper for creating a `Model` instance (which may be used as a context manager).
-
-    This is just an alias for the `Model` constructor, added for convenience.
-
-    This function returns a `Model` instance that implements the context manager protocol.
-    When used with a `with` statement, the model will be set in context and used by both
-    `llm.use_model()` and `llm.call()` within that context. This allows you to override
-    the default model at runtime without modifying function definitions.
-
-    The returned `Model` instance can also be stored and reused:
+) -> Iterator[None]:
+    """Set a model in context for the duration of the context manager.
 
-    ```python
-    m = llm.model("openai/gpt-4o")
-    # Use directly
-    response = m.call("Hello!")
-    # Or use as context manager
-    with m:
-        response = recommend_book("fantasy")
-    ```
-
-    When a model is set in context, it completely overrides any model ID or parameters
-    specified in `llm.use_model()` or `llm.call()`. The context model's parameters take
-    precedence, and any unset parameters use default values.
+    This context manager sets a model that will be used by `llm.use_model()` calls
+    within the context. This allows you to override the default model at runtime.
 
     Args:
-        model_id: A model ID string (e.g., "openai/gpt-4").
+        provider: The LLM provider to use (e.g., "openai:completions", "anthropic", "google").
+        model_id: The specific model identifier for the chosen provider.
         **params: Additional parameters to configure the model (e.g. temperature). See `llm.Params`.
 
-    Returns:
-        A Model instance that can be used as a context manager.
-
     Raises:
         ValueError: If the specified provider is not supported.
 
     Example:
-        With `llm.use_model()`
 
         ```python
         import mirascope.llm as llm
 
         def recommend_book(genre: str) -> llm.Response:
-            model = llm.use_model("openai/gpt-5-mini")
-            return model.call(f"Please recommend a book in {genre}.")
+            model = llm.use_model(provider="openai", model_id="gpt-4o-mini")
+            message = llm.messages.user(f"Please recommend a book in {genre}.")
+            return model.call(messages=[message])
 
         # Override the default model at runtime
-        with llm.model("anthropic/claude-sonnet-4-5"):
-           response = recommend_book("fantasy")  # Uses Claude instead of GPT
-        ```
-
-    Example:
-        With `llm.call()`
-
-        ```python
-        import mirascope.llm as llm
-
-        @llm.call("openai/gpt-5-mini")
-        def recommend_book(genre: str):
-            return f"Please recommend a {genre} book."
-
-        # Override the decorated model at runtime
-        with llm.model("anthropic/claude-sonnet-4-0"):
+        with llm.model(provider="anthropic", model_id="claude-sonnet-4-0"):
             response = recommend_book("fantasy")  # Uses Claude instead of GPT
         ```
-
-    Example:
-        Storing and reusing Model instances
-
-        ```python
-        import mirascope.llm as llm
-
-        # Create and store a model
-        m = llm.model("openai/gpt-4o")
-
-        # Use it directly
-        response = m.call("Hello!")
-
-        # Or use it as a context manager
-        with m:
-            response = recommend_book("fantasy")
-        ```
-    """
-    return Model(model_id, **params)
-
-
-@overload
-def use_model(
-    model: ModelId,
-    **params: Unpack[Params],
-) -> Model:
-    """Get the model from context if available, otherwise create a new `Model`.
-
-    This overload accepts a model ID string and allows additional params.
     """
-    ...
+    token = MODEL_CONTEXT.set(Model(provider, model_id, **params))
+    try:
+        yield
+    finally:
+        MODEL_CONTEXT.reset(token)
 
 
-@overload
 def use_model(
-    model: Model,
-) -> Model:
-    """Get the model from context if available, otherwise use the provided `Model`.
-
-    This overload accepts a `Model` instance and does not allow additional params.
-    """
-    ...
-
-
-def use_model(
-    model: Model | ModelId,
+    *,
+    provider: Provider,
+    model_id: ModelId,
     **params: Unpack[Params],
 ) -> Model:
-    """Get the model from context if available, otherwise create a new `Model`.
+    """Get the model from context if available, otherwise create a new Model.
 
     This function checks if a model has been set in the context (via `llm.model()`
-    context manager). If a model is found in the context, it returns that model,
-    ignoring any model ID or parameters passed to this function. Otherwise, it creates
-    and returns a new `llm.Model` instance with the provided arguments.
+    context manager). If a model is found in the context, it returns that model.
+    Otherwise, it creates and returns a new `llm.Model` instance with the provided
+    arguments as defaults.
 
     This allows you to write functions that work with a default model but can be
     overridden at runtime using the `llm.model()` context manager.
 
     Args:
-        model: A model ID string (e.g., "openai/gpt-4") or a Model instance
+        provider: The LLM provider to use (e.g., "openai:completions", "anthropic", "google").
+        model_id: The specific model identifier for the chosen provider.
         **params: Additional parameters to configure the model (e.g. temperature). See `llm.Params`.
-            Only available when passing a model ID string
 
     Returns:
-        An `llm.Model` instance from context (if set) or a new instance with the specified settings.
+        An `llm.Model` instance from context or a new instance with the specified settings.
 
     Raises:
         ValueError: If the specified provider is not supported.
@@ -1400,20 +1225,19 @@ def use_model(
         import mirascope.llm as llm
 
         def recommend_book(genre: str) -> llm.Response:
-            model = llm.use_model("openai/gpt-5-mini")
-            return model.call(f"Please recommend a book in {genre}.")
+            model = llm.use_model(provider="openai", model_id="gpt-4o-mini")
+            message = llm.messages.user(f"Please recommend a book in {genre}.")
+            return model.call(messages=[message])
 
-        # Uses the default model (gpt-5-mini)
+        # Uses the default model (gpt-4o-mini)
         response = recommend_book("fantasy")
 
         # Override with a different model
-        with llm.model(provider="anthropic", model_id="anthropic/claude-sonnet-4-5"):
+        with llm.model(provider="anthropic", model_id="claude-sonnet-4-0"):
             response = recommend_book("fantasy")  # Uses Claude instead
         ```
     """
-    context_model = model_from_context()
+    context_model = get_model_from_context()
     if context_model is not None:
         return context_model
-    if isinstance(model, str):
-        return Model(model, **params)
-    return model
+    return Model(provider, model_id, **params)