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

mirascope/llm/__init__.py

@@ -75,6 +75,7 @@ from .exceptions import (
 )
 from .formatting import (
     Format,
+    FormatSpec,
     FormattableT,
     FormattingMode,
     OutputParser,
@@ -130,6 +131,7 @@ from .responses import (
     ContextResponse,
     ContextStreamResponse,
     FinishReason,
+    ProviderToolUsage,
     RawMessageChunk,
     Response,
     RootResponse,
@@ -144,18 +146,25 @@ from .responses import (
 )
 from .tools import (
     AnyToolFn,
+    AnyTools,
     AnyToolSchema,
     AsyncContextTool,
     AsyncContextToolkit,
+    AsyncContextTools,
     AsyncTool,
     AsyncToolkit,
+    AsyncTools,
     BaseToolkit,
     ContextTool,
     ContextToolkit,
+    ContextTools,
+    ProviderTool,
     Tool,
     Toolkit,
     ToolkitT,
+    Tools,
     ToolSchema,
+    WebSearchTool,
     tool,
 )
 from .types import Jsonable
@@ -165,6 +174,7 @@ __all__ = [
     "AnyResponse",
     "AnyToolFn",
     "AnyToolSchema",
+    "AnyTools",
     "AssistantContent",
     "AssistantContentChunk",
     "AssistantContentPart",
@@ -177,6 +187,7 @@ __all__ = [
     "AsyncContextStreamResponse",
     "AsyncContextTool",
     "AsyncContextToolkit",
+    "AsyncContextTools",
     "AsyncPrompt",
     "AsyncResponse",
     "AsyncStream",
@@ -186,6 +197,7 @@ __all__ = [
     "AsyncTool",
     "AsyncToolCallStream",
     "AsyncToolkit",
+    "AsyncTools",
     "Audio",
     "AuthenticationError",
     "BadRequestError",
@@ -203,12 +215,14 @@ __all__ = [
     "ContextStreamResponse",
     "ContextTool",
     "ContextToolkit",
+    "ContextTools",
     "DepsT",
     "Document",
     "Error",
     "FeatureNotSupportedError",
     "FinishReason",
     "Format",
+    "FormatSpec",
     "FormattableT",
     "FormattingMode",
     "Image",
@@ -229,6 +243,8 @@ __all__ = [
     "Provider",
     "ProviderError",
     "ProviderId",
+    "ProviderTool",
+    "ProviderToolUsage",
     "RateLimitError",
     "RawMessageChunk",
     "Response",
@@ -266,12 +282,15 @@ __all__ = [
     "ToolSchema",
     "Toolkit",
     "ToolkitT",
+    "Tools",
     "URLImageSource",
     "Usage",
     "UsageDeltaChunk",
     "UserContent",
     "UserContentPart",
     "UserMessage",
+    "WebSearchTool",
+    "WebSearchTool",
     "call",
     "calls",
     "content",

mirascope/llm/calls/decorator.py

@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING, Generic, cast, overload
 from typing_extensions import Unpack
 
 from ..context import DepsT
-from ..formatting import Format, FormattableT, OutputParser
+from ..formatting import FormatSpec, FormattableT
 from ..models import Model
 from ..prompts import (
     AsyncContextMessageTemplate,
@@ -29,6 +29,7 @@ from ..tools import (
     AsyncToolkit,
     ContextTool,
     ContextToolkit,
+    ProviderTool,
     Tool,
     Toolkit,
     ToolT,
@@ -58,12 +59,10 @@ class CallDecorator(Generic[ToolT, FormattableT]):
     model: Model
     """The default model to use with this call. May be overridden."""
 
-    tools: Sequence[ToolT] | None
+    tools: Sequence[ToolT | ProviderTool] | 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."""
 
     @overload
@@ -114,7 +113,8 @@ class CallDecorator(Generic[ToolT, FormattableT]):
 
         if is_context and is_async:
             tools = cast(
-                Sequence[AsyncTool | AsyncContextTool[DepsT]] | None, self.tools
+                Sequence[AsyncTool | AsyncContextTool[DepsT] | ProviderTool] | None,
+                self.tools,
             )
             prompt = AsyncContextPrompt(
                 fn=fn,
@@ -126,7 +126,9 @@ class CallDecorator(Generic[ToolT, FormattableT]):
                 default_model=self.model,
             )
         elif is_context:
-            tools = cast(Sequence[Tool | ContextTool[DepsT]] | None, self.tools)
+            tools = cast(
+                Sequence[Tool | ContextTool[DepsT] | ProviderTool] | None, self.tools
+            )
             prompt = ContextPrompt(
                 fn=fn,
                 toolkit=ContextToolkit(tools=tools),
@@ -137,7 +139,7 @@ class CallDecorator(Generic[ToolT, FormattableT]):
                 default_model=self.model,
             )
         elif is_async:
-            tools = cast(Sequence[AsyncTool] | None, self.tools)
+            tools = cast(Sequence[AsyncTool | ProviderTool] | None, self.tools)
             prompt = AsyncPrompt(
                 fn=fn, toolkit=AsyncToolkit(tools=tools), format=self.format
             )
@@ -146,7 +148,7 @@ class CallDecorator(Generic[ToolT, FormattableT]):
                 default_model=self.model,
             )
         else:
-            tools = cast(Sequence[Tool] | None, self.tools)
+            tools = cast(Sequence[Tool | ProviderTool] | None, self.tools)
             prompt = Prompt(fn=fn, toolkit=Toolkit(tools=tools), format=self.format)
             return Call(
                 prompt=prompt,
@@ -158,11 +160,8 @@ class CallDecorator(Generic[ToolT, FormattableT]):
 def call(
     model: ModelId,
     *,
-    tools: Sequence[ToolT] | None = None,
-    format: type[FormattableT]
-    | Format[FormattableT]
-    | OutputParser[FormattableT]
-    | None = None,
+    tools: Sequence[ToolT | ProviderTool] | None = None,
+    format: FormatSpec[FormattableT] | None = None,
     **params: Unpack[Params],
 ) -> CallDecorator[ToolT, FormattableT]:
     """Decorator for converting prompt functions into LLM calls.
@@ -176,11 +175,8 @@ def call(
 def call(
     model: Model,
     *,
-    tools: Sequence[ToolT] | None = None,
-    format: type[FormattableT]
-    | Format[FormattableT]
-    | OutputParser[FormattableT]
-    | None = None,
+    tools: Sequence[ToolT | ProviderTool] | None = None,
+    format: FormatSpec[FormattableT] | None = None,
 ) -> CallDecorator[ToolT, FormattableT]:
     """Decorator for converting prompt functions into LLM calls.
 
@@ -192,11 +188,8 @@ def call(
 def call(
     model: ModelId | Model,
     *,
-    tools: Sequence[ToolT] | None = None,
-    format: type[FormattableT]
-    | Format[FormattableT]
-    | OutputParser[FormattableT]
-    | None = None,
+    tools: Sequence[ToolT | ProviderTool] | None = None,
+    format: FormatSpec[FormattableT] | None = None,
     **params: Unpack[Params],
 ) -> CallDecorator[ToolT, FormattableT]:
     """Decorates a `MessageTemplate` to create a `Call` that can be invoked directly.

mirascope/llm/formatting/__init__.py

@@ -18,11 +18,11 @@ from .primitives import (
     create_wrapper_model,
     is_primitive_type,
 )
-from .types import FormattableT, FormattingMode
+from .types import FormatSpec, FormattableT, FormattingMode
 
 __all__ = [
     "Format",
-    "FormattableT",
+    "FormatSpec",
     "FormattableT",
     "FormattingMode",
     "FromCallArgs",

mirascope/llm/formatting/format.py

@@ -11,7 +11,7 @@ from ..tools import FORMAT_TOOL_NAME, ToolFn, ToolParameterSchema, ToolSchema
 from ..types import NoneType
 from .output_parser import OutputParser, is_output_parser
 from .primitives import create_wrapper_model, is_primitive_type
-from .types import FormattableT, FormattingMode, HasFormattingInstructions
+from .types import FormatSpec, FormattableT, FormattingMode, HasFormattingInstructions
 
 TOOL_MODE_INSTRUCTIONS = f"""Always respond to the user's query using the {FORMAT_TOOL_NAME} tool for structured output."""
 
@@ -267,9 +267,7 @@ def format(
 
 
 def resolve_format(
-    formattable: (
-        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
-    ),
+    formattable: FormatSpec[FormattableT] | None,
     default_mode: FormattingMode,
 ) -> Format[FormattableT] | None:
     """Resolve a `Format` (or None) from a possible `Format`, Formattable, or `OutputParser`.

mirascope/llm/formatting/types.py

@@ -1,15 +1,32 @@
 """Type for the formatting module."""
 
-from typing import Literal, Protocol, runtime_checkable
-from typing_extensions import TypeVar
+from typing import TYPE_CHECKING, Literal, Protocol, runtime_checkable
+from typing_extensions import TypeAliasType, TypeVar
 
 from pydantic import BaseModel
 
 from .primitives import PrimitiveType
 
+if TYPE_CHECKING:
+    from .format import Format
+    from .output_parser import OutputParser
+
 FormattableT = TypeVar(
     "FormattableT", bound=BaseModel | PrimitiveType | None, default=None
 )
+
+FormatSpec = TypeAliasType(
+    "FormatSpec",
+    "type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT]",
+    type_params=(FormattableT,),
+)
+"""Type alias for format parameter types.
+
+A FormatSpec can be:
+- A type (class) that represents the format schema (e.g., a Pydantic BaseModel)
+- A Format wrapper that includes mode and other metadata
+- An OutputParser for custom parsing logic
+"""
 """Type variable for structured response format types.
 
 This TypeVar represents the type of structured output format that LLM responses