praval.core.tool_registry

Tool Registry for Praval Framework.

This module provides a centralized registry for managing tools and their relationships to agents. Tools can be registered, discovered, and assigned to agents dynamically.

Functions

get_tool_registry()	Get the global tool registry instance.
reset_tool_registry()	Reset the global tool registry (primarily for testing).

Classes

Tool(func, metadata)	Wrapper class for a registered tool function.
ToolMetadata(tool_name[, owned_by, ...])	Metadata for a registered tool.
ToolRegistry()	Centralized registry for managing tools and their relationships to agents.

class praval.core.tool_registry.ToolMetadata(tool_name, owned_by=None, description='', category='general', shared=False, version='1.0.0', author='', tags=<factory>, parameters=<factory>, return_type='Any')

Bases: object

Metadata for a registered tool.

Parameters:

• tool_name (str)

• owned_by (str | None)

• description (str)

• category (str)

• shared (bool)

• version (str)

• author (str)

• tags (List[str])

• parameters (Dict[str, Any])

• return_type (str)

tool_name: str

owned_by: Optional[str] = None

description: str = ''

category: str = 'general'

shared: bool = False

version: str = '1.0.0'

author: str = ''

tags: List[str]

parameters: Dict[str, Any]

return_type: str = 'Any'

__init__(tool_name, owned_by=None, description='', category='general', shared=False, version='1.0.0', author='', tags=<factory>, parameters=<factory>, return_type='Any')

Parameters:

• tool_name (str)

• owned_by (str | None)

• description (str)

• category (str)

• shared (bool)

• version (str)

• author (str)

• tags (List[str])

• parameters (Dict[str, Any])

• return_type (str)

Return type:

None

class praval.core.tool_registry.Tool(func, metadata)

Bases: object

Wrapper class for a registered tool function.

Provides metadata, validation, and execution capabilities for functions registered as tools in the Praval framework.

Parameters:

• func (Callable)

• metadata (ToolMetadata)

__init__(func, metadata)

Initialize a Tool instance.

Parameters:

• func (Callable) – The function to wrap as a tool

• metadata (ToolMetadata) – Metadata describing the tool

Raises:

ToolError – If function validation fails

execute(*args, **kwargs)

Execute the tool function with given arguments.

Parameters:

• *args – Positional arguments for the tool function

• **kwargs – Keyword arguments for the tool function

Return type:

Any

Returns:

Result of tool function execution

Raises:

ToolError – If execution fails

to_dict()

Convert tool to dictionary representation for serialization.

Return type:

Dict[str, Any]

class praval.core.tool_registry.ToolRegistry

Bases: object

Centralized registry for managing tools and their relationships to agents.

The registry provides functionality to: - Register and retrieve tools - Associate tools with agents - Manage shared tools - Query tools by category - Handle tool lifecycle

__init__()

Initialize the tool registry.

register_tool(tool)

Register a tool in the registry.

Parameters:

tool (Tool) – Tool instance to register

Raises:

ToolError – If tool name already exists or registration fails

Return type:

None

get_tool(tool_name)

Retrieve a tool by name.

Parameters:

tool_name (str) – Name of the tool to retrieve

Return type:

Optional[Tool]

Returns:

Tool instance if found, None otherwise

get_tools_for_agent(agent_name)

Get all tools available to a specific agent.

This includes: - Tools owned by the agent - Shared tools - Tools explicitly assigned to the agent

Parameters:

agent_name (str) – Name of the agent

Return type:

List[Tool]

Returns:

List of Tool instances available to the agent

get_tools_by_category(category)

Get all tools in a specific category.

Parameters:

category (str) – Category name

Return type:

List[Tool]

Returns:

List of Tool instances in the category

get_shared_tools()

Get all shared tools.

Return type:

List[Tool]

Returns:

List of all shared Tool instances

list_all_tools()

List all registered tools.

Return type:

List[Tool]

Returns:

List of all Tool instances

assign_tool_to_agent(tool_name, agent_name)

Assign a tool to an agent at runtime.

Parameters:

• tool_name (str) – Name of the tool to assign

• agent_name (str) – Name of the agent to assign to

Return type:

bool

Returns:

True if assignment successful, False if tool doesn’t exist

remove_tool_from_agent(tool_name, agent_name)

Remove a tool assignment from an agent.

Parameters:

• tool_name (str) – Name of the tool to remove

• agent_name (str) – Name of the agent to remove from

Return type:

bool

Returns:

True if removal successful, False if assignment didn’t exist

unregister_tool(tool_name)

Unregister a tool from the registry.

Parameters:

tool_name (str) – Name of the tool to unregister

Return type:

bool

Returns:

True if unregistration successful, False if tool didn’t exist

clear_registry()

Clear all tools from the registry.

Return type:

None

get_registry_stats()

Get statistics about the registry.

Return type:

Dict[str, Any]

Returns:

Dictionary with registry statistics

search_tools(name_pattern=None, category=None, owned_by=None, shared_only=False, tags=None)

Search for tools based on multiple criteria.

Parameters:

• name_pattern (Optional[str]) – Pattern to match in tool names (case-insensitive)

• category (Optional[str]) – Specific category to filter by

• owned_by (Optional[str]) – Specific owner to filter by

• shared_only (bool) – Only return shared tools

• tags (Optional[List[str]]) – Tags that tools must have (any match)

Return type:

List[Tool]

Returns:

List of Tool instances matching the criteria

praval.core.tool_registry.get_tool_registry()

Get the global tool registry instance.

Return type:

ToolRegistry

Returns:

Global ToolRegistry instance

praval.core.tool_registry.reset_tool_registry()

Reset the global tool registry (primarily for testing).

Warning: This will clear all registered tools.

Return type:

None