tooluniverse.tool_registry module

Simplified tool registry for automatic tool discovery and registration.

tooluniverse.tool_registry.mark_tool_unavailable(tool_name, error, module=None)

Record tool failure.

tooluniverse.tool_registry.get_tool_errors()

Get all tool errors.

tooluniverse.tool_registry.register_tool(tool_type_name=None, config=None)

Decorator to automatically register tool classes and their configs.

Usage:

@register_tool(‘CustomToolName’, config={…}) class MyTool:

pass

tooluniverse.tool_registry.register_external_tool(tool_name, tool_class)

Allow external registration of tool classes.

tooluniverse.tool_registry.register_config(tool_type_name, config)

Register a config for a tool type.

tooluniverse.tool_registry.get_tool_registry()

Get a copy of the current tool registry.

tooluniverse.tool_registry.get_config_registry()

Get a copy of the current config registry.

tooluniverse.tool_registry.register_tool_configs(configs)

Register a list of tool configs from a sub-package (e.g. tooluniverse-circuit).

Sub-package __init__.py files call this to make their JSON configs discoverable by ToolUniverse.load_tools() without requiring any entries in default_config.py.

Parameters:

configs (list) – List of tool config dicts, each containing at least a name key.

tooluniverse.tool_registry.get_list_config_registry()

Return the flat list of configs registered by sub-packages.

tooluniverse.tool_registry.clear_lazy_cache()

Clear the module-level lazy import cache.

Built-in tool modules (in src/tooluniverse/tools/) are cached after their first import. Call this function in development environments when you have edited a built-in tool module and want the changes to take effect without restarting the process. After calling this, the next access to the tool will re-import its module from disk.

Note: this does NOT affect workspace user tool files; those are handled separately via mtime tracking in _import_user_python_tools().

Example:

from tooluniverse.tool_registry import clear_lazy_cache
clear_lazy_cache()
tu.refresh_tools()

tooluniverse.tool_registry.lazy_import_tool(tool_name)

Lazily import a tool by name without importing all tool modules. Only imports the specific module containing the requested tool.

tooluniverse.tool_registry.build_lazy_registry(package_name=None)

Build a mapping of tool names to module names. Prioritizes pre-computed static registry (for bundles/frozen envs). Falls back to AST analysis if static registry is missing.

tooluniverse.tool_registry.reset_plugin_discovery()

Clear the set of already-discovered plugin names.

Call this before build_lazy_registry() (or refresh_tools()) when a new plugin package has been installed in the current process and you want _discover_entry_point_plugins() to pick it up without restarting.

tooluniverse.tool_registry.auto_discover_tools(package_name=None, lazy=True)

Automatically discover and import all tool modules. If lazy=True, only builds the mapping without importing any modules. If lazy=False, imports all tool modules immediately.

tooluniverse.tool_registry.get_tool_class_lazy(tool_name)

Get a tool class by name, using lazy loading if possible. Only imports the specific module needed, not all modules.