1use crate::validate::types::Contradiction;
7use serde::{Deserialize, Serialize};
8
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
11pub enum ReflectionCheckpoint {
12 NeedMore,
14 Relevant,
16 Sufficient,
18 Supported,
20 Consistent,
22}
23
24#[derive(Debug, Clone, Serialize, Deserialize)]
26pub enum RarAction {
27 Proceed,
29 ExpandQuery { new_query: String },
31 ReformulateQuery { reason: String, new_query: String },
33 FetchMore { urls: Vec<String> },
35 RemoveUnsupported { claim_ids: Vec<String> },
37 FlagContradictions { contradictions: Vec<Contradiction> },
39}
40
41#[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#[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#[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 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#[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 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 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 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 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 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 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 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}