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/// One document of a dataset, as listed by [`VectorStore::list_documents`].
63#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
64pub struct DocumentSummary {
65    pub document_id: String,
66    #[serde(default)]
67    pub title: String,
68    /// Number of stored chunks.
69    pub chunks: usize,
70    /// Total characters across the chunks.
71    pub characters: usize,
72    /// `false` when the document is disabled (kept, but skipped by searches).
73    pub enabled: bool,
74    /// Document-level metadata (the per-chunk `chunk_index` and `heading` keys are left out).
75    #[serde(default)]
76    pub metadata: Metadata,
77}
78
79/// Reserved chunk metadata key marking a disabled document: its chunks stay
80/// stored but every search skips them.
81pub const DISABLED_KEY: &str = "_disabled";
82
83/// Whether chunk metadata marks its document as disabled.
84pub fn is_disabled(metadata: &Metadata) -> bool {
85    metadata.get(DISABLED_KEY).and_then(serde_json::Value::as_bool).unwrap_or(false)
86}
87
88/// Chunk metadata key holding a child chunk's parent index (parent-child chunking).
89pub const PARENT_KEY: &str = "parent_index";
90
91/// Chunk metadata keys managed per chunk by graphrt, not part of a document's metadata.
92pub(crate) const PER_CHUNK_KEYS: [&str; 4] = ["chunk_index", "heading", DISABLED_KEY, PARENT_KEY];
93
94/// Default and largest page size for document listings.
95pub const DEFAULT_DOCUMENT_PAGE: usize = 50;
96pub const MAX_DOCUMENT_PAGE: usize = 500;
97
98/// Vector similarity query.
99#[derive(Clone, Debug)]
100pub struct VectorQuery<'a> {
101    pub datasets: &'a [String],
102    pub vector: &'a [f32],
103    pub top_k: usize,
104    pub filter: Option<&'a MetadataFilter>,
105}
106
107/// Keyword (BM25) query.
108#[derive(Clone, Debug)]
109pub struct KeywordQuery<'a> {
110    pub datasets: &'a [String],
111    pub text: &'a str,
112    pub top_k: usize,
113    pub filter: Option<&'a MetadataFilter>,
114}
115
116/// Turns text into embedding vectors.
117pub trait Embedder: Send + Sync + fmt::Debug {
118    /// Model identifier (used to detect mixing incompatible embeddings).
119    fn model(&self) -> &str;
120
121    /// Vector dimensionality, when known up front.
122    fn dimensions(&self) -> Option<usize> {
123        None
124    }
125
126    /// Embed documents for indexing. Returns one vector per input, in order.
127    fn embed_documents<'a>(&'a self, texts: &'a [String]) -> BoxFuture<'a, Result<Vec<Vec<f32>>, RagError>>;
128
129    /// Embed a search query. Defaults to [`Embedder::embed_documents`] on one text;
130    /// override for models that need a query-specific prefix or endpoint.
131    fn embed_query<'a>(&'a self, text: &'a str) -> BoxFuture<'a, Result<Vec<f32>, RagError>> {
132        Box::pin(async move {
133            let texts = [text.to_owned()];
134            let mut vectors = self.embed_documents(&texts).await?;
135            vectors.pop().ok_or_else(|| RagError::Decode("embedder returned no vector".into()))
136        })
137    }
138}
139
140/// Stores chunks with vectors and answers similarity queries.
141pub trait VectorStore: Send + Sync + fmt::Debug {
142    /// Insert or replace chunks (by `id`).
143    fn upsert(&self, chunks: Vec<StoredChunk>) -> BoxFuture<'_, Result<(), RagError>>;
144
145    /// Remove every chunk of a document. Returns the number removed when known.
146    fn delete_document<'a>(
147        &'a self,
148        dataset_id: &'a str,
149        document_id: &'a str,
150    ) -> BoxFuture<'a, Result<usize, RagError>>;
151
152    /// Remove every chunk of a dataset.
153    fn delete_dataset<'a>(&'a self, dataset_id: &'a str) -> BoxFuture<'a, Result<usize, RagError>>;
154
155    /// Every chunk of one document, vectors included. The ingestor uses this to
156    /// re-ingest a document without re-embedding unchanged chunks and to find the
157    /// chunks a new version no longer contains.
158    fn document_chunks<'a>(
159        &'a self,
160        dataset_id: &'a str,
161        document_id: &'a str,
162    ) -> BoxFuture<'a, Result<Vec<StoredChunk>, RagError>>;
163
164    /// Remove chunks by id. Returns the number removed when known.
165    fn delete_chunks<'a>(&'a self, dataset_id: &'a str, ids: &'a [String]) -> BoxFuture<'a, Result<usize, RagError>>;
166
167    /// Up to `limit` documents of a dataset ordered by document id, starting after
168    /// `after` (a document id from the previous page). Stores that cannot list
169    /// return [`RagError::Unsupported`].
170    fn list_documents<'a>(
171        &'a self,
172        dataset_id: &'a str,
173        limit: usize,
174        after: Option<&'a str>,
175    ) -> BoxFuture<'a, Result<Vec<DocumentSummary>, RagError>> {
176        let _ = (dataset_id, limit, after);
177        Box::pin(futures::future::ready(Err(RagError::Unsupported("this store cannot list documents".into()))))
178    }
179
180    /// Nearest neighbours by cosine similarity, best first.
181    fn search<'a>(&'a self, query: VectorQuery<'a>) -> BoxFuture<'a, Result<Vec<Hit>, RagError>>;
182
183    /// Whether [`VectorStore::keyword_search`] is implemented.
184    fn supports_keyword(&self) -> bool {
185        false
186    }
187
188    /// Keyword (BM25) search, best first. Stores without a keyword index return nothing.
189    fn keyword_search<'a>(&'a self, query: KeywordQuery<'a>) -> BoxFuture<'a, Result<Vec<Hit>, RagError>> {
190        let _ = query;
191        Box::pin(futures::future::ready(Ok(Vec::new())))
192    }
193
194    /// Whether a chunk with this content hash already exists in the dataset.
195    /// Stores that cannot answer cheaply return `false`. The built-in [`crate::Ingestor`]
196    /// does not use this (it de-duplicates per document via [`VectorStore::document_chunks`]).
197    fn contains_hash<'a>(
198        &'a self,
199        dataset_id: &'a str,
200        content_hash: &'a str,
201    ) -> BoxFuture<'a, Result<bool, RagError>> {
202        let _ = (dataset_id, content_hash);
203        Box::pin(futures::future::ready(Ok(false)))
204    }
205}
206
207/// Re-scores documents against a query (cross-encoder style).
208pub trait Reranker: Send + Sync + fmt::Debug {
209    /// Return one relevance score per document, in input order.
210    fn rerank<'a>(&'a self, query: &'a str, documents: &'a [String]) -> BoxFuture<'a, Result<Vec<f32>, RagError>>;
211}
212
213/// How vector and keyword scores are blended.
214#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
215pub struct HybridWeights {
216    pub vector: f32,
217    pub keyword: f32,
218}
219
220impl Default for HybridWeights {
221    fn default() -> Self {
222        Self { vector: 1.0, keyword: 0.0 }
223    }
224}
225
226/// A high-level retrieval request.
227#[derive(Clone, Debug, PartialEq)]
228pub struct RetrievalRequest {
229    pub query: String,
230    pub datasets: Vec<String>,
231    pub top_k: usize,
232    /// Hits scoring below this are dropped (after reranking, when enabled).
233    pub score_threshold: Option<f32>,
234    pub filter: Option<MetadataFilter>,
235    pub weights: HybridWeights,
236    /// Apply the dataset's reranker, when one is configured.
237    pub rerank: bool,
238}
239
240impl RetrievalRequest {
241    pub fn new(query: impl Into<String>, datasets: Vec<String>) -> Self {
242        Self {
243            query: query.into(),
244            datasets,
245            top_k: 4,
246            score_threshold: None,
247            filter: None,
248            weights: HybridWeights::default(),
249            rerank: false,
250        }
251    }
252
253    pub fn top_k(mut self, top_k: usize) -> Self {
254        self.top_k = top_k;
255        self
256    }
257
258    pub fn threshold(mut self, threshold: Option<f32>) -> Self {
259        self.score_threshold = threshold;
260        self
261    }
262
263    pub fn filter(mut self, filter: Option<MetadataFilter>) -> Self {
264        self.filter = filter;
265        self
266    }
267
268    pub fn weights(mut self, weights: HybridWeights) -> Self {
269        self.weights = weights;
270        self
271    }
272
273    pub fn rerank(mut self, rerank: bool) -> Self {
274        self.rerank = rerank;
275        self
276    }
277}
278
279/// End-to-end retrieval: query in, ranked hits out. Implement this to plug an
280/// external RAG service in place of the built-in store pipeline.
281pub trait Retriever: Send + Sync + fmt::Debug {
282    fn retrieve<'a>(&'a self, request: &'a RetrievalRequest) -> BoxFuture<'a, Result<Vec<Hit>, RagError>>;
283}
284
285/// Turns raw document bytes into text for ingestion (PDF, DOCX, ... extractors plug in here).
286pub trait Extractor: Send + Sync + fmt::Debug {
287    fn extract(&self, bytes: &[u8], mime_type: Option<&str>, file_name: &str) -> Result<String, RagError>;
288}
289
290/// Extractor for UTF-8 text formats (plain text, Markdown, JSON, CSV, HTML as-is).
291#[derive(Clone, Copy, Debug, Default)]
292pub struct PlainTextExtractor;
293
294impl Extractor for PlainTextExtractor {
295    fn extract(&self, bytes: &[u8], mime_type: Option<&str>, file_name: &str) -> Result<String, RagError> {
296        let textual = mime_type.is_none_or(|m| {
297            m.starts_with("text/")
298                || m.contains("json")
299                || m.contains("xml")
300                || m.contains("markdown")
301                || m.contains("csv")
302        });
303        if !textual {
304            return Err(RagError::Input(format!(
305                "`{file_name}` ({}) is not a text format; register a document extractor",
306                mime_type.unwrap_or("unknown")
307            )));
308        }
309        String::from_utf8(bytes.to_vec()).map_err(|_| RagError::Input(format!("`{file_name}` is not valid UTF-8")))
310    }
311}
312
313/// Check that a vector can be stored or searched: non-empty and finite.
314pub fn check_vector(vector: &[f32], what: &str) -> Result<(), RagError> {
315    if vector.is_empty() {
316        return Err(RagError::Input(format!("{what} has an empty embedding vector")));
317    }
318    if vector.iter().any(|x| !x.is_finite()) {
319        return Err(RagError::Input(format!("{what} has a non-finite (NaN or infinite) embedding value")));
320    }
321    Ok(())
322}
323
324/// Stable 64-bit FNV-1a hash rendered as hex.
325pub fn content_hash(dataset_id: &str, text: &str) -> String {
326    let mut h: u64 = 0xcbf2_9ce4_8422_2325;
327    for b in dataset_id.bytes().chain(std::iter::once(0)).chain(text.bytes()) {
328        h ^= u64::from(b);
329        h = h.wrapping_mul(0x0100_0000_01b3);
330    }
331    format!("{h:016x}")
332}