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', requires_approval=False, risk_level='low', approval_reason='')[source]

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)
requires_approval (bool)
risk_level (str)
approval_reason (str)

tool_name: str

owned_by: str | None = 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'

requires_approval: bool = False

risk_level: str = 'low'

approval_reason: str = ''

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

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)
requires_approval (bool)
risk_level (str)
approval_reason (str)

Return type:

None

class praval.core.tool_registry.Tool(func, metadata)[source]

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)[source]

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)[source]

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()[source]

Convert tool to dictionary representation for serialization.

Return type:: Dict[str, Any]

class praval.core.tool_registry.ToolRegistry[source]

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__()[source]: Initialize the tool registry.

register_tool(tool)[source]

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)[source]

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)[source]

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)[source]

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()[source]

Get all shared tools.

Return type:: List[Tool]
Returns:: List of all shared Tool instances

list_all_tools()[source]

List all registered tools.

Return type:: List[Tool]
Returns:: List of all Tool instances

assign_tool_to_agent(tool_name, agent_name)[source]

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)[source]

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)[source]

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()[source]

Clear all tools from the registry.

Return type:: None

get_registry_stats()[source]

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)[source]

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()[source]

Get the global tool registry instance.

Return type:: ToolRegistry
Returns:: Global ToolRegistry instance

praval.core.tool_registry.reset_tool_registry()[source]

Reset the global tool registry (primarily for testing).

Warning: This will clear all registered tools.

Return type:: None