Skip to main content

hyprstream_metrics/storage/
context.rs

1//! Context storage for RAG/CAG functionality.
2//!
3//! This module provides embedding storage with metadata for retrieval-augmented
4//! and cache-augmented generation. It uses the existing StorageBackend trait
5//! for ADBC-agnostic database operations.
6//!
7//! # Data Model
8//!
9//! - **Embeddings + metadata only**: Text is stored elsewhere
10//! - **Vector similarity**: Uses existing VectorizedOperator for cosine similarity
11//! - **Session-based retrieval**: For cache-augmented generation (CAG)
12//! - **Quality filtering**: Retrieve only high-quality context
13
14// tonic::Status is the idiomatic gRPC error type - boxing would break API
15#![allow(clippy::result_large_err)]
16
17use super::StorageBackend;
18use duckdb::arrow::array::{
19    Array, ArrayRef, FixedSizeListArray, FixedSizeListBuilder, Float32Array, Float32Builder,
20    Float64Array, Int64Array, RecordBatch, StringArray,
21};
22use duckdb::arrow::datatypes::{DataType, Field, Schema};
23use std::sync::Arc;
24use tonic::Status;
25
26/// Default embedding dimension (can be configured per model)
27pub const DEFAULT_EMBEDDING_DIM: i32 = 768;
28
29/// Context embedding schema - embeddings + metadata, no text
30pub fn context_schema(embedding_dim: i32) -> Schema {
31    Schema::new(vec![
32        // Identity
33        Field::new("id", DataType::Utf8, false),
34        Field::new("conversation_id", DataType::Utf8, false),
35        Field::new("session_id", DataType::Utf8, true),
36        // Embedding vector as fixed-size list of floats
37        // Note: inner field nullable=true to match FixedSizeListBuilder default
38        Field::new(
39            "embedding",
40            DataType::FixedSizeList(
41                Arc::new(Field::new("item", DataType::Float32, true)),
42                embedding_dim,
43            ),
44            false,
45        ),
46        // Metadata for filtering
47        Field::new("model_id", DataType::Utf8, false),
48        Field::new("timestamp", DataType::Int64, false),
49        Field::new("quality_score", DataType::Float64, true),
50        Field::new("token_count", DataType::Int64, true),
51    ])
52}
53
54/// A single context record for storage
55#[derive(Debug, Clone)]
56pub struct ContextRecord {
57    pub id: String,
58    pub conversation_id: String,
59    pub session_id: Option<String>,
60    pub embedding: Vec<f32>,
61    pub model_id: String,
62    pub timestamp: i64,
63    pub quality_score: Option<f64>,
64    pub token_count: Option<i64>,
65}
66
67impl ContextRecord {
68    /// Convert to Arrow RecordBatch for storage
69    pub fn to_record_batch(&self) -> Result<RecordBatch, Status> {
70        // Embedding dimension is typically small (< 10000), safe conversion
71        let embedding_dim = i32::try_from(self.embedding.len())
72            .map_err(|_| Status::invalid_argument("Embedding dimension too large"))?;
73        let schema = Arc::new(context_schema(embedding_dim));
74
75        // Build the fixed-size list array for embedding
76        let mut embedding_builder = FixedSizeListBuilder::new(Float32Builder::new(), embedding_dim);
77        let values = embedding_builder.values();
78        for &val in &self.embedding {
79            values.append_value(val);
80        }
81        embedding_builder.append(true);
82        let embedding_array = embedding_builder.finish();
83
84        let batch = RecordBatch::try_new(
85            schema,
86            vec![
87                Arc::new(StringArray::from(vec![self.id.as_str()])) as ArrayRef,
88                Arc::new(StringArray::from(vec![self.conversation_id.as_str()])) as ArrayRef,
89                Arc::new(StringArray::from(vec![self.session_id.as_deref()])) as ArrayRef,
90                Arc::new(embedding_array) as ArrayRef,
91                Arc::new(StringArray::from(vec![self.model_id.as_str()])) as ArrayRef,
92                Arc::new(Int64Array::from(vec![self.timestamp])) as ArrayRef,
93                Arc::new(Float64Array::from(vec![self.quality_score])) as ArrayRef,
94                Arc::new(Int64Array::from(vec![self.token_count])) as ArrayRef,
95            ],
96        )
97        .map_err(|e| Status::internal(format!("Failed to create record batch: {e}")))?;
98
99        Ok(batch)
100    }
101
102    /// Create multiple records as a single batch (more efficient for bulk inserts)
103    pub fn batch_to_record_batch(records: &[ContextRecord]) -> Result<RecordBatch, Status> {
104        if records.is_empty() {
105            return Err(Status::invalid_argument(
106                "Cannot create batch from empty records",
107            ));
108        }
109
110        // Embedding dimension is typically small (< 10000), safe conversion
111        let embedding_dim = i32::try_from(records[0].embedding.len())
112            .map_err(|_| Status::invalid_argument("Embedding dimension too large"))?;
113        let schema = Arc::new(context_schema(embedding_dim));
114
115        // Build arrays
116        let ids: Vec<&str> = records.iter().map(|r| r.id.as_str()).collect();
117        let conversation_ids: Vec<&str> =
118            records.iter().map(|r| r.conversation_id.as_str()).collect();
119        let session_ids: Vec<Option<&str>> =
120            records.iter().map(|r| r.session_id.as_deref()).collect();
121        let model_ids: Vec<&str> = records.iter().map(|r| r.model_id.as_str()).collect();
122        let timestamps: Vec<i64> = records.iter().map(|r| r.timestamp).collect();
123        let quality_scores: Vec<Option<f64>> = records.iter().map(|r| r.quality_score).collect();
124        let token_counts: Vec<Option<i64>> = records.iter().map(|r| r.token_count).collect();
125
126        // Build fixed-size list array for embeddings
127        let mut embedding_builder = FixedSizeListBuilder::new(Float32Builder::new(), embedding_dim);
128        for record in records {
129            let values = embedding_builder.values();
130            for &val in &record.embedding {
131                values.append_value(val);
132            }
133            embedding_builder.append(true);
134        }
135        let embedding_array = embedding_builder.finish();
136
137        let batch = RecordBatch::try_new(
138            schema,
139            vec![
140                Arc::new(StringArray::from(ids)) as ArrayRef,
141                Arc::new(StringArray::from(conversation_ids)) as ArrayRef,
142                Arc::new(StringArray::from(session_ids)) as ArrayRef,
143                Arc::new(embedding_array) as ArrayRef,
144                Arc::new(StringArray::from(model_ids)) as ArrayRef,
145                Arc::new(Int64Array::from(timestamps)) as ArrayRef,
146                Arc::new(Float64Array::from(quality_scores)) as ArrayRef,
147                Arc::new(Int64Array::from(token_counts)) as ArrayRef,
148            ],
149        )
150        .map_err(|e| Status::internal(format!("Failed to create record batch: {e}")))?;
151
152        Ok(batch)
153    }
154}
155
156/// Result of a similarity search
157#[derive(Debug, Clone)]
158pub struct SearchResult {
159    pub id: String,
160    pub conversation_id: String,
161    pub score: f32,
162    pub quality_score: Option<f64>,
163}
164
165/// Context store for embedding storage and retrieval
166pub struct ContextStore<B: StorageBackend> {
167    backend: Arc<B>,
168    table_name: String,
169    embedding_dim: i32,
170}
171
172impl<B: StorageBackend> ContextStore<B> {
173    /// Create a new context store
174    pub fn new(backend: Arc<B>, table_name: &str, embedding_dim: i32) -> Self {
175        Self {
176            backend,
177            table_name: table_name.to_owned(),
178            embedding_dim,
179        }
180    }
181
182    /// Create with default embedding dimension (768)
183    pub fn with_defaults(backend: Arc<B>, table_name: &str) -> Self {
184        Self::new(backend, table_name, DEFAULT_EMBEDDING_DIM)
185    }
186
187    /// Initialize the context table
188    pub async fn init(&self) -> Result<(), Status> {
189        let schema = context_schema(self.embedding_dim);
190        self.backend.create_table(&self.table_name, &schema).await
191    }
192
193    /// Store a single context record
194    pub async fn store(&self, record: ContextRecord) -> Result<(), Status> {
195        let batch = record.to_record_batch()?;
196        self.backend
197            .insert_into_table(&self.table_name, batch)
198            .await
199    }
200
201    /// Store multiple context records in a batch
202    pub async fn store_batch(&self, records: &[ContextRecord]) -> Result<(), Status> {
203        if records.is_empty() {
204            return Ok(());
205        }
206        let batch = ContextRecord::batch_to_record_batch(records)?;
207        self.backend
208            .insert_into_table(&self.table_name, batch)
209            .await
210    }
211
212    /// Get recent context by session (CAG - no semantic search)
213    pub async fn recent_by_session(
214        &self,
215        session_id: &str,
216        limit: usize,
217    ) -> Result<Vec<String>, Status> {
218        // Escape single quotes to prevent SQL injection
219        let escaped_session_id = session_id.replace('\'', "''");
220        let sql = format!(
221            "SELECT conversation_id FROM {} WHERE session_id = '{}' ORDER BY timestamp DESC LIMIT {}",
222            self.table_name, escaped_session_id, limit
223        );
224        let handle = self.backend.prepare_sql(&sql).await?;
225        let batch = self.backend.query_sql(&handle).await?;
226
227        // Extract conversation_ids from result
228        let mut conversation_ids = Vec::new();
229        if batch.num_rows() > 0 {
230            if let Some(col) = batch.column_by_name("conversation_id") {
231                if let Some(arr) = col.as_any().downcast_ref::<StringArray>() {
232                    for i in 0..arr.len() {
233                        if !arr.is_null(i) {
234                            conversation_ids.push(arr.value(i).to_owned());
235                        }
236                    }
237                }
238            }
239        }
240
241        Ok(conversation_ids)
242    }
243
244    /// Get recent context by model with quality filter
245    pub async fn recent_by_model(
246        &self,
247        model_id: &str,
248        min_quality: Option<f64>,
249        limit: usize,
250    ) -> Result<Vec<String>, Status> {
251        // Escape single quotes to prevent SQL injection
252        let escaped_model_id = model_id.replace('\'', "''");
253        let quality_filter = min_quality
254            .map(|q| format!(" AND quality_score >= {q}"))
255            .unwrap_or_default();
256
257        let sql = format!(
258            "SELECT conversation_id FROM {} WHERE model_id = '{}'{} ORDER BY timestamp DESC LIMIT {}",
259            self.table_name, escaped_model_id, quality_filter, limit
260        );
261        let handle = self.backend.prepare_sql(&sql).await?;
262        let batch = self.backend.query_sql(&handle).await?;
263
264        // Extract conversation_ids from result
265        let mut conversation_ids = Vec::new();
266        if batch.num_rows() > 0 {
267            if let Some(col) = batch.column_by_name("conversation_id") {
268                if let Some(arr) = col.as_any().downcast_ref::<StringArray>() {
269                    for i in 0..arr.len() {
270                        if !arr.is_null(i) {
271                            conversation_ids.push(arr.value(i).to_owned());
272                        }
273                    }
274                }
275            }
276        }
277
278        Ok(conversation_ids)
279    }
280
281    /// Similarity search using cosine similarity
282    ///
283    /// This loads all embeddings and computes similarity in-memory.
284    /// For large datasets, consider using an external vector database via ADBC.
285    pub async fn search(
286        &self,
287        query_embedding: &[f32],
288        limit: usize,
289        min_quality: Option<f64>,
290    ) -> Result<Vec<SearchResult>, Status> {
291        // Build query with optional quality filter
292        let quality_filter = min_quality
293            .map(|q| format!(" WHERE quality_score >= {q}"))
294            .unwrap_or_default();
295
296        let sql = format!(
297            "SELECT id, conversation_id, embedding, quality_score FROM {}{}",
298            self.table_name, quality_filter
299        );
300        let handle = self.backend.prepare_sql(&sql).await?;
301        let batch = self.backend.query_sql(&handle).await?;
302
303        if batch.num_rows() == 0 {
304            return Ok(Vec::new());
305        }
306
307        // Extract columns
308        let id_col = batch
309            .column_by_name("id")
310            .and_then(|c| c.as_any().downcast_ref::<StringArray>())
311            .ok_or_else(|| Status::internal("Missing id column"))?;
312
313        let conv_id_col = batch
314            .column_by_name("conversation_id")
315            .and_then(|c| c.as_any().downcast_ref::<StringArray>())
316            .ok_or_else(|| Status::internal("Missing conversation_id column"))?;
317
318        let embedding_col = batch
319            .column_by_name("embedding")
320            .and_then(|c| c.as_any().downcast_ref::<FixedSizeListArray>())
321            .ok_or_else(|| Status::internal("Missing embedding column"))?;
322
323        let quality_col = batch
324            .column_by_name("quality_score")
325            .and_then(|c| c.as_any().downcast_ref::<Float64Array>());
326
327        // Compute similarities
328        let query_norm = (query_embedding.iter().map(|x| x * x).sum::<f32>()).sqrt();
329        let mut results: Vec<SearchResult> = Vec::with_capacity(batch.num_rows());
330
331        for i in 0..batch.num_rows() {
332            // Get embedding vector from fixed-size list
333            let embedding_values = embedding_col.value(i);
334            let embedding = embedding_values
335                .as_any()
336                .downcast_ref::<Float32Array>()
337                .ok_or_else(|| Status::internal("Invalid embedding data type"))?;
338
339            // Compute cosine similarity
340            let mut dot_product = 0.0f32;
341            let mut stored_norm_sq = 0.0f32;
342            for j in 0..embedding.len() {
343                let stored_val = embedding.value(j);
344                let query_val = query_embedding.get(j).copied().unwrap_or(0.0);
345                dot_product += stored_val * query_val;
346                stored_norm_sq += stored_val * stored_val;
347            }
348            let stored_norm = stored_norm_sq.sqrt();
349            let score = if query_norm > 0.0 && stored_norm > 0.0 {
350                dot_product / (query_norm * stored_norm)
351            } else {
352                0.0
353            };
354
355            results.push(SearchResult {
356                id: id_col.value(i).to_owned(),
357                conversation_id: conv_id_col.value(i).to_owned(),
358                score,
359                quality_score: quality_col.and_then(|c| {
360                    if c.is_null(i) {
361                        None
362                    } else {
363                        Some(c.value(i))
364                    }
365                }),
366            });
367        }
368
369        // Sort by score descending and take top-k
370        results.sort_by(|a, b| {
371            b.score
372                .partial_cmp(&a.score)
373                .unwrap_or(std::cmp::Ordering::Equal)
374        });
375        results.truncate(limit);
376
377        Ok(results)
378    }
379
380    /// Delete old context entries
381    pub async fn cleanup_before(&self, timestamp: i64) -> Result<usize, Status> {
382        let sql = format!(
383            "DELETE FROM {} WHERE timestamp < {}",
384            self.table_name, timestamp
385        );
386        let handle = self.backend.prepare_sql(&sql).await?;
387        let result = self.backend.query_sql(&handle).await?;
388
389        // Return number of deleted rows (if available)
390        Ok(result.num_rows())
391    }
392}
393
394#[cfg(test)]
395mod tests {
396    use super::*;
397
398    #[test]
399    fn test_context_schema() {
400        let schema = context_schema(768);
401        assert_eq!(schema.fields().len(), 8);
402        assert!(schema.field_with_name("embedding").is_ok());
403        assert!(schema.field_with_name("conversation_id").is_ok());
404    }
405
406    #[test]
407    fn test_context_record_to_batch() -> Result<(), Status> {
408        let record = ContextRecord {
409            id: "test-id".to_owned(),
410            conversation_id: "conv-123".to_owned(),
411            session_id: Some("sess-456".to_owned()),
412            embedding: vec![0.1; 768],
413            model_id: "qwen3-small".to_owned(),
414            timestamp: 1234567890,
415            quality_score: Some(0.85),
416            token_count: Some(100),
417        };
418
419        let batch = record.to_record_batch()?;
420        assert_eq!(batch.num_rows(), 1);
421        assert_eq!(batch.num_columns(), 8);
422        Ok(())
423    }
424
425    #[test]
426    fn test_batch_records() -> Result<(), Status> {
427        let records = vec![
428            ContextRecord {
429                id: "id-1".to_owned(),
430                conversation_id: "conv-1".to_owned(),
431                session_id: None,
432                embedding: vec![0.1; 768],
433                model_id: "model-1".to_owned(),
434                timestamp: 1000,
435                quality_score: Some(0.9),
436                token_count: Some(50),
437            },
438            ContextRecord {
439                id: "id-2".to_owned(),
440                conversation_id: "conv-2".to_owned(),
441                session_id: Some("sess-1".to_owned()),
442                embedding: vec![0.2; 768],
443                model_id: "model-1".to_owned(),
444                timestamp: 2000,
445                quality_score: None,
446                token_count: None,
447            },
448        ];
449
450        let batch = ContextRecord::batch_to_record_batch(&records)?;
451        assert_eq!(batch.num_rows(), 2);
452        Ok(())
453    }
454}