aimx/values/

eval.rs

//! Evaluation scoring and statistics for AIMX expressions.
//!
//! This module provides the [`Eval`] type, which represents evaluation scoring
//! statistics used in agentic workflow applications. An `Eval` value tracks
//! success counts and total attempts, enabling statistical analysis of workflow
//! performance, inference accuracy, and task completion rates.
//!
//! # Overview
//!
//! The [`Eval`] struct maintains two counters:
//! - `score`: Number of successful evaluations/attempts
//! - `count`: Total number of evaluations/attempts
//!
//! This enables calculation of success rates and statistical metrics for
//! workflow performance monitoring and optimization.
//!
//! # Usage
//!
//! ```rust
//! use aimx::values::Eval;
//! use aimx::Value;
//!
//! // Create an evaluation with 3 successes out of 5 attempts
//! let eval_value = Eval::new(3, 5);
//! assert!(eval_value.is_eval());
//!
//! // To access the inner Eval struct, match on the Value::Eval variant
//! if let Value::Eval(eval) = &eval_value {
//!     // Record additional results
//!     let passed = eval.set_pass();  // Increments both score and count
//!     let failed = eval.set_fail();  // Increments count only
//!
//!     // Calculate success rate
//!     let success_rate = eval.score();  // Returns Value::Literal(Literal::Number(0.6))
//! }
//! ```
//!
//! # Integration
//!
//! [`Eval`] values are integrated into the AIMX expression system as [`crate::value::Value::Eval`]
//! variants. They can be parsed from strings, evaluated in contexts, and formatted
//! for display like any other AIMX value.
//!
//! # Examples
//!
//! ## Parsing Evaluation Values
//!
//! ```rust
//! use aimx::values::parse_eval;
//!
//! let input = "7, 10";
//! let (remaining, eval_value) = parse_eval(input).unwrap();
//! assert!(remaining.is_empty());
//! assert!(eval_value.is_eval());
//! ```
//!
//! ## Using in Expressions
//!
//! ```rust
//! use aimx::{values::Eval, evaluate::ExpressionLike, context::Context};
//!
//! let eval = Eval::new(8, 10);
//! let mut context = Context::new();
//! let result = eval.evaluate(&mut context).unwrap();
//! assert!(result.is_eval());
//! ```
//!
//! ## Statistical Analysis
//!
//! ```rust
//! use aimx::values::Eval;
//! use aimx::Value;
//!
//! // Track performance over multiple iterations
//! let eval_value = Eval::new(0, 0);
//! 
//! // Simulate some results (this is just an example)
//! // We need to extract the Eval struct to call its methods
//! let eval_value = if let Value::Eval(eval) = &eval_value {
//!     eval.set_pass() // 1/1
//! } else {
//!     panic!("Expected Eval value");
//! };
//!
//! let eval_value = if let Value::Eval(eval) = &eval_value {
//!     eval.set_pass() // 2/2
//! } else {
//!     panic!("Expected Eval value");
//! };
//!
//! let eval_value = if let Value::Eval(eval) = &eval_value {
//!     eval.set_fail() // 2/3
//! } else {
//!     panic!("Expected Eval value");
//! };
//! 
//! // Get success rate (2/3 = 0.666...)
//! let success_rate = if let Value::Eval(eval) = &eval_value {
//!     eval.score()
//! } else {
//!     panic!("Expected Eval value");
//! };
//!
//! assert!(success_rate.is_number());
//! ```

use nom::{
    IResult, Parser,
    combinator::{map, opt},
    bytes::complete::tag,
    character::complete::multispace0,
    sequence::delimited,
};
use crate::{
    ContextLike,
    ExpressionLike,
    Literal,
    literals::parse_unsigned,
    Value,
    Writer,
};
use std::fmt;
use anyhow::Result;

/// Evaluation scoring statistics for workflow performance tracking.
///
/// The `Eval` struct represents statistical data about evaluation attempts,
/// typically used to track success rates, inference accuracy, or task completion
/// metrics in agentic workflow applications.
///
/// # Fields
///
/// - `score`: Number of successful evaluations/attempts
/// - `count`: Total number of evaluations/attempts
///
/// # Examples
///
/// ```rust
/// use aimx::values::Eval;
///
/// // Create evaluation with 75% success rate
/// let eval_value = Eval::new(3, 4);
/// assert!(eval_value.is_eval());
/// 
/// // Record additional results by extracting the Eval struct
/// let after_pass = if let aimx::Value::Eval(eval) = &eval_value {
///     eval.set_pass()  // Now 4/5
/// } else {
///     panic!("Expected Eval value");
/// };
/// 
/// let after_fail = if let aimx::Value::Eval(eval) = &after_pass {
///     eval.set_fail()  // Now 4/6
/// } else {
///     panic!("Expected Eval value");
/// };
///
/// // Calculate current success rate
/// let rate = if let aimx::Value::Eval(eval) = &after_fail {
///     eval.score()
/// } else {
///     panic!("Expected Eval value");
/// };
/// ```
///
/// # Statistical Properties
///
/// - **Success Rate**: `score / count` as a floating-point number
/// - **Sample Size**: `count` determines statistical significance
/// - **Confidence**: Higher `count` values provide more reliable metrics
///
/// # Integration
///
/// `Eval` values are wrapped in [`crate::value::Value::Eval`] variants and can
/// be used throughout the AIMX expression system. They implement the
/// [`crate::evaluate::ExpressionLike`] trait for seamless integration.
#[derive(Debug, Clone, PartialEq)]
pub struct Eval {
    score: u32,
    count: u32,
}

impl Eval {
    /// Create a new evaluation value with the specified score and count.
    ///
    /// This method constructs an `Eval` value wrapped in a [`crate::value::Value::Eval`]
    /// variant. The resulting value can be used directly in AIMX expressions.
    ///
    /// # Arguments
    ///
    /// * `score` - Number of successful evaluations/attempts
    /// * `count` - Total number of evaluations/attempts
    ///
    /// # Returns
    ///
    /// Returns a [`crate::value::Value::Eval`] variant containing the evaluation statistics.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::values::Eval;
    ///
    /// let eval_value = Eval::new(5, 10);
    /// assert!(eval_value.is_eval());
    /// ```
    pub fn new(score: u32, count: u32,) -> Value {
        Value::Eval(Eval{score, count})
    }

    /// Record a successful evaluation attempt.
    ///
    /// This method returns a new evaluation value with both the score and count
    /// incremented by 1, representing a successful outcome.
    ///
    /// # Returns
    ///
    /// Returns a new [`crate::value::Value::Eval`] with updated statistics.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::values::Eval;
    ///
    /// let eval_value = Eval::new(3, 5);
    /// assert!(eval_value.is_eval());
    /// 
    /// let after_success = if let aimx::Value::Eval(eval) = &eval_value {
    ///     eval.set_pass()
    /// } else {
    ///     panic!("Expected Eval value");
    /// };
    /// // Now represents 4 successes out of 6 attempts
    /// assert!(after_success.is_eval());
    /// ```
    pub fn set_pass(&self) -> Value {
        Self::new(self.score + 1, self.count + 1)
    }

    /// Record a failed evaluation attempt.
    ///
    /// This method returns a new evaluation value with only the count
    /// incremented by 1, representing a failed outcome.
    ///
    /// # Returns
    ///
    /// Returns a new [`crate::value::Value::Eval`] with updated statistics.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::values::Eval;
    ///
    /// let eval_value = Eval::new(3, 5);
    /// assert!(eval_value.is_eval());
    /// 
    /// let after_failure = if let aimx::Value::Eval(eval) = &eval_value {
    ///     eval.set_fail()
    /// } else {
    ///     panic!("Expected Eval value");
    /// };
    /// // Now represents 3 successes out of 6 attempts
    /// assert!(after_failure.is_eval());
    /// ```
    pub fn set_fail(&self) -> Value {
        Self::new(self.score, self.count + 1)
    }

    /// Calculate and return the success rate as a numeric value.
    ///
    /// This method computes the success rate as `score / count` and returns
    /// it as a [`crate::value::Value::Literal`] containing a floating-point number.
    /// If count is 0, returns 0.0 to avoid division by zero.
    ///
    /// # Returns
    ///
    /// Returns a [`crate::value::Value::Literal`] with the calculated success rate.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::values::Eval;
    ///
    /// let eval_value = Eval::new(3, 4);
    /// assert!(eval_value.is_eval());
    /// 
    /// let rate = if let aimx::Value::Eval(eval) = &eval_value {
    ///     eval.score()
    /// } else {
    ///     panic!("Expected Eval value");
    /// };
    /// // rate is Value::Literal(Literal::Number(0.75))
    /// assert!(rate.is_number());
    /// ```
    pub fn score(&self) -> Value {
        if self.count == 0 {
            Value::Literal(Literal::Number(0.0))
        } else {
            Value::Literal(Literal::Number(self.score as f64 / self.count as f64))
        }
    }
}

/// Parse an evaluation value from string input.
///
/// This function parses a string representation of an evaluation value in the
/// format `"score, count"`, where both `score` and `count` are unsigned integers.
/// The input is expected to be a comma-separated pair of numbers with optional
/// whitespace around the comma.
///
/// # Arguments
///
/// * `input` - The input string to parse. Expected format: `"score, count"`
///
/// # Returns
///
/// Returns an `IResult<&str, Value>` containing the remaining input and the
/// parsed evaluation value as a [`crate::value::Value::Eval`] variant.
///
/// # Examples
///
/// ```rust
/// use aimx::values::parse_eval;
///
/// let input = "7, 10";
/// let (remaining, eval_value) = parse_eval(input).unwrap();
/// assert!(remaining.is_empty());
/// assert!(eval_value.is_eval());
/// 
/// // Also accepts formats without spaces
/// let input = "5,8";
/// let (_, eval_value) = parse_eval(input).unwrap();
/// assert!(eval_value.is_eval());
/// ```
pub fn parse_eval(input: &str) -> IResult<&str, Value> {
    map(
        (
            parse_unsigned,
            parse_comma_separator,
            parse_unsigned,
        ),
        |(score, _, count)| Value::Eval(Eval{score, count}),
    )
    .parse(input)
}

/// Parse a comma separator with optional whitespace.
///
/// This helper function parses a comma character with optional whitespace
/// around it. It's used internally by [`parse_eval`] to separate the score
/// and count values in the input string.
///
/// # Arguments
///
/// * `input` - The input string to parse
///
/// # Returns
///
/// Returns an `IResult<&str, &str>` containing the remaining input and
/// the parsed comma separator.
fn parse_comma_separator(input: &str) -> IResult<&str, &str> {
    delimited(
        opt(multispace0),
        tag(","),
        opt(multispace0)
    ).parse(input)
}

impl ExpressionLike for Eval {
    /// Evaluate this evaluation value in the provided context.
    ///
    /// Since `Eval` values are constant (they represent statistical data),
    /// this method simply returns a clone of the current value without
    /// performing any context-dependent computation.
    ///
    /// # Arguments
    ///
    /// * `_context` - The evaluation context (unused for `Eval` values)
    ///
    /// # Returns
    ///
    /// Returns `Ok(Value::Eval(self.clone()))` containing the evaluation statistics.
    fn evaluate(&self, _context: &mut dyn ContextLike) -> Result<Value> {
        Ok(Value::Eval(self.clone()))
    }

    /// Write this evaluation value to the provided writer.
    ///
    /// This method formats the evaluation statistics as `"score, count"`
    /// and writes them to the writer using the appropriate formatting.
    ///
    /// # Arguments
    ///
    /// * `writer` - The writer to write the formatted evaluation to
    fn write(&self, writer: &mut Writer) {
        writer.write_unsigned(self.score);
        writer.write_str(", ");
        writer.write_unsigned(self.count);
    }
    
    /// Convert this evaluation value to a sanitized string representation.
    ///
    /// This method produces a string with special characters escaped
    /// to make it safe for various contexts. For `Eval` values, this
    /// is equivalent to the standard string representation.
    ///
    /// # Returns
    ///
    /// A sanitized string representation of this evaluation value.
    fn to_sanitized(&self) -> String {
        let mut writer = Writer::sanitizer();
        self.write(&mut writer);
        writer.finish()
    }
    
    /// Convert this evaluation value to a formula string representation.
    ///
    /// This method produces a string with proper quoting and escaping
    /// for use in formulas. For `Eval` values, this is equivalent to
    /// the standard string representation.
    ///
    /// # Returns
    ///
    /// A formula string representation of this evaluation value.
    fn to_formula(&self) -> String {
        let mut writer = Writer::formulizer();
        self.write(&mut writer);
        writer.finish()
    }
}

impl fmt::Display for Eval {
    /// Format this evaluation value for display.
    ///
    /// This implementation formats the evaluation statistics as `"score, count"`
    /// using the standard string representation.
    ///
    /// # Arguments
    ///
    /// * `f` - The formatter to write to
    ///
    /// # Returns
    ///
    /// A `fmt::Result` indicating success or failure of the formatting operation.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut writer = Writer::stringizer();
        self.write(&mut writer);
        write!(f, "{}", writer.finish())
    }
}