haive.core.common.mixins.tool_route_mixin

Tool routing mixin for managing tool destinations and metadata.

This module provides a mixin for managing tool routes and related metadata in configuration classes. It enables mapping tool names to their types or destinations, keeping track of metadata, and provides utilities for creating tools from configs.

Usage:

from pydantic import BaseModel
from haive.core.common.mixins import ToolRouteMixin

class AgentConfig(ToolRouteMixin, BaseModel):
    name: str
    description: str

    def _create_tool_implementation(self, name, description, **kwargs):
        # Custom tool creation logic
        return SomeTool(name=name, description=description)

# Create config with tool routes
config = AgentConfig(
    name="MyAgent",
    description="Agent configuration"
)

# Set tool routes
config.set_tool_route("search", "retriever", {"source": "web"})
config.set_tool_route("math", "function", {"language": "python"})

# Create a tool
search_tool = config.to_tool(name="search", description="Web search tool")

# Get routes by type
retriever_tools = config.list_tools_by_route("retriever")

Classes

ToolRouteMixin

Enhanced mixin for managing tools, routes, and converting configurations to tools.

Functions

sanitize_tool_name(raw_name)

Sanitize tool names for OpenAI compliance and readability.

Module Contents

class haive.core.common.mixins.tool_route_mixin.ToolRouteMixin(/, **data)

Bases: pydantic.BaseModel

Enhanced mixin for managing tools, routes, and converting configurations to tools.

This mixin provides functionality for: - Setting and managing tool routes (mapping tool names to types/destinations) - Storing and retrieving tool metadata - Supporting tools as dict with string keys for tool lists - Supporting routed tools with before validators for tuple handling - Generating tools from configurations - Visualizing tool routing information

Tool routes define where a tool request should be directed, such as to a specific retriever, model, or function. This helps implement routing logic in agents and other tool-using components.

Parameters:

data (Any)

tool_routes

Dictionary mapping tool names to their routes/types.

tool_metadata

Dictionary with additional metadata for each tool.

tools_dict

Dictionary mapping tool category strings to lists of tools.

routed_tools

List of tuples containing (tool, route) pairs.

before_tool_validator

Optional callable to validate tools before routing.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

add_routed_tool(tool, route)

Add a single tool with explicit route.

Parameters:

• tool (Any)

• route (str)

Return type:

ToolRouteMixin

add_tool(tool, route=None, metadata=None)

Add a tool with automatic routing and metadata.

Parameters:

• tool (Any) – Tool instance to add

• route (str | None) – Optional explicit route (auto-detected if not provided)

• metadata (dict[str, Any] | None) – Optional metadata for the tool

Returns:

Self for method chaining

Return type:

ToolRouteMixin

add_tools_from_list(tools, clear_existing=False)

Add tools from a list to tool_routes without clearing existing routes.

This method analyzes a list of tools and automatically creates appropriate routes based on their types. Supports both regular tools and tuples of (tool, route) for explicit routing.

Parameters:

• tools (list[Any | tuple[Any, str]]) – List of tools or (tool, route) tuples to analyze and create routes for.

• clear_existing (bool) – Whether to clear existing routes first.

Returns:

Self for method chaining.

Return type:

ToolRouteMixin

add_tools_to_category(category, tools)

Add tools to a specific category in tools_dict.

Parameters:

• category (str)

• tools (list[Any])

Return type:

ToolRouteMixin

clear_tool_routes()

Clear all tool routes and metadata.

Returns:

Self for method chaining.

Return type:

ToolRouteMixin

clear_tools()

Clear all tools and routes.

Returns:

Self for method chaining

Return type:

ToolRouteMixin

debug_tool_routes()

Print debug information about tool routes.

This method uses the Rich library to create a visual representation of the tool routes and metadata, including the new dict and routed tools.

Returns:

Self for method chaining.

Return type:

ToolRouteMixin

get_all_tools_flat()

Get all tools from tools_dict and routed_tools as a flat list.

Return type:

list[Any]

get_tool(tool_name)

Get a tool instance by name.

Parameters:

tool_name (str) – Name of the tool

Returns:

Tool instance or None if not found

Return type:

Any | None

get_tool_metadata(tool_name)

Get metadata for a specific tool.

Parameters:

tool_name (str) – Name of the tool to look up.

Returns:

Dictionary of metadata if found, None otherwise.

Return type:

dict[str, Any] | None

get_tool_route(tool_name)

Get the route for a specific tool.

Parameters:

tool_name (str) – Name of the tool to look up.

Returns:

The route string if found, None otherwise.

Return type:

str | None

get_tools_by_category(category)

Get all tools in a specific category.

Parameters:

category (str)

Return type:

list[Any]

get_tools_by_route(route)

Get all tools with a specific route.

Parameters:

route (str) – Route to filter by

Returns:

List of tools with that route

Return type:

list[Any]

list_tools_by_route(route)

Get all tool names for a specific route.

This method finds all tools that are routed to a specific destination.

Parameters:

route (str) – The route to search for.

Returns:

List of tool names with the matching route.

Return type:

list[str]

remove_tool_route(tool_name)

Remove a tool route and its metadata.

Parameters:

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

Returns:

Self for method chaining.

Return type:

ToolRouteMixin

set_tool_route(tool_name, route, metadata=None)

Set a tool route with optional metadata.

This method defines where a tool request should be routed, along with optional metadata to inform the routing decision.

Parameters:

• tool_name (str) – Name of the tool.

• route (str) – Route/type for the tool (e.g., ‘retriever’, ‘pydantic_model’, ‘function’).

• metadata (dict[str, Any] | None) – Optional metadata for the tool.

Returns:

Self for method chaining.

Return type:

ToolRouteMixin

set_tool_route_for_existing(tool_identifier, new_route)

Set or update the route for an existing tool by name or partial match.

Parameters:

• tool_identifier (str) – Tool name or partial name to match

• new_route (str) – New route to assign to the tool

Returns:

Self for method chaining.

Return type:

ToolRouteMixin

sync_tool_routes_from_tools(tools)

Synchronize tool_routes with a list of tools.

This method analyzes a list of tools and automatically creates appropriate routes based on their types.

Parameters:

tools (list[Any]) – List of tools to analyze and create routes for.

Returns:

Self for method chaining.

Return type:

ToolRouteMixin

to_tool(name=None, description=None, route=None, **kwargs)

Convert this configuration to a tool.

This method provides a base implementation for creating tools from configuration objects. Specific config classes should override the _create_tool_implementation method to provide custom tool creation logic.

Parameters:

• name (str | None) – Tool name (defaults to config name if available).

• description (str | None) – Tool description (defaults to config description if available).

• route (str | None) – Tool route/type to set.

• **kwargs – Additional kwargs for tool creation.

Returns:

A tool that can be used with LLMs.

Return type:

Any

update_tool_route(tool_name, new_route)

Update an existing tool’s route dynamically.

Parameters:

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

• new_route (str) – New route to assign

Returns:

Self for method chaining

Return type:

ToolRouteMixin

update_tool_routes(routes)

Update multiple tool routes at once.

Parameters:

routes (dict[str, str]) – Dictionary mapping tool names to routes.

Returns:

Self for method chaining.

Return type:

ToolRouteMixin

haive.core.common.mixins.tool_route_mixin.sanitize_tool_name(raw_name)

Sanitize tool names for OpenAI compliance and readability.

Converts generic class names like ‘Plan[Task]’ to snake_case like ‘plan_task_generic’ and handles other naming edge cases.

Parameters:

raw_name (str) – Raw tool name from __name__ or other source

Returns:

Sanitized snake_case name that’s OpenAI-compliant

Return type:

str