1use std::collections::HashMap;
17use std::sync::{Arc, Mutex};
18
19use anyhow::Result;
20use async_trait::async_trait;
21use serde::{Deserialize, Serialize};
22
23#[derive(Clone)]
27pub struct VectorStoreExt(pub Arc<dyn VectorStore>);
28
29const RRF_K: f32 = 60.0;
31
32#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
38pub struct KnowledgeIndexCitation {
39 pub id: String,
41 pub index_id: String,
43 pub document_title: Option<String>,
45 pub source_uri: String,
47 pub location: Option<serde_json::Value>,
49 pub snippet: String,
51 pub score: f32,
53}
54
55#[derive(Debug, Clone, PartialEq)]
61pub struct EmbeddingCallUsage {
62 pub model: String,
64 pub provider: Option<String>,
66 pub total_tokens: u32,
68 pub actual_cost_usd: Option<f64>,
70}
71
72#[derive(Debug, Clone, Default)]
77pub struct KnowledgeIndexSearchOutcome {
78 pub citations: Vec<KnowledgeIndexCitation>,
80 pub embedding_usage: Vec<EmbeddingCallUsage>,
82}
83
84#[async_trait]
90pub trait KnowledgeIndexSearch: Send + Sync {
91 async fn search(
102 &self,
103 org_id: i64,
104 index_ids: &[String],
105 query: &str,
106 top_k: usize,
107 ) -> Result<KnowledgeIndexSearchOutcome>;
108}
109
110pub fn index_namespace(org_id: i64, public_id: &str) -> String {
115 format!("org_{org_id}__{public_id}")
116}
117
118#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
121pub struct VectorRecord {
122 pub id: String,
124 pub vector: Vec<f32>,
126 pub text: String,
128 pub document_id: String,
130}
131
132#[derive(Debug, Clone, Default, Serialize, Deserialize)]
136pub struct VectorQuery {
137 pub vector: Option<Vec<f32>>,
139 pub text: Option<String>,
141 pub top_k: usize,
143}
144
145#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
147pub struct VectorMatch {
148 pub id: String,
150 pub document_id: String,
152 pub score: f32,
154}
155
156#[async_trait]
160pub trait VectorStore: Send + Sync {
161 async fn upsert(&self, namespace: &str, records: Vec<VectorRecord>) -> Result<()>;
163
164 async fn query(&self, namespace: &str, query: VectorQuery) -> Result<Vec<VectorMatch>>;
167
168 async fn delete_by_document(&self, namespace: &str, document_id: &str) -> Result<()>;
170
171 async fn delete_namespace(&self, namespace: &str) -> Result<()>;
173}
174
175#[derive(Default)]
181pub struct InMemoryVectorStore {
182 namespaces: Mutex<HashMap<String, Vec<VectorRecord>>>,
183}
184
185impl InMemoryVectorStore {
186 pub fn new() -> Self {
187 Self::default()
188 }
189}
190
191#[async_trait]
192impl VectorStore for InMemoryVectorStore {
193 async fn upsert(&self, namespace: &str, records: Vec<VectorRecord>) -> Result<()> {
194 let mut store = self
195 .namespaces
196 .lock()
197 .map_err(|_| anyhow::anyhow!("vector store poisoned"))?;
198 let entry = store.entry(namespace.to_string()).or_default();
199 for record in records {
200 if let Some(existing) = entry.iter_mut().find(|r| r.id == record.id) {
201 *existing = record;
202 } else {
203 entry.push(record);
204 }
205 }
206 Ok(())
207 }
208
209 async fn query(&self, namespace: &str, query: VectorQuery) -> Result<Vec<VectorMatch>> {
210 if query.top_k == 0 {
211 return Ok(Vec::new());
212 }
213 let store = self
214 .namespaces
215 .lock()
216 .map_err(|_| anyhow::anyhow!("vector store poisoned"))?;
217 let Some(records) = store.get(namespace) else {
218 return Ok(Vec::new());
219 };
220
221 let vector_ranked = query
222 .vector
223 .as_ref()
224 .map(|v| rank_by(records, |r| cosine_similarity(&r.vector, v)));
225 let text_ranked = query.text.as_ref().and_then(|t| {
226 let t = t.trim();
227 (!t.is_empty()).then(|| rank_by(records, |r| term_overlap_score(&r.text, t)))
228 });
229
230 let ordered_ids = match (vector_ranked, text_ranked) {
231 (Some(v), Some(t)) => fuse_rrf(&v, &t),
232 (Some(v), None) => v,
233 (None, Some(t)) => t,
234 (None, None) => return Ok(Vec::new()),
236 };
237
238 let by_id: HashMap<&str, &VectorRecord> =
239 records.iter().map(|r| (r.id.as_str(), r)).collect();
240 let matches = ordered_ids
241 .into_iter()
242 .take(query.top_k)
243 .filter_map(|(id, score)| {
244 by_id.get(id.as_str()).map(|r| VectorMatch {
245 id: r.id.clone(),
246 document_id: r.document_id.clone(),
247 score,
248 })
249 })
250 .collect();
251 Ok(matches)
252 }
253
254 async fn delete_by_document(&self, namespace: &str, document_id: &str) -> Result<()> {
255 let mut store = self
256 .namespaces
257 .lock()
258 .map_err(|_| anyhow::anyhow!("vector store poisoned"))?;
259 if let Some(entry) = store.get_mut(namespace) {
260 entry.retain(|r| r.document_id != document_id);
261 }
262 Ok(())
263 }
264
265 async fn delete_namespace(&self, namespace: &str) -> Result<()> {
266 let mut store = self
267 .namespaces
268 .lock()
269 .map_err(|_| anyhow::anyhow!("vector store poisoned"))?;
270 store.remove(namespace);
271 Ok(())
272 }
273}
274
275fn rank_by(records: &[VectorRecord], score: impl Fn(&VectorRecord) -> f32) -> Vec<(String, f32)> {
277 let mut scored: Vec<(String, f32)> = records
278 .iter()
279 .map(|r| (r.id.clone(), score(r)))
280 .filter(|(_, s)| *s > f32::NEG_INFINITY)
281 .collect();
282 scored.sort_by(|a, b| b.1.total_cmp(&a.1));
283 scored
284}
285
286fn fuse_rrf(a: &[(String, f32)], b: &[(String, f32)]) -> Vec<(String, f32)> {
289 let mut fused: HashMap<&str, f32> = HashMap::new();
290 for list in [a, b] {
291 for (rank, (id, _)) in list.iter().enumerate() {
292 *fused.entry(id.as_str()).or_insert(0.0) += 1.0 / (RRF_K + rank as f32 + 1.0);
293 }
294 }
295 let mut ranked: Vec<(String, f32)> = fused
296 .into_iter()
297 .map(|(id, s)| (id.to_string(), s))
298 .collect();
299 ranked.sort_by(|x, y| y.1.total_cmp(&x.1));
300 ranked
301}
302
303fn cosine_similarity(a: &[f32], b: &[f32]) -> f32 {
306 if a.len() != b.len() || a.is_empty() {
307 return f32::NEG_INFINITY;
308 }
309 let mut dot = 0.0;
310 let mut norm_a = 0.0;
311 let mut norm_b = 0.0;
312 for (x, y) in a.iter().zip(b.iter()) {
313 dot += x * y;
314 norm_a += x * x;
315 norm_b += y * y;
316 }
317 if norm_a == 0.0 || norm_b == 0.0 {
318 return f32::NEG_INFINITY;
319 }
320 dot / (norm_a.sqrt() * norm_b.sqrt())
321}
322
323fn term_overlap_score(text: &str, query: &str) -> f32 {
326 let haystack = text.to_lowercase();
327 let terms: Vec<String> = query
328 .to_lowercase()
329 .split_whitespace()
330 .map(str::to_string)
331 .collect::<std::collections::BTreeSet<_>>()
332 .into_iter()
333 .collect();
334 if terms.is_empty() {
335 return f32::NEG_INFINITY;
336 }
337 let hits = terms.iter().filter(|t| haystack.contains(*t)).count();
338 if hits == 0 {
339 f32::NEG_INFINITY
340 } else {
341 hits as f32 / terms.len() as f32
342 }
343}
344
345#[cfg(test)]
346mod tests {
347 use super::*;
348
349 #[tokio::test]
350 async fn poisoned_store_returns_errors_without_panicking() {
351 let store = InMemoryVectorStore::new();
352 let poisoned = std::panic::catch_unwind(|| {
353 let _guard = store.namespaces.lock().unwrap();
354 panic!("poison reference store");
355 });
356 assert!(poisoned.is_err());
357
358 let errors = [
359 store.upsert("org_1__index", Vec::new()).await.unwrap_err(),
360 store
361 .query(
362 "org_1__index",
363 VectorQuery {
364 top_k: 1,
365 ..Default::default()
366 },
367 )
368 .await
369 .unwrap_err(),
370 store
371 .delete_by_document("org_1__index", "document")
372 .await
373 .unwrap_err(),
374 store.delete_namespace("org_1__index").await.unwrap_err(),
375 ];
376 for error in errors {
377 assert_eq!(error.to_string(), "vector store poisoned");
378 }
379 }
380
381 fn record(id: &str, doc: &str, vector: Vec<f32>, text: &str) -> VectorRecord {
382 VectorRecord {
383 id: id.to_string(),
384 vector,
385 text: text.to_string(),
386 document_id: doc.to_string(),
387 }
388 }
389
390 #[test]
391 fn namespace_is_org_prefixed() {
392 assert_eq!(
393 index_namespace(1, "kidx_00000000000000000000000000000001"),
394 "org_1__kidx_00000000000000000000000000000001"
395 );
396 }
397
398 #[tokio::test]
399 async fn vector_query_ranks_by_cosine() {
400 let store = InMemoryVectorStore::new();
401 let ns = index_namespace(1, "kidx_00000000000000000000000000000001");
402 store
403 .upsert(
404 &ns,
405 vec![
406 record("kchk_a", "kidoc_1", vec![1.0, 0.0], "alpha"),
407 record("kchk_b", "kidoc_1", vec![0.0, 1.0], "beta"),
408 record("kchk_c", "kidoc_2", vec![0.9, 0.1], "gamma"),
409 ],
410 )
411 .await
412 .unwrap();
413
414 let matches = store
415 .query(
416 &ns,
417 VectorQuery {
418 vector: Some(vec![1.0, 0.0]),
419 text: None,
420 top_k: 2,
421 },
422 )
423 .await
424 .unwrap();
425
426 let ids: Vec<_> = matches.iter().map(|m| m.id.as_str()).collect();
427 assert_eq!(ids, vec!["kchk_a", "kchk_c"]);
428 assert_eq!(matches[0].document_id, "kidoc_1");
429 }
430
431 #[tokio::test]
432 async fn upsert_replaces_existing_id() {
433 let store = InMemoryVectorStore::new();
434 let ns = "org_1__kidx_x";
435 store
436 .upsert(ns, vec![record("kchk_a", "kidoc_1", vec![1.0, 0.0], "old")])
437 .await
438 .unwrap();
439 store
440 .upsert(ns, vec![record("kchk_a", "kidoc_1", vec![0.0, 1.0], "new")])
441 .await
442 .unwrap();
443
444 let matches = store
445 .query(
446 ns,
447 VectorQuery {
448 vector: Some(vec![0.0, 1.0]),
449 text: None,
450 top_k: 5,
451 },
452 )
453 .await
454 .unwrap();
455 assert_eq!(matches.len(), 1);
456 assert!(matches[0].score > 0.99);
457 }
458
459 #[tokio::test]
460 async fn text_query_ranks_by_term_overlap() {
461 let store = InMemoryVectorStore::new();
462 let ns = "org_1__kidx_x";
463 store
464 .upsert(
465 ns,
466 vec![
467 record("kchk_a", "kidoc_1", vec![0.0], "the quick brown fox"),
468 record("kchk_b", "kidoc_1", vec![0.0], "a slow green turtle"),
469 ],
470 )
471 .await
472 .unwrap();
473
474 let matches = store
475 .query(
476 ns,
477 VectorQuery {
478 vector: None,
479 text: Some("quick fox".to_string()),
480 top_k: 5,
481 },
482 )
483 .await
484 .unwrap();
485 assert_eq!(matches.len(), 1);
486 assert_eq!(matches[0].id, "kchk_a");
487 }
488
489 #[tokio::test]
490 async fn delete_by_document_and_namespace() {
491 let store = InMemoryVectorStore::new();
492 let ns = "org_1__kidx_x";
493 store
494 .upsert(
495 ns,
496 vec![
497 record("kchk_a", "kidoc_1", vec![1.0], "a"),
498 record("kchk_b", "kidoc_2", vec![1.0], "b"),
499 ],
500 )
501 .await
502 .unwrap();
503
504 store.delete_by_document(ns, "kidoc_1").await.unwrap();
505 let after = store
506 .query(
507 ns,
508 VectorQuery {
509 vector: Some(vec![1.0]),
510 text: None,
511 top_k: 5,
512 },
513 )
514 .await
515 .unwrap();
516 assert_eq!(after.len(), 1);
517 assert_eq!(after[0].id, "kchk_b");
518
519 store.delete_namespace(ns).await.unwrap();
520 let empty = store
521 .query(
522 ns,
523 VectorQuery {
524 vector: Some(vec![1.0]),
525 text: None,
526 top_k: 5,
527 },
528 )
529 .await
530 .unwrap();
531 assert!(empty.is_empty());
532 }
533
534 #[tokio::test]
535 async fn hybrid_query_fuses_both_signals() {
536 let store = InMemoryVectorStore::new();
537 let ns = "org_1__kidx_x";
538 store
539 .upsert(
540 ns,
541 vec![
542 record(
543 "kchk_a",
544 "kidoc_1",
545 vec![1.0, 0.0],
546 "database indexing guide",
547 ),
548 record("kchk_b", "kidoc_1", vec![0.0, 1.0], "cooking recipes"),
549 ],
550 )
551 .await
552 .unwrap();
553
554 let matches = store
555 .query(
556 ns,
557 VectorQuery {
558 vector: Some(vec![1.0, 0.0]),
559 text: Some("database".to_string()),
560 top_k: 2,
561 },
562 )
563 .await
564 .unwrap();
565 assert_eq!(matches[0].id, "kchk_a");
566 }
567}