haive.core.contracts.tool_config

Tool configuration system with contracts and capabilities.

This module provides a focused tool management system extracted from AugLLMConfig, reducing complexity while adding explicit contracts and capability-based routing.

Classes

ToolCapability	Defines what a tool can do at runtime.
ToolConfig	Focused tool configuration with contracts.
ToolContract	Contract defining tool's behavior and requirements.

Module Contents

class haive.core.contracts.tool_config.ToolCapability(/, **data)

Bases: pydantic.BaseModel

Defines what a tool can do at runtime.

Parameters:

data (Any)

can_read_state

Whether tool can read from state.

can_write_state

Whether tool can write to state.

can_call_external

Whether tool makes external calls.

is_stateful

Whether tool maintains internal state.

is_async

Whether tool supports async execution.

requires_confirmation

Whether tool needs user confirmation.

computational_cost

Relative cost of tool execution.

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_config.ToolConfig(/, **data)

Bases: pydantic.BaseModel

Focused tool configuration with contracts.

This replaces the scattered tool management in AugLLMConfig (~266 lines) with a focused, contract-based approach.

Parameters:

data (Any)

tools

List of tools to configure.

contracts

Tool contracts by name.

routing_strategy

How to route tool calls.

force_tool_use

Whether to force tool usage.

specific_tool

Force specific tool selection.

tool_choice_mode

Tool selection mode.

allow_parallel

Whether to allow parallel tool execution.

max_retries

Maximum retry attempts for failed tools.

timeout_seconds

Tool execution timeout.

Examples

Basic tool configuration:

>>> config = ToolConfig(
...     tools=[calculator, web_search],
...     routing_strategy="capability"
... )

With contracts:

>>> config = ToolConfig(
...     tools=[data_processor],
...     contracts={
...         "data_processor": ToolContract(
...             name="data_processor",
...             description="Process data",
...             capabilities=ToolCapability(
...                 can_write_state=True,
...                 computational_cost="high"
...             )
...         )
...     }
... )

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_tool(tool, contract=None)

Add a tool with optional contract.

Parameters:

• tool (Any) – Tool to add.

• contract (Optional[ToolContract]) – Optional tool contract.

Returns:

Self for chaining.

Return type:

ToolConfig

get_safe_tools()

Get tools that don’t have side effects.

Returns:

List of safe tools.

Return type:

List[Any]

get_tools_by_capability(capability, value=True)

Get tools matching a capability.

Parameters:

• capability (str) – Capability field name.

• value (bool) – Expected capability value.

Returns:

List of matching tools.

Return type:

List[Any]

remove_tool(tool)

Remove a tool and its contract.

Parameters:

tool (Any) – Tool to remove.

Returns:

Self for chaining.

Return type:

ToolConfig

to_dict()

Convert to dictionary for serialization.

Returns:

Configuration as dictionary.

Return type:

Dict[str, Any]

validate_permissions(tool, available_permissions)

Check if tool has required permissions.

Parameters:

• tool (Any) – Tool to validate.

• available_permissions (Set[str]) – Available permissions.

Returns:

True if permissions are satisfied.

Return type:

bool

class haive.core.contracts.tool_config.ToolContract(/, **data)

Bases: pydantic.BaseModel

Contract defining tool’s behavior and requirements.

Parameters:

data (Any)

name

Tool identifier.

description

Human-readable description.

capabilities

What the tool can do.

input_schema

Expected input structure.

output_schema

Expected output structure.

side_effects

List of potential side effects.

required_permissions

Permissions needed to execute.

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.