agent_reflection/

lib.rs

/*!
agent-reflection: self-evaluation loop for LLM agent outputs.

```rust
use agent_reflection::{ReflectionResult, ReflectionStore};

let mut store = ReflectionStore::new();
let id = store.record("original output", "my critique", 0.7);
let r = store.get(id).unwrap();
assert!((r.score - 0.7).abs() < 1e-9);
```
*/

/// A reflection entry.
#[derive(Debug, Clone)]
pub struct ReflectionResult {
    pub id: usize,
    /// The original output being evaluated.
    pub output: String,
    /// The critique / self-evaluation text.
    pub critique: String,
    /// Quality score [0.0, 1.0].
    pub score: f64,
    /// Suggested improvement.
    pub suggestion: Option<String>,
}

impl ReflectionResult {
    pub fn passes(&self, threshold: f64) -> bool {
        self.score >= threshold
    }
}

/// Stores reflection results across turns.
#[derive(Default)]
pub struct ReflectionStore {
    entries: Vec<ReflectionResult>,
}

impl ReflectionStore {
    pub fn new() -> Self { Self::default() }

    /// Record a reflection and return its id.
    pub fn record(&mut self, output: &str, critique: &str, score: f64) -> usize {
        let id = self.entries.len();
        self.entries.push(ReflectionResult { id, output: output.to_string(), critique: critique.to_string(), score, suggestion: None });
        id
    }

    /// Record with a suggestion.
    pub fn record_with_suggestion(&mut self, output: &str, critique: &str, score: f64, suggestion: &str) -> usize {
        let id = self.record(output, critique, score);
        self.entries[id].suggestion = Some(suggestion.to_string());
        id
    }

    pub fn get(&self, id: usize) -> Option<&ReflectionResult> {
        self.entries.get(id)
    }

    pub fn len(&self) -> usize { self.entries.len() }
    pub fn is_empty(&self) -> bool { self.entries.is_empty() }

    /// Average score across all entries.
    pub fn avg_score(&self) -> Option<f64> {
        if self.entries.is_empty() { return None; }
        Some(self.entries.iter().map(|e| e.score).sum::<f64>() / self.entries.len() as f64)
    }

    /// Entries that pass a given threshold.
    pub fn passing(&self, threshold: f64) -> Vec<&ReflectionResult> {
        self.entries.iter().filter(|e| e.passes(threshold)).collect()
    }

    /// Entries below threshold.
    pub fn failing(&self, threshold: f64) -> Vec<&ReflectionResult> {
        self.entries.iter().filter(|e| !e.passes(threshold)).collect()
    }

    /// Best-scoring entry.
    pub fn best(&self) -> Option<&ReflectionResult> {
        self.entries.iter().max_by(|a, b| a.score.partial_cmp(&b.score).unwrap())
    }

    pub fn clear(&mut self) { self.entries.clear(); }
}

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

    #[test]
    fn record_and_get() {
        let mut s = ReflectionStore::new();
        let id = s.record("output", "good", 0.8);
        let r = s.get(id).unwrap();
        assert_eq!(r.output, "output");
        assert!((r.score - 0.8).abs() < 1e-9);
    }

    #[test]
    fn passes_threshold() {
        let r = ReflectionResult { id: 0, output: "x".into(), critique: "ok".into(), score: 0.75, suggestion: None };
        assert!(r.passes(0.7));
        assert!(!r.passes(0.8));
    }

    #[test]
    fn avg_score() {
        let mut s = ReflectionStore::new();
        s.record("a", "ok", 0.6);
        s.record("b", "ok", 0.8);
        let avg = s.avg_score().unwrap();
        assert!((avg - 0.7).abs() < 1e-9);
    }

    #[test]
    fn avg_score_empty() {
        let s = ReflectionStore::new();
        assert!(s.avg_score().is_none());
    }

    #[test]
    fn passing_and_failing() {
        let mut s = ReflectionStore::new();
        s.record("a", "bad", 0.4);
        s.record("b", "ok", 0.9);
        s.record("c", "meh", 0.7);
        assert_eq!(s.passing(0.7).len(), 2);
        assert_eq!(s.failing(0.7).len(), 1);
    }

    #[test]
    fn best() {
        let mut s = ReflectionStore::new();
        s.record("a", "c", 0.5);
        s.record("b", "c", 0.9);
        s.record("c", "c", 0.7);
        assert!((s.best().unwrap().score - 0.9).abs() < 1e-9);
    }

    #[test]
    fn record_with_suggestion() {
        let mut s = ReflectionStore::new();
        let id = s.record_with_suggestion("out", "bad", 0.3, "try being more concise");
        assert_eq!(s.get(id).unwrap().suggestion.as_deref(), Some("try being more concise"));
    }

    #[test]
    fn len_and_empty() {
        let mut s = ReflectionStore::new();
        assert!(s.is_empty());
        s.record("x", "y", 0.5);
        assert_eq!(s.len(), 1);
    }

    #[test]
    fn clear() {
        let mut s = ReflectionStore::new();
        s.record("x", "y", 0.5);
        s.clear();
        assert!(s.is_empty());
    }

    #[test]
    fn ids_sequential() {
        let mut s = ReflectionStore::new();
        let a = s.record("x", "y", 0.5);
        let b = s.record("p", "q", 0.6);
        assert_eq!(a, 0);
        assert_eq!(b, 1);
    }

    #[test]
    fn missing_id_returns_none() {
        let s = ReflectionStore::new();
        assert!(s.get(99).is_none());
    }

    #[test]
    fn no_suggestion_is_none() {
        let mut s = ReflectionStore::new();
        let id = s.record("x", "y", 0.5);
        assert!(s.get(id).unwrap().suggestion.is_none());
    }

    #[test]
    fn passing_all() {
        let mut s = ReflectionStore::new();
        s.record("a", "c", 1.0);
        s.record("b", "c", 1.0);
        assert_eq!(s.passing(0.9).len(), 2);
    }
}