Skip to main content

graphrt_rag/
types.rs

1//! Core retrieval types and the pluggable traits.
2
3use std::fmt;
4
5use futures::future::BoxFuture;
6use serde::{Deserialize, Serialize};
7
8use crate::error::RagError;
9use crate::filter::MetadataFilter;
10
11/// Free-form chunk / document metadata.
12pub type Metadata = serde_json::Map<String, serde_json::Value>;
13
14/// A chunk as stored in a [`VectorStore`].
15#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
16pub struct StoredChunk {
17    /// Unique id within the store.
18    pub id: String,
19    pub dataset_id: String,
20    pub document_id: String,
21    #[serde(default)]
22    pub title: String,
23    pub text: String,
24    #[serde(default)]
25    pub metadata: Metadata,
26    /// Stable hash of `dataset_id` + `text`, used for de-duplication.
27    #[serde(default)]
28    pub content_hash: String,
29    pub vector: Vec<f32>,
30}
31
32/// One retrieved chunk with its relevance score (higher is better).
33#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
34pub struct Hit {
35    pub id: String,
36    pub dataset_id: String,
37    #[serde(default)]
38    pub document_id: String,
39    #[serde(default)]
40    pub title: String,
41    pub content: String,
42    pub score: f32,
43    #[serde(default)]
44    pub metadata: Metadata,
45}
46
47impl Hit {
48    /// Build a hit from a stored chunk.
49    pub fn from_chunk(chunk: &StoredChunk, score: f32) -> Self {
50        Self {
51            id: chunk.id.clone(),
52            dataset_id: chunk.dataset_id.clone(),
53            document_id: chunk.document_id.clone(),
54            title: chunk.title.clone(),
55            content: chunk.text.clone(),
56            score,
57            metadata: chunk.metadata.clone(),
58        }
59    }
60}
61
62/// Vector similarity query.
63#[derive(Clone, Debug)]
64pub struct VectorQuery<'a> {
65    pub datasets: &'a [String],
66    pub vector: &'a [f32],
67    pub top_k: usize,
68    pub filter: Option<&'a MetadataFilter>,
69}
70
71/// Keyword (BM25) query.
72#[derive(Clone, Debug)]
73pub struct KeywordQuery<'a> {
74    pub datasets: &'a [String],
75    pub text: &'a str,
76    pub top_k: usize,
77    pub filter: Option<&'a MetadataFilter>,
78}
79
80/// Turns text into embedding vectors.
81pub trait Embedder: Send + Sync + fmt::Debug {
82    /// Model identifier (used to detect mixing incompatible embeddings).
83    fn model(&self) -> &str;
84
85    /// Vector dimensionality, when known up front.
86    fn dimensions(&self) -> Option<usize> {
87        None
88    }
89
90    /// Embed documents for indexing. Returns one vector per input, in order.
91    fn embed_documents<'a>(&'a self, texts: &'a [String]) -> BoxFuture<'a, Result<Vec<Vec<f32>>, RagError>>;
92
93    /// Embed a search query. Defaults to [`Embedder::embed_documents`] on one text;
94    /// override for models that need a query-specific prefix or endpoint.
95    fn embed_query<'a>(&'a self, text: &'a str) -> BoxFuture<'a, Result<Vec<f32>, RagError>> {
96        Box::pin(async move {
97            let texts = [text.to_owned()];
98            let mut vectors = self.embed_documents(&texts).await?;
99            vectors.pop().ok_or_else(|| RagError::Decode("embedder returned no vector".into()))
100        })
101    }
102}
103
104/// Stores chunks with vectors and answers similarity queries.
105pub trait VectorStore: Send + Sync + fmt::Debug {
106    /// Insert or replace chunks (by `id`).
107    fn upsert(&self, chunks: Vec<StoredChunk>) -> BoxFuture<'_, Result<(), RagError>>;
108
109    /// Remove every chunk of a document. Returns the number removed when known.
110    fn delete_document<'a>(
111        &'a self,
112        dataset_id: &'a str,
113        document_id: &'a str,
114    ) -> BoxFuture<'a, Result<usize, RagError>>;
115
116    /// Remove every chunk of a dataset.
117    fn delete_dataset<'a>(&'a self, dataset_id: &'a str) -> BoxFuture<'a, Result<usize, RagError>>;
118
119    /// Every chunk of one document, vectors included. The ingestor uses this to
120    /// re-ingest a document without re-embedding unchanged chunks and to find the
121    /// chunks a new version no longer contains.
122    fn document_chunks<'a>(
123        &'a self,
124        dataset_id: &'a str,
125        document_id: &'a str,
126    ) -> BoxFuture<'a, Result<Vec<StoredChunk>, RagError>>;
127
128    /// Remove chunks by id. Returns the number removed when known.
129    fn delete_chunks<'a>(&'a self, dataset_id: &'a str, ids: &'a [String]) -> BoxFuture<'a, Result<usize, RagError>>;
130
131    /// Nearest neighbours by cosine similarity, best first.
132    fn search<'a>(&'a self, query: VectorQuery<'a>) -> BoxFuture<'a, Result<Vec<Hit>, RagError>>;
133
134    /// Whether [`VectorStore::keyword_search`] is implemented.
135    fn supports_keyword(&self) -> bool {
136        false
137    }
138
139    /// Keyword (BM25) search, best first. Stores without a keyword index return nothing.
140    fn keyword_search<'a>(&'a self, query: KeywordQuery<'a>) -> BoxFuture<'a, Result<Vec<Hit>, RagError>> {
141        let _ = query;
142        Box::pin(futures::future::ready(Ok(Vec::new())))
143    }
144
145    /// Whether a chunk with this content hash already exists in the dataset.
146    /// Stores that cannot answer cheaply return `false`. The built-in [`crate::Ingestor`]
147    /// does not use this (it de-duplicates per document via [`VectorStore::document_chunks`]).
148    fn contains_hash<'a>(
149        &'a self,
150        dataset_id: &'a str,
151        content_hash: &'a str,
152    ) -> BoxFuture<'a, Result<bool, RagError>> {
153        let _ = (dataset_id, content_hash);
154        Box::pin(futures::future::ready(Ok(false)))
155    }
156}
157
158/// Re-scores documents against a query (cross-encoder style).
159pub trait Reranker: Send + Sync + fmt::Debug {
160    /// Return one relevance score per document, in input order.
161    fn rerank<'a>(&'a self, query: &'a str, documents: &'a [String]) -> BoxFuture<'a, Result<Vec<f32>, RagError>>;
162}
163
164/// How vector and keyword scores are blended.
165#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
166pub struct HybridWeights {
167    pub vector: f32,
168    pub keyword: f32,
169}
170
171impl Default for HybridWeights {
172    fn default() -> Self {
173        Self { vector: 1.0, keyword: 0.0 }
174    }
175}
176
177/// A high-level retrieval request.
178#[derive(Clone, Debug, PartialEq)]
179pub struct RetrievalRequest {
180    pub query: String,
181    pub datasets: Vec<String>,
182    pub top_k: usize,
183    /// Hits scoring below this are dropped (after reranking, when enabled).
184    pub score_threshold: Option<f32>,
185    pub filter: Option<MetadataFilter>,
186    pub weights: HybridWeights,
187    /// Apply the dataset's reranker, when one is configured.
188    pub rerank: bool,
189}
190
191impl RetrievalRequest {
192    pub fn new(query: impl Into<String>, datasets: Vec<String>) -> Self {
193        Self {
194            query: query.into(),
195            datasets,
196            top_k: 4,
197            score_threshold: None,
198            filter: None,
199            weights: HybridWeights::default(),
200            rerank: false,
201        }
202    }
203
204    pub fn top_k(mut self, top_k: usize) -> Self {
205        self.top_k = top_k;
206        self
207    }
208
209    pub fn threshold(mut self, threshold: Option<f32>) -> Self {
210        self.score_threshold = threshold;
211        self
212    }
213
214    pub fn filter(mut self, filter: Option<MetadataFilter>) -> Self {
215        self.filter = filter;
216        self
217    }
218
219    pub fn weights(mut self, weights: HybridWeights) -> Self {
220        self.weights = weights;
221        self
222    }
223
224    pub fn rerank(mut self, rerank: bool) -> Self {
225        self.rerank = rerank;
226        self
227    }
228}
229
230/// End-to-end retrieval: query in, ranked hits out. Implement this to plug an
231/// external RAG service in place of the built-in store pipeline.
232pub trait Retriever: Send + Sync + fmt::Debug {
233    fn retrieve<'a>(&'a self, request: &'a RetrievalRequest) -> BoxFuture<'a, Result<Vec<Hit>, RagError>>;
234}
235
236/// Turns raw document bytes into text for ingestion (PDF, DOCX, ... extractors plug in here).
237pub trait Extractor: Send + Sync + fmt::Debug {
238    fn extract(&self, bytes: &[u8], mime_type: Option<&str>, file_name: &str) -> Result<String, RagError>;
239}
240
241/// Extractor for UTF-8 text formats (plain text, Markdown, JSON, CSV, HTML as-is).
242#[derive(Clone, Copy, Debug, Default)]
243pub struct PlainTextExtractor;
244
245impl Extractor for PlainTextExtractor {
246    fn extract(&self, bytes: &[u8], mime_type: Option<&str>, file_name: &str) -> Result<String, RagError> {
247        let textual = mime_type.is_none_or(|m| {
248            m.starts_with("text/")
249                || m.contains("json")
250                || m.contains("xml")
251                || m.contains("markdown")
252                || m.contains("csv")
253        });
254        if !textual {
255            return Err(RagError::Input(format!(
256                "`{file_name}` ({}) is not a text format; register a document extractor",
257                mime_type.unwrap_or("unknown")
258            )));
259        }
260        String::from_utf8(bytes.to_vec()).map_err(|_| RagError::Input(format!("`{file_name}` is not valid UTF-8")))
261    }
262}
263
264/// Check that a vector can be stored or searched: non-empty and finite.
265pub fn check_vector(vector: &[f32], what: &str) -> Result<(), RagError> {
266    if vector.is_empty() {
267        return Err(RagError::Input(format!("{what} has an empty embedding vector")));
268    }
269    if vector.iter().any(|x| !x.is_finite()) {
270        return Err(RagError::Input(format!("{what} has a non-finite (NaN or infinite) embedding value")));
271    }
272    Ok(())
273}
274
275/// Stable 64-bit FNV-1a hash rendered as hex.
276pub fn content_hash(dataset_id: &str, text: &str) -> String {
277    let mut h: u64 = 0xcbf2_9ce4_8422_2325;
278    for b in dataset_id.bytes().chain(std::iter::once(0)).chain(text.bytes()) {
279        h ^= u64::from(b);
280        h = h.wrapping_mul(0x0100_0000_01b3);
281    }
282    format!("{h:016x}")
283}