laurus 0.8.0

Unified search library for lexical, vector, and semantic retrieval
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

//! Shared helpers for Laurus examples.
//!
//! Provides common setup utilities so that each example can focus on
//! demonstrating its specific feature rather than repeating boilerplate.

#![allow(dead_code)]

use std::any::Any;
use std::sync::Arc;

use async_trait::async_trait;

use laurus::analysis::analyzer::analyzer::Analyzer;
use laurus::analysis::analyzer::keyword::KeywordAnalyzer;
use laurus::analysis::analyzer::per_field::PerFieldAnalyzer;
use laurus::analysis::analyzer::standard::StandardAnalyzer;
use laurus::storage::memory::MemoryStorageConfig;
use laurus::storage::{Storage, StorageConfig, StorageFactory};
use laurus::vector::Vector;
use laurus::{DataValue, EmbedInput, EmbedInputType, Embedder, Result, SearchResult};

// ---------------------------------------------------------------------------
// Storage helpers
// ---------------------------------------------------------------------------

/// Create an in-memory storage backend.
pub fn memory_storage() -> Result<Arc<dyn Storage>> {
    StorageFactory::create(StorageConfig::Memory(MemoryStorageConfig::default()))
}

// ---------------------------------------------------------------------------
// Analyzer helpers
// ---------------------------------------------------------------------------

/// Create a `PerFieldAnalyzer` where `keyword_fields` use `KeywordAnalyzer`
/// (exact match) and all other fields use `StandardAnalyzer` (tokenization +
/// lowercasing).
pub fn per_field_analyzer(keyword_fields: &[&str]) -> Arc<PerFieldAnalyzer> {
    let std_analyzer: Arc<dyn Analyzer> = Arc::new(StandardAnalyzer::default());
    let kw_analyzer: Arc<dyn Analyzer> = Arc::new(KeywordAnalyzer::new());
    let pfa = PerFieldAnalyzer::new(Arc::clone(&std_analyzer));
    for &field in keyword_fields {
        pfa.add_analyzer(field, Arc::clone(&kw_analyzer));
    }
    Arc::new(pfa)
}

// ---------------------------------------------------------------------------
// MockEmbedder (for vector / hybrid search examples)
// ---------------------------------------------------------------------------

/// A mock embedder that converts text into a 4-dimensional vector based on
/// keyword matching. In production, use a real embedding model.
#[derive(Debug, Clone)]
pub struct MockEmbedder;

#[async_trait]
impl Embedder for MockEmbedder {
    async fn embed(&self, input: &EmbedInput<'_>) -> Result<Vector> {
        match input {
            EmbedInput::Text(t) => {
                let t = t.to_lowercase();
                // Semantic dimensions: [systems, language, memory, concurrency]
                let vec = if t.contains("ownership")
                    || t.contains("borrow")
                    || t.contains("lifetime")
                {
                    [0.2, 0.3, 0.9, 0.1] // Memory safety
                } else if t.contains("async") || t.contains("thread") || t.contains("concurrent") {
                    [0.3, 0.1, 0.2, 0.9] // Concurrency
                } else if t.contains("type") || t.contains("generic") || t.contains("trait") {
                    [0.4, 0.8, 0.2, 0.1] // Type system
                } else if t.contains("cargo") || t.contains("crate") || t.contains("build") {
                    [0.8, 0.3, 0.1, 0.2] // Build system
                } else if t.contains("memory") || t.contains("safe") {
                    [0.3, 0.2, 0.8, 0.2] // Memory
                } else {
                    [0.0, 0.0, 0.0, 0.0]
                };
                Ok(Vector::new(vec.to_vec()))
            }
            _ => Ok(Vector::new(vec![0.0; 4])),
        }
    }

    fn supported_input_types(&self) -> Vec<EmbedInputType> {
        vec![EmbedInputType::Text]
    }

    fn supports_text(&self) -> bool {
        true
    }

    fn supports_image(&self) -> bool {
        false
    }

    fn name(&self) -> &str {
        "MockEmbedder"
    }

    fn as_any(&self) -> &dyn Any {
        self
    }
}

// ---------------------------------------------------------------------------
// Print helpers
// ---------------------------------------------------------------------------

/// Print unified (Engine) search results in a human-readable format.
///
/// Displays all document fields (except `_id` and vector fields).
pub fn print_search_results(results: &[SearchResult]) {
    if results.is_empty() {
        println!("  (No results found)");
        return;
    }
    for (i, hit) in results.iter().enumerate() {
        println!("  {}. (score: {:.4})", i + 1, hit.score);
        if let Some(doc) = &hit.document {
            let mut fields: Vec<_> = doc.fields.iter().collect();
            fields.sort_by_key(|(k, _)| (*k).clone());
            for (name, value) in fields {
                if name == "_id" || matches!(value, DataValue::Vector(_)) {
                    continue;
                }
                let formatted = format_data_value(value);
                let display = if formatted.len() > 80 {
                    format!("{}...", &formatted[..80])
                } else {
                    formatted
                };
                println!("     {}: {}", name, display);
            }
        }
    }
}

/// Format a `DataValue` for display.
fn format_data_value(value: &DataValue) -> String {
    match value {
        DataValue::Text(s) => s.clone(),
        DataValue::Int64(n) => n.to_string(),
        DataValue::Float64(f) => format!("{f:.2}"),
        DataValue::Bool(b) => b.to_string(),
        DataValue::DateTime(dt) => dt.to_rfc3339(),
        DataValue::Geo(lat, lon) => format!("({lat:.4}, {lon:.4})"),
        DataValue::Vector(v) => format!("{v:?}"),
        DataValue::Bytes(b, _) => format!("[{} bytes]", b.len()),
        DataValue::Null => "null".to_string(),
    }
}