mirascope 2.0.2__py3-none-any.whl → 2.1.0__py3-none-any.whl

mirascope/llm/models/models.py

@@ -9,7 +9,7 @@ from typing import overload
 from typing_extensions import Unpack
 
 from ..context import Context, DepsT
-from ..formatting import Format, FormattableT, OutputParser
+from ..formatting import Format, FormatSpec, FormattableT
 from ..messages import Message, UserContent, promote_to_messages
 from ..providers import (
     ModelId,
@@ -28,14 +28,14 @@ from ..responses import (
     StreamResponse,
 )
 from ..tools import (
-    AsyncContextTool,
-    AsyncContextToolkit,
-    AsyncTool,
-    AsyncToolkit,
-    ContextTool,
-    ContextToolkit,
-    Tool,
-    Toolkit,
+    AsyncContextTools,
+    AsyncTools,
+    ContextTools,
+    Tools,
+    normalize_async_context_tools,
+    normalize_async_tools,
+    normalize_context_tools,
+    normalize_tools,
 )
 from .params import Params
 
@@ -156,7 +156,7 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[Tool] | Toolkit | None = None,
+        tools: Tools | None = None,
         format: None = None,
     ) -> Response:
         """Generate an `llm.Response` without a response format."""
@@ -167,7 +167,7 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[Tool] | Toolkit | None = None,
+        tools: Tools | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> Response[FormattableT]:
         """Generate an `llm.Response` with a response format."""
@@ -178,11 +178,8 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        tools: Tools | None = None,
+        format: FormatSpec[FormattableT] | None,
     ) -> Response | Response[FormattableT]:
         """Generate an `llm.Response` with an optional response format."""
         ...
@@ -191,11 +188,8 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        tools: Tools | None = None,
+        format: FormatSpec[FormattableT] | None = None,
     ) -> Response | Response[FormattableT]:
         """Generate an `llm.Response` by synchronously calling this model's LLM provider.
 
@@ -213,7 +207,7 @@ class Model:
         return self.provider.call(
             model_id=self.model_id,
             messages=messages,
-            tools=tools,
+            toolkit=normalize_tools(tools),
             format=format,
             **self.params,
         )
@@ -223,7 +217,7 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        tools: AsyncTools | None = None,
         format: None = None,
     ) -> AsyncResponse:
         """Generate an `llm.AsyncResponse` without a response format."""
@@ -234,7 +228,7 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        tools: AsyncTools | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> AsyncResponse[FormattableT]:
         """Generate an `llm.AsyncResponse` with a response format."""
@@ -245,11 +239,8 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        tools: AsyncTools | None = None,
+        format: FormatSpec[FormattableT] | None,
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Generate an `llm.AsyncResponse` with an optional response format."""
         ...
@@ -258,11 +249,8 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        tools: AsyncTools | None = None,
+        format: FormatSpec[FormattableT] | None = None,
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Generate an `llm.AsyncResponse` by asynchronously calling this model's LLM provider.
 
@@ -280,9 +268,9 @@ class Model:
         return await self.provider.call_async(
             model_id=self.model_id,
             messages=messages,
-            tools=tools,
-            **self.params,
+            toolkit=normalize_async_tools(tools),
             format=format,
+            **self.params,
         )
 
     @overload
@@ -290,7 +278,7 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[Tool] | Toolkit | None = None,
+        tools: Tools | None = None,
         format: None = None,
     ) -> StreamResponse:
         """Stream an `llm.StreamResponse` without a response format."""
@@ -301,7 +289,7 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[Tool] | Toolkit | None = None,
+        tools: Tools | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> StreamResponse[FormattableT]:
         """Stream an `llm.StreamResponse` with a response format."""
@@ -312,11 +300,8 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        tools: Tools | None = None,
+        format: FormatSpec[FormattableT] | None,
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Stream an `llm.StreamResponse` with an optional response format."""
         ...
@@ -325,11 +310,8 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        tools: Tools | None = None,
+        format: FormatSpec[FormattableT] | None = None,
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Generate an `llm.StreamResponse` by synchronously streaming from this model's LLM provider.
 
@@ -347,7 +329,7 @@ class Model:
         return self.provider.stream(
             model_id=self.model_id,
             messages=messages,
-            tools=tools,
+            toolkit=normalize_tools(tools),
             format=format,
             **self.params,
         )
@@ -357,7 +339,7 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        tools: AsyncTools | None = None,
         format: None = None,
     ) -> AsyncStreamResponse:
         """Stream an `llm.AsyncStreamResponse` without a response format."""
@@ -368,7 +350,7 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        tools: AsyncTools | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> AsyncStreamResponse[FormattableT]:
         """Stream an `llm.AsyncStreamResponse` with a response format."""
@@ -379,11 +361,8 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        tools: AsyncTools | None = None,
+        format: FormatSpec[FormattableT] | None,
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
         """Stream an `llm.AsyncStreamResponse` with an optional response format."""
         ...
@@ -392,11 +371,8 @@ class Model:
         self,
         content: UserContent | Sequence[Message],
         *,
-        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        tools: AsyncTools | None = None,
+        format: FormatSpec[FormattableT] | None = None,
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
         """Generate an `llm.AsyncStreamResponse` by asynchronously streaming from this model's LLM provider.
 
@@ -414,7 +390,7 @@ class Model:
         return await self.provider.stream_async(
             model_id=self.model_id,
             messages=messages,
-            tools=tools,
+            toolkit=normalize_async_tools(tools),
             format=format,
             **self.params,
         )
@@ -425,9 +401,7 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
+        tools: ContextTools[DepsT] | None = None,
         format: None = None,
     ) -> ContextResponse[DepsT, None]:
         """Generate an `llm.ContextResponse` without a response format."""
@@ -439,9 +413,7 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
+        tools: ContextTools[DepsT] | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> ContextResponse[DepsT, FormattableT]:
         """Generate an `llm.ContextResponse` with a response format."""
@@ -453,13 +425,8 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        tools: ContextTools[DepsT] | None = None,
+        format: FormatSpec[FormattableT] | None,
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
         """Generate an `llm.ContextResponse` with an optional response format."""
         ...
@@ -469,13 +436,8 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        tools: ContextTools[DepsT] | None = None,
+        format: FormatSpec[FormattableT] | None = None,
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
         """Generate an `llm.ContextResponse` by synchronously calling this model's LLM provider.
 
@@ -495,7 +457,7 @@ class Model:
             ctx=ctx,
             model_id=self.model_id,
             messages=messages,
-            tools=tools,
+            toolkit=normalize_context_tools(tools),
             format=format,
             **self.params,
         )
@@ -506,9 +468,7 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
+        tools: AsyncContextTools[DepsT] | None = None,
         format: None = None,
     ) -> AsyncContextResponse[DepsT, None]:
         """Generate an `llm.AsyncContextResponse` without a response format."""
@@ -520,9 +480,7 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
+        tools: AsyncContextTools[DepsT] | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> AsyncContextResponse[DepsT, FormattableT]:
         """Generate an `llm.AsyncContextResponse` with a response format."""
@@ -534,13 +492,8 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        tools: AsyncContextTools[DepsT] | None = None,
+        format: FormatSpec[FormattableT] | None,
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
         """Generate an `llm.AsyncContextResponse` with an optional response format."""
         ...
@@ -550,13 +503,8 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        tools: AsyncContextTools[DepsT] | None = None,
+        format: FormatSpec[FormattableT] | None = None,
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
         """Generate an `llm.AsyncContextResponse` by asynchronously calling this model's LLM provider.
 
@@ -576,7 +524,7 @@ class Model:
             ctx=ctx,
             model_id=self.model_id,
             messages=messages,
-            tools=tools,
+            toolkit=normalize_async_context_tools(tools),
             format=format,
             **self.params,
         )
@@ -587,9 +535,7 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
+        tools: ContextTools[DepsT] | None = None,
         format: None = None,
     ) -> ContextStreamResponse[DepsT, None]:
         """Stream an `llm.ContextStreamResponse` without a response format."""
@@ -601,9 +547,7 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
+        tools: ContextTools[DepsT] | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> ContextStreamResponse[DepsT, FormattableT]:
         """Stream an `llm.ContextStreamResponse` with a response format."""
@@ -615,13 +559,8 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        tools: ContextTools[DepsT] | None = None,
+        format: FormatSpec[FormattableT] | None,
     ) -> (
         ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
     ):
@@ -633,13 +572,8 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[Tool | ContextTool[DepsT]]
-        | ContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        tools: ContextTools[DepsT] | None = None,
+        format: FormatSpec[FormattableT] | None = None,
     ) -> (
         ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
     ):
@@ -661,7 +595,7 @@ class Model:
             ctx=ctx,
             model_id=self.model_id,
             messages=messages,
-            tools=tools,
+            toolkit=normalize_context_tools(tools),
             format=format,
             **self.params,
         )
@@ -672,9 +606,7 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
+        tools: AsyncContextTools[DepsT] | None = None,
         format: None = None,
     ) -> AsyncContextStreamResponse[DepsT, None]:
         """Stream an `llm.AsyncContextStreamResponse` without a response format."""
@@ -686,9 +618,7 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
+        tools: AsyncContextTools[DepsT] | None = None,
         format: type[FormattableT] | Format[FormattableT],
     ) -> AsyncContextStreamResponse[DepsT, FormattableT]:
         """Stream an `llm.AsyncContextStreamResponse` with a response format."""
@@ -700,13 +630,8 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None,
+        tools: AsyncContextTools[DepsT] | None = None,
+        format: FormatSpec[FormattableT] | None,
     ) -> (
         AsyncContextStreamResponse[DepsT, None]
         | AsyncContextStreamResponse[DepsT, FormattableT]
@@ -719,13 +644,8 @@ class Model:
         content: UserContent | Sequence[Message],
         *,
         ctx: Context[DepsT],
-        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
-        | AsyncContextToolkit[DepsT]
-        | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        tools: AsyncContextTools[DepsT] | None = None,
+        format: FormatSpec[FormattableT] | None = None,
     ) -> (
         AsyncContextStreamResponse[DepsT, None]
         | AsyncContextStreamResponse[DepsT, FormattableT]
@@ -748,7 +668,7 @@ class Model:
             ctx=ctx,
             model_id=self.model_id,
             messages=messages,
-            tools=tools,
+            toolkit=normalize_async_context_tools(tools),
             format=format,
             **self.params,
         )

mirascope/llm/prompts/decorator.py

@@ -4,7 +4,7 @@ from collections.abc import Sequence
 from typing import Generic, cast, overload
 
 from ..context import DepsT
-from ..formatting import Format, FormattableT, OutputParser
+from ..formatting import FormatSpec, FormattableT
 from ..tools import (
     AsyncContextTool,
     AsyncContextToolkit,
@@ -46,18 +46,13 @@ class PromptDecorator(Generic[ToolT, FormattableT]):
     tools: Sequence[ToolT] | None
     """The tools that are included in the prompt, if any."""
 
-    format: (
-        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
-    )
+    format: FormatSpec[FormattableT] | None
     """The structured output format off the prompt, if any."""
 
     def __init__(
         self,
         tools: Sequence[ToolT] | None = None,
-        format: type[FormattableT]
-        | Format[FormattableT]
-        | OutputParser[FormattableT]
-        | None = None,
+        format: FormatSpec[FormattableT] | None = None,
     ) -> None:
         """Initialize the decorator with optional tools and format."""
         self.tools = tools
@@ -173,10 +168,7 @@ def prompt(
 def prompt(
     *,
     tools: Sequence[ToolT] | None = None,
-    format: type[FormattableT]
-    | Format[FormattableT]
-    | OutputParser[FormattableT]
-    | None = None,
+    format: FormatSpec[FormattableT] | None = None,
 ) -> PromptDecorator[ToolT, FormattableT]:
     """Create a decorator for Prompt functions with tools and format"""
 
@@ -189,10 +181,7 @@ def prompt(
     | None = None,
     *,
     tools: Sequence[ToolT] | None = None,
-    format: type[FormattableT]
-    | Format[FormattableT]
-    | OutputParser[FormattableT]
-    | None = None,
+    format: FormatSpec[FormattableT] | None = None,
 ) -> (
     AsyncContextPrompt[P, DepsT, FormattableT]
     | ContextPrompt[P, DepsT, FormattableT]

mirascope/llm/prompts/prompts.py

@@ -6,7 +6,7 @@ from typing import Any, Generic, TypeVar, overload
 
 from ..._utils import copy_function_metadata
 from ..context import Context, DepsT
-from ..formatting import Format, FormattableT, OutputParser
+from ..formatting import FormatSpec, FormattableT
 from ..messages import Message, promote_to_messages
 from ..models import Model
 from ..providers import ModelId
@@ -61,9 +61,7 @@ class Prompt(BasePrompt[MessageTemplate[P]], Generic[P, FormattableT]):
     toolkit: Toolkit
     """The toolkit containing this prompt's tools."""
 
-    format: (
-        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
-    )
+    format: FormatSpec[FormattableT] | None
     """The response format for the generated response."""
 
     def messages(self, *args: P.args, **kwargs: P.kwargs) -> Sequence[Message]:
@@ -157,9 +155,7 @@ class AsyncPrompt(BasePrompt[AsyncMessageTemplate[P]], Generic[P, FormattableT])
     toolkit: AsyncToolkit
     """The toolkit containing this prompt's async tools."""
 
-    format: (
-        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
-    )
+    format: FormatSpec[FormattableT] | None
     """The response format for the generated response."""
 
     async def messages(self, *args: P.args, **kwargs: P.kwargs) -> Sequence[Message]:
@@ -258,9 +254,7 @@ class ContextPrompt(
     toolkit: ContextToolkit[DepsT]
     """The toolkit containing this prompt's context-aware tools."""
 
-    format: (
-        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
-    )
+    format: FormatSpec[FormattableT] | None
     """The response format for the generated response."""
 
     def messages(
@@ -383,9 +377,7 @@ class AsyncContextPrompt(
     toolkit: AsyncContextToolkit[DepsT]
     """The toolkit containing this prompt's async context-aware tools."""
 
-    format: (
-        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
-    )
+    format: FormatSpec[FormattableT] | None
     """The response format for the generated response."""
 
     async def messages(