ahvn.tool.base module¶

class ahvn.tool.base.ToolSpec(*args, **kwargs)[源代码]¶

基类：object

A specification wrapper for tools that can be used with LLMs.

ToolSpec can be used as a decorator to convert functions into tool specifications:

示例

>>> @ToolSpec(name="add", description="Add two numbers")
... def add(a: int, b: int) -> int:
...     return a + b
>>> result = add(a=3, b=5)  # Still works as a function
8
>>> llm.tooluse("Add 3 and 5", tools=[add])  # Works as a tool

static __new__(cls, *args, **kwargs)[源代码]¶

Create a new ToolSpec instance or return a decorator.

When called with keyword arguments (e.g., @ToolSpec(name="add")), returns a decorator that creates a ToolSpec from the decorated function.

When called with no arguments, returns a normal ToolSpec instance.

__init__()[源代码]¶

property name¶

property binded¶

property input_schema¶

property params¶

property output_schema¶

async aexec(**kwargs)[源代码]¶

Execute the tool asynchronously with the provided keyword arguments, returning the full structured content.

参数:: **kwargs -- The keyword arguments to pass to the tool.
返回:: ToolResult. The full structured content.

exec(**kwargs)[源代码]¶

Execute the tool synchronously with the provided keyword arguments, returning the full structured content.

参数:: **kwargs -- The keyword arguments to pass to the tool
返回:: ToolResult. The full structured content.

async acall(**kwargs)[源代码]¶

Execute the tool asynchronously with the provided keyword arguments, returning the main output value.

参数:: **kwargs -- The keyword arguments to pass to the tool
返回:: Any. The main output value.

call(**kwargs)[源代码]¶

Execute the tool synchronously with the provided keyword arguments, returning the main output value.

参数:: **kwargs -- The keyword arguments to pass to the tool
返回:: Any. The main output value.

available()[源代码]¶

Check if this ToolSpec has an active MCP client connection.

This is useful for ToolSpecs created via from_client() to verify the connection is still active before attempting remote calls.

返回:

True if connected to an MCP server, False otherwise.: For local tools (from_function), always returns True.

返回类型:

bool

示例

>>> spec = await ToolSpec.from_client(client, "add")
>>> if spec.available():
...     result = await spec.acall(a=3, b=7)

classmethod from_function(func, examples=None, parse_docstring=True, *args, **kwargs)[源代码]¶

Create a ToolSpec from a Python function.

参数:

func (Callable) -- The Python function or callable class instance to convert into a tool. If a class instance with a __call__ method is provided, that method will be used.
examples (Optional[Iterable[ExperienceType]], optional) -- Example usages of the tool. Defaults to None.
parse_docstring (bool, optional) -- Whether to parse the function's docstring for description. Defaults to True.
*args -- Additional positional arguments to pass to FastMCPTool.from_function.
**kwargs -- Additional keyword arguments to pass to FastMCPTool.from_function.

返回:

An instance of ToolSpec wrapping the provided function.

返回类型:

ToolSpec

classmethod from_mcp(tool, examples=None, *args, **kwargs)[源代码]¶

Create a ToolSpec from an MCP Tool.

参数:

tool (Union[MCPTool, FastMCPTool]) -- The MCP Tool to convert into a ToolSpec.
examples (Optional[Iterable[ExperienceType]], optional) -- Example usages of the tool. Defaults to None.
*args -- Additional positional arguments to pass to FastMCPTool.from_tool.
**kwargs -- Additional keyword arguments to pass to FastMCPTool.from_tool.

返回:

An instance of ToolSpec wrapping the provided MCP tool.

返回类型:

ToolSpec

async classmethod from_client(client, tool_name, examples=None, *args, **kwargs)[源代码]¶

Create a ToolSpec from a FastMCP Client by retrieving a tool from an MCP server.

This method connects to an MCP server via the provided client, retrieves the specified tool's definition, and creates a ToolSpec that can call the remote tool.

参数:

client -- FastMCP Client instance (must be within an async context manager).
tool_name (str) -- The name of the tool to retrieve from the server.
examples (Optional[Iterable[ExperienceType]], optional) -- Example usages of the tool. Defaults to None.
*args -- Additional positional arguments (ignored for client-based tools).
**kwargs -- Additional keyword arguments (ignored for client-based tools).

返回:

An instance of ToolSpec wrapping the remote tool.

返回类型:

ToolSpec

抛出:

ValueError -- If the specified tool is not found on the server.
RuntimeError -- If the client is not connected.

示例

>>> from fastmcp import FastMCP, Client
>>> server = FastMCP("test")
>>> @server.tool()
>>> def add(a: int, b: int = 5) -> int:
...     return a + b
>>> client = Client(server)
>>> async with client:
...     spec = await ToolSpec.from_client(client, "add")
...     result = spec.call(a=3, b=7)
...     print(result)  # 10

classmethod from_code(code, func_name=None, env=None, examples=None, *args, **kwargs)[源代码]¶

Create a ToolSpec from a code snippet.

参数:

code (str) -- The code snippet containing the function definition.
func_name (Optional[str], optional) -- The name of the function to extract from the code. Defaults to None. If None, and only one callable is found, that function will be used. Notice that func_name is NOT the same as name, which will be used as the function name in the tool spec. func_name only helps to identify which function to use from the code snippet, it does NOT affect the tool spec.
env (Optional[Dict], optional) -- The environment in which to execute the code. Defaults to None.
examples (Optional[Iterable[ExperienceType]], optional) -- Example usages of the tool. Defaults to None.
*args -- Additional positional arguments to pass to FastMCPTool.from_function.
**kwargs -- Additional keyword arguments to pass to FastMCPTool.from_function.

返回:

An instance of ToolSpec wrapping the function defined in the provided code.

返回类型:

ToolSpec

bind(param, state_key=None, default=None)[源代码]¶

Bind a parameter to a state key (and a value if the key is not present). The benefit of using a state instead of a direct value is that the state can be updated externally, and the tool will always use the latest value from the state.

参数:

param (str) -- The parameter name to bind.
state_key (Optional[str]) -- The dot-separated state key path to bind the parameter to. It supports nested keys using dot notation (e.g., "user.age"). If None, the parameter name will be used as the state key. Defaults to None.
default (Optional[Any]) -- The default value if the state key is not present. Defaults to None.

返回: