praval.tools

Tool decorator and utilities for Praval Framework.

This module provides the @tool decorator for creating tools that can be registered and used by agents. Tools are automatically registered in the global tool registry and can be associated with specific agents.

Functions

`discover_tools`([module, pattern, category])	Discover tools based on various criteria.
`get_tool_info`(tool_func)	Get information about a @tool decorated function.
`is_tool`(func)	Check if a function is decorated with @tool.
`list_tools`([agent_name, category, shared_only])	List tools with optional filtering.
`register_tool_with_agent`(tool_name, agent_name)	Register an existing tool with an agent at runtime.
`tool`([tool_name, owned_by, description, ...])	Decorator to register a function as a tool in the Praval framework.
`unregister_tool_from_agent`(tool_name, agent_name)	Unregister a tool from an agent at runtime.

Classes

ToolCollection(name[, description])

A collection of related tools that can be managed as a group.

praval.tools.tool(tool_name=None, owned_by=None, description=None, category='general', shared=False, version='1.0.0', author='', tags=None)[source]

Decorator to register a function as a tool in the Praval framework.

The @tool decorator automatically registers functions as tools that can be used by agents. Tools can be owned by specific agents, shared across all agents, or organized by category.

Parameters:

tool_name (Optional[str]) – Name of the tool (defaults to function name)
owned_by (Optional[str]) – Agent that owns this tool
description (Optional[str]) – Description of what the tool does (defaults to docstring)
category (str) – Category for organizing tools
shared (bool) – Whether this tool is available to all agents
version (str) – Version of the tool
author (str) – Author of the tool
tags (Optional[List[str]]) – Tags for tool discovery

Return type:

Callable

Returns:

Decorated function with tool metadata attached

Raises:

ToolError – If tool registration fails or validation errors occur

Examples

Basic tool owned by specific agent: ```python @tool(“add_numbers”, owned_by=”calculator”) def add(x: float, y: float) -> float:

‘’’Add two numbers together.’’’ return x + y

```

Shared tool available to all agents: ```python @tool(“logger”, shared=True, category=”utility”) def log_message(level: str, message: str) -> str:

‘’’Log a message at the specified level.’’’ import logging logger = logging.getLogger(“praval.tools”) getattr(logger, level.lower())(message) return f”Logged: {message}”

```

Tool with metadata: ```python @tool(

“validate_email”, owned_by=”data_processor”, category=”validation”, tags=[“email”, “validation”, “data”], version=”2.0.0”, author=”Praval Team”

) def validate_email(email: str) -> bool:

‘’’Validate email address format.’’’ import re pattern = r’^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$’ return bool(re.match(pattern, email))

```

praval.tools.get_tool_info(tool_func)[source]

Get information about a @tool decorated function.

Parameters:: tool_func (Callable) – Function decorated with @tool
Return type:: dict
Returns:: Dictionary with tool metadata
Raises:: ValueError – If function is not decorated with @tool

praval.tools.is_tool(func)[source]

Check if a function is decorated with @tool.

Parameters:: func (Callable) – Function to check
Return type:: bool
Returns:: True if function is a tool, False otherwise

praval.tools.discover_tools(module=None, pattern=None, category=None)[source]

Discover tools based on various criteria.

Parameters:

module (Optional[str]) – Module name to search for tools
pattern (Optional[str]) – File pattern to search (e.g., “*_tool.py”)
category (Optional[str]) – Category to filter by

Return type:

List[Tool]

Returns:

List of discovered Tool instances

praval.tools.list_tools(agent_name=None, category=None, shared_only=False)[source]

List tools with optional filtering.

Parameters:

agent_name (Optional[str]) – Filter by agent owner
category (Optional[str]) – Filter by category
shared_only (bool) – Only show shared tools

Return type:

List[dict]

Returns:

List of tool information dictionaries

praval.tools.register_tool_with_agent(tool_name, agent_name)[source]

Register an existing tool with an agent at runtime.

Parameters:

tool_name (str) – Name of the tool to register
agent_name (str) – Name of the agent to register with

Return type:

bool

Returns:

True if registration successful, False otherwise

praval.tools.unregister_tool_from_agent(tool_name, agent_name)[source]

Unregister a tool from an agent at runtime.

Parameters:

tool_name (str) – Name of the tool to unregister
agent_name (str) – Name of the agent to unregister from

Return type:

bool

Returns:

True if unregistration successful, False otherwise

class praval.tools.ToolCollection(name, description='')[source]

Bases: object

A collection of related tools that can be managed as a group.

Useful for organizing tools by functionality or creating tool suites that can be easily assigned to agents.

Parameters:

name (str)
description (str)

__init__(name, description='')[source]

Initialize a tool collection.

Parameters:

name (str) – Name of the collection
description (str) – Description of the collection

add_tool(tool_name)[source]

Add a tool to the collection.

Parameters:: tool_name (str) – Name of the tool to add
Raises:: ToolError – If tool doesn’t exist
Return type:: None

remove_tool(tool_name)[source]

Remove a tool from the collection.

Parameters:: tool_name (str) – Name of the tool to remove
Return type:: bool
Returns:: True if removal successful, False if tool wasn’t in collection

assign_to_agent(agent_name)[source]

Assign all tools in the collection to an agent.

Parameters:: agent_name (str) – Name of the agent to assign tools to
Return type:: int
Returns:: Number of tools successfully assigned

get_tools()[source]

Get all tools in the collection.

Return type:: List[Tool]
Returns:: List of Tool instances in the collection