toolregistry.tool module

class toolregistry.tool.Tool(*, name: str, description: str, parameters: Dict[str, Any], callable: Callable[[...], Any], is_async: bool = False, parameters_model: Any | None = None)

Bases: BaseModel

Base class representing an executable tool/function.

Provides core functionality for:

• Function wrapping and metadata management

• Parameter validation using Pydantic

• Synchronous/asynchronous execution

• JSON schema generation

name: str

The name of the tool.

Used as the primary identifier when calling the tool. Must be unique within a tool registry.

description: str

Detailed description of the tool’s functionality.

Should clearly explain what the tool does, its purpose, and any important usage considerations.

parameters: Dict[str, Any]

Parameter schema defining the tool’s expected inputs.

Follows JSON Schema format. Automatically generated from the wrapped function’s type hints when using from_function().

callable: Callable[[...], Any]

The underlying function/method that implements the tool’s logic.

This is excluded from serialization to prevent accidental exposure of sensitive implementation details.

is_async: bool

Flag indicating if the tool requires async execution.

Automatically detected from the wrapped function when using from_function(). Defaults to False for synchronous tools.

parameters_model: Any | None

Pydantic model used for parameter validation.

Automatically generated from the wrapped function’s type hints when using from_function(). Can be None for tools without parameter validation.

classmethod from_function(func: Callable[[...], Any], name: str | None = None, description: str | None = None, namespace: str | None = None) → Tool

Factory method to create Tool from callable.

Automatically:

• Extracts function metadata

• Generates parameter schema

• Handles async/sync detection

Parameters:

• func (Callable[..., Any]) – Function to convert to tool.

• name (Optional[str]) – Override tool name (defaults to function name).

• description (Optional[str]) – Override description (defaults to docstring).

Returns:

Configured Tool instance.

Return type:

Tool

Raises:

ValueError – For unnamed lambda functions.

get_json_schema() → Dict[str, Any]

Generate JSON Schema representation of tool.

Schema includes:

• Name and description

• Parameter definitions

• Async flag

Returns:

JSON Schema compliant tool definition.

Return type:

Dict[str, Any]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

describe() → Dict[str, Any]

Alias for get_json_schema.

Returns:

JSON schema representation of the tool

Return type:

Dict[str, Any]

run(parameters: Dict[str, Any]) → Any

Execute tool synchronously.

Parameters:

parameters (Dict[str, Any]) – Validated input parameters.

Returns:

Tool execution result.

Return type:

Any

Raises:

Exception – On execution failure.

async arun(parameters: Dict[str, Any]) → Any

Execute tool asynchronously.

Parameters:

parameters (Dict[str, Any]) – Validated input parameters.

Returns:

Tool execution result.

Return type:

Any

Raises:

• NotImplementedError – If async execution unsupported.

• Exception – On execution failure.

update_namespace(namespace: str | None, force: bool = False, sep: Literal['-', '.'] = '-') → None

Updates the namespace of a tool.

This method checks if the tool’s name already contains a namespace (indicated by the presence of a separator character). OpenAI requires that function names match the pattern ^[a-zA-Z0-9_-]+$. Some other providers allow dot (.) as separator. If it does and force is True, the existing namespace is replaced with the provided namespace. If force is False and an existing namespace is present, no changes are made. If the tool’s name does not contain a namespace, the namespace is prepended as a prefix to the tool’s name.

Parameters:

• namespace (str) – The new namespace to apply to the tool’s name.

• force (bool, optional) – If True, forces the replacement of an existing namespace. Defaults to False.

Returns:

This method modifies the tool.name attribute in place and does not return a value.

Return type:

None

Example

>>> tool = Tool(name="example_tool")
>>> tool.update_namespace("new_namespace")
>>> tool.name
'new_namespace-example_tool'

>>> tool = Tool(name="old_namespace.example_tool")
>>> tool.update_namespace("new_namespace", force=False)
>>> tool.name
'old_namespace-example_tool'

>>> tool = Tool(name="old_namespace.example_tool")
>>> tool.update_namespace("new_namespace", force=True, sep=".")
>>> tool.name
'new_namespace.example_tool'