evidential_protocol/

scoring.rs

//! Continuous Multi-Axis Scoring for the Evidential Protocol.
//!
//! Defines a scoring engine that evaluates entities across weighted axes
//! and produces composite scores. Supports ranking and outlier detection.

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

// ---------------------------------------------------------------------------
// ScoringAxis
// ---------------------------------------------------------------------------

/// A single named scoring dimension with a weight and value.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ScoringAxis {
    /// Human-readable axis name (e.g. "accuracy", "latency").
    pub name: String,
    /// Weight of this axis in the composite score (0.0 to 1.0).
    pub weight: f64,
    /// Raw value for this axis (0.0 to 1.0).
    pub value: f64,
}

// ---------------------------------------------------------------------------
// ContinuousScore
// ---------------------------------------------------------------------------

/// A multi-axis score for a single entity.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContinuousScore {
    /// Identifier of the scored entity.
    pub entity_id: String,
    /// Individual axis scores.
    pub axes: Vec<ScoringAxis>,
    /// Weighted composite score (0.0 to 1.0).
    pub composite_score: f64,
    /// Confidence in the composite score (0.0 to 1.0).
    pub confidence: f64,
    /// ISO-8601 timestamp of when this score was assessed.
    pub assessed_at: String,
}

// ---------------------------------------------------------------------------
// ScoringEngine
// ---------------------------------------------------------------------------

/// Engine that defines scoring axes and computes multi-axis scores.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ScoringEngine {
    /// Axis definitions: `(name, weight)` pairs.
    axes: Vec<(String, f64)>,
}

impl Default for ScoringEngine {
    fn default() -> Self {
        Self::new()
    }
}

impl ScoringEngine {
    /// Create an empty scoring engine with no axes defined.
    pub fn new() -> Self {
        Self { axes: Vec::new() }
    }

    /// Define the scoring axes and their weights.
    ///
    /// Replaces any previously defined axes.
    pub fn define_axes(&mut self, axes: Vec<(&str, f64)>) {
        self.axes = axes
            .into_iter()
            .map(|(name, weight)| (name.to_string(), weight))
            .collect();
    }

    /// Score an entity by providing values for each defined axis.
    ///
    /// Values not present in `values` default to 0.0. The composite score
    /// is the weighted average of all axes. Confidence is the fraction of
    /// defined axes that had values provided.
    pub fn score(&self, entity_id: &str, values: &HashMap<String, f64>) -> ContinuousScore {
        let total_weight: f64 = self.axes.iter().map(|(_, w)| w).sum();
        let mut weighted_sum = 0.0_f64;
        let mut axes = Vec::new();
        let mut provided_count = 0_usize;

        for (name, weight) in &self.axes {
            let value = values.get(name).copied().unwrap_or(0.0);
            if values.contains_key(name) {
                provided_count += 1;
            }
            weighted_sum += value * weight;
            axes.push(ScoringAxis {
                name: name.clone(),
                weight: *weight,
                value,
            });
        }

        let composite_score = if total_weight > 0.0 {
            (weighted_sum / total_weight).clamp(0.0, 1.0)
        } else {
            0.0
        };

        let confidence = if self.axes.is_empty() {
            0.0
        } else {
            provided_count as f64 / self.axes.len() as f64
        };

        ContinuousScore {
            entity_id: entity_id.to_string(),
            axes,
            composite_score,
            confidence,
            assessed_at: chrono::Utc::now().to_rfc3339(),
        }
    }

    /// Sort a slice of scores by composite score in descending order.
    pub fn rank(scores: &mut [ContinuousScore]) {
        scores.sort_by(|a, b| {
            b.composite_score
                .partial_cmp(&a.composite_score)
                .unwrap_or(std::cmp::Ordering::Equal)
        });
    }

    /// Return scores whose composite value deviates from the mean by more
    /// than `threshold` (in absolute terms).
    pub fn get_outliers(
        scores: &[ContinuousScore],
        threshold: f64,
    ) -> Vec<&ContinuousScore> {
        if scores.is_empty() {
            return Vec::new();
        }

        let mean: f64 =
            scores.iter().map(|s| s.composite_score).sum::<f64>() / scores.len() as f64;

        scores
            .iter()
            .filter(|s| (s.composite_score - mean).abs() > threshold)
            .collect()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn basic_scoring() {
        let mut engine = ScoringEngine::new();
        engine.define_axes(vec![("accuracy", 0.6), ("speed", 0.4)]);

        let mut values = HashMap::new();
        values.insert("accuracy".to_string(), 0.9);
        values.insert("speed".to_string(), 0.7);

        let score = engine.score("agent-1", &values);
        // composite = (0.9*0.6 + 0.7*0.4) / (0.6+0.4) = 0.82
        assert!((score.composite_score - 0.82).abs() < 1e-10);
        assert!((score.confidence - 1.0).abs() < 1e-10);
        assert_eq!(score.axes.len(), 2);
    }

    #[test]
    fn partial_values() {
        let mut engine = ScoringEngine::new();
        engine.define_axes(vec![("a", 0.5), ("b", 0.5)]);

        let mut values = HashMap::new();
        values.insert("a".to_string(), 0.8);
        // "b" not provided — defaults to 0.0.

        let score = engine.score("x", &values);
        // composite = (0.8*0.5 + 0.0*0.5) / 1.0 = 0.4
        assert!((score.composite_score - 0.4).abs() < 1e-10);
        assert!((score.confidence - 0.5).abs() < 1e-10);
    }

    #[test]
    fn ranking() {
        let mut engine = ScoringEngine::new();
        engine.define_axes(vec![("score", 1.0)]);

        let mut scores: Vec<ContinuousScore> = (1..=5)
            .map(|i| {
                let mut v = HashMap::new();
                v.insert("score".to_string(), i as f64 * 0.2);
                engine.score(&format!("e-{}", i), &v)
            })
            .collect();

        ScoringEngine::rank(&mut scores);
        assert_eq!(scores[0].entity_id, "e-5");
        assert_eq!(scores[4].entity_id, "e-1");
    }

    #[test]
    fn outlier_detection() {
        let mut engine = ScoringEngine::new();
        engine.define_axes(vec![("val", 1.0)]);

        let scores: Vec<ContinuousScore> = vec![0.5, 0.5, 0.5, 0.5, 0.95]
            .into_iter()
            .enumerate()
            .map(|(i, v)| {
                let mut vals = HashMap::new();
                vals.insert("val".to_string(), v);
                engine.score(&format!("e-{}", i), &vals)
            })
            .collect();

        // Mean = (0.5*4 + 0.95)/5 = 0.59. Outlier at 0.95 deviates by 0.36.
        let outliers = ScoringEngine::get_outliers(&scores, 0.3);
        assert_eq!(outliers.len(), 1);
        assert_eq!(outliers[0].entity_id, "e-4");
    }
}