1use std::fmt;
5use std::time::Duration;
6
7use futures::future::BoxFuture;
8use serde::{Deserialize, Serialize};
9
10use crate::error::RagError;
11use crate::types::{Embedder, Hit, Metadata, Reranker, RetrievalRequest, Retriever};
12
13const MAX_BODY_BYTES: usize = 32 * 1024 * 1024;
15const MAX_ERROR_BYTES: usize = 2 * 1024;
17
18#[derive(Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
20#[serde(transparent)]
21pub struct Secret(String);
22
23impl Secret {
24 pub fn new(value: impl Into<String>) -> Self {
25 Self(value.into())
26 }
27
28 pub fn expose(&self) -> &str {
29 &self.0
30 }
31
32 pub fn is_empty(&self) -> bool {
33 self.0.is_empty()
34 }
35}
36
37impl fmt::Debug for Secret {
38 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
39 f.write_str(if self.0.is_empty() { "\"\"" } else { "\"***\"" })
40 }
41}
42
43#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
45pub struct HttpSettings {
46 #[serde(default)]
48 pub api_key: Secret,
49 #[serde(default)]
51 pub api_key_header: Option<String>,
52 #[serde(default)]
54 pub headers: indexmap::IndexMap<String, String>,
55 #[serde(default = "default_timeout")]
57 pub timeout_ms: u64,
58}
59
60fn default_timeout() -> u64 {
61 60_000
62}
63
64impl Default for HttpSettings {
65 fn default() -> Self {
66 Self {
67 api_key: Secret::default(),
68 api_key_header: None,
69 headers: indexmap::IndexMap::new(),
70 timeout_ms: default_timeout(),
71 }
72 }
73}
74
75pub(crate) fn build_client(settings: &HttpSettings) -> Result<reqwest::Client, RagError> {
77 let _already_installed = rustls::crypto::ring::default_provider().install_default();
80 reqwest::Client::builder()
81 .redirect(reqwest::redirect::Policy::none())
84 .connect_timeout(Duration::from_secs(10))
85 .timeout(Duration::from_millis(settings.timeout_ms.max(1)))
86 .build()
87 .map_err(|e| RagError::Config(format!("cannot build HTTP client: {}", e.without_url())))
88}
89
90fn apply_settings(mut req: reqwest::RequestBuilder, settings: &HttpSettings) -> reqwest::RequestBuilder {
91 if !settings.api_key.is_empty() {
92 req = match &settings.api_key_header {
93 Some(header) => req.header(header.as_str(), settings.api_key.expose()),
94 None => req.bearer_auth(settings.api_key.expose()),
95 };
96 }
97 for (k, v) in &settings.headers {
98 req = req.header(k.as_str(), v.as_str());
99 }
100 req
101}
102
103async fn post_json<T: serde::de::DeserializeOwned>(
105 client: &reqwest::Client,
106 url: &str,
107 settings: &HttpSettings,
108 body: &serde_json::Value,
109) -> Result<T, RagError> {
110 let response = apply_settings(client.post(url), settings)
111 .json(body)
112 .send()
113 .await
114 .map_err(|e| RagError::Network(e.without_url().to_string()))?;
115 let status = response.status().as_u16();
116 let retry_after_ms = response
117 .headers()
118 .get("retry-after")
119 .and_then(|v| v.to_str().ok())
120 .and_then(|v| v.trim().parse::<u64>().ok())
121 .map(|s| s.saturating_mul(1000));
122 let bytes = read_capped(response).await?;
123 if !(200..300).contains(&status) {
124 let snippet =
125 String::from_utf8_lossy(bytes.get(..bytes.len().min(MAX_ERROR_BYTES)).unwrap_or_default()).into_owned();
126 return Err(match status {
127 401 | 403 => RagError::Auth(format!("HTTP {status}: {snippet}")),
128 429 => RagError::RateLimit { message: snippet, retry_after_ms },
129 _ => RagError::Http { status, message: snippet },
130 });
131 }
132 serde_json::from_slice(&bytes).map_err(|e| RagError::Decode(e.to_string()))
133}
134
135async fn read_capped(mut response: reqwest::Response) -> Result<Vec<u8>, RagError> {
136 let mut out = Vec::new();
137 while let Some(chunk) = response.chunk().await.map_err(|e| RagError::Network(e.without_url().to_string()))? {
138 if out.len() + chunk.len() > MAX_BODY_BYTES {
139 return Err(RagError::Decode(format!("response exceeds {MAX_BODY_BYTES} bytes")));
140 }
141 out.extend_from_slice(&chunk);
142 }
143 Ok(out)
144}
145
146fn join_url(base: &str, path: &str) -> String {
147 format!("{}/{}", base.trim_end_matches('/'), path.trim_start_matches('/'))
148}
149
150#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
156pub struct OpenAiEmbedderConfig {
157 #[serde(default = "default_openai_base")]
159 pub base_url: String,
160 pub model: String,
161 #[serde(default)]
163 pub dimensions: Option<usize>,
164 #[serde(default = "default_batch")]
166 pub batch_size: usize,
167 #[serde(default)]
169 pub query_prefix: String,
170 #[serde(default)]
172 pub document_prefix: String,
173 #[serde(default, flatten)]
174 pub http: HttpSettings,
175}
176
177fn default_openai_base() -> String {
178 "https://api.openai.com/v1".to_owned()
179}
180fn default_batch() -> usize {
181 64
182}
183
184impl OpenAiEmbedderConfig {
185 pub fn new(base_url: impl Into<String>, model: impl Into<String>) -> Self {
186 Self {
187 base_url: base_url.into(),
188 model: model.into(),
189 dimensions: None,
190 batch_size: default_batch(),
191 query_prefix: String::new(),
192 document_prefix: String::new(),
193 http: HttpSettings::default(),
194 }
195 }
196
197 pub fn api_key(mut self, key: impl Into<String>) -> Self {
198 self.http.api_key = Secret::new(key);
199 self
200 }
201}
202
203#[derive(Clone, Debug)]
205pub struct OpenAiEmbedder {
206 config: OpenAiEmbedderConfig,
207 client: reqwest::Client,
208}
209
210#[derive(Deserialize)]
211struct EmbeddingResponse {
212 data: Vec<EmbeddingItem>,
213}
214
215#[derive(Deserialize)]
216struct EmbeddingItem {
217 #[serde(default)]
218 index: usize,
219 embedding: Vec<f32>,
220}
221
222impl OpenAiEmbedder {
223 pub fn new(config: OpenAiEmbedderConfig) -> Result<Self, RagError> {
224 if config.model.trim().is_empty() {
225 return Err(RagError::Config("embedding model is required".into()));
226 }
227 let client = build_client(&config.http)?;
228 Ok(Self { config, client })
229 }
230
231 async fn embed_batch(&self, texts: Vec<String>) -> Result<Vec<Vec<f32>>, RagError> {
232 let expected = texts.len();
233 let mut body = serde_json::json!({ "model": self.config.model, "input": texts, "encoding_format": "float" });
234 if let (Some(dims), Some(obj)) = (self.config.dimensions, body.as_object_mut()) {
235 obj.insert("dimensions".into(), serde_json::Value::from(dims));
236 }
237 let url = join_url(&self.config.base_url, "embeddings");
238 let mut response: EmbeddingResponse = post_json(&self.client, &url, &self.config.http, &body).await?;
239 if response.data.len() != expected {
240 return Err(RagError::Decode(format!("expected {expected} embeddings, got {}", response.data.len())));
241 }
242 response.data.sort_by_key(|item| item.index);
243 Ok(response.data.into_iter().map(|item| item.embedding).collect())
244 }
245}
246
247impl Embedder for OpenAiEmbedder {
248 fn model(&self) -> &str {
249 &self.config.model
250 }
251
252 fn dimensions(&self) -> Option<usize> {
253 self.config.dimensions
254 }
255
256 fn embed_documents<'a>(&'a self, texts: &'a [String]) -> BoxFuture<'a, Result<Vec<Vec<f32>>, RagError>> {
257 Box::pin(async move {
258 let mut out = Vec::with_capacity(texts.len());
259 for batch in texts.chunks(self.config.batch_size.max(1)) {
260 let prefixed = batch.iter().map(|t| format!("{}{t}", self.config.document_prefix)).collect();
261 out.extend(self.embed_batch(prefixed).await?);
262 }
263 Ok(out)
264 })
265 }
266
267 fn embed_query<'a>(&'a self, text: &'a str) -> BoxFuture<'a, Result<Vec<f32>, RagError>> {
268 Box::pin(async move {
269 let mut vectors = self.embed_batch(vec![format!("{}{text}", self.config.query_prefix)]).await?;
270 vectors.pop().ok_or_else(|| RagError::Decode("embedder returned no vector".into()))
271 })
272 }
273}
274
275#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
293pub struct HttpRetrieverConfig {
294 pub url: String,
295 #[serde(default, flatten)]
296 pub http: HttpSettings,
297}
298
299#[derive(Clone, Debug)]
301pub struct HttpRetriever {
302 config: HttpRetrieverConfig,
303 client: reqwest::Client,
304}
305
306#[derive(Deserialize)]
307struct RecordsResponse {
308 records: Vec<Record>,
309}
310
311#[derive(Deserialize)]
312struct Record {
313 content: String,
314 score: f32,
315 #[serde(default)]
316 title: String,
317 #[serde(default)]
318 id: Option<String>,
319 #[serde(default)]
320 document_id: String,
321 #[serde(default)]
322 dataset_id: Option<String>,
323 #[serde(default)]
324 metadata: Metadata,
325}
326
327impl HttpRetriever {
328 pub fn new(config: HttpRetrieverConfig) -> Result<Self, RagError> {
329 if config.url.trim().is_empty() {
330 return Err(RagError::Config("retriever url is required".into()));
331 }
332 let client = build_client(&config.http)?;
333 Ok(Self { config, client })
334 }
335}
336
337impl Retriever for HttpRetriever {
338 fn retrieve<'a>(&'a self, request: &'a RetrievalRequest) -> BoxFuture<'a, Result<Vec<Hit>, RagError>> {
339 Box::pin(async move {
340 let body = serde_json::json!({
341 "query": request.query,
342 "top_k": request.top_k,
343 "datasets": request.datasets,
344 "score_threshold": request.score_threshold,
345 "filter": request.filter,
346 "rerank": request.rerank,
347 });
348 let response: RecordsResponse = post_json(&self.client, &self.config.url, &self.config.http, &body).await?;
349 let default_dataset = request.datasets.first().cloned().unwrap_or_default();
350 let hits = response
351 .records
352 .into_iter()
353 .enumerate()
354 .map(|(i, r)| Hit {
355 id: r.id.unwrap_or_else(|| format!("{}#{i}", r.document_id)),
356 dataset_id: r.dataset_id.unwrap_or_else(|| default_dataset.clone()),
357 document_id: r.document_id,
358 title: r.title,
359 content: r.content,
360 score: r.score,
361 metadata: r.metadata,
362 })
363 .collect();
364 Ok(hits)
365 })
366 }
367}
368
369#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
375pub struct HttpRerankerConfig {
376 pub base_url: String,
378 pub model: String,
379 #[serde(default, flatten)]
380 pub http: HttpSettings,
381}
382
383#[derive(Clone, Debug)]
385pub struct HttpReranker {
386 config: HttpRerankerConfig,
387 client: reqwest::Client,
388}
389
390#[derive(Deserialize)]
391struct RerankResponse {
392 #[serde(alias = "data")]
393 results: Vec<RerankItem>,
394}
395
396#[derive(Deserialize)]
397struct RerankItem {
398 index: usize,
399 #[serde(alias = "score")]
400 relevance_score: f32,
401}
402
403impl HttpReranker {
404 pub fn new(config: HttpRerankerConfig) -> Result<Self, RagError> {
405 let client = build_client(&config.http)?;
406 Ok(Self { config, client })
407 }
408}
409
410impl Reranker for HttpReranker {
411 fn rerank<'a>(&'a self, query: &'a str, documents: &'a [String]) -> BoxFuture<'a, Result<Vec<f32>, RagError>> {
412 Box::pin(async move {
413 let body = serde_json::json!({
414 "model": self.config.model,
415 "query": query,
416 "documents": documents,
417 "top_n": documents.len(),
418 });
419 let url = join_url(&self.config.base_url, "rerank");
420 let response: RerankResponse = post_json(&self.client, &url, &self.config.http, &body).await?;
421 let mut scores: Vec<Option<f32>> = vec![None; documents.len()];
422 for item in response.results {
423 let slot = scores
424 .get_mut(item.index)
425 .ok_or_else(|| RagError::Decode(format!("reranker returned out-of-range index {}", item.index)))?;
426 *slot = Some(item.relevance_score);
427 }
428 let scored = scores.iter().filter(|s| s.is_some()).count();
431 if scored != documents.len() {
432 return Err(RagError::Decode(format!("reranker scored {scored} of {} documents", documents.len())));
433 }
434 Ok(scores.into_iter().map(|s| s.unwrap_or(f32::MIN)).collect())
435 })
436 }
437}
438
439#[cfg(test)]
440mod tests {
441 use super::*;
442
443 #[test]
444 fn secret_is_redacted() {
445 let cfg = OpenAiEmbedderConfig::new("http://x", "m").api_key("sk-very-secret");
446 assert!(!format!("{cfg:?}").contains("sk-very-secret"));
447 }
448
449 #[test]
450 fn url_join() {
451 assert_eq!(join_url("http://a/v1/", "/embeddings"), "http://a/v1/embeddings");
452 }
453}