ValidationManager in the Heurist Agent Framework: Input Validation and Integration Guide

The ValidationManager is a lightweight pre-validation component in core/components/validation_manager.py that filters incoming user messages through mention detection or LLM-based relevance checks before heavy-weight agent workflows execute, returning False to abort processing or True to allow the request to continue.

The ValidationManager serves as the first line of defense in the heurist-network/heurist-agent-framework, ensuring only relevant and properly formatted messages trigger expensive agent operations. Located in core/components/validation_manager.py, this component integrates directly with the CoreAgent class to perform early-stage validation that prevents irrelevant inputs from consuming computational resources downstream.

Core Responsibility and Architecture

The ValidationManager operates as a pre-validation gate that executes before knowledge retrieval, tool execution, or chain-of-thought reasoning occur. Its architecture follows a fail-safe design: any exception during validation automatically returns False, ensuring the system defaults to blocking rather than allowing potentially malformed inputs to propagate.

The manager supports pluggable validation strategies selectable at runtime, with clear extension points for custom validation logic.

Integration with CoreAgent

The validation hook resides in CoreAgent.pre_process within agents/core_agent_refactor.py (lines 73-94). When do_pre_validation is enabled, the agent delegates the decision to the manager:

if do_pre_validation:
    return await self.validation_manager.validate(
        message, agent_name=self.personality_provider.get_name()
    )

If validate() returns False, the request terminates immediately. In CoreAgent.handle_message (or smart_message), this results in the return of None, None, None, effectively aborting processing before any output generation begins. This protects the system from noisy or irrelevant inputs without invoking expensive LLM calls or tool executions.

Validation Strategies and Flow

The validation flow in ValidationManager.validate (lines 14-20) supports multiple strategies that execute based on the strategies parameter passed by the caller. If no strategies are specified, the manager defaults to the relevance strategy.

Mention Strategy

When "mention" is requested and an agent_name is provided, the manager performs a simple case-insensitive substring check (lines 25-30 in validation_manager.py):

# Conceptual implementation from source

if "mention" in strategies and agent_name:
    return agent_name.lower() in message.lower()

This lightweight check determines if the user explicitly mentioned the agent by name, making it ideal for multi-agent environments where specific agents should only respond to direct invocations.

Relevance Strategy (Default)

The primary validation mechanism uses function-calling to leverage the LLM for semantic relevance detection. In _validate_relevance (lines 38-90), the manager constructs a tool definition named filter_message that asks the LLM to evaluate whether the input should be ignored.

The implementation follows these steps:

1. Tool Definition: Creates a function schema describing the filter_message tool with a boolean parameter should_ignore
2. LLM Invocation: Calls self.llm_provider.call_with_tools() with the user message and tool definition
3. Result Parsing: Extracts the should_ignore boolean from the LLM's tool response
4. Decision: Returns False (validation failed) if should_ignore is True, or True (validation passed) if False

This strategy filters out spam, off-topic content, or messages intended for other systems without hard-coded keyword matching.

Skip Flag and Short-Circuit

For system-generated messages or trusted internal calls, the skip_validation keyword argument (lines 21-24) bypasses all checks and immediately returns True:

if skip_validation:
    return True

This allows administrative or internal messages to flow through without LLM overhead.

Error Handling and Output Impact

The ValidationManager implements defensive error handling (lines 92-94). Any exception raised during the LLM call or parsing logic logs the error and returns False, ensuring the system fails closed rather than passing invalid inputs downstream.

Output impact: The manager exclusively validates inputs, not outputs. When validation fails, the CoreAgent receives a False result during pre_process, causing handle_message to return None, None, None. This prevents any response generation, image creation, or tool execution for that specific request.

Practical Implementation Example

You can instantiate and use the ValidationManager directly for custom validation scenarios:

from core.components.validation_manager import ValidationManager

# Assume llm_provider is a configured LLMProvider instance

validation_mgr = ValidationManager(llm_provider)

# Default relevance check against agent purpose

is_valid = await validation_mgr.validate(
    "Hey assistant, can you analyze this smart contract?",
    agent_name="HeuristAssistant"
)
print(is_valid)  # → True (processing continues)

# Mention-based validation

is_valid = await validation_mgr.validate(
    "@HeuristAssistant what's the price of ETH?",
    agent_name="HeuristAssistant",
    strategies=["mention"]
)

# Bypass validation for system messages

is_valid = await validation_mgr.validate(
    "system_ping",
    skip_validation=True
)
print(is_valid)  # → True (validation skipped)

This same validation logic runs automatically inside CoreAgent.pre_process for every user message when pre-validation is enabled.

Summary

• Location: core/components/validation_manager.py implements the ValidationManager class
• Primary Method: validate() accepts a message, optional agent_name, strategies list, and skip_validation flag
• Integration: Called from CoreAgent.pre_process in agents/core_agent_refactor.py to gate message processing
• Strategies: Supports "mention" (case-insensitive name check) and "relevance" (LLM-based function calling via _validate_relevance)
• Fail-Safe: Exceptions during validation return False, preventing malformed inputs from triggering downstream workflows
• Impact: Failed validation causes CoreAgent.handle_message to return None, None, None, aborting output generation

Frequently Asked Questions

What happens if ValidationManager raises an exception during validation?

Any exception caught during the validation process causes the manager to return False immediately (lines 92-94 in validation_manager.py). This fail-safe design ensures that potential LLM timeouts, parsing errors, or network issues result in the request being blocked rather than allowing potentially invalid inputs to proceed through the agent pipeline.

How does the mention strategy differ from the relevance strategy?

The mention strategy performs a lightweight, case-insensitive substring search checking if agent_name appears in the user message (lines 25-30), making it ideal for detecting direct agent invocations. The relevance strategy (default) constructs a function-calling tool named filter_message and invokes the LLM via llm_provider.call_with_tools() to semantically evaluate whether the message aligns with the agent's purpose (lines 38-90), providing more nuanced filtering but requiring an LLM round-trip.

Can validation be bypassed entirely for specific messages?

Yes. Passing skip_validation=True as a keyword argument to validate() short-circuits all checks and immediately returns True (lines 21-24). This flag is intended for system-generated messages, administrative commands, or trusted internal calls where validation overhead is unnecessary.

Where is ValidationManager instantiated in the agent lifecycle?

The ValidationManager is instantiated within CoreAgent (located in agents/core_agent_refactor.py), which passes a configured llm_provider to the constructor. The manager persists as an instance attribute and is invoked synchronously during the pre_process method before any heavy-weight workflows like knowledge retrieval or tool execution begin.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}