Skip to main content

fetchium_core/validate/
rar.rs

1//! RAR (Reflection-Augmented Research) self-correction loop (PRD §8.6).
2//!
3//! 5 reflection checkpoints: R1 NeedMore, R2 Relevant, R3 Sufficient,
4//! R4 Supported, R5 Consistent.
5
6use crate::validate::types::Contradiction;
7use serde::{Deserialize, Serialize};
8
9/// The 5 RAR reflection checkpoints.
10#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
11pub enum ReflectionCheckpoint {
12    /// R1: Are there enough relevant results?
13    NeedMore,
14    /// R2: Are the results relevant to the query?
15    Relevant,
16    /// R3: Does extracted content actually answer the query?
17    Sufficient,
18    /// R4: Does synthesis contain only source-supported claims?
19    Supported,
20    /// R5: Do sources agree with each other?
21    Consistent,
22}
23
24/// Action the RAR loop decides to take.
25#[derive(Debug, Clone, Serialize, Deserialize)]
26pub enum RarAction {
27    /// Retrieval is good; proceed.
28    Proceed,
29    /// Expand query and re-search (R1 action).
30    ExpandQuery { new_query: String },
31    /// Discard irrelevant results and reformulate (R2 action).
32    ReformulateQuery { reason: String, new_query: String },
33    /// Fetch additional pages for more evidence (R3 action).
34    FetchMore { urls: Vec<String> },
35    /// Remove unsupported claims from synthesis (R4 action).
36    RemoveUnsupported { claim_ids: Vec<String> },
37    /// Flag contradictions for the user (R5 action).
38    FlagContradictions { contradictions: Vec<Contradiction> },
39}
40
41/// Result of one RAR loop iteration.
42#[derive(Debug, Clone, Serialize, Deserialize)]
43pub struct RarIterationResult {
44    pub iteration: usize,
45    pub checkpoint: ReflectionCheckpoint,
46    pub action: RarAction,
47    pub quality_before: f64,
48    pub quality_after: f64,
49}
50
51/// Configuration for the RAR loop.
52#[derive(Debug, Clone)]
53pub struct RarConfig {
54    pub max_loops: usize,
55    pub min_relevant_ratio: f64,
56    pub min_sufficiency_score: f64,
57    pub min_consistency_score: f64,
58    pub min_results: usize,
59}
60
61impl Default for RarConfig {
62    fn default() -> Self {
63        Self {
64            max_loops: 3,
65            min_relevant_ratio: 0.5,
66            min_sufficiency_score: 0.4,
67            min_consistency_score: 0.5,
68            min_results: 3,
69        }
70    }
71}
72
73/// Snapshot of retrieval quality passed to the RAR engine.
74#[derive(Debug, Clone)]
75pub struct RarState {
76    pub query: String,
77    pub total_results: usize,
78    pub relevant_count: usize,
79    pub sufficiency_score: f64,
80    pub support_ratio: f64,
81    pub consistency_score: f64,
82    pub unsupported_claims: Vec<String>,
83    pub contradictions: Vec<Contradiction>,
84    pub candidate_urls: Vec<String>,
85    pub low_relevance_terms: Vec<String>,
86}
87
88impl RarState {
89    /// Overall quality: average of relevance, sufficiency, and consistency.
90    pub fn overall_quality(&self) -> f64 {
91        let relevance = self.relevant_count as f64 / self.total_results.max(1) as f64;
92        (relevance + self.sufficiency_score + self.consistency_score) / 3.0
93    }
94}
95
96/// The RAR engine evaluates retrieval quality and triggers corrective actions.
97#[derive(Default)]
98pub struct RarEngine {
99    config: RarConfig,
100}
101
102impl RarEngine {
103    pub fn new(config: RarConfig) -> Self {
104        Self { config }
105    }
106
107    /// Evaluate one RAR iteration and return the recommended action.
108    ///
109    /// The caller is responsible for executing actions (re-search, re-fetch)
110    /// and calling this again with updated state.
111    pub fn evaluate(&self, state: &RarState, iteration: usize) -> RarIterationResult {
112        if iteration >= self.config.max_loops {
113            return RarIterationResult {
114                iteration,
115                checkpoint: ReflectionCheckpoint::Consistent,
116                action: RarAction::Proceed,
117                quality_before: state.overall_quality(),
118                quality_after: state.overall_quality(),
119            };
120        }
121
122        // R1: Need more results?
123        if state.total_results < self.config.min_results {
124            let new_query = Self::expand_query(&state.query);
125            return RarIterationResult {
126                iteration,
127                checkpoint: ReflectionCheckpoint::NeedMore,
128                action: RarAction::ExpandQuery { new_query },
129                quality_before: state.overall_quality(),
130                quality_after: state.overall_quality(),
131            };
132        }
133
134        // R2: Are results relevant?
135        let relevant_ratio = state.relevant_count as f64 / state.total_results.max(1) as f64;
136        if relevant_ratio < self.config.min_relevant_ratio {
137            let new_query = Self::reformulate(&state.query, &state.low_relevance_terms);
138            return RarIterationResult {
139                iteration,
140                checkpoint: ReflectionCheckpoint::Relevant,
141                action: RarAction::ReformulateQuery {
142                    reason: format!(
143                        "Only {:.0}% relevant (need {:.0}%)",
144                        relevant_ratio * 100.0,
145                        self.config.min_relevant_ratio * 100.0
146                    ),
147                    new_query,
148                },
149                quality_before: relevant_ratio,
150                quality_after: relevant_ratio,
151            };
152        }
153
154        // R3: Is content sufficient?
155        if state.sufficiency_score < self.config.min_sufficiency_score {
156            return RarIterationResult {
157                iteration,
158                checkpoint: ReflectionCheckpoint::Sufficient,
159                action: RarAction::FetchMore {
160                    urls: state.candidate_urls.clone(),
161                },
162                quality_before: state.sufficiency_score,
163                quality_after: state.sufficiency_score,
164            };
165        }
166
167        // R4: Are claims supported?
168        if !state.unsupported_claims.is_empty() {
169            return RarIterationResult {
170                iteration,
171                checkpoint: ReflectionCheckpoint::Supported,
172                action: RarAction::RemoveUnsupported {
173                    claim_ids: state.unsupported_claims.clone(),
174                },
175                quality_before: state.support_ratio,
176                quality_after: 1.0,
177            };
178        }
179
180        // R5: Are sources consistent?
181        if state.consistency_score < self.config.min_consistency_score {
182            return RarIterationResult {
183                iteration,
184                checkpoint: ReflectionCheckpoint::Consistent,
185                action: RarAction::FlagContradictions {
186                    contradictions: state.contradictions.clone(),
187                },
188                quality_before: state.consistency_score,
189                quality_after: state.consistency_score,
190            };
191        }
192
193        // All checks pass
194        RarIterationResult {
195            iteration,
196            checkpoint: ReflectionCheckpoint::Consistent,
197            action: RarAction::Proceed,
198            quality_before: state.overall_quality(),
199            quality_after: state.overall_quality(),
200        }
201    }
202
203    fn expand_query(query: &str) -> String {
204        format!("{query} overview")
205    }
206
207    fn reformulate(query: &str, _low_terms: &[String]) -> String {
208        let words: Vec<&str> = query
209            .split_whitespace()
210            .filter(|w| w.len() > 3)
211            .take(5)
212            .collect();
213        if words.is_empty() {
214            query.to_string()
215        } else {
216            words.join(" ")
217        }
218    }
219}
220
221#[cfg(test)]
222mod tests {
223    use super::*;
224
225    fn good_state() -> RarState {
226        RarState {
227            query: "what is Rust".into(),
228            total_results: 10,
229            relevant_count: 8,
230            sufficiency_score: 0.8,
231            support_ratio: 1.0,
232            consistency_score: 0.9,
233            unsupported_claims: vec![],
234            contradictions: vec![],
235            candidate_urls: vec![],
236            low_relevance_terms: vec![],
237        }
238    }
239
240    #[test]
241    fn good_state_proceeds() {
242        let engine = RarEngine::default();
243        let r = engine.evaluate(&good_state(), 0);
244        assert!(matches!(r.action, RarAction::Proceed));
245    }
246
247    #[test]
248    fn insufficient_results_expands() {
249        let engine = RarEngine::default();
250        let mut state = good_state();
251        state.total_results = 1;
252        state.relevant_count = 1;
253        let r = engine.evaluate(&state, 0);
254        assert!(matches!(r.action, RarAction::ExpandQuery { .. }));
255        assert_eq!(r.checkpoint, ReflectionCheckpoint::NeedMore);
256    }
257
258    #[test]
259    fn low_relevance_reformulates() {
260        let engine = RarEngine::default();
261        let mut state = good_state();
262        state.total_results = 10;
263        state.relevant_count = 2;
264        let r = engine.evaluate(&state, 0);
265        assert!(matches!(r.action, RarAction::ReformulateQuery { .. }));
266    }
267
268    #[test]
269    fn max_loops_respected() {
270        let engine = RarEngine::new(RarConfig {
271            max_loops: 2,
272            ..Default::default()
273        });
274        let mut state = good_state();
275        state.total_results = 1;
276        let r = engine.evaluate(&state, 2);
277        assert!(matches!(r.action, RarAction::Proceed));
278    }
279
280    #[test]
281    fn unsupported_claims_removed() {
282        let engine = RarEngine::default();
283        let mut state = good_state();
284        state.unsupported_claims = vec!["claim_1".into()];
285        let r = engine.evaluate(&state, 0);
286        assert!(matches!(r.action, RarAction::RemoveUnsupported { .. }));
287    }
288
289    #[test]
290    fn low_consistency_flags_contradictions() {
291        let engine = RarEngine::default();
292        let mut state = good_state();
293        state.consistency_score = 0.2;
294        let r = engine.evaluate(&state, 0);
295        assert!(matches!(r.action, RarAction::FlagContradictions { .. }));
296    }
297}