Skip to content

Registry Module

registry

Tool registry for managing and calling registered tools.

ToolError

Bases: Exception

Base exception for tool-related errors.

Source code in openai_toolchain/registry.py 
13
14
class ToolError(Exception):
    """Base exception for tool-related errors."""

ToolRegistry

Singleton registry for AI tools with automatic schema generation.

Source code in openai_toolchain/registry.py 
 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
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
class ToolRegistry:
    """Singleton registry for AI tools with automatic schema generation."""

    _instance: Optional["ToolRegistry"] = None
    _initialized: bool = False

    def __new__(cls) -> "ToolRegistry":
        if cls._instance is None:
            instance = super().__new__(cls)
            cls._instance = instance
        return cls._instance

    def __init__(self) -> None:
        if not getattr(self, "_initialized", False):
            self._tools: Dict[str, Dict[str, Any]] = {}
            self._initialized = True

    def register(
        self,
        func: Optional[T] = None,
        *,
        name: Optional[str] = None,
        description: Optional[str] = None,
        non_ai_params: Optional[List[str]] = None,
        **kwargs: Any,
    ) -> Union[Callable[[T], T], T]:
        """Register a function as a tool.

        Can be used as a decorator with or without arguments.

        Args:
            func: The function to register (automatically passed when used as decorator)
            name: Optional custom name for the tool
            description: Optional description for the tool
            **kwargs: Additional tool metadata

        Returns:
            The decorated function or a decorator
        """

        def decorator(f: T) -> T:
            tool_name = name or f.__name__
            tool_description = description or (f.__doc__ or "").strip()

            # Initialize local non_ai_params list
            local_non_ai_params = (
                non_ai_params.copy() if non_ai_params is not None else []
            )

            if local_non_ai_params:
                non_ai_param_joined = "\\n- ".join(local_non_ai_params)
                tool_description += f"""

                Non-AI parameters (do not use these):
                {non_ai_param_joined}
                """

            # Extract parameter information
            sig = inspect.signature(f)
            parameters: Dict[str, Any] = {}
            required: List[str] = []
            type_hints = get_type_hints(f)

            for param_name, param in sig.parameters.items():
                if param_name == "self" or param_name in local_non_ai_params:
                    continue

                param_type = type_hints.get(param_name, str)
                param_info = self._get_parameter_info(param, param_type)
                parameters[param_name] = param_info

                if param.default == inspect.Parameter.empty:
                    required.append(param_name)

            # Create the tool schema with proper typing
            tool_schema: Dict[str, Any] = {
                "type": "function",
                "function": {
                    "name": tool_name,
                    "description": tool_description,
                    "parameters": {
                        "type": "object",
                        "properties": parameters,
                    },
                },
            }

            if required:
                # Explicitly type the parameters dictionary
                function_params = tool_schema["function"]["parameters"]
                if isinstance(function_params, MutableMapping):
                    function_params["required"] = required

            # Store the tool
            self._tools[tool_name] = {
                "function": f,
                "schema": tool_schema,
                "metadata": kwargs,
            }

            return f

        if func is not None:
            return decorator(func)
        return decorator

    def _get_parameter_info(
        self,
        param: inspect.Parameter,
        param_type: Type[Any],
    ) -> Dict[str, Any]:
        """Get parameter information for the schema.

        Args:
            param: The parameter to get info for
            param_type: The type of the parameter

        Returns:
            Dictionary containing parameter schema information
        """
        param_info: Dict[str, Any] = {}

        # Handle different parameter types
        if param_type in (str, int, float, bool):
            param_info["type"] = param_type.__name__
        elif param_type == list:
            param_info.update({"type": "array", "items": {"type": "string"}})
        elif param_type == dict:
            param_info["type"] = "object"
        else:
            param_info["type"] = "string"

        # Add description if available
        if param.annotation != inspect.Parameter.empty:
            param_info["description"] = str(param.annotation)

        # Add default value if available
        if param.default != inspect.Parameter.empty:
            param_info["default"] = param.default

        return param_info

    def _get_type_name(self, type_: Type[Any]) -> str:
        """Convert Python type to JSON schema type name.

        Args:
            type_: The Python type to convert

        Returns:
            String representing the JSON schema type
        """
        type_map = {
            str: "string",
            int: "integer",
            float: "number",
            bool: "boolean",
        }
        return type_map.get(type_, "string")

    def get_tool(self, name: str) -> Optional[Callable[..., Any]]:
        """Get a registered tool by name.

        Args:
            name: The name of the tool

        Returns:
            The registered function or None if not found
        """
        tool = self._tools.get(name)
        if tool is None:
            return None
        return tool.get("function")

    def call_tool(self, name: str, arguments: Dict[str, Any]) -> Any:
        """Call a registered tool by name with the given arguments.

        Args:
            name: The name of the tool to call
            arguments: The arguments to pass to the tool

        Returns:
            The result of the tool call

        Raises:
            ToolError: If the tool is not found or an error occurs during execution
        """
        tool = self._tools.get(name)
        if not tool:
            raise ToolError(f"Tool '{name}' not found")

        try:
            return tool["function"](**arguments)
        except Exception as e:
            _logger.error(f"Error calling tool '{name}': {e}", exc_info=True)
            raise ToolError(f"Error calling tool '{name}': {e}") from e

    def get_openai_tools(self) -> List[Dict[str, Any]]:
        """Get all registered tools in OpenAI format.

        Returns:
            List[Dict[str, Any]]: A list of tool definitions in OpenAI format
        """
        return [tool["schema"] for tool in self._tools.values() if "schema" in tool]

    def clear(self) -> None:
        """Clear all registered tools."""
        self._tools.clear()

    # Make the registry callable as a decorator
    tool = register

call_tool(name, arguments)

Call a registered tool by name with the given arguments.

Parameters:

Name Type Description Default
name str

The name of the tool to call

 required
arguments Dict[str, Any]

The arguments to pass to the tool

 required

Returns:

Type Description
Any

The result of the tool call

Raises:

Type Description
ToolError

If the tool is not found or an error occurs during execution
Source code in openai_toolchain/registry.py 
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
def call_tool(self, name: str, arguments: Dict[str, Any]) -> Any:
    """Call a registered tool by name with the given arguments.

    Args:
        name: The name of the tool to call
        arguments: The arguments to pass to the tool

    Returns:
        The result of the tool call

    Raises:
        ToolError: If the tool is not found or an error occurs during execution
    """
    tool = self._tools.get(name)
    if not tool:
        raise ToolError(f"Tool '{name}' not found")

    try:
        return tool["function"](**arguments)
    except Exception as e:
        _logger.error(f"Error calling tool '{name}': {e}", exc_info=True)
        raise ToolError(f"Error calling tool '{name}': {e}") from e

clear()

Clear all registered tools.

Source code in openai_toolchain/registry.py 
221
222
223
def clear(self) -> None:
    """Clear all registered tools."""
    self._tools.clear()

get_openai_tools()

Get all registered tools in OpenAI format.

Returns:

Type Description
List[Dict[str, Any]]

List[Dict[str, Any]]: A list of tool definitions in OpenAI format
Source code in openai_toolchain/registry.py 
213
214
215
216
217
218
219
def get_openai_tools(self) -> List[Dict[str, Any]]:
    """Get all registered tools in OpenAI format.

    Returns:
        List[Dict[str, Any]]: A list of tool definitions in OpenAI format
    """
    return [tool["schema"] for tool in self._tools.values() if "schema" in tool]

get_tool(name)

Get a registered tool by name.

Parameters:

Name Type Description Default
name str

The name of the tool

 required

Returns:

Type Description
Optional[Callable[..., Any]]

The registered function or None if not found
Source code in openai_toolchain/registry.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
def get_tool(self, name: str) -> Optional[Callable[..., Any]]:
    """Get a registered tool by name.

    Args:
        name: The name of the tool

    Returns:
        The registered function or None if not found
    """
    tool = self._tools.get(name)
    if tool is None:
        return None
    return tool.get("function")

register(func=None, *, name=None, description=None, non_ai_params=None, **kwargs)

Register a function as a tool.

Can be used as a decorator with or without arguments.

Parameters:

Name Type Description Default
func Optional[T]

The function to register (automatically passed when used as decorator)

 None
name Optional[str]

Optional custom name for the tool

 None
description Optional[str]

Optional description for the tool

 None
**kwargs Any

Additional tool metadata

 {}

Returns:

Type Description
Union[Callable[[T], T], T]

The decorated function or a decorator
Source code in openai_toolchain/registry.py 
 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
def register(
    self,
    func: Optional[T] = None,
    *,
    name: Optional[str] = None,
    description: Optional[str] = None,
    non_ai_params: Optional[List[str]] = None,
    **kwargs: Any,
) -> Union[Callable[[T], T], T]:
    """Register a function as a tool.

    Can be used as a decorator with or without arguments.

    Args:
        func: The function to register (automatically passed when used as decorator)
        name: Optional custom name for the tool
        description: Optional description for the tool
        **kwargs: Additional tool metadata

    Returns:
        The decorated function or a decorator
    """

    def decorator(f: T) -> T:
        tool_name = name or f.__name__
        tool_description = description or (f.__doc__ or "").strip()

        # Initialize local non_ai_params list
        local_non_ai_params = (
            non_ai_params.copy() if non_ai_params is not None else []
        )

        if local_non_ai_params:
            non_ai_param_joined = "\\n- ".join(local_non_ai_params)
            tool_description += f"""

            Non-AI parameters (do not use these):
            {non_ai_param_joined}
            """

        # Extract parameter information
        sig = inspect.signature(f)
        parameters: Dict[str, Any] = {}
        required: List[str] = []
        type_hints = get_type_hints(f)

        for param_name, param in sig.parameters.items():
            if param_name == "self" or param_name in local_non_ai_params:
                continue

            param_type = type_hints.get(param_name, str)
            param_info = self._get_parameter_info(param, param_type)
            parameters[param_name] = param_info

            if param.default == inspect.Parameter.empty:
                required.append(param_name)

        # Create the tool schema with proper typing
        tool_schema: Dict[str, Any] = {
            "type": "function",
            "function": {
                "name": tool_name,
                "description": tool_description,
                "parameters": {
                    "type": "object",
                    "properties": parameters,
                },
            },
        }

        if required:
            # Explicitly type the parameters dictionary
            function_params = tool_schema["function"]["parameters"]
            if isinstance(function_params, MutableMapping):
                function_params["required"] = required

        # Store the tool
        self._tools[tool_name] = {
            "function": f,
            "schema": tool_schema,
            "metadata": kwargs,
        }

        return f

    if func is not None:
        return decorator(func)
    return decorator