1use std::fmt;
4
5use futures::future::BoxFuture;
6use serde::{Deserialize, Serialize};
7
8use crate::error::RagError;
9use crate::filter::MetadataFilter;
10
11pub type Metadata = serde_json::Map<String, serde_json::Value>;
13
14#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
16pub struct StoredChunk {
17 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 #[serde(default)]
28 pub content_hash: String,
29 pub vector: Vec<f32>,
30}
31
32#[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 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#[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#[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
80pub trait Embedder: Send + Sync + fmt::Debug {
82 fn model(&self) -> &str;
84
85 fn dimensions(&self) -> Option<usize> {
87 None
88 }
89
90 fn embed_documents<'a>(&'a self, texts: &'a [String]) -> BoxFuture<'a, Result<Vec<Vec<f32>>, RagError>>;
92
93 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
104pub trait VectorStore: Send + Sync + fmt::Debug {
106 fn upsert(&self, chunks: Vec<StoredChunk>) -> BoxFuture<'_, Result<(), RagError>>;
108
109 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 fn delete_dataset<'a>(&'a self, dataset_id: &'a str) -> BoxFuture<'a, Result<usize, RagError>>;
118
119 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 fn delete_chunks<'a>(&'a self, dataset_id: &'a str, ids: &'a [String]) -> BoxFuture<'a, Result<usize, RagError>>;
130
131 fn search<'a>(&'a self, query: VectorQuery<'a>) -> BoxFuture<'a, Result<Vec<Hit>, RagError>>;
133
134 fn supports_keyword(&self) -> bool {
136 false
137 }
138
139 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 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
158pub trait Reranker: Send + Sync + fmt::Debug {
160 fn rerank<'a>(&'a self, query: &'a str, documents: &'a [String]) -> BoxFuture<'a, Result<Vec<f32>, RagError>>;
162}
163
164#[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#[derive(Clone, Debug, PartialEq)]
179pub struct RetrievalRequest {
180 pub query: String,
181 pub datasets: Vec<String>,
182 pub top_k: usize,
183 pub score_threshold: Option<f32>,
185 pub filter: Option<MetadataFilter>,
186 pub weights: HybridWeights,
187 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
230pub trait Retriever: Send + Sync + fmt::Debug {
233 fn retrieve<'a>(&'a self, request: &'a RetrievalRequest) -> BoxFuture<'a, Result<Vec<Hit>, RagError>>;
234}
235
236pub 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#[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
264pub 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
275pub 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}