mirascope 1.0.5__py3-none-any.whl → 2.1.1__py3-none-any.whl

mirascope/llm/tools/toolkit.py

@@ -0,0 +1,178 @@
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from ..content import ToolCall, ToolOutput
+from ..context import Context, DepsT
+from ..exceptions import ToolNotFoundError
+from ..types import Jsonable
+from .provider_tools import ProviderTool
+from .tool_schema import ToolSchemaT
+from .tools import AsyncContextTool, AsyncTool, ContextTool, Tool
+
+ToolkitT = TypeVar(
+    "ToolkitT",
+    bound="Toolkit | AsyncToolkit | ContextToolkit[Any] | AsyncContextToolkit[Any]",
+    covariant=True,
+)
+
+
+@dataclass
+class BaseToolkit(Generic[ToolSchemaT]):
+    """Base class for tool collections.
+
+    Provides common functionality for managing collections of tools,
+    including name validation and tool lookup.
+    """
+
+    tools: Sequence[ToolSchemaT | ProviderTool]
+    """The tools included in the toolkit."""
+
+    tools_dict: dict[str, ToolSchemaT]
+    """A mapping from tool names to tools in the toolkit.
+
+    This dict does not include any `ProviderTool`s, since they do not correspond
+    to tool calls that your code executes.
+    """
+
+    provider_tools_dict: dict[str, ProviderTool]
+    """A mapping from provider tool names to provider tools in the toolkit.
+
+    Provider tools are capabilities built into the provider's API (like web search)
+    that are executed server-side, not by your code.
+    """
+
+    def __init__(self, tools: Sequence[ToolSchemaT | ProviderTool] | None) -> None:
+        """Initialize the toolkit with a collection of tools.
+
+        Args:
+            tools: Sequence of tools to include in the toolkit.
+
+        Raises:
+            ValueError: If multiple tools have the same name.
+        """
+        self.tools = tools or []
+        self.tools_dict = {}
+        self.provider_tools_dict = {}
+        for tool in self.tools:
+            if isinstance(tool, ProviderTool):
+                if tool.name in self.provider_tools_dict:
+                    raise ValueError(f"Multiple provider tools with name: {tool.name}")
+                self.provider_tools_dict[tool.name] = tool
+            else:
+                if tool.name in self.tools_dict:
+                    raise ValueError(f"Multiple tools with name: {tool.name}")
+                self.tools_dict[tool.name] = tool
+
+    def get(self, tool_call: ToolCall) -> ToolSchemaT:
+        """Get a tool that can execute a specific tool call.
+
+        Args:
+            tool_call: The tool call containing the tool name to lookup.
+
+        Returns:
+            The tool whose name matches the tool call.
+
+        Raises:
+            ToolNotFoundError: If no tool with the given name exists.
+        """
+        tool = self.tools_dict.get(tool_call.name, None)
+        if not tool:
+            raise ToolNotFoundError(tool_call.name)
+        return tool
+
+
+class Toolkit(BaseToolkit[Tool]):
+    """A collection of `Tool`s, with helpers for getting and executing specific tools."""
+
+    def execute(self, tool_call: ToolCall) -> ToolOutput[Jsonable]:
+        """Execute a `Tool` using the provided tool call.
+
+        Args:
+            tool_call: The tool call to execute.
+
+        Returns:
+            The output from executing the `Tool`.
+        """
+        try:
+            tool = self.get(tool_call)
+            return tool.execute(tool_call)
+        except ToolNotFoundError as e:
+            return ToolOutput(
+                id=tool_call.id, result=str(e), error=e, name=tool_call.name
+            )
+
+
+class AsyncToolkit(BaseToolkit[AsyncTool]):
+    """A collection of `AsyncTool`s, with helpers for getting and executing specific tools."""
+
+    async def execute(self, tool_call: ToolCall) -> ToolOutput[Jsonable]:
+        """Execute an `AsyncTool` using the provided tool call.
+
+        Args:
+            tool_call: The tool call to execute.
+
+        Returns:
+            The output from executing the `AsyncTool`.
+        """
+        try:
+            tool = self.get(tool_call)
+            return await tool.execute(tool_call)
+        except ToolNotFoundError as e:
+            return ToolOutput(
+                id=tool_call.id, result=str(e), error=e, name=tool_call.name
+            )
+
+
+class ContextToolkit(BaseToolkit[Tool | ContextTool[DepsT]], Generic[DepsT]):
+    """A collection of `ContextTool`s, with helpers for getting and executing specific tools."""
+
+    def execute(self, ctx: Context[DepsT], tool_call: ToolCall) -> ToolOutput[Jsonable]:
+        """Execute a `ContextTool` using the provided tool call.
+
+        Args:
+            ctx: The context containing dependencies that match the tool.
+            tool_call: The tool call to execute.
+
+        Returns:
+            The output from executing the `ContextTool`.
+        """
+        try:
+            tool = self.get(tool_call)
+            if isinstance(tool, ContextTool):
+                return tool.execute(ctx, tool_call)
+            else:
+                return tool.execute(tool_call)
+        except ToolNotFoundError as e:
+            return ToolOutput(
+                id=tool_call.id, result=str(e), error=e, name=tool_call.name
+            )
+
+
+class AsyncContextToolkit(
+    BaseToolkit[AsyncTool | AsyncContextTool[DepsT]], Generic[DepsT]
+):
+    """A collection of `AsyncContextTool`s, with helpers for getting and executing specific tools."""
+
+    async def execute(
+        self, ctx: Context[DepsT], tool_call: ToolCall
+    ) -> ToolOutput[Jsonable]:
+        """Execute an `AsyncContextTool` using the provided tool call.
+
+        Args:
+            ctx: The context containing dependencies that match the tool.
+            tool_call: The tool call to execute.
+
+        Returns:
+            The output from executing the `AsyncContextTool`.
+        """
+        try:
+            tool = self.get(tool_call)
+            if isinstance(tool, AsyncContextTool):
+                return await tool.execute(ctx, tool_call)
+            else:
+                return await tool.execute(tool_call)
+        except ToolNotFoundError as e:
+            return ToolOutput(
+                id=tool_call.id, result=str(e), error=e, name=tool_call.name
+            )

mirascope/llm/tools/tools.py

@@ -0,0 +1,263 @@
+"""The `Tool` class for defining tools that LLMs can request be called."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable
+from typing import Any, Generic, cast
+from typing_extensions import TypeVar
+
+from ..content import ToolCall, ToolOutput
+from ..context import Context, DepsT
+from ..exceptions import ToolError, ToolExecutionError
+from ..types import AnyP, JsonableCovariantT
+from .protocols import (
+    AsyncContextToolFn,
+    AsyncJsonKwargsCallable,
+    AsyncKwargsCallable,
+    AsyncToolFn,
+    ContextKwargsCallable,
+    ContextToolFn,
+    KwargsCallable,
+    ToolFn,
+)
+from .tool_schema import ToolSchema
+
+ToolT = TypeVar(
+    "ToolT",
+    bound="Tool | AsyncTool | ContextTool[Any] | AsyncContextTool[Any]",
+    covariant=True,
+)
+
+
+class Tool(
+    ToolSchema[ToolFn[AnyP, JsonableCovariantT]], Generic[AnyP, JsonableCovariantT]
+):
+    """A tool that can be used by LLMs.
+
+    A `Tool` represents a function that can be called by an LLM during a call.
+    It includes metadata like name, description, and parameter schema.
+
+    This class is not instantiated directly but created by the `@tool()` decorator.
+    """
+
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        cls, fn: ToolFn[AnyP, JsonableCovariantT], *, strict: bool | None = None
+    ) -> Tool[AnyP, JsonableCovariantT]:
+        """Create a `Tool` by inspecting a function and its docstring.
+
+        Args:
+            fn: The function to extract schema from
+            strict: Whether the tool should use strict mode when supported.
+                If None, uses provider's default (usually as strict as possible).
+
+        Returns:
+            a `Tool` representing the function
+        """
+        schema = ToolSchema.from_function(fn, strict=strict, is_context_tool=False)
+        return cls(
+            fn=cast(ToolFn[AnyP, JsonableCovariantT], schema.fn),
+            name=schema.name,
+            description=schema.description,
+            parameters=schema.parameters,
+            strict=schema.strict,
+        )
+
+    def __call__(self, *args: AnyP.args, **kwargs: AnyP.kwargs) -> JsonableCovariantT:
+        """Call the underlying function directly."""
+        return self.fn(*args, **kwargs)
+
+    def execute(self, tool_call: ToolCall) -> ToolOutput[JsonableCovariantT]:
+        """Execute the tool using an LLM-provided `ToolCall`."""
+        kwargs_callable = cast(KwargsCallable[JsonableCovariantT], self.fn)
+        error: ToolError | None = None
+        try:
+            kwargs_from_json = json.loads(tool_call.args)
+            result = kwargs_callable(**kwargs_from_json)
+        except Exception as e:
+            result = str(e)
+            error = ToolExecutionError(e)
+        return ToolOutput(id=tool_call.id, result=result, error=error, name=self.name)
+
+
+class AsyncTool(
+    ToolSchema[AsyncToolFn[AnyP, JsonableCovariantT]],
+    Generic[AnyP, JsonableCovariantT],
+):
+    """An async tool that can be used by LLMs.
+
+    An `AsyncTool` represents an async function that can be called by an LLM during a call.
+    It includes metadata like name, description, and parameter schema.
+
+    This class is not instantiated directly but created by the `@tool()` decorator.
+    """
+
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        cls, fn: AsyncToolFn[AnyP, JsonableCovariantT], *, strict: bool | None = None
+    ) -> AsyncTool[AnyP, JsonableCovariantT]:
+        """Create an `AsyncTool` by inspecting a function and its docstring.
+
+        Args:
+            fn: The function to extract schema from
+            strict: Whether the tool should use strict mode when supported.
+                If None, uses provider's default (usually as strict as possible).
+
+        Returns:
+            an `AsyncTool` representing the function
+        """
+        schema = ToolSchema.from_function(fn, strict=strict, is_context_tool=False)
+        return cls(
+            fn=cast(AsyncToolFn[AnyP, JsonableCovariantT], schema.fn),
+            name=schema.name,
+            description=schema.description,
+            parameters=schema.parameters,
+            strict=schema.strict,
+        )
+
+    def __call__(
+        self, *args: AnyP.args, **kwargs: AnyP.kwargs
+    ) -> Awaitable[JsonableCovariantT]:
+        """Call the underlying async function directly."""
+        return self.fn(*args, **kwargs)
+
+    async def execute(self, tool_call: ToolCall) -> ToolOutput[JsonableCovariantT]:
+        """Execute the async tool using an LLM-provided `ToolCall`."""
+        kwargs_callable = cast(AsyncKwargsCallable[JsonableCovariantT], self.fn)
+        error: ToolError | None = None
+        try:
+            kwargs_from_json = json.loads(tool_call.args)
+            result = await kwargs_callable(**kwargs_from_json)
+        except Exception as e:
+            result = str(e)
+            error = ToolExecutionError(e)
+        return ToolOutput(id=tool_call.id, result=result, error=error, name=self.name)
+
+
+class ContextTool(
+    ToolSchema[ContextToolFn[DepsT, AnyP, JsonableCovariantT]],
+    Generic[DepsT, JsonableCovariantT, AnyP],
+):
+    """Protocol defining a tool that can be used by LLMs.
+
+    A `ContextTool` represents a function that can be called by an LLM during a call.
+    It includes metadata like name, description, and parameter schema.
+
+    This class is not instantiated directly but created by the `@tool()` decorator.
+    """
+
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        cls,
+        fn: ContextToolFn[DepsT, AnyP, JsonableCovariantT],
+        *,
+        strict: bool | None = None,
+    ) -> ContextTool[DepsT, JsonableCovariantT, AnyP]:
+        """Create a `ContextTool` by inspecting a function and its docstring.
+
+        Args:
+            fn: The function to extract schema from
+            strict: Whether the tool should use strict mode when supported.
+                If None, uses provider's default (usually as strict as possible).
+
+        Returns:
+            a `ContextTool` representing the function
+        """
+        schema = ToolSchema.from_function(fn, strict=strict, is_context_tool=True)
+        return cls(
+            fn=cast(ContextToolFn[DepsT, AnyP, JsonableCovariantT], schema.fn),
+            name=schema.name,
+            description=schema.description,
+            parameters=schema.parameters,
+            strict=schema.strict,
+        )
+
+    def __call__(
+        self,
+        ctx: Context[DepsT],
+        *args: AnyP.args,
+        **kwargs: AnyP.kwargs,
+    ) -> JsonableCovariantT:
+        """Call the underlying function directly with context."""
+        return self.fn(ctx, *args, **kwargs)
+
+    def execute(
+        self, ctx: Context[DepsT], tool_call: ToolCall
+    ) -> ToolOutput[JsonableCovariantT]:
+        """Execute the context tool using an LLM-provided `ToolCall`."""
+        kwargs_callable = cast(
+            ContextKwargsCallable[DepsT, JsonableCovariantT], self.fn
+        )
+        error: ToolError | None = None
+        try:
+            kwargs_from_json = json.loads(tool_call.args)
+            result = kwargs_callable(ctx, **kwargs_from_json)
+        except Exception as e:
+            result = str(e)
+            error = ToolExecutionError(e)
+        return ToolOutput(id=tool_call.id, result=result, error=error, name=self.name)
+
+
+class AsyncContextTool(
+    ToolSchema[AsyncContextToolFn[DepsT, AnyP, JsonableCovariantT]],
+    Generic[DepsT, JsonableCovariantT, AnyP],
+):
+    """Protocol defining an async tool that can be used by LLMs with context.
+
+    An `AsyncContextTool` represents an async function that can be called by an LLM during a call.
+    It includes metadata like name, description, and parameter schema.
+
+    This class is not instantiated directly but created by the `@tool()` decorator.
+    """
+
+    @classmethod
+    def from_function(  # pyright: ignore[reportIncompatibleMethodOverride]
+        cls,
+        fn: AsyncContextToolFn[DepsT, AnyP, JsonableCovariantT],
+        *,
+        strict: bool | None = None,
+    ) -> AsyncContextTool[DepsT, JsonableCovariantT, AnyP]:
+        """Create an `AsyncContextTool` by inspecting a function and its docstring.
+
+        Args:
+            fn: The function to extract schema from
+            strict: Whether the tool should use strict mode when supported.
+                If None, uses provider's default (usually as strict as possible).
+
+        Returns:
+            an `AsyncContextTool` representing the function
+        """
+        schema = ToolSchema.from_function(fn, strict=strict, is_context_tool=True)
+        return cls(
+            fn=cast(AsyncContextToolFn[DepsT, AnyP, JsonableCovariantT], schema.fn),
+            name=schema.name,
+            description=schema.description,
+            parameters=schema.parameters,
+            strict=schema.strict,
+        )
+
+    def __call__(
+        self,
+        ctx: Context[DepsT],
+        *args: AnyP.args,
+        **kwargs: AnyP.kwargs,
+    ) -> Awaitable[JsonableCovariantT]:
+        """Call the underlying async function directly with context."""
+        return self.fn(ctx, *args, **kwargs)
+
+    async def execute(
+        self, ctx: Context[DepsT], tool_call: ToolCall
+    ) -> ToolOutput[JsonableCovariantT]:
+        """Execute the async context tool using an LLM-provided `ToolCall`."""
+        kwargs_callable = cast(
+            AsyncJsonKwargsCallable[DepsT, JsonableCovariantT], self.fn
+        )
+        error: ToolError | None = None
+        try:
+            kwargs_from_json = json.loads(tool_call.args)
+            result = await kwargs_callable(ctx, **kwargs_from_json)
+        except Exception as e:
+            result = str(e)
+            error = ToolExecutionError(e)
+        return ToolOutput(id=tool_call.id, result=result, error=error, name=self.name)

mirascope/llm/tools/types.py

@@ -0,0 +1,112 @@
+"""Type aliases for tool parameter types used in provider signatures."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TypeAlias
+from typing_extensions import TypeAliasType
+
+from ..context import DepsT
+from .provider_tools import ProviderTool
+from .tool_schema import AnyToolSchema
+from .toolkit import (
+    AsyncContextToolkit,
+    AsyncToolkit,
+    BaseToolkit,
+    ContextToolkit,
+    Toolkit,
+)
+from .tools import AsyncContextTool, AsyncTool, ContextTool, Tool
+
+AnyTools: TypeAlias = (
+    Sequence[AnyToolSchema | ProviderTool] | BaseToolkit[AnyToolSchema]
+)
+
+Tools: TypeAlias = Sequence[Tool | ProviderTool] | Toolkit
+"""Type alias for sync tool parameters: a sequence of Tools or a Toolkit."""
+
+AsyncTools: TypeAlias = Sequence[AsyncTool | ProviderTool] | AsyncToolkit
+"""Type alias for async tool parameters: a sequence of AsyncTools or an AsyncToolkit."""
+
+ContextTools = TypeAliasType(
+    "ContextTools",
+    Sequence[Tool | ContextTool[DepsT] | ProviderTool] | ContextToolkit[DepsT],
+    type_params=(DepsT,),
+)
+"""Type alias for sync context tool parameters: a sequence of Tools/ContextTools or a ContextToolkit."""
+
+AsyncContextTools = TypeAliasType(
+    "AsyncContextTools",
+    Sequence[AsyncTool | AsyncContextTool[DepsT] | ProviderTool]
+    | AsyncContextToolkit[DepsT],
+    type_params=(DepsT,),
+)
+"""Type alias for async context tool parameters: a sequence of AsyncTools/AsyncContextTools or an AsyncContextToolkit."""
+
+
+def normalize_tools(tools: Tools | None) -> Toolkit:
+    """Normalize tools input to a Toolkit.
+
+    Args:
+        tools: A sequence of Tools, a Toolkit, or None.
+
+    Returns:
+        A Toolkit containing the tools (or an empty Toolkit if None).
+    """
+    if tools is None:
+        return Toolkit(None)
+    if isinstance(tools, Toolkit):
+        return tools
+    return Toolkit(tools)
+
+
+def normalize_async_tools(tools: AsyncTools | None) -> AsyncToolkit:
+    """Normalize async tools input to an AsyncToolkit.
+
+    Args:
+        tools: A sequence of AsyncTools, an AsyncToolkit, or None.
+
+    Returns:
+        An AsyncToolkit containing the tools (or an empty AsyncToolkit if None).
+    """
+    if tools is None:
+        return AsyncToolkit(None)
+    if isinstance(tools, AsyncToolkit):
+        return tools
+    return AsyncToolkit(tools)
+
+
+def normalize_context_tools(
+    tools: ContextTools[DepsT] | None,
+) -> ContextToolkit[DepsT]:
+    """Normalize context tools input to a ContextToolkit.
+
+    Args:
+        tools: A sequence of Tools/ContextTools, a ContextToolkit, or None.
+
+    Returns:
+        A ContextToolkit containing the tools (or an empty ContextToolkit if None).
+    """
+    if tools is None:
+        return ContextToolkit(None)
+    if isinstance(tools, ContextToolkit):
+        return tools
+    return ContextToolkit(tools)
+
+
+def normalize_async_context_tools(
+    tools: AsyncContextTools[DepsT] | None,
+) -> AsyncContextToolkit[DepsT]:
+    """Normalize async context tools input to an AsyncContextToolkit.
+
+    Args:
+        tools: A sequence of AsyncTools/AsyncContextTools, an AsyncContextToolkit, or None.
+
+    Returns:
+        An AsyncContextToolkit containing the tools (or an empty AsyncContextToolkit if None).
+    """
+    if tools is None:
+        return AsyncContextToolkit(None)
+    if isinstance(tools, AsyncContextToolkit):
+        return tools
+    return AsyncContextToolkit(tools)

mirascope/llm/tools/web_search_tool.py

@@ -0,0 +1,32 @@
+"""Web search tool for provider-native web search capabilities."""
+
+from dataclasses import dataclass, field
+
+from .provider_tools import ProviderTool
+
+
+@dataclass(frozen=True)
+class WebSearchTool(ProviderTool):
+    """Web search tool that allows the model to search the internet.
+
+    This is a provider tool - the search is executed server-side by the provider,
+    not by your code. The model decides when to search based on the prompt,
+    and the provider returns search results with citations.
+
+    Supported providers include Anthropic, Google, and OpenAI (when using the Responses API).
+
+    Example:
+        ```python
+        from mirascope import llm
+
+        @llm.call("anthropic/claude-sonnet-4-5", tools=[llm.WebSearchTool()])
+        def search_web(query: str) -> str:
+            return f"Search the web for: {query}"
+
+        response = search_web("Who won the 2024 Super Bowl?")
+        print(response.text())  # Response includes citations from web search
+        ```
+    """
+
+    name: str = field(default="web_search", init=False)
+    """The tool name. Always "web_search" for this tool type."""

mirascope/llm/types/__init__.py

@@ -0,0 +1,22 @@
+"""Types for the LLM module."""
+
+from .dataclass import Dataclass
+from .jsonable import (
+    Jsonable,
+    JsonableCovariantT,
+    JsonableT,
+)
+from .type_vars import AnyP, CovariantT, P
+
+NoneType = type(None)
+
+__all__ = [
+    "AnyP",
+    "CovariantT",
+    "Dataclass",
+    "Jsonable",
+    "JsonableCovariantT",
+    "JsonableT",
+    "NoneType",
+    "P",
+]

mirascope/llm/types/dataclass.py

@@ -0,0 +1,9 @@
+"""A protocol for defining a dataclass type."""
+
+from dataclasses import Field
+from typing import Any, ClassVar, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Dataclass(Protocol):
+    __dataclass_fields__: ClassVar[dict[str, Field[Any]]]

mirascope/llm/types/jsonable.py

@@ -0,0 +1,44 @@
+"""Typing for JSON serializable objects."""
+
+from collections.abc import Mapping, Sequence
+from typing import Protocol, TypeAlias
+from typing_extensions import TypeVar
+
+
+class JsonableObject(Protocol):
+    """Protocol for JSON-serializable objects.
+
+    This protocol defines the interface for objects that can be serialized to
+    JSON. It is used to annotate the `JsonableType` type alias.
+    """
+
+    def json(self) -> str:
+        """Serialize the object as a JSON string."""
+        ...
+
+
+Jsonable: TypeAlias = (
+    None
+    | str
+    | int
+    | float
+    | bool
+    | Sequence["Jsonable"]
+    | Mapping[str, "Jsonable"]
+    | JsonableObject
+)
+"""Simple type alias for JSON-serializable types."""
+
+
+JsonableT = TypeVar("JsonableT", bound=Jsonable)
+"""Type variable for tool output types.
+
+This TypeVar represents the return type of tool functions, which must be
+serializable to JSON (bound to Jsonable) for LLM consumption.
+"""
+
+
+JsonableCovariantT = TypeVar(
+    "JsonableCovariantT", covariant=True, bound=Jsonable, default=Jsonable
+)
+"""Type variable for covariant types that are Jsonable."""

mirascope/llm/types/type_vars.py

@@ -0,0 +1,19 @@
+"""Common TypeVar definitions for the LLM module."""
+
+from typing import TypeVar
+from typing_extensions import ParamSpec
+
+P = ParamSpec("P")
+"""Parameter specification for function signatures.
+
+This ParamSpec is used to preserve function parameter types and signatures
+when wrapping functions with decorators or creating generic callable types.
+It captures both positional and keyword arguments (*args, **kwargs) while
+maintaining their original types.
+"""
+
+AnyP = ParamSpec("AnyP", default=...)
+"""A parameter specification that defaults to ..."""
+
+CovariantT = TypeVar("CovariantT", covariant=True)
+"""Type variable for covariant types."""