Skip to content

ToolRegistry Class API Reference

The ToolRegistry class manages the registration and organization of tools, maintaining indices by name and scope.

Class Definition

Registry for managing and organizing tools by name and scope.

A centralized registry that maintains a collection of tools with efficient lookup by name and scope. It ensures unique tool names and proper scope indexing for quick access to tools available in different execution contexts.

Attributes:

Name Type Description
_tools Dict[str, Tool]

Dictionary mapping tool names to Tool instances.
_scope_index Dict[ToolScope, Set[str]]

Dictionary mapping scopes to sets of tool names.
Example 
registry = ToolRegistry()

# Register a tool with configuration
config = ToolConfig(
    tool=calculator_func,
    scopes=["think", "act"],
    name="Calculator"
)
registry.register(config)

# Get tools for a scope
think_tools = registry.get_for_scope("think")

# Check if tool exists
if "Calculator" in registry:
    tool = registry.get("Calculator")
Source code in clientai/agent/tools/registry.py 
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
class ToolRegistry:
    """Registry for managing and organizing tools by name and scope.

    A centralized registry that maintains a collection of tools with
    efficient lookup by name and scope. It ensures unique tool names
    and proper scope indexing for quick access to tools available in
    different execution contexts.

    Attributes:
        _tools: Dictionary mapping tool names to Tool instances.
        _scope_index: Dictionary mapping scopes to sets of tool names.

    Example:
        ```python
        registry = ToolRegistry()

        # Register a tool with configuration
        config = ToolConfig(
            tool=calculator_func,
            scopes=["think", "act"],
            name="Calculator"
        )
        registry.register(config)

        # Get tools for a scope
        think_tools = registry.get_for_scope("think")

        # Check if tool exists
        if "Calculator" in registry:
            tool = registry.get("Calculator")
        ```
    """

    def __init__(self) -> None:
        """
        Initialize an empty tool registry.

        Creates empty storage for tools and initializes scope indexing for
        all available tool scopes.
        """
        self._tools: Dict[str, Tool] = {}
        self._scope_index: Dict[ToolScope, Set[str]] = {
            scope: set() for scope in ToolScope
        }

    def register(self, tool_config: ToolConfig) -> None:
        """Register a new tool with the registry.

        Creates a Tool instance if needed and adds it to the registry with
        proper scope indexing. Handles scope inheritance for tools marked
        as available in all scopes.

        Args:
            tool_config: Configuration specifying the tool and its properties.

        Raises:
            ValueError: If a tool with the same name is already registered.

        Example:
            ```python
            registry = ToolRegistry()
            registry.register(ToolConfig(
                tool=my_tool,
                scopes=["think"],
                name="MyTool"
            ))
            ```
        """
        tool = (
            tool_config.tool
            if isinstance(tool_config.tool, Tool)
            else Tool.create(
                func=tool_config.tool,
                name=tool_config.name,
                description=tool_config.description,
            )
        )

        if tool.name in self._tools:
            raise ValueError(f"Tool '{tool.name}' already registered")

        self._tools[tool.name] = tool

        for scope in tool_config.scopes:
            self._scope_index[scope].add(tool.name)
            if scope == ToolScope.ALL:
                for s in ToolScope:
                    self._scope_index[s].add(tool.name)

    def get(self, name: str) -> Optional[Tool]:
        """Retrieve a tool by its name.

        Args:
            name: The name of the tool to retrieve.

        Returns:
            The requested Tool instance, or None if not found.

        Example:
            ```python
            tool = registry.get("Calculator")
            if tool:
                result = tool(5, 3)
            ```
        """
        return self._tools.get(name)

    def get_for_scope(self, scope: Optional[str] = None) -> List[Tool]:
        """Get all tools available in a specific scope.

        Args:
            scope: The scope to filter tools by. If None, returns all tools.

        Returns:
            List of Tool instances available in the specified scope.

        Raises:
            ValueError: If the specified scope is invalid.

        Example:
            ```python
            think_tools = registry.get_for_scope("think")
            all_tools = registry.get_for_scope(None)
            ```
        """
        if scope is None:
            return list(self._tools.values())

        tool_scope = ToolScope.from_str(scope)
        return [self._tools[name] for name in self._scope_index[tool_scope]]

    def __contains__(self, name: str) -> bool:
        """
        Check if a tool is registered by name.

        Args:
            name: The name of the tool to check.

        Returns:
            True if the tool is registered, False otherwise.

        Example:
            ```python
            if "Calculator" in registry:
                tool = registry.get("Calculator")
            ```
        """
        return name in self._tools

    def __len__(self) -> int:
        """
        Get the total number of registered tools.

        Returns:
            Number of tools in the registry.

        Example:
            ```python
            print(f"Registry contains {len(registry)} tools")
            ```
        """
        return len(self._tools)

__contains__(name)

Check if a tool is registered by name.

Parameters:

Name Type Description Default
name str

The name of the tool to check.

 required

Returns:

Type Description
bool

True if the tool is registered, False otherwise.
Example 
if "Calculator" in registry:
    tool = registry.get("Calculator")
Source code in clientai/agent/tools/registry.py 
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
def __contains__(self, name: str) -> bool:
    """
    Check if a tool is registered by name.

    Args:
        name: The name of the tool to check.

    Returns:
        True if the tool is registered, False otherwise.

    Example:
        ```python
        if "Calculator" in registry:
            tool = registry.get("Calculator")
        ```
    """
    return name in self._tools

__init__()

Initialize an empty tool registry.

Creates empty storage for tools and initializes scope indexing for all available tool scopes.

Source code in clientai/agent/tools/registry.py 
41
42
43
44
45
46
47
48
49
50
51
def __init__(self) -> None:
    """
    Initialize an empty tool registry.

    Creates empty storage for tools and initializes scope indexing for
    all available tool scopes.
    """
    self._tools: Dict[str, Tool] = {}
    self._scope_index: Dict[ToolScope, Set[str]] = {
        scope: set() for scope in ToolScope
    }

__len__()

Get the total number of registered tools.

Returns:

Type Description
int

Number of tools in the registry.
Example 
print(f"Registry contains {len(registry)} tools")
Source code in clientai/agent/tools/registry.py 
157
158
159
160
161
162
163
164
165
166
167
168
169
def __len__(self) -> int:
    """
    Get the total number of registered tools.

    Returns:
        Number of tools in the registry.

    Example:
        ```python
        print(f"Registry contains {len(registry)} tools")
        ```
    """
    return len(self._tools)

get(name)

Retrieve a tool by its name.

Parameters:

Name Type Description Default
name str

The name of the tool to retrieve.

 required

Returns:

Type Description
Optional[Tool]

The requested Tool instance, or None if not found.
Example 
tool = registry.get("Calculator")
if tool:
    result = tool(5, 3)
Source code in clientai/agent/tools/registry.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def get(self, name: str) -> Optional[Tool]:
    """Retrieve a tool by its name.

    Args:
        name: The name of the tool to retrieve.

    Returns:
        The requested Tool instance, or None if not found.

    Example:
        ```python
        tool = registry.get("Calculator")
        if tool:
            result = tool(5, 3)
        ```
    """
    return self._tools.get(name)

get_for_scope(scope=None)

Get all tools available in a specific scope.

Parameters:

Name Type Description Default
scope Optional[str]

The scope to filter tools by. If None, returns all tools.

 None

Returns:

Type Description
List[Tool]

List of Tool instances available in the specified scope.

Raises:

Type Description
ValueError

If the specified scope is invalid.
Example 
think_tools = registry.get_for_scope("think")
all_tools = registry.get_for_scope(None)
Source code in clientai/agent/tools/registry.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
def get_for_scope(self, scope: Optional[str] = None) -> List[Tool]:
    """Get all tools available in a specific scope.

    Args:
        scope: The scope to filter tools by. If None, returns all tools.

    Returns:
        List of Tool instances available in the specified scope.

    Raises:
        ValueError: If the specified scope is invalid.

    Example:
        ```python
        think_tools = registry.get_for_scope("think")
        all_tools = registry.get_for_scope(None)
        ```
    """
    if scope is None:
        return list(self._tools.values())

    tool_scope = ToolScope.from_str(scope)
    return [self._tools[name] for name in self._scope_index[tool_scope]]

register(tool_config)

Register a new tool with the registry.

Creates a Tool instance if needed and adds it to the registry with proper scope indexing. Handles scope inheritance for tools marked as available in all scopes.

Parameters:

Name Type Description Default
tool_config ToolConfig

Configuration specifying the tool and its properties.

 required

Raises:

Type Description
ValueError

If a tool with the same name is already registered.
Example 
registry = ToolRegistry()
registry.register(ToolConfig(
    tool=my_tool,
    scopes=["think"],
    name="MyTool"
))
Source code in clientai/agent/tools/registry.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
def register(self, tool_config: ToolConfig) -> None:
    """Register a new tool with the registry.

    Creates a Tool instance if needed and adds it to the registry with
    proper scope indexing. Handles scope inheritance for tools marked
    as available in all scopes.

    Args:
        tool_config: Configuration specifying the tool and its properties.

    Raises:
        ValueError: If a tool with the same name is already registered.

    Example:
        ```python
        registry = ToolRegistry()
        registry.register(ToolConfig(
            tool=my_tool,
            scopes=["think"],
            name="MyTool"
        ))
        ```
    """
    tool = (
        tool_config.tool
        if isinstance(tool_config.tool, Tool)
        else Tool.create(
            func=tool_config.tool,
            name=tool_config.name,
            description=tool_config.description,
        )
    )

    if tool.name in self._tools:
        raise ValueError(f"Tool '{tool.name}' already registered")

    self._tools[tool.name] = tool

    for scope in tool_config.scopes:
        self._scope_index[scope].add(tool.name)
        if scope == ToolScope.ALL:
            for s in ToolScope:
                self._scope_index[s].add(tool.name)