Skip to main content

everruns_contracts/
vector_store.rs

1//! Vendor-neutral vector store abstraction for Knowledge Indexes.
2//!
3//! See `knowledge/runtime-resources/knowledge-indexes.md`. Embedding vectors for Knowledge Index
4//! chunks live in an external vector database, not in Postgres. This module
5//! defines the platform-selected `VectorStore` trait (mirroring how
6//! `SessionFileSystemFactory` keeps the filesystem pluggable) plus an
7//! `InMemoryVectorStore` used by dev mode and storage-parity tests.
8//!
9//! The store is **multitenant and multi-index** by construction: one namespace
10//! per index, org-prefixed for isolation. Callers derive the namespace with
11//! [`index_namespace`] and must validate the index's `org_id` before issuing a
12//! call so cross-org reads are structurally impossible. The reference
13//! production backend (Turbopuffer) maps each namespace onto a Turbopuffer
14//! namespace.
15
16use std::collections::HashMap;
17use std::sync::{Arc, Mutex};
18
19use anyhow::Result;
20use async_trait::async_trait;
21use serde::{Deserialize, Serialize};
22
23/// Type-keyed wrapper installed on a host composition by
24/// hosted presets. Core carries the generic extension bag but does not name the
25/// Knowledge Index service.
26#[derive(Clone)]
27pub struct VectorStoreExt(pub Arc<dyn VectorStore>);
28
29/// Reciprocal-rank-fusion constant for hybrid (vector + text) queries.
30const RRF_K: f32 = 60.0;
31
32/// A single retrieved chunk returned by [`KnowledgeIndexSearch::search`], shaped
33/// to the `search_index` citation contract in `knowledge/runtime-resources/knowledge-indexes.md`. The
34/// `id` (`kchk_…`) + `source_uri` + `location` give the agent a stable, linkable
35/// citation. Kept compatible with the planned `search_knowledge` citation shape
36/// so the UI can render both uniformly.
37#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
38pub struct KnowledgeIndexCitation {
39    /// Chunk `public_id` (`kchk_…`). The stable citation id.
40    pub id: String,
41    /// Owning Knowledge Index `public_id` (`kidx_…`).
42    pub index_id: String,
43    /// Title of the source document, if known.
44    pub document_title: Option<String>,
45    /// Stable per-source locator (e.g. `github://owner/repo@main/docs/x.md`).
46    pub source_uri: String,
47    /// Provenance within the document (line / char / page ranges).
48    pub location: Option<serde_json::Value>,
49    /// A trimmed prefix of the chunk passage.
50    pub snippet: String,
51    /// Relevance score; higher is more relevant. Use for ordering only.
52    pub score: f32,
53}
54
55/// Usage from a single embedding call made while serving a retrieval query.
56///
57/// Retrieval embeds the query once per bound index (indexes may use different
58/// embedding models), so a search reports one entry per call. The caller meters
59/// these — the retrieval seam itself has no event emitter (EVE-894).
60#[derive(Debug, Clone, PartialEq)]
61pub struct EmbeddingCallUsage {
62    /// Provider-side embedding model id (e.g. `text-embedding-3-small`).
63    pub model: String,
64    /// Provider that served the call, when known.
65    pub provider: Option<String>,
66    /// Total tokens the provider billed for this call.
67    pub total_tokens: u32,
68    /// Provider-reported cost in USD, when the provider returns one.
69    pub actual_cost_usd: Option<f64>,
70}
71
72/// Citations plus the embedding usage incurred to produce them.
73///
74/// Usage is reported even when retrieval returns no citations: the embedding
75/// call was billed regardless of whether anything matched (EVE-894).
76#[derive(Debug, Clone, Default)]
77pub struct KnowledgeIndexSearchOutcome {
78    /// Matching chunks, ordered by score (descending).
79    pub citations: Vec<KnowledgeIndexCitation>,
80    /// One entry per embedding call made to serve this query.
81    pub embedding_usage: Vec<EmbeddingCallUsage>,
82}
83
84/// Server-implemented hybrid retrieval over an org's bound Knowledge Indexes.
85///
86/// Carried on `ToolContext` so the `search_index` agent tool can reach the
87/// server-side embedding + vector-store machinery without `everruns-core`
88/// depending on server types (mirrors `PlatformStore` / `UserConnectionResolver`).
89#[async_trait]
90pub trait KnowledgeIndexSearch: Send + Sync {
91    /// Embed `query`, run hybrid retrieval against each bound index's
92    /// vector-store namespace, and return up to `top_k` citations ordered by
93    /// score (descending).
94    ///
95    /// `index_ids` are the `kidx_` public ids bound in the capability config.
96    /// Ids that are missing, cross-org, archived, or deleted are silently
97    /// skipped — no existence leak.
98    ///
99    /// Returns the embedding usage alongside the citations so the caller can
100    /// meter query-time embedding spend (EVE-894).
101    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
110/// Derive the vector-store namespace for an index.
111///
112/// Org-prefixed so every query targets a single, org-derived namespace and
113/// cross-org reads cannot happen. `public_id` is the `kidx_…` index id.
114pub fn index_namespace(org_id: i64, public_id: &str) -> String {
115    format!("org_{org_id}__{public_id}")
116}
117
118/// A single point stored in the vector store, keyed by the chunk `public_id`
119/// (`kchk_…`), which is also the stable citation id.
120#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
121pub struct VectorRecord {
122    /// Chunk `public_id` (`kchk_…`). Stable citation id and primary key.
123    pub id: String,
124    /// Embedding for the chunk. Length must match the index's `vector_dim`.
125    pub vector: Vec<f32>,
126    /// Chunk passage text, stored to enable BM25 full-text scoring.
127    pub text: String,
128    /// Owning document `public_id` (`kidoc_…`), used for bulk delete on re-sync.
129    pub document_id: String,
130}
131
132/// A retrieval request against a single namespace. At least one of `vector`
133/// (semantic KNN) or `text` (BM25) must be set; when both are present the
134/// backend fuses them with reciprocal-rank fusion.
135#[derive(Debug, Clone, Default, Serialize, Deserialize)]
136pub struct VectorQuery {
137    /// Query embedding for semantic KNN.
138    pub vector: Option<Vec<f32>>,
139    /// Query text for full-text (BM25) scoring.
140    pub text: Option<String>,
141    /// Maximum number of matches to return.
142    pub top_k: usize,
143}
144
145/// A ranked match returned from [`VectorStore::query`].
146#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
147pub struct VectorMatch {
148    /// Chunk `public_id` (`kchk_…`) — hydrate text/citation from Postgres.
149    pub id: String,
150    /// Owning document `public_id` (`kidoc_…`).
151    pub document_id: String,
152    /// Higher is more relevant. Scale is backend-defined; use for ordering only.
153    pub score: f32,
154}
155
156/// Pluggable embedding store for Knowledge Indexes. Selected through
157/// `HostComposition`; the in-memory backend backs dev/tests, Turbopuffer is
158/// the reference production backend.
159#[async_trait]
160pub trait VectorStore: Send + Sync {
161    /// Insert or replace records in a namespace, keyed by `VectorRecord::id`.
162    async fn upsert(&self, namespace: &str, records: Vec<VectorRecord>) -> Result<()>;
163
164    /// Rank records in a namespace against the query. Returns up to
165    /// `query.top_k` matches, most relevant first.
166    async fn query(&self, namespace: &str, query: VectorQuery) -> Result<Vec<VectorMatch>>;
167
168    /// Remove every record belonging to a document (used on document re-sync).
169    async fn delete_by_document(&self, namespace: &str, document_id: &str) -> Result<()>;
170
171    /// Drop an entire namespace (used on index hard delete).
172    async fn delete_namespace(&self, namespace: &str) -> Result<()>;
173}
174
175/// In-memory brute-force `VectorStore` for dev mode and storage-parity tests.
176///
177/// Vector ranking uses cosine similarity; text ranking uses a simple
178/// term-overlap score standing in for BM25. Hybrid queries fuse the two ranked
179/// lists with reciprocal-rank fusion. Not for production scale.
180#[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            // No query signal: nothing to rank against.
235            (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
275/// Rank records by a scoring function, descending. Returns `(id, score)` pairs.
276fn 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
286/// Fuse two ranked lists with reciprocal-rank fusion, returning ids ordered by
287/// fused score (descending). The score carried out is the RRF score.
288fn 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
303/// Cosine similarity in [-1, 1]; mismatched dimensions or zero vectors score
304/// as the minimum so they sort last.
305fn 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
323/// Fraction of distinct query terms present in the text (case-insensitive).
324/// A lightweight stand-in for BM25 in the in-memory backend.
325fn 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}