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

mirascope/llm/models/models.py

@@ -2,16 +2,22 @@
 
 from __future__ import annotations
 
-from collections.abc import Iterator, Sequence
-from contextlib import contextmanager
-from contextvars import ContextVar
-from typing import TYPE_CHECKING, overload
+from collections.abc import Sequence
+from contextvars import ContextVar, Token
+from types import TracebackType
+from typing import overload
 from typing_extensions import Unpack
 
-from ..clients import PROVIDERS, get_client
 from ..context import Context, DepsT
 from ..formatting import Format, FormattableT
 from ..messages import Message, UserContent
+from ..providers import (
+    ModelId,
+    Params,
+    Provider,
+    ProviderId,
+    get_provider_for_model,
+)
 from ..responses import (
     AsyncContextResponse,
     AsyncContextStreamResponse,
@@ -33,18 +39,10 @@ from ..tools import (
     Toolkit,
 )
 
-if TYPE_CHECKING:
-    from ..clients import (
-        ModelId,
-        Params,
-        Provider,
-    )
-
-
 MODEL_CONTEXT: ContextVar[Model | None] = ContextVar("MODEL_CONTEXT", default=None)
 
 
-def get_model_from_context() -> Model | None:
+def model_from_context() -> Model | None:
     """Get the LLM currently set via context, if any."""
     return MODEL_CONTEXT.get()
 
@@ -68,7 +66,7 @@ class Model:
 
         def recommend_book(genre: str) -> llm.Response:
             # Uses context model if available, otherwise creates default
-            model = llm.use_model(provider="openai", model_id="gpt-4o-mini")
+            model = llm.use_model("openai/gpt-5-mini")
             message = llm.messages.user(f"Please recommend a book in {genre}.")
             return model.call(messages=[message])
 
@@ -76,7 +74,7 @@ class Model:
         response = recommend_book("fantasy")
 
         # Override with different model
-        with llm.model(provider="anthropic", model_id="claude-sonnet-4-0"):
+        with llm.model(provider="anthropic", model_id="anthropic/claude-sonnet-4-5"):
             response = recommend_book("fantasy")  # Uses Claude
         ```
 
@@ -87,33 +85,73 @@ class Model:
 
         def recommend_book(genre: str) -> llm.Response:
             # Hardcoded model, cannot be overridden by context
-            model = llm.Model(provider="openai", model_id="gpt-4o-mini")
+            model = llm.Model("openai/gpt-5-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. `gpt-4o-mini`)."""
+    """The model being used (e.g. `"openai/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 provider, model_id, and optional params."""
-        if provider not in PROVIDERS:
-            raise ValueError(f"Unknown provider: {provider}")
-        self.provider = provider
+        """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}'"
+            )
         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(
@@ -165,7 +203,7 @@ class Model:
         Returns:
             An `llm.Response` object containing the LLM-generated content.
         """
-        return get_client(self.provider).call(
+        return self.provider.call(
             model_id=self.model_id,
             messages=messages,
             tools=tools,
@@ -223,7 +261,7 @@ class Model:
         Returns:
             An `llm.AsyncResponse` object containing the LLM-generated content.
         """
-        return await get_client(self.provider).call_async(
+        return await self.provider.call_async(
             model_id=self.model_id,
             messages=messages,
             tools=tools,
@@ -281,7 +319,7 @@ class Model:
         Returns:
             An `llm.StreamResponse` object for iterating over the LLM-generated content.
         """
-        return get_client(self.provider).stream(
+        return self.provider.stream(
             model_id=self.model_id,
             messages=messages,
             tools=tools,
@@ -293,7 +331,7 @@ class Model:
     async def stream_async(
         self,
         *,
-        messages: list[Message],
+        messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: None = None,
     ) -> AsyncStreamResponse:
@@ -304,7 +342,7 @@ class Model:
     async def stream_async(
         self,
         *,
-        messages: list[Message],
+        messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> AsyncStreamResponse[FormattableT]:
@@ -315,7 +353,7 @@ class Model:
     async def stream_async(
         self,
         *,
-        messages: list[Message],
+        messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: type[FormattableT] | Format[FormattableT] | None,
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
@@ -325,7 +363,7 @@ class Model:
     async def stream_async(
         self,
         *,
-        messages: list[Message],
+        messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: type[FormattableT] | Format[FormattableT] | None = None,
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
@@ -339,7 +377,7 @@ class Model:
         Returns:
             An `llm.AsyncStreamResponse` object for asynchronously iterating over the LLM-generated content.
         """
-        return await get_client(self.provider).stream_async(
+        return await self.provider.stream_async(
             model_id=self.model_id,
             messages=messages,
             tools=tools,
@@ -410,7 +448,7 @@ class Model:
         Returns:
             An `llm.ContextResponse` object containing the LLM-generated content.
         """
-        return get_client(self.provider).context_call(
+        return self.provider.context_call(
             ctx=ctx,
             model_id=self.model_id,
             messages=messages,
@@ -482,7 +520,7 @@ class Model:
         Returns:
             An `llm.AsyncContextResponse` object containing the LLM-generated content.
         """
-        return await get_client(self.provider).context_call_async(
+        return await self.provider.context_call_async(
             ctx=ctx,
             model_id=self.model_id,
             messages=messages,
@@ -558,7 +596,7 @@ class Model:
         Returns:
             An `llm.ContextStreamResponse` object for iterating over the LLM-generated content.
         """
-        return get_client(self.provider).context_stream(
+        return self.provider.context_stream(
             ctx=ctx,
             model_id=self.model_id,
             messages=messages,
@@ -572,7 +610,7 @@ class Model:
         self,
         *,
         ctx: Context[DepsT],
-        messages: list[Message],
+        messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
@@ -586,7 +624,7 @@ class Model:
         self,
         *,
         ctx: Context[DepsT],
-        messages: list[Message],
+        messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
@@ -600,7 +638,7 @@ class Model:
         self,
         *,
         ctx: Context[DepsT],
-        messages: list[Message],
+        messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
@@ -616,7 +654,7 @@ class Model:
         self,
         *,
         ctx: Context[DepsT],
-        messages: list[Message],
+        messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
@@ -636,7 +674,7 @@ class Model:
         Returns:
             An `llm.AsyncContextStreamResponse` object for asynchronously iterating over the LLM-generated content.
         """
-        return await get_client(self.provider).context_stream_async(
+        return await self.provider.context_stream_async(
             ctx=ctx,
             model_id=self.model_id,
             messages=messages,
@@ -696,7 +734,7 @@ class Model:
         Returns:
             A new `llm.Response` object containing the extended conversation.
         """
-        return get_client(self.provider).resume(
+        return self.provider.resume(
             model_id=self.model_id,
             response=response,
             content=content,
@@ -754,7 +792,7 @@ class Model:
         Returns:
             A new `llm.AsyncResponse` object containing the extended conversation.
         """
-        return await get_client(self.provider).resume_async(
+        return await self.provider.resume_async(
             model_id=self.model_id,
             response=response,
             content=content,
@@ -817,7 +855,7 @@ class Model:
         Returns:
             A new `llm.ContextResponse` object containing the extended conversation.
         """
-        return get_client(self.provider).context_resume(
+        return self.provider.context_resume(
             ctx=ctx,
             model_id=self.model_id,
             response=response,
@@ -883,7 +921,7 @@ class Model:
         Returns:
             A new `llm.AsyncContextResponse` object containing the extended conversation.
         """
-        return await get_client(self.provider).context_resume_async(
+        return await self.provider.context_resume_async(
             ctx=ctx,
             model_id=self.model_id,
             response=response,
@@ -942,7 +980,7 @@ class Model:
         Returns:
             A new `llm.StreamResponse` object for streaming the extended conversation.
         """
-        return get_client(self.provider).resume_stream(
+        return self.provider.resume_stream(
             model_id=self.model_id,
             response=response,
             content=content,
@@ -1000,7 +1038,7 @@ class Model:
         Returns:
             A new `llm.AsyncStreamResponse` object for asynchronously streaming the extended conversation.
         """
-        return await get_client(self.provider).resume_stream_async(
+        return await self.provider.resume_stream_async(
             model_id=self.model_id,
             response=response,
             content=content,
@@ -1069,7 +1107,7 @@ class Model:
         Returns:
             A new `llm.ContextStreamResponse` object for streaming the extended conversation.
         """
-        return get_client(self.provider).context_resume_stream(
+        return self.provider.context_resume_stream(
             ctx=ctx,
             model_id=self.model_id,
             response=response,
@@ -1141,7 +1179,7 @@ class Model:
         Returns:
             A new `llm.AsyncContextStreamResponse` object for asynchronously streaming the extended conversation.
         """
-        return await get_client(self.provider).context_resume_stream_async(
+        return await self.provider.context_resume_stream_async(
             ctx=ctx,
             model_id=self.model_id,
             response=response,
@@ -1150,71 +1188,139 @@ class Model:
         )
 
 
-@contextmanager
 def model(
-    *,
-    provider: Provider,
     model_id: ModelId,
     **params: Unpack[Params],
-) -> Iterator[None]:
-    """Set a model in context for the duration of the context manager.
+) -> 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:
 
-    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.
+    ```python
+    m = llm.model("openai/gpt-4o")
+    # Use directly
+    response = m.call(messages=[...])
+    # 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.
 
     Args:
-        provider: The LLM provider to use (e.g., "openai:completions", "anthropic", "google").
-        model_id: The specific model identifier for the chosen provider.
+        model_id: A model ID string (e.g., "openai/gpt-4").
         **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(provider="openai", model_id="gpt-4o-mini")
+            model = llm.use_model("openai/gpt-5-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(provider="anthropic", model_id="claude-sonnet-4-0"):
+        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"):
             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(messages=[llm.messages.user("Hello!")])
+
+        # Or use it as a context manager
+        with m:
+            response = recommend_book("fantasy")
+        ```
     """
-    token = MODEL_CONTEXT.set(Model(provider, model_id, **params))
-    try:
-        yield
-    finally:
-        MODEL_CONTEXT.reset(token)
+    return Model(model_id, **params)
 
 
+@overload
 def use_model(
-    *,
-    provider: Provider,
-    model_id: ModelId,
+    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.
+    """
+    ...
+
+
+@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,
     **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.
-    Otherwise, it creates and returns a new `llm.Model` instance with the provided
-    arguments as defaults.
+    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.
 
     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:
-        provider: The LLM provider to use (e.g., "openai:completions", "anthropic", "google").
-        model_id: The specific model identifier for the chosen provider.
+        model: A model ID string (e.g., "openai/gpt-4") or a Model instance
         **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 or a new instance with the specified settings.
+        An `llm.Model` instance from context (if set) or a new instance with the specified settings.
 
     Raises:
         ValueError: If the specified provider is not supported.
@@ -1225,19 +1331,21 @@ def use_model(
         import mirascope.llm as llm
 
         def recommend_book(genre: str) -> llm.Response:
-            model = llm.use_model(provider="openai", model_id="gpt-4o-mini")
+            model = llm.use_model("openai/gpt-5-mini")
             message = llm.messages.user(f"Please recommend a book in {genre}.")
             return model.call(messages=[message])
 
-        # Uses the default model (gpt-4o-mini)
+        # Uses the default model (gpt-5-mini)
         response = recommend_book("fantasy")
 
         # Override with a different model
-        with llm.model(provider="anthropic", model_id="claude-sonnet-4-0"):
+        with llm.model(provider="anthropic", model_id="anthropic/claude-sonnet-4-5"):
             response = recommend_book("fantasy")  # Uses Claude instead
         ```
     """
-    context_model = get_model_from_context()
+    context_model = model_from_context()
     if context_model is not None:
         return context_model
-    return Model(provider, model_id, **params)
+    if isinstance(model, str):
+        return Model(model, **params)
+    return model

mirascope/llm/prompts/__init__.py

@@ -5,29 +5,30 @@ python functions.
 """
 
 from . import _utils
-from .decorator import prompt
-from .protocols import (
+from .decorator import PromptDecorator, prompt
+from .prompts import (
     AsyncContextPrompt,
-    AsyncContextPromptable,
     AsyncPrompt,
-    AsyncPromptable,
     ContextPrompt,
-    ContextPromptable,
     Prompt,
-    Promptable,
-    PromptT,
+)
+from .protocols import (
+    AsyncContextMessageTemplate,
+    AsyncMessageTemplate,
+    ContextMessageTemplate,
+    MessageTemplate,
 )
 
 __all__ = [
+    "AsyncContextMessageTemplate",
     "AsyncContextPrompt",
-    "AsyncContextPromptable",
+    "AsyncMessageTemplate",
     "AsyncPrompt",
-    "AsyncPromptable",
+    "ContextMessageTemplate",
     "ContextPrompt",
-    "ContextPromptable",
+    "MessageTemplate",
     "Prompt",
-    "PromptT",
-    "Promptable",
+    "PromptDecorator",
     "_utils",
     "prompt",
 ]

mirascope/llm/prompts/_utils.py

@@ -1,4 +1,5 @@
 import inspect
+from collections.abc import Sequence
 from typing_extensions import TypeIs
 
 from ..context import DepsT, _utils as _context_utils
@@ -12,24 +13,26 @@ from ..messages import (
 )
 from ..types import P
 from .protocols import (
-    AsyncContextPromptable,
-    AsyncPromptable,
-    ContextPromptable,
-    Promptable,
+    AsyncContextMessageTemplate,
+    AsyncMessageTemplate,
+    ContextMessageTemplate,
+    MessageTemplate,
 )
 
 
 def is_messages(
-    messages_or_content: list[Message] | UserContent,
-) -> TypeIs[list[Message]]:
-    if not messages_or_content:
-        raise ValueError("Prompt returned empty content")
-    return isinstance(messages_or_content, list) and isinstance(
-        messages_or_content[0], SystemMessage | UserMessage | AssistantMessage
-    )
-
-
-def promote_to_messages(result: list[Message] | UserContent) -> list[Message]:
+    messages_or_content: Sequence[Message] | UserContent,
+) -> TypeIs[Sequence[Message]]:
+    if isinstance(messages_or_content, list):
+        if not messages_or_content:
+            raise ValueError("Empty array may not be used as message content")
+        return isinstance(
+            messages_or_content[0], SystemMessage | UserMessage | AssistantMessage
+        )
+    return False
+
+
+def promote_to_messages(result: Sequence[Message] | UserContent) -> Sequence[Message]:
     """Promote a prompt result to a list of messages.
 
     If the result is already a list of Messages, returns it as-is.
@@ -41,20 +44,20 @@ def promote_to_messages(result: list[Message] | UserContent) -> list[Message]:
 
 
 def is_context_promptable(
-    fn: ContextPromptable[P, DepsT]
-    | AsyncContextPromptable[P, DepsT]
-    | Promptable[P]
-    | AsyncPromptable[P],
-) -> TypeIs[ContextPromptable[P, DepsT] | AsyncContextPromptable[P, DepsT]]:
+    fn: ContextMessageTemplate[P, DepsT]
+    | AsyncContextMessageTemplate[P, DepsT]
+    | MessageTemplate[P]
+    | AsyncMessageTemplate[P],
+) -> TypeIs[ContextMessageTemplate[P, DepsT] | AsyncContextMessageTemplate[P, DepsT]]:
     """Type guard to check if a function is a context promptable function."""
     return _context_utils.first_param_is_context(fn)
 
 
 def is_async_promptable(
-    fn: ContextPromptable[P, DepsT]
-    | AsyncContextPromptable[P, DepsT]
-    | Promptable[P]
-    | AsyncPromptable[P],
-) -> TypeIs[AsyncPromptable[P] | AsyncContextPromptable[P, DepsT]]:
+    fn: ContextMessageTemplate[P, DepsT]
+    | AsyncContextMessageTemplate[P, DepsT]
+    | MessageTemplate[P]
+    | AsyncMessageTemplate[P],
+) -> TypeIs[AsyncMessageTemplate[P] | AsyncContextMessageTemplate[P, DepsT]]:
     """Type guard to check if a function is an async promptable function."""
     return inspect.iscoroutinefunction(fn)