tooluniverse.output_hook module¶

Output Hook System for ToolUniverse

This module provides a comprehensive hook-based output processing system that allows for intelligent post-processing of tool outputs. The system supports various types of hooks including summarization, filtering, and transformation hooks.

Key Components: - HookRule: Defines conditions for when hooks should trigger - OutputHook: Base class for all output hooks - SummarizationHook: Specialized hook for output summarization - HookManager: Manages and coordinates all hooks

The hook system integrates seamlessly with ToolUniverse’s existing architecture, leveraging AgenticTool and ComposeTool for intelligent output processing.

class tooluniverse.output_hook.HookRule[source]¶

Bases: object

Defines rules for when hooks should be triggered.

This class evaluates various conditions to determine if a hook should be applied to a tool’s output. Supports multiple condition types including output length, content type, and tool-specific criteria.

Parameters:: conditions (Dict[str, Any]) – Dictionary containing condition specifications

conditions¶

The condition specifications

Type:: Dict[str, Any]

__init__(conditions)[source]¶

Initialize the hook rule with conditions.

Parameters:: conditions (Dict[str, Any]) – Condition specifications including output_length, content_type, tool_type, etc.

evaluate(result, tool_name, arguments, context)[source]¶

Evaluate whether the rule conditions are met.

Parameters:

result (Any) – The tool output to evaluate
tool_name (str) – Name of the tool that produced the output
arguments (Dict[str, Any]) – Arguments passed to the tool
context (Dict[str, Any]) – Additional context information

Returns:

True if conditions are met, False otherwise

Return type:

bool

class tooluniverse.output_hook.OutputHook[source]¶

Bases: object

Base class for all output hooks.

This abstract base class defines the interface that all output hooks must implement. Hooks are used to process tool outputs after execution, enabling features like summarization, filtering, transformation, and validation.

Parameters:: config (Dict[str, Any]) – Hook configuration including name, enabled status, priority, and conditions

config¶

Hook configuration

Type:: Dict[str, Any]

name¶

Name of the hook

Type:: str

enabled¶

Whether the hook is enabled

Type:: bool

priority¶

Hook priority (lower numbers execute first)

Type:: int

rule¶

Rule for when this hook should trigger

Type:: HookRule

__init__(config)[source]¶

Initialize the output hook with configuration.

Parameters:: config (Dict[str, Any]) – Hook configuration containing: - name: Hook identifier - enabled: Whether hook is active - priority: Execution priority - conditions: Trigger conditions

should_trigger(result, tool_name, arguments, context)[source]¶

Determine if this hook should be triggered for the given output.

Parameters:

result (Any) – The tool output to evaluate
tool_name (str) – Name of the tool that produced the output
arguments (Dict[str, Any]) – Arguments passed to the tool
context (Dict[str, Any]) – Additional context information

Returns:

True if hook should trigger, False otherwise

Return type:

bool

process(result, tool_name=None, arguments=None, context=None)[source]¶

Process the tool output.

This method must be implemented by subclasses to define the specific processing logic for the hook.

Parameters:

result (Any) – The tool output to process
tool_name (str) – Name of the tool that produced the output
arguments (Dict[str, Any]) – Arguments passed to the tool
context (Dict[str, Any]) – Additional context information

Returns:

The processed output

Return type:

Any

Raises:

NotImplementedError – If not implemented by subclass

class tooluniverse.output_hook.SummarizationHookConfig[source]¶

Bases: object

SummarizationHookConfig(composer_tool: str = ‘OutputSummarizationComposer’, chunk_size: int = 30000, focus_areas: str = ‘key_findings_and_results’, max_summary_length: int = 3000, composer_timeout_sec: int = 60)

composer_tool: str = 'OutputSummarizationComposer'¶

chunk_size: int = 30000¶

focus_areas: str = 'key_findings_and_results'¶

max_summary_length: int = 3000¶

composer_timeout_sec: int = 60¶

validate()[source]¶

__init__(composer_tool='OutputSummarizationComposer', chunk_size=30000, focus_areas='key_findings_and_results', max_summary_length=3000, composer_timeout_sec=60)¶

class tooluniverse.output_hook.SummarizationHook[source]¶

Bases: OutputHook

Hook for intelligent output summarization using AI.

This hook uses the ToolUniverse’s AgenticTool and ComposeTool infrastructure to provide intelligent summarization of long tool outputs. It supports chunking large outputs, processing each chunk with AI, and merging results.

Parameters:

config (Dict[str, Any]) – Hook configuration including summarization parameters
tooluniverse – Reference to the ToolUniverse instance

tooluniverse¶: ToolUniverse instance for tool execution

composer_tool¶

Name of the ComposeTool for summarization

Type:: str

chunk_size¶

Size of chunks for processing large outputs

Type:: int

focus_areas¶

Areas to focus on during summarization

Type:: str

max_summary_length¶

Maximum length of final summary

Type:: int

__init__(config, tooluniverse)[source]¶

Initialize the summarization hook.

Parameters:

config (Dict[str, Any]) – Hook configuration
tooluniverse – ToolUniverse instance for executing summarization tools

process(result, tool_name=None, arguments=None, context=None)[source]¶

Execute summarization processing using Compose Summarizer Tool.

This method orchestrates the summarization workflow by: 1. Preparing parameters for the Compose Summarizer Tool 2. Calling the tool through ToolUniverse 3. Processing and returning the summarized result

Parameters:

result (Any) – The tool output to summarize
tool_name (str) – Name of the tool that produced the output
arguments (Dict[str, Any]) – Arguments passed to the tool
context (Dict[str, Any]) – Additional context information

Returns:

The summarized output, or original output if summarization fails

Return type:

Any

class tooluniverse.output_hook.HookManager[source]¶

Bases: object

Manages and coordinates all output hooks.

The HookManager is responsible for loading hook configurations, creating hook instances, and applying hooks to tool outputs. It provides a unified interface for hook management and supports dynamic configuration updates.

Parameters:

config (Dict[str, Any]) – Hook manager configuration
tooluniverse – Reference to the ToolUniverse instance

config¶

Hook manager configuration

Type:: Dict[str, Any]

tooluniverse¶: ToolUniverse instance for tool execution

hooks¶

List of loaded hook instances

Type:: List[OutputHook]

enabled¶

Whether hook processing is enabled

Type:: bool

config_path¶

Path to hook configuration file

Type:: str

__init__(config, tooluniverse)[source]¶

Initialize the hook manager.

Parameters:

config (Dict[str, Any]) – Configuration for hook manager
tooluniverse – ToolUniverse instance for executing tools

apply_hooks(result, tool_name, arguments, context)[source]¶

Apply all applicable hooks to the tool output.

This method iterates through all loaded hooks, checks if they should be applied to the current output, and processes the output through each applicable hook in priority order.

Parameters:

result (Any) – The tool output to process
tool_name (str) – Name of the tool that produced the output
arguments (Dict[str, Any]) – Arguments passed to the tool
context (Dict[str, Any]) – Additional context information

Returns:

The processed output after applying all applicable hooks

Return type:

Any

enable_hook(hook_name)[source]¶

Enable a specific hook by name.

Parameters:: hook_name (str) – Name of the hook to enable

disable_hook(hook_name)[source]¶

Disable a specific hook by name.

Parameters:: hook_name (str) – Name of the hook to disable

toggle_hooks(enabled)[source]¶

Enable or disable all hooks globally.

Parameters:: enabled (bool) – True to enable all hooks, False to disable

enable_hooks()[source]¶: Enable hooks and (re)load configurations and required tools.

disable_hooks()[source]¶: Disable hooks and clear in-memory hook instances.

reload_config(config_path=None)[source]¶

Reload hook configuration from file.

Parameters:: config_path (Optional[str]) – Path to configuration file. If None, uses the current config_path

get_hook(hook_name)[source]¶

Get a hook instance by name.

Parameters:: hook_name (str) – Name of the hook to retrieve
Returns:: Hook instance if found, None otherwise
Return type:: Optional[OutputHook]

class tooluniverse.output_hook.FileSaveHook[source]¶

Bases: OutputHook

Hook that saves tool outputs to temporary files and returns file information.

This hook saves the tool output to a temporary file and returns information about the file path, data format, and data structure instead of the original output. This is useful for handling large outputs or when you need to process outputs as files rather than in-memory data.

Configuration options: - temp_dir: Directory to save temporary files (default: system temp) - file_prefix: Prefix for generated filenames (default: ‘tool_output’) - include_metadata: Whether to include metadata in the response (default: True) - auto_cleanup: Whether to automatically clean up old files (default: False) - cleanup_age_hours: Age in hours for auto cleanup (default: 24)

__init__(config)[source]¶

Initialize the FileSaveHook.

Parameters:: config (Dict[str, Any]) – Hook configuration including: - name: Hook name - temp_dir: Directory for temporary files - file_prefix: Prefix for filenames - include_metadata: Include metadata flag - auto_cleanup: Auto cleanup flag - cleanup_age_hours: Cleanup age in hours

process(result, tool_name, arguments, context)[source]¶

Process the tool output by saving it to a temporary file.

Parameters:

result (Any) – The tool output to process
tool_name (str) – Name of the tool that produced the output
arguments (Dict[str, Any]) – Arguments passed to the tool
context (Dict[str, Any]) – Execution context

Returns:

Dictionary containing file information:

file_path: Path to the saved file
data_format: Format of the data (json, text, binary, etc.)
data_structure: Structure information about the data
file_size: Size of the file in bytes
created_at: Timestamp when file was created
metadata: Additional metadata (if include_metadata is True)

Return type:

Dict[str, Any]