mirascope 2.0.0a5__py3-none-any.whl → 2.0.1__py3-none-any.whl

mirascope/llm/models/models.py

@@ -9,11 +9,10 @@ from typing import overload
 from typing_extensions import Unpack
 
 from ..context import Context, DepsT
-from ..formatting import Format, FormattableT
-from ..messages import Message, UserContent
+from ..formatting import Format, FormattableT, OutputParser
+from ..messages import Message, UserContent, promote_to_messages
 from ..providers import (
     ModelId,
-    Params,
     Provider,
     ProviderId,
     get_provider_for_model,
@@ -38,6 +37,7 @@ from ..tools import (
     Tool,
     Toolkit,
 )
+from .params import Params
 
 MODEL_CONTEXT: ContextVar[Model | None] = ContextVar("MODEL_CONTEXT", default=None)
 
@@ -67,8 +67,7 @@ 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")
-            message = llm.messages.user(f"Please recommend a book in {genre}.")
-            return model.call(messages=[message])
+            return model.call(f"Please recommend a book in {genre}.")
 
         # Uses default model
         response = recommend_book("fantasy")
@@ -86,8 +85,7 @@ class Model:
         def recommend_book(genre: str) -> llm.Response:
             # Hardcoded model, cannot be overridden by context
             model = llm.Model("openai/gpt-5-mini")
-            message = llm.messages.user(f"Please recommend a book in {genre}.")
-            return model.call(messages=[message])
+            return model.call(f"Please recommend a book in {genre}.")
         ```
     """
 
@@ -156,8 +154,8 @@ class Model:
     @overload
     def call(
         self,
+        content: UserContent | Sequence[Message],
         *,
-        messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
         format: None = None,
     ) -> Response:
@@ -167,8 +165,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]:
@@ -178,31 +176,40 @@ class Model:
     @overload
     def call(
         self,
+        content: UserContent | Sequence[Message],
         *,
-        messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[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] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
     ) -> Response | Response[FormattableT]:
         """Generate an `llm.Response` by synchronously calling this model's LLM provider.
 
         Args:
-            messages: Messages to send to the LLM.
+            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.
             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(
             model_id=self.model_id,
             messages=messages,
@@ -214,8 +221,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:
@@ -225,8 +232,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]:
@@ -236,31 +243,40 @@ 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] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[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] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Generate an `llm.AsyncResponse` by asynchronously calling this model's LLM provider.
 
         Args:
-            messages: Messages to send to the LLM.
+            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.
             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(
             model_id=self.model_id,
             messages=messages,
@@ -272,8 +288,8 @@ class Model:
     @overload
     def stream(
         self,
+        content: UserContent | Sequence[Message],
         *,
-        messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
         format: None = None,
     ) -> StreamResponse:
@@ -283,8 +299,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]:
@@ -294,31 +310,40 @@ class Model:
     @overload
     def stream(
         self,
+        content: UserContent | Sequence[Message],
         *,
-        messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[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] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Generate an `llm.StreamResponse` by synchronously streaming from this model's LLM provider.
 
         Args:
-            messages: Messages to send to the LLM.
+            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.
             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(
             model_id=self.model_id,
             messages=messages,
@@ -330,8 +355,8 @@ class Model:
     @overload
     async def stream_async(
         self,
+        content: UserContent | Sequence[Message],
         *,
-        messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: None = None,
     ) -> AsyncStreamResponse:
@@ -341,8 +366,8 @@ class Model:
     @overload
     async def stream_async(
         self,
+        content: UserContent | Sequence[Message],
         *,
-        messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> AsyncStreamResponse[FormattableT]:
@@ -352,31 +377,40 @@ class Model:
     @overload
     async def stream_async(
         self,
+        content: UserContent | Sequence[Message],
         *,
-        messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None,
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
         """Stream an `llm.AsyncStreamResponse` with an optional response format."""
         ...
 
     async def stream_async(
         self,
+        content: UserContent | Sequence[Message],
         *,
-        messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
         """Generate an `llm.AsyncStreamResponse` by asynchronously streaming from this model's LLM provider.
 
         Args:
-            messages: Messages to send to the LLM.
+            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.
             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(
             model_id=self.model_id,
             messages=messages,
@@ -388,9 +422,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,
@@ -402,9 +436,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,
@@ -416,38 +450,47 @@ 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] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[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] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[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(
             ctx=ctx,
             model_id=self.model_id,
@@ -460,9 +503,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,
@@ -474,9 +517,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,
@@ -488,38 +531,47 @@ 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] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[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] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[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(
             ctx=ctx,
             model_id=self.model_id,
@@ -532,9 +584,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,
@@ -546,9 +598,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,
@@ -560,13 +612,16 @@ 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] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None,
     ) -> (
         ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
     ):
@@ -575,27 +630,33 @@ 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] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[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(
             ctx=ctx,
             model_id=self.model_id,
@@ -608,9 +669,9 @@ class Model:
     @overload
     async def context_stream_async(
         self,
+        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
@@ -622,9 +683,9 @@ class Model:
     @overload
     async def context_stream_async(
         self,
+        content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        messages: Sequence[Message],
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
@@ -636,13 +697,16 @@ class Model:
     @overload
     async def context_stream_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] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None,
     ) -> (
         AsyncContextStreamResponse[DepsT, None]
         | AsyncContextStreamResponse[DepsT, FormattableT]
@@ -652,13 +716,16 @@ class Model:
 
     async def context_stream_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] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
     ) -> (
         AsyncContextStreamResponse[DepsT, None]
         | AsyncContextStreamResponse[DepsT, FormattableT]
@@ -666,14 +733,17 @@ 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(
             ctx=ctx,
             model_id=self.model_id,
@@ -1206,7 +1276,7 @@ def model(
     ```python
     m = llm.model("openai/gpt-4o")
     # Use directly
-    response = m.call(messages=[...])
+    response = m.call("Hello!")
     # Or use as context manager
     with m:
         response = recommend_book("fantasy")
@@ -1234,8 +1304,7 @@ def model(
 
         def recommend_book(genre: str) -> llm.Response:
             model = llm.use_model("openai/gpt-5-mini")
-            message = llm.messages.user(f"Please recommend a book in {genre}.")
-            return model.call(messages=[message])
+            return model.call(f"Please recommend a book in {genre}.")
 
         # Override the default model at runtime
         with llm.model("anthropic/claude-sonnet-4-5"):
@@ -1267,7 +1336,7 @@ def model(
         m = llm.model("openai/gpt-4o")
 
         # Use it directly
-        response = m.call(messages=[llm.messages.user("Hello!")])
+        response = m.call("Hello!")
 
         # Or use it as a context manager
         with m:
@@ -1332,8 +1401,7 @@ def use_model(
 
         def recommend_book(genre: str) -> llm.Response:
             model = llm.use_model("openai/gpt-5-mini")
-            message = llm.messages.user(f"Please recommend a book in {genre}.")
-            return model.call(messages=[message])
+            return model.call(f"Please recommend a book in {genre}.")
 
         # Uses the default model (gpt-5-mini)
         response = recommend_book("fantasy")