aimx/inference/

validate.rs

//! Response validation for AIM (Agentic Inference Markup) workflows.
//!
//! This module provides the core functionality for validating and assigning 
//! inference responses to AIM rules. The validation process ensures type safety 
//! and proper assignment of values to rules that are designed to receive inference
//! results from AI models.
//!
//! # Overview
//!
//! The validation system bridges the gap between raw AI model responses and 
//! structured AIM workflow rules. It follows a systematic process:
//!
//! 1. **Rule Identification** - Iterates through all rules in an AIM structure
//! 2. **Assignment Detection** - Identifies assignment rules (underscore prefixes)
//! 3. **Response Matching** - Converts rule identifiers to uppercase for matching
//! 4. **Type Validation** - Validates responses against rule type definitions
//! 5. **Value Assignment** - Assigns validated values to rules via context
//!
//! This module is designed to be fault-tolerant, recognizing that AI model responses
//! can be probabilistic and sometimes malformed.
//!
//! # Assignment Rule Convention
//!
//! AIM workflows use a special naming convention for rules that accept inference results:
//! - **Assignment Rules**: Identifiers starting with `_` (e.g., `_summary`, `_sentiment`)
//! - **Uppercase Matching**: Rules like `_example` match responses keyed as `EXAMPLE`
//!
//! This convention allows workflows to clearly separate inference-assigned values from
//! statically defined ones.
//!
//! # Typical Usage Flow
//!
//! ```text
//! AI Model Response → Response Parsing → Validation → Rule Assignment
//! ```
//!
//! The module is typically used after parsing inference responses to automatically
//! populate AIM rules with validated results.

use crate::{
    ContextLike,
    Reference,
    inference::Response,
    WorkflowLike,
};
use std::{
    collections::HashMap,
    sync::Arc,
};
use anyhow::{anyhow, Result};

/// Validates inference responses and assigns them to matching assignment rules in an AIM structure.
///
/// This function processes a collection of parsed inference responses and assigns them to
/// corresponding assignment rules in the AIM structure. Assignment rules are identified by
/// their underscore prefix (e.g., `_example`) which gets converted to an uppercase identifier
/// (e.g., `EXAMPLE`) for matching with responses.
///
/// # Process
///
/// The validation follows a systematic workflow:
///
/// 1. **Rule Enumeration** - Iterates through all rules in the AIM structure
/// 2. **Assignment Detection** - Identifies rules with underscore prefixes (`_`)  
/// 3. **Identifier Conversion** - Converts rule identifiers to uppercase for matching
/// 4. **Response Matching** - Finds responses with matching uppercase identifiers
/// 5. **Type Validation** - Validates responses against rule type definitions
/// 6. **Value Assignment** - Assigns validated values through the execution context
///
/// # Fault Tolerance
///
/// The validation process is intentionally fault-tolerant to handle the probabilistic
/// nature of AI model responses:
///
/// - **Non-matching Responses**: Silently ignores responses without matching assignment rules
/// - **Type Validation Failures**: Silently ignores responses that fail type conversion
/// - **Partial Success**: Returns success if at least one response is validated
///
/// This design ensures that workflows continue even when some inference responses
/// are malformed or unexpected.
///
/// # Parameters
///
/// * `workflow` - An [`Arc`] reference to the workflow containing assignment rules
/// * `context` - A mutable reference to the execution context for value assignment
/// * `responses` - A [`HashMap`] of parsed responses, keyed by uppercase identifiers
///
/// # Returns
///
/// * `Ok(usize)` - Number of successfully validated and assigned responses
/// * `Err(anyhow::Error)` - If no responses were validated, containing the last error
///
/// # Example
///
/// ```rust
/// use aimx::{
///     inference::{validate_responses, Response, Item},
///     Context, Workflow, Rule, Typedef, Expression, Value, Literal, Prefix
/// };
/// use std::collections::HashMap;
/// use std::sync::Arc;
///
/// // Create a workflow with an assignment rule
/// let mut workflow = Workflow::new();
/// let rule = Rule::new(
///     "_answer".to_string(), 
///     Typedef::Number, 
///     Expression::Empty, 
///     Value::Empty
/// );
/// workflow.append_or_update(Some(rule));
/// 
/// // Create a context
/// let mut context = Context::new();
/// 
/// // Create a response map with a matching response
/// let mut responses = HashMap::new();
/// let item = Item::Value(Prefix::None, "42".to_string());
/// responses.insert("ANSWER".to_string(), Response::Single(item));
/// 
/// // Validate responses (this would assign 42 to the _answer rule)
/// let result = validate_responses(Arc::new(workflow), &mut context, responses);
/// // Note: In a real scenario, this would succeed if the context could properly set the value
/// ```
pub fn validate_responses(workflow: Arc<dyn WorkflowLike>, context: &mut dyn ContextLike, responses: HashMap<String, Response>) -> Result<usize> {
    let mut error = anyhow!("Nothing to assign");
    let mut validated_responses: usize = 0;

    // Iterate through each rule in the workflow to find assignment rules
    for rule in workflow.iter_rules() {
        // Identify assignment rules (those starting with underscore prefix)
        if rule.is_assignment() {
            // Convert rule identifier to uppercase for matching with responses
            // Example: "_example" becomes "EXAMPLE"
            let ucid = rule.ucid();
            
            // Check if there's a matching response for this assignment rule
            if let Some(response) = responses.get(&ucid) {
                // Attempt to convert the response to the rule's expected type
                // This performs type validation and conversion
                if let Ok(value) = response.to_value(rule.typedef()) {
                    // Create a reference to the rule for assignment
                    let identifier = rule.identifier();
                    let reference = Reference::One(identifier.to_string());
                    
                    // Assign the validated value through the context
                    // The context handles the actual assignment mechanism
                    match context.set_referenced(&reference, value) {
                        Ok(_) => validated_responses += 1,
                        Err(e) => error = e,
                    }
                }
                // Note: Type conversion failures are silently ignored
                // This is intentional fault tolerance for probabilistic AI responses
            }
            // Note: Non-matching responses are silently ignored
            // This allows workflows to continue even with partial responses
        }
    }

    // Return success if at least one response was validated
    // Return error only if no responses could be assigned
    if validated_responses > 0 {
        Ok(validated_responses)
    }
    else {
        Err(error)
    }
}