Merge pull request #1111 from Mirascope/mira-286

v2: add response.to_tool, stream.to_tool, remove ContextTool

Author: willbakst

python/mirascope/llm/__init__.py

@@ -56,6 +56,7 @@
     RateLimitError,
     ServerError,
     TimeoutError,
+    ToolNotFoundError,
 )
 from .messages import AssistantMessage, Message, SystemMessage, UserMessage
 from .models import LLM, model
@@ -120,6 +121,7 @@
     "ToolCall",
     "ToolCallChunk",
     "ToolDef",
+    "ToolNotFoundError",
     "ToolOutput",
     "UserContent",
     "UserMessage",

python/mirascope/llm/exceptions.py

@@ -42,6 +42,10 @@ class NotFoundError(APIError):
     """Raised when requested resource is not found (404)."""
 
 
+class ToolNotFoundError(APIError):
+    """Raised if a tool_call cannot be converted to any corresponding tool."""
+
+
 class RateLimitError(APIError):
     """Raised when rate limits are exceeded (429)."""
 

python/mirascope/llm/responses/response.py

@@ -13,6 +13,7 @@
 
 from ..content import AssistantContent, Audio, Image, Thinking, ToolCall
 from ..messages import Message
+from ..tools import Tool
 from .finish_reason import FinishReason
 from .usage import Usage
 
@@ -67,11 +68,11 @@ class Response(Generic[T]):
     cost: Decimal | None
     """The cost of the request to the LLM, if available."""
 
-    tools: Sequence[ToolCall]
+    tool_calls: Sequence[ToolCall]
     """The tools the LLM wants called on its behalf, if any."""
 
     @property
-    def tool(self) -> ToolCall | None:
+    def tool_call(self) -> ToolCall | None:
         """Returns the first tool used in the response, if any."""
         raise NotImplementedError()
 
@@ -95,6 +96,14 @@ def thinking(self) -> Thinking | None:
         """Returns the first thinking in the response content, if any."""
         raise NotImplementedError()
 
+    def tool(self, tool_call: ToolCall) -> Tool:
+        """Converts a ToolCall into a Tool. May raise llm.ToolNotFoundError."""
+        raise NotImplementedError()
+
+    def tools(self, tool_calls: list[ToolCall]) -> list[Tool]:
+        """Converts a list of ToolCalls into a list of Tools. May raise llm.ToolNotFoundError."""
+        raise NotImplementedError()
+
     def format(self) -> T:
         """Format the response according to the response format parser.
 

python/mirascope/llm/streams/base.py

@@ -2,7 +2,9 @@
 
 from decimal import Decimal
 
+from ..content import ToolCall
 from ..responses import FinishReason, Response, Usage
+from ..tools import Tool
 
 
 class BaseStream:
@@ -39,3 +41,11 @@ def to_response(self) -> Response:
 
         """
         raise NotImplementedError()
+
+    def tool(self, tool_call: ToolCall) -> Tool:
+        """Converts a ToolCall into a Tool. May raise llm.ToolNotFoundError."""
+        raise NotImplementedError()
+
+    def tools(self, tool_calls: list[ToolCall]) -> list[Tool]:
+        """Converts a list of ToolCalls into a list of Tools. May raise llm.ToolNotFoundError."""
+        raise NotImplementedError()

python/mirascope/llm/tools/__init__.py

@@ -1,17 +1,13 @@
 """The Tools module for LLMs."""
 
-from .base_tool import BaseTool
 from .base_tool_def import BaseToolDef
-from .context_tool import ContextTool
 from .context_tool_def import ContextToolDef
 from .decorator import ContextToolDecorator, ToolDecorator, tool
 from .tool import Tool
 from .tool_def import ToolDef
 
 __all__ = [
-    "BaseTool",
     "BaseToolDef",
-    "ContextTool",
     "ContextToolDecorator",
     "ContextToolDef",
     "Tool",

python/mirascope/llm/tools/base_tool.py

@@ -1,7 +1,7 @@
 """The `BaseToolDef` class for defining tools that LLMs can request be called."""
 
 from dataclasses import dataclass
-from typing import Any, Generic, ParamSpec
+from typing import Generic, ParamSpec
 
 from typing_extensions import TypeVar
 
@@ -28,7 +28,7 @@ class BaseToolDef(Generic[P, R]):
     description: str
     """Description of what the tool does, extracted from the function's docstring."""
 
-    parameters: dict[str, Any]
+    parameters: dict[str, Jsonable]
     """JSON Schema describing the parameters accepted by the tool."""
 
     strict: bool

python/mirascope/llm/tools/base_tool_def.py

@@ -4,17 +4,14 @@
 
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Concatenate, Generic, ParamSpec, TypeGuard
+from typing import Concatenate, Generic, ParamSpec, TypeGuard
 
 from typing_extensions import TypeVar
 
 from ..context import Context
 from ..types import Jsonable
-from .base_tool import BaseTool
 from .base_tool_def import BaseToolDef
-
-if TYPE_CHECKING:
-    from .context_tool import ContextTool
+from .tool import Tool
 
 P = ParamSpec("P")
 R = TypeVar("R", bound=Jsonable)
@@ -45,7 +42,7 @@ def __call__(self, ctx: Context[DepsT], *args: P.args, **kwargs: P.kwargs) -> R:
         """
         return self.fn(ctx, *args, **kwargs)
 
-    def defines(self, tool: BaseTool) -> TypeGuard[ContextTool[P, R, DepsT]]:
+    def defines(self, tool: Tool) -> TypeGuard[Tool[P, R, DepsT]]:
         """Check if this ToolDef matches a specific Tool instance.
 
         This method is used to ensure that the ToolDef was created from a specific

python/mirascope/llm/tools/context_tool.py

@@ -7,26 +7,38 @@
 """
 
 from dataclasses import dataclass
-from typing import ParamSpec, TypeVar
+from typing import Generic, ParamSpec
+
+from typing_extensions import TypeVar
 
 from ..content import ToolOutput
 from ..types import Jsonable
-from .base_tool import BaseTool
+from .context_tool_def import ContextToolDef
 from .tool_def import ToolDef
 
 P = ParamSpec("P")
 R = TypeVar("R", bound=Jsonable)
+DepsT = TypeVar("DepsT", default=None)
 
 
 @dataclass
-class Tool(BaseTool[P, R]):
+class Tool(Generic[P, R, DepsT]):
     """Tool instance with arguments provided by an LLM.
 
     When an LLM uses a tool during a call, a Tool instance is created with the specific
     arguments provided by the LLM.
     """
 
-    tool_def: ToolDef[P, R]
+    name: str
+    """The name of the tool being called."""
+
+    args: dict[str, Jsonable]
+    """The arguments provided by the LLM for this tool call."""
+
+    id: str
+    """Unique identifier for this tool call."""
+
+    tool_def: ToolDef[P, R] | ContextToolDef[P, R, DepsT]
     """The ToolDef that defines the tool being called."""
 
     def call(self) -> ToolOutput[R]: