Skip to main content

fetchium_core/compare/
mod.rs

1//! Comparison research engine — "A vs B vs C" (Phase 5, PRD §10, Mode F).
2//!
3//! Researches each item in parallel, extracts comparison dimensions,
4//! and generates a structured comparison table.
5
6pub mod parser;
7pub use parser::{parse_comparison_query, ComparisonQuery};
8
9use serde::{Deserialize, Serialize};
10
11/// Configuration for a comparison run.
12#[derive(Debug, Clone)]
13pub struct CompareConfig {
14    /// Maximum sources per item.
15    pub max_sources_per_item: usize,
16    /// Token budget for each item's research.
17    pub token_budget: usize,
18    /// Output format: "markdown", "json".
19    pub format: String,
20}
21
22impl Default for CompareConfig {
23    fn default() -> Self {
24        Self {
25            max_sources_per_item: 5,
26            token_budget: 2000,
27            format: "markdown".into(),
28        }
29    }
30}
31
32/// A single cell in the comparison table.
33#[derive(Debug, Clone, Serialize, Deserialize)]
34pub struct ComparisonCell {
35    /// The item being described (e.g., "React").
36    pub item: String,
37    /// The dimension (e.g., "Performance").
38    pub dimension: String,
39    /// The value/description for this cell.
40    pub value: String,
41    /// Source URL(s) supporting this cell.
42    pub sources: Vec<String>,
43}
44
45/// A complete comparison result.
46#[derive(Debug, Clone, Serialize, Deserialize)]
47pub struct ComparisonResult {
48    /// Original parsed query.
49    pub raw_query: String,
50    /// Items compared.
51    pub items: Vec<String>,
52    /// Dimensions extracted (e.g., "Performance", "Learning Curve").
53    pub dimensions: Vec<String>,
54    /// Flat list of comparison cells (items × dimensions).
55    pub cells: Vec<ComparisonCell>,
56    /// Pre-rendered markdown table.
57    pub markdown_table: String,
58}
59
60/// Standard comparison dimensions extracted from research.
61const STANDARD_DIMENSIONS: &[&str] = &[
62    "Performance",
63    "Learning Curve",
64    "Ecosystem",
65    "Community",
66    "Production Readiness",
67    "License",
68    "Key Use Case",
69];
70
71/// Build a comparison result from per-item research snippets.
72///
73/// `item_data` maps item name → (summary, source URLs).
74pub fn build_comparison(
75    query: &ComparisonQuery,
76    item_data: &[(String, String, Vec<String>)], // (item, summary, sources)
77) -> ComparisonResult {
78    let items: Vec<String> = query.items.clone();
79    let dimensions: Vec<String> = STANDARD_DIMENSIONS.iter().map(|s| s.to_string()).collect();
80
81    let mut cells = Vec::new();
82
83    for (item, summary, sources) in item_data {
84        // Extract a value for each dimension — BM25-scored with item awareness
85        for dim in &dimensions {
86            let value = extract_dimension_value(summary, dim, item);
87            cells.push(ComparisonCell {
88                item: item.clone(),
89                dimension: dim.clone(),
90                value,
91                sources: sources.clone(),
92            });
93        }
94    }
95
96    let markdown_table = render_markdown_table(&items, &dimensions, &cells);
97
98    ComparisonResult {
99        raw_query: query.raw_query.clone(),
100        items,
101        dimensions,
102        cells,
103        markdown_table,
104    }
105}
106
107/// Extract a value for a dimension from a text summary using BM25 scoring.
108///
109/// 1. Split text into sentences
110/// 2. Filter to sentences that mention the item (case-insensitive)
111/// 3. Score each with BM25 against "{item} {dimension}"
112/// 4. Return highest-scoring sentence (truncated to 120 chars)
113/// 5. Falls back to "Insufficient data" instead of garbage
114fn extract_dimension_value(summary: &str, dimension: &str, item: &str) -> String {
115    if summary.trim().is_empty() {
116        return "Insufficient data".to_string();
117    }
118
119    let item_lower = item.to_lowercase();
120    let dim_lower = dimension.to_lowercase();
121    let bm25_query = format!("{} {}", item, dimension);
122
123    // Split into sentences (handle multiple delimiters)
124    let sentences: Vec<&str> = summary
125        .split(['.', '!', '?'])
126        .map(|s| s.trim())
127        .filter(|s| s.len() > 15) // skip very short fragments
128        .collect();
129
130    if sentences.is_empty() {
131        return "Insufficient data".to_string();
132    }
133
134    // Score sentences: prefer those mentioning the item AND relevant to dimension
135    let mut scored: Vec<(f64, &str)> = sentences
136        .iter()
137        .map(|&sentence| {
138            let lower = sentence.to_lowercase();
139            let mut score = crate::rank::bm25_score(sentence, &bm25_query);
140
141            // Bonus for mentioning the item directly
142            if lower.contains(&item_lower) {
143                score += 0.5;
144            }
145
146            // Bonus for dimension-related keywords
147            let keywords = dimension_keywords(&dim_lower);
148            for kw in keywords {
149                if lower.contains(kw) {
150                    score += 0.3;
151                }
152            }
153
154            (score, sentence)
155        })
156        .collect();
157
158    scored.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));
159
160    // Take best scoring sentence
161    if let Some((score, best)) = scored.first() {
162        if *score < 0.1 {
163            return "Insufficient data".to_string();
164        }
165        let truncated: String = best.chars().take(120).collect();
166        if best.len() > 120 {
167            format!("{}…", truncated.trim_end())
168        } else {
169            truncated
170        }
171    } else {
172        "Insufficient data".to_string()
173    }
174}
175
176/// Return dimension-specific keywords for scoring boosts.
177fn dimension_keywords(dim_lower: &str) -> &'static [&'static str] {
178    match dim_lower {
179        "performance" => &[
180            "fast",
181            "slow",
182            "speed",
183            "benchmark",
184            "performance",
185            "throughput",
186            "latency",
187            "efficient",
188        ],
189        "learning curve" => &[
190            "easy",
191            "difficult",
192            "complex",
193            "beginner",
194            "learn",
195            "learning",
196            "intuitive",
197            "documentation",
198        ],
199        "ecosystem" => &[
200            "libraries",
201            "packages",
202            "npm",
203            "crate",
204            "ecosystem",
205            "plugins",
206            "tools",
207            "framework",
208        ],
209        "community" => &[
210            "community",
211            "users",
212            "popular",
213            "adoption",
214            "developers",
215            "contributors",
216            "active",
217        ],
218        "production readiness" => &[
219            "stable",
220            "production",
221            "enterprise",
222            "mature",
223            "ready",
224            "reliable",
225            "battle-tested",
226        ],
227        "license" => &[
228            "mit",
229            "apache",
230            "gpl",
231            "bsd",
232            "license",
233            "open source",
234            "proprietary",
235        ],
236        "key use case" => &[
237            "use case",
238            "application",
239            "web",
240            "server",
241            "mobile",
242            "cli",
243            "ideal for",
244            "best for",
245        ],
246        _ => &[],
247    }
248}
249
250/// Configuration for AI-powered comparison.
251#[derive(Debug, Clone, Default)]
252pub struct AiCompareConfig {
253    /// Whether to use AI for dimension extraction.
254    pub use_ai: bool,
255    /// Optional model override.
256    pub model: Option<String>,
257}
258
259/// Build a comparison using AI with a SINGLE call for the entire table.
260///
261/// Uses all collected search snippets as context and asks the AI to fill
262/// every cell at once. Much faster and more accurate than per-item calls.
263pub async fn build_comparison_ai_unified(
264    query: &ComparisonQuery,
265    snippet_text: &str,
266    sources: &[String],
267    fetchium_config: &crate::config::FetchiumConfig,
268) -> ComparisonResult {
269    use crate::ai::types::{AiConfig, ChatMessage};
270
271    let items: Vec<String> = query.items.clone();
272    let dimensions: Vec<String> = STANDARD_DIMENSIONS.iter().map(|s| s.to_string()).collect();
273    let ai_config = AiConfig::from_fetchium_config(fetchium_config);
274    let providers = ai_config.providers.clone();
275
276    let items_str = items
277        .iter()
278        .map(|i| capitalise(i))
279        .collect::<Vec<_>>()
280        .join(", ");
281    let _dim_str = dimensions.join(", ");
282
283    // Truncate snippet text to fit in context
284    let context: String = snippet_text.chars().take(6000).collect();
285
286    let prompt = format!(
287        r#"Compare these items: {items_str}
288
289Context from the user's query: "{raw_query}"
290
291Below are search results that MAY contain relevant information. WARNING: Search results
292can be noisy or irrelevant (e.g., "Go" may match "GoPro" cameras, "Rust" may match the
293video game). IGNORE any search result that is not actually about the items being compared.
294Use YOUR OWN KNOWLEDGE as the primary source of information.
295
296SEARCH RESULTS (use only if relevant):
297{context}
298
299Fill in this comparison table with factual, specific assessments.
300
301Respond in EXACTLY this format:
302
303{format_str}
304
305Rules:
306- Use YOUR knowledge as primary source — search results are supplementary
307- Be specific: cite numbers, stats, percentages where possible
308- Keep each value to 1-2 sentences max
309- IGNORE irrelevant search results entirely
310- If genuinely unknown, write "Insufficient data"
311- Do NOT repeat the dimension name in the value"#,
312        raw_query = query.raw_query,
313        format_str = items
314            .iter()
315            .map(|item| {
316                let cap = capitalise(item);
317                dimensions
318                    .iter()
319                    .map(|d| format!("[{cap}] {d}: ..."))
320                    .collect::<Vec<_>>()
321                    .join("\n")
322            })
323            .collect::<Vec<_>>()
324            .join("\n\n")
325    );
326
327    let messages = vec![
328        ChatMessage {
329            role: "system".into(),
330            content: "You are a technical comparison expert. Produce concise, factual comparisons."
331                .into(),
332        },
333        ChatMessage {
334            role: "user".into(),
335            content: prompt,
336        },
337    ];
338
339    let mut noop = |_: &str| {};
340    tracing::debug!(
341        "Compare AI: calling chat_with_fallback with {} chars of context",
342        context.len()
343    );
344    let ai_result = crate::ai::provider_client::chat_with_fallback(
345        &messages, None, &ai_config, &providers, false, &mut noop,
346    )
347    .await;
348
349    let mut cells = Vec::new();
350
351    match ai_result {
352        Ok(result) => {
353            tracing::debug!(
354                "Compare AI succeeded: {} chars response",
355                result.content.len()
356            );
357            for item in &items {
358                for dim in &dimensions {
359                    let value = parse_unified_response(&result.content, item, dim);
360                    cells.push(ComparisonCell {
361                        item: item.clone(),
362                        dimension: dim.clone(),
363                        value,
364                        sources: sources.to_vec(),
365                    });
366                }
367            }
368        }
369        Err(e) => {
370            tracing::warn!("Compare AI call failed: {e}, falling back to heuristic extraction");
371            // Fall back to heuristic — build per-item data from snippet_text
372            for item in &items {
373                for dim in &dimensions {
374                    let value = extract_dimension_value(snippet_text, dim, item);
375                    cells.push(ComparisonCell {
376                        item: item.clone(),
377                        dimension: dim.clone(),
378                        value,
379                        sources: sources.to_vec(),
380                    });
381                }
382            }
383        }
384    }
385
386    let markdown_table = render_markdown_table(&items, &dimensions, &cells);
387
388    ComparisonResult {
389        raw_query: query.raw_query.clone(),
390        items,
391        dimensions,
392        cells,
393        markdown_table,
394    }
395}
396
397/// Parse unified AI response for a specific [Item] Dimension: value.
398fn parse_unified_response(response: &str, item: &str, dimension: &str) -> String {
399    let item_cap = capitalise(item);
400    let prefix = format!("[{}] {}:", item_cap, dimension);
401    let prefix_lower = prefix.to_lowercase();
402
403    for line in response.lines() {
404        let line_trimmed = line.trim();
405        let line_lower = line_trimmed.to_lowercase();
406        if line_lower.starts_with(&prefix_lower) {
407            let value = line_trimmed[prefix.len()..].trim().to_string();
408            if !value.is_empty() {
409                return value;
410            }
411        }
412    }
413
414    // Fallback: try without the [Item] prefix (AI might use "Dimension:" format)
415    let dim_prefix = format!("{}:", dimension);
416    let dim_prefix_lower = dim_prefix.to_lowercase();
417    for line in response.lines() {
418        let line_lower = line.trim().to_lowercase();
419        if line_lower.starts_with(&dim_prefix_lower) {
420            let value = line.trim()[dim_prefix.len()..].trim().to_string();
421            if !value.is_empty() {
422                return value;
423            }
424        }
425    }
426
427    "Insufficient data".to_string()
428}
429
430/// Build a comparison using AI to extract dimension values (per-item calls).
431pub async fn build_comparison_ai(
432    query: &ComparisonQuery,
433    item_data: &[(String, String, Vec<String>)],
434    fetchium_config: &crate::config::FetchiumConfig,
435) -> ComparisonResult {
436    use crate::ai::types::{AiConfig, ChatMessage};
437
438    let items: Vec<String> = query.items.clone();
439    let dimensions: Vec<String> = STANDARD_DIMENSIONS.iter().map(|s| s.to_string()).collect();
440    let mut cells = Vec::new();
441    let ai_config = AiConfig::from_fetchium_config(fetchium_config);
442    let providers = ai_config.providers.clone();
443
444    for (item, summary, sources) in item_data {
445        let snippet: String = summary.chars().take(3000).collect();
446        let dim_list = dimensions.join(", ");
447
448        let prompt = format!(
449            "Based on the following information about \"{item}\", provide a brief (1-2 sentence) assessment for each dimension.\n\n\
450             SOURCE TEXT:\n{snippet}\n\n\
451             DIMENSIONS: {dim_list}\n\n\
452             Respond in this exact format (one line per dimension):\n\
453             Performance: ...\n\
454             Learning Curve: ...\n\
455             Ecosystem: ...\n\
456             Community: ...\n\
457             Production Readiness: ...\n\
458             License: ...\n\
459             Key Use Case: ...\n\n\
460             Be specific and concise. If information is insufficient, say \"Insufficient data\"."
461        );
462
463        let messages = vec![
464            ChatMessage {
465                role: "system".into(),
466                content: "You are a technical comparison assistant. Extract factual dimension values from source text.".into(),
467            },
468            ChatMessage {
469                role: "user".into(),
470                content: prompt,
471            },
472        ];
473
474        let mut noop = |_: &str| {};
475        let ai_result = crate::ai::provider_client::chat_with_fallback(
476            &messages, None, &ai_config, &providers, false, &mut noop,
477        )
478        .await;
479
480        match ai_result {
481            Ok(result) => {
482                // Parse AI response into dimension values
483                for dim in &dimensions {
484                    let value = parse_ai_dimension(&result.content, dim);
485                    cells.push(ComparisonCell {
486                        item: item.clone(),
487                        dimension: dim.clone(),
488                        value,
489                        sources: sources.clone(),
490                    });
491                }
492            }
493            Err(_) => {
494                // Fall back to BM25 extraction
495                for dim in &dimensions {
496                    let value = extract_dimension_value(summary, dim, item);
497                    cells.push(ComparisonCell {
498                        item: item.clone(),
499                        dimension: dim.clone(),
500                        value,
501                        sources: sources.clone(),
502                    });
503                }
504            }
505        }
506    }
507
508    let markdown_table = render_markdown_table(&items, &dimensions, &cells);
509
510    ComparisonResult {
511        raw_query: query.raw_query.clone(),
512        items,
513        dimensions,
514        cells,
515        markdown_table,
516    }
517}
518
519/// Parse an AI response to extract the value for a specific dimension.
520fn parse_ai_dimension(response: &str, dimension: &str) -> String {
521    let dim_prefix = format!("{}:", dimension);
522    let dim_prefix_lower = dim_prefix.to_lowercase();
523    for line in response.lines() {
524        let line_lower = line.to_lowercase().trim().to_string();
525        if line_lower.starts_with(&dim_prefix_lower) {
526            let value = line[dim_prefix.len()..].trim().to_string();
527            if !value.is_empty() {
528                return value;
529            }
530        }
531    }
532    "Insufficient data".to_string()
533}
534
535/// Render a markdown comparison table.
536fn render_markdown_table(
537    items: &[String],
538    dimensions: &[String],
539    cells: &[ComparisonCell],
540) -> String {
541    if items.is_empty() || dimensions.is_empty() {
542        return String::new();
543    }
544
545    let mut out = String::new();
546
547    // Header
548    out.push_str("| Dimension |");
549    for item in items {
550        out.push_str(&format!(" {} |", capitalise(item)));
551    }
552    out.push('\n');
553
554    // Separator
555    out.push_str("|-----------|");
556    for _ in items {
557        out.push_str("--------|");
558    }
559    out.push('\n');
560
561    // Rows
562    for dim in dimensions {
563        out.push_str(&format!("| **{}** |", dim));
564        for item in items {
565            let value = cells
566                .iter()
567                .find(|c| &c.item == item && &c.dimension == dim)
568                .map(|c| c.value.as_str())
569                .unwrap_or("N/A");
570            out.push_str(&format!(" {} |", value.replace('|', "\\|")));
571        }
572        out.push('\n');
573    }
574
575    out
576}
577
578fn capitalise(s: &str) -> String {
579    let mut chars = s.chars();
580    match chars.next() {
581        None => String::new(),
582        Some(c) => c.to_uppercase().to_string() + chars.as_str(),
583    }
584}
585
586#[cfg(test)]
587mod tests {
588    use super::*;
589
590    #[test]
591    fn build_comparison_produces_table() {
592        let query = parse_comparison_query("Rust vs Go");
593        let item_data = vec![
594            (
595                "rust".to_string(),
596                "Rust is fast and has great performance. It has a steep learning curve."
597                    .to_string(),
598                vec!["https://rust-lang.org".to_string()],
599            ),
600            (
601                "go".to_string(),
602                "Go is easy to learn and has a good community ecosystem.".to_string(),
603                vec!["https://golang.org".to_string()],
604            ),
605        ];
606        let result = build_comparison(&query, &item_data);
607        assert_eq!(result.items.len(), 2);
608        assert!(!result.markdown_table.is_empty());
609        assert!(result.markdown_table.contains("Rust") || result.markdown_table.contains("rust"));
610    }
611
612    #[test]
613    fn markdown_table_has_header() {
614        let query = parse_comparison_query("A vs B");
615        let item_data = vec![
616            ("a".to_string(), "A is good.".to_string(), vec![]),
617            ("b".to_string(), "B is better.".to_string(), vec![]),
618        ];
619        let result = build_comparison(&query, &item_data);
620        assert!(result.markdown_table.contains("Dimension"));
621        assert!(result.markdown_table.contains("---"));
622    }
623
624    #[test]
625    fn extract_dimension_value_finds_relevant_sentence() {
626        let summary =
627            "Rust is blazingly fast. Learning Rust has a steep learning curve for beginners.";
628        let val = extract_dimension_value(summary, "Learning Curve", "Rust");
629        assert!(!val.is_empty());
630        assert_ne!(val, "Insufficient data");
631    }
632}