evidential_protocol/

fingerprint.rs

//! Behavioral Fingerprinting for the Evidential Protocol.
//!
//! Builds statistical fingerprints from agent behavior samples. Detects
//! anomalies by comparing new observations against established baselines,
//! and measures similarity between agents.

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

// ---------------------------------------------------------------------------
// BehaviorSample
// ---------------------------------------------------------------------------

/// A single observed behavior from an agent.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BehaviorSample {
    /// Identifier of the agent that produced this sample.
    pub agent_id: String,
    /// ISO-8601 timestamp of when the behavior was observed.
    pub timestamp: String,
    /// The tool that was used.
    pub tool_used: String,
    /// Evidence classification of the tool's output.
    pub evidence_class: EvidenceClass,
    /// Confidence of the tool's output.
    pub confidence: f64,
    /// How long the tool invocation took in milliseconds.
    pub response_time_ms: u64,
    /// Whether the invocation succeeded.
    pub success: bool,
}

// ---------------------------------------------------------------------------
// AgentFingerprint
// ---------------------------------------------------------------------------

/// Statistical fingerprint derived from an agent's behavior history.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentFingerprint {
    /// Agent identifier.
    pub agent_id: String,
    /// Number of samples ingested.
    pub sample_count: usize,
    /// Mean response time in milliseconds.
    pub avg_response_time: f64,
    /// Fraction of samples that failed (0.0 to 1.0).
    pub error_rate: f64,
    /// Distribution of evidence classes as percentages (0.0 to 1.0).
    pub evidence_distribution: HashMap<EvidenceClass, f64>,
    /// Most frequently used tools, ordered by frequency.
    pub top_tools: Vec<String>,
    /// Mean confidence across all samples.
    pub confidence_mean: f64,
    /// Standard deviation of confidence.
    pub confidence_stddev: f64,
    /// ISO-8601 timestamp of the most recent sample.
    pub last_active: String,
}

// ---------------------------------------------------------------------------
// AnomalyResult
// ---------------------------------------------------------------------------

/// Result of anomaly detection against an agent's baseline.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AnomalyResult {
    /// Whether the sample was flagged as anomalous.
    pub anomalous: bool,
    /// Human-readable reasons for the anomaly flag.
    pub reasons: Vec<String>,
    /// Severity score from 0.0 (normal) to 1.0 (extreme).
    pub severity: f64,
}

// ---------------------------------------------------------------------------
// HealthStatus
// ---------------------------------------------------------------------------

/// High-level health classification of an agent.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum HealthStatus {
    /// Agent is operating within expected parameters.
    Healthy,
    /// Agent shows minor deviations from baseline.
    Degraded,
    /// Agent shows significant deviations; investigation needed.
    Anomalous,
    /// Agent has not been active recently.
    Inactive,
}

// ---------------------------------------------------------------------------
// FingerprintEngine
// ---------------------------------------------------------------------------

/// Engine that ingests behavior samples and computes agent fingerprints.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FingerprintEngine {
    samples: HashMap<String, Vec<BehaviorSample>>,
}

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

impl FingerprintEngine {
    /// Create an empty fingerprint engine.
    pub fn new() -> Self {
        Self {
            samples: HashMap::new(),
        }
    }

    /// Ingest a new behavior sample.
    pub fn ingest(&mut self, sample: BehaviorSample) {
        self.samples
            .entry(sample.agent_id.clone())
            .or_default()
            .push(sample);
    }

    /// Compute the fingerprint for a given agent, or `None` if no samples exist.
    pub fn get_fingerprint(&self, agent_id: &str) -> Option<AgentFingerprint> {
        let samples = self.samples.get(agent_id)?;
        if samples.is_empty() {
            return None;
        }

        let count = samples.len();
        let avg_response_time =
            samples.iter().map(|s| s.response_time_ms as f64).sum::<f64>() / count as f64;
        let error_count = samples.iter().filter(|s| !s.success).count();
        let error_rate = error_count as f64 / count as f64;

        // Evidence distribution as percentages.
        let mut class_counts: HashMap<EvidenceClass, usize> = HashMap::new();
        for s in samples {
            *class_counts.entry(s.evidence_class).or_insert(0) += 1;
        }
        let evidence_distribution: HashMap<EvidenceClass, f64> = class_counts
            .into_iter()
            .map(|(k, v)| (k, v as f64 / count as f64))
            .collect();

        // Top tools by frequency.
        let mut tool_counts: HashMap<&str, usize> = HashMap::new();
        for s in samples {
            *tool_counts.entry(s.tool_used.as_str()).or_insert(0) += 1;
        }
        let mut tool_vec: Vec<(&str, usize)> = tool_counts.into_iter().collect();
        tool_vec.sort_by(|a, b| b.1.cmp(&a.1));
        let top_tools: Vec<String> = tool_vec.into_iter().map(|(t, _)| t.to_string()).collect();

        // Confidence mean and stddev.
        let confidence_mean =
            samples.iter().map(|s| s.confidence).sum::<f64>() / count as f64;
        let variance = samples
            .iter()
            .map(|s| (s.confidence - confidence_mean).powi(2))
            .sum::<f64>()
            / count as f64;
        let confidence_stddev = variance.sqrt();

        let last_active = samples
            .iter()
            .map(|s| s.timestamp.as_str())
            .max()
            .unwrap_or("")
            .to_string();

        Some(AgentFingerprint {
            agent_id: agent_id.to_string(),
            sample_count: count,
            avg_response_time,
            error_rate,
            evidence_distribution,
            top_tools,
            confidence_mean,
            confidence_stddev,
            last_active,
        })
    }

    /// Detect whether a new sample is anomalous relative to the agent's baseline.
    ///
    /// Checks:
    /// - Response time > 2x the baseline mean
    /// - Error rate > 3x the baseline rate (inferred from a single failing sample)
    /// - Confidence drop > 0.2 below the baseline mean
    pub fn detect_anomaly(&self, agent_id: &str, sample: &BehaviorSample) -> AnomalyResult {
        let fingerprint = match self.get_fingerprint(agent_id) {
            Some(fp) => fp,
            None => {
                return AnomalyResult {
                    anomalous: false,
                    reasons: vec!["no baseline established".to_string()],
                    severity: 0.0,
                }
            }
        };

        let mut reasons = Vec::new();
        let mut severity: f64 = 0.0;

        // Response time check: > 2x mean.
        if fingerprint.avg_response_time > 0.0 {
            let ratio = sample.response_time_ms as f64 / fingerprint.avg_response_time;
            if ratio > 2.0 {
                reasons.push(format!(
                    "response time {:.0}ms is {:.1}x baseline {:.0}ms",
                    sample.response_time_ms as f64, ratio, fingerprint.avg_response_time
                ));
                severity += (ratio - 2.0).min(1.0) * 0.4;
            }
        }

        // Error rate check: if this sample fails and baseline error rate is low.
        if !sample.success {
            let implied_error_rate = 1.0; // single failing sample = 100%
            if fingerprint.error_rate > 0.0 {
                let ratio = implied_error_rate / fingerprint.error_rate;
                if ratio > 3.0 {
                    reasons.push(format!(
                        "failure with baseline error rate {:.1}%",
                        fingerprint.error_rate * 100.0
                    ));
                    severity += 0.3;
                }
            } else {
                // Baseline has zero errors — any failure is anomalous.
                reasons.push("failure against zero-error baseline".to_string());
                severity += 0.3;
            }
        }

        // Confidence drop check: > 0.2 below mean.
        let confidence_drop = fingerprint.confidence_mean - sample.confidence;
        if confidence_drop > 0.2 {
            reasons.push(format!(
                "confidence {:.2} is {:.2} below baseline mean {:.2}",
                sample.confidence, confidence_drop, fingerprint.confidence_mean
            ));
            severity += confidence_drop.min(1.0) * 0.3;
        }

        severity = severity.min(1.0);
        let anomalous = !reasons.is_empty();

        AnomalyResult {
            anomalous,
            reasons,
            severity,
        }
    }

    /// Compute a similarity score (0.0 to 1.0) between two agents.
    ///
    /// Compares evidence distribution, confidence mean, error rate, and
    /// average response time. Returns 0.0 if either agent has no samples.
    pub fn similarity(&self, a: &str, b: &str) -> f64 {
        let fp_a = match self.get_fingerprint(a) {
            Some(fp) => fp,
            None => return 0.0,
        };
        let fp_b = match self.get_fingerprint(b) {
            Some(fp) => fp,
            None => return 0.0,
        };

        // Evidence distribution similarity (cosine-like overlap).
        let all_classes = [
            EvidenceClass::Direct,
            EvidenceClass::Inferred,
            EvidenceClass::Reported,
            EvidenceClass::Conjecture,
        ];
        let dist_sim = {
            let mut dot = 0.0_f64;
            let mut mag_a = 0.0_f64;
            let mut mag_b = 0.0_f64;
            for class in &all_classes {
                let va = fp_a.evidence_distribution.get(class).copied().unwrap_or(0.0);
                let vb = fp_b.evidence_distribution.get(class).copied().unwrap_or(0.0);
                dot += va * vb;
                mag_a += va * va;
                mag_b += vb * vb;
            }
            let denom = mag_a.sqrt() * mag_b.sqrt();
            if denom > 0.0 {
                dot / denom
            } else {
                0.0
            }
        };

        // Confidence similarity.
        let conf_sim = 1.0 - (fp_a.confidence_mean - fp_b.confidence_mean).abs();

        // Error rate similarity.
        let err_sim = 1.0 - (fp_a.error_rate - fp_b.error_rate).abs();

        // Response time similarity (normalized, capped).
        let max_rt = fp_a.avg_response_time.max(fp_b.avg_response_time);
        let rt_sim = if max_rt > 0.0 {
            1.0 - (fp_a.avg_response_time - fp_b.avg_response_time).abs() / max_rt
        } else {
            1.0
        };

        // Weighted average of all axes.
        (dist_sim * 0.4 + conf_sim * 0.3 + err_sim * 0.15 + rt_sim * 0.15).clamp(0.0, 1.0)
    }
}

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

    fn sample(agent: &str, tool: &str, class: EvidenceClass, conf: f64, ms: u64, ok: bool) -> BehaviorSample {
        BehaviorSample {
            agent_id: agent.to_string(),
            timestamp: chrono::Utc::now().to_rfc3339(),
            tool_used: tool.to_string(),
            evidence_class: class,
            confidence: conf,
            response_time_ms: ms,
            success: ok,
        }
    }

    #[test]
    fn fingerprint_and_anomaly() {
        let mut engine = FingerprintEngine::new();
        for _ in 0..10 {
            engine.ingest(sample("a", "Read", EvidenceClass::Direct, 0.9, 50, true));
        }

        let fp = engine.get_fingerprint("a").unwrap();
        assert_eq!(fp.sample_count, 10);
        assert!((fp.avg_response_time - 50.0).abs() < 1e-10);
        assert!((fp.error_rate - 0.0).abs() < 1e-10);

        // Normal sample — not anomalous.
        let normal = sample("a", "Read", EvidenceClass::Direct, 0.85, 60, true);
        let result = engine.detect_anomaly("a", &normal);
        assert!(!result.anomalous);

        // Anomalous sample — slow + low confidence.
        let bad = sample("a", "Read", EvidenceClass::Conjecture, 0.3, 200, false);
        let result = engine.detect_anomaly("a", &bad);
        assert!(result.anomalous);
        assert!(result.severity > 0.0);
    }

    #[test]
    fn similarity_identical() {
        let mut engine = FingerprintEngine::new();
        for _ in 0..5 {
            engine.ingest(sample("x", "Read", EvidenceClass::Direct, 0.9, 50, true));
            engine.ingest(sample("y", "Read", EvidenceClass::Direct, 0.9, 50, true));
        }
        let sim = engine.similarity("x", "y");
        assert!(sim > 0.95, "identical agents should have high similarity: {sim}");
    }
}