tools package

Extensible tool-calling framework.

Register tools with the @registry.tool decorator. Each tool is an async callable that receives keyword arguments and returns a string result.

Example usage:

from tools import ToolRegistry

registry = ToolRegistry()

@registry.tool(
    name="get_weather",
    description="Get the current weather for a location.",
    parameters={
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City and state, e.g. 'San Francisco, CA'",
            },
        },
        "required": ["location"],
    },
)
async def get_weather(location: str) -> str:
    return f"The weather in {location} is sunny and 72°F."

class tools.ToolDefinition(name, description, parameters, handler, no_background=False, allow_repeat=False)[source]

Bases: object

Internal representation of a registered tool.

Parameters:

name (str)
description (str)
parameters (dict[str, Any])
handler (Callable[[...], Awaitable[str]])
no_background (bool)
allow_repeat (bool)

name: str

description: str

parameters: dict[str, Any]

handler: Callable[[...], Awaitable[str]]

no_background: bool = False

allow_repeat: bool = False

class tools.ToolRegistry(task_manager=None)[source]

Bases: object

Registry that stores tool definitions and executes tool calls.

Parameters:: task_manager (TaskManager | None)

__init__(task_manager=None)[source]

Initialize the instance.

Parameters:: task_manager (TaskManager | None) – The task manager value.
Return type:: None

task_manager: TaskManager | None

set_permissions(permissions)[source]

Set per-tool user whitelists.

permissions maps tool names to lists of allowed user IDs. A special value "*" in the list means everyone. Tools not present in the dict are allowed for all users.

Return type:: None
Parameters:: permissions (dict[str, list[str]])

is_allowed(tool_name, user_id)[source]

Return True if user_id may execute tool_name.

Rules: 1. Tool not in the permissions dict -> allow (backward compatible). 2. "*" in the tool’s allowed list -> allow. 3. user_id in the tool’s allowed list -> allow. 4. Otherwise -> deny.

Return type:

bool

Parameters:

tool_name (str)
user_id (str)

tool(name, description, parameters)[source]

Decorator to register an async function as a tool.

Parameters:

name (str) – The tool name exposed to the LLM.
description (str) – Human-readable description of what the tool does.
parameters (dict[str, Any]) – JSON Schema object describing the tool’s parameters.

Return type:

Callable

async call(name, arguments, user_id='', ctx=None)[source]

Execute a registered tool by name and return the result string.

If user_id is provided, the tool’s permission whitelist is checked first. If ctx is provided and the handler declares a ctx parameter, the context is injected automatically.

If the tool raises an exception the error message is returned so the LLM can see what went wrong and recover.

Return type:

str

Parameters:

name (str)
arguments (dict[str, Any])
user_id (str)
ctx (ToolContext | None)

invalidate_cache()[source]

Clear the cached OpenAI tool representations.

Called automatically when tools are registered via the tool decorator. Must also be called explicitly after bulk mutations such as _tools.clear() (e.g. in reload_tools).

Return type:: None

get_openai_tools()[source]

Return tool definitions in the OpenAI function-calling JSON format.

Returns an empty list when no tools are registered, which means the tools parameter can be omitted from the API call.

Return type:: list[dict[str, Any]]

get_openai_tools_by_names(names)[source]

Return only the OpenAI tool dicts whose names are in names.

Uses a cached dict for O(1) per-name lookup instead of rebuilding and filtering the full list each time.

Return type:: list[dict[str, Any]]
Parameters:: names (set[str])

list_tools()[source]

Return all registered tool definitions.

Return type:: list[ToolDefinition]

repeat_allowed_tools()[source]

Return names of tools that are exempt from repetition-loop detection.

Return type:: frozenset[str]

property has_tools: bool

Check whether has tools.

Returns:: True on success, False otherwise.
Return type:: bool

__len__()[source]

Internal helper: len .

Returns:: The result.
Return type:: int

tools package

Submodules