haive.core.contracts.tool_registry¶

Central tool registry with contract enforcement.

This module provides a centralized registry for tools with capability-based lookup and contract enforcement, extracted from scattered tool management.

Classes¶

`ToolMetadata`	Metadata about a registered tool.
`ToolRegistry`	Central registry for tools with contract enforcement.

Module Contents¶

class haive.core.contracts.tool_registry.ToolMetadata(/, **data)[source]¶

Bases: pydantic.BaseModel

Metadata about a registered tool.

Parameters:: data (Any)

name¶: Tool identifier.

contract¶: Tool contract.

tags¶: Categorization tags.

version¶: Tool version.

registered_at¶: Registration timestamp.

usage_count¶: Number of times used.

last_used¶: Last usage timestamp.

performance_metrics¶: Performance statistics.

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.

class haive.core.contracts.tool_registry.ToolRegistry(/, **data)[source]¶

Bases: pydantic.BaseModel

Central registry for tools with contract enforcement.

Provides: - Tool registration with contracts - Capability-based tool discovery - Permission validation - Usage tracking - Performance monitoring

Parameters:: data (Any)

tools¶: Registered tools by name.

metadata¶: Tool metadata by name.

capability_index¶: Tools indexed by capability.

tag_index¶: Tools indexed by tag.

permission_requirements¶: Global permission requirements.

Examples

Basic registration:

>>> registry = ToolRegistry()
>>> registry.register(
...     name="calculator",
...     tool=calculator_tool,
...     contract=calculator_contract
... )

Capability-based lookup:

>>> safe_tools = registry.find_by_capability(
...     "can_write_state", False
... )

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.

find_async_tools()[source]¶

Find async-capable tools.

Returns:: List of async tools.
Return type:: List[Any]

find_by_capability(capability, value=True)[source]¶

Find tools by capability.

Parameters:

capability (str) – Capability field name.
value (bool) – Expected capability value.

Returns:

List of matching tools.

Return type:

List[Any]

find_by_tag(tag)[source]¶

Find tools by tag.

Parameters:: tag (str) – Tag to search for.
Returns:: List of matching tools.
Return type:: List[Any]

find_safe_tools()[source]¶

Find tools without side effects.

Returns:: List of safe tools.
Return type:: List[Any]

find_stateful_tools()[source]¶

Find tools that maintain state.

Returns:: List of stateful tools.
Return type:: List[Any]

get_capability_summary()[source]¶

Get summary of tool capabilities.

Returns:: Count of tools by capability.
Return type:: Dict[str, int]

get_tool(name)[source]¶

Get a tool by name.

Parameters:: name (str) – Tool name.
Returns:: Tool instance or None.
Return type:: Optional[Any]

get_usage_stats()[source]¶

Get usage statistics for all tools.

Returns:: Usage statistics by tool name.
Return type:: Dict[str, Dict[str, Any]]

register(name, tool, contract=None, tags=None, version='1.0.0')[source]¶

Parameters:

name (str) – Tool name.
tool (Any) – Tool instance.
contract (Optional[haive.core.contracts.tool_config.ToolContract]) – Tool contract.
tags (Optional[Set[str]]) – Tool tags.
version (str) – Tool version.

Returns:

Self for chaining.

Return type:

ToolRegistry

to_dict()[source]¶

Convert to dictionary for serialization.

Returns:: Registry as dictionary.
Return type:: Dict[str, Any]

track_usage(tool_name, execution_time=0.0)[source]¶

Track tool usage.

Parameters:

tool_name (str) – Tool that was used.
execution_time (float) – Execution time in seconds.

Return type:

None

unregister(name)[source]¶

Unregister a tool.

Parameters:: name (str) – Tool name to unregister.
Returns:: Self for chaining.
Return type:: ToolRegistry

validate_permissions(tool_name, available_permissions)[source]¶

Validate tool permissions.

Parameters:

tool_name (str) – Tool to validate.
available_permissions (Set[str]) – Available permissions.

Returns:

Tuple of (is_valid, missing_permissions).

Return type:

tuple[bool, List[str]]