Skip to main content

graphrt_rag/
http.rs

1//! HTTP-backed components: OpenAI-compatible embeddings, a generic retriever
2//! endpoint and Cohere/Jina/Voyage-compatible rerankers.
3
4use 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
13/// Maximum bytes read from a response body.
14const MAX_BODY_BYTES: usize = 32 * 1024 * 1024;
15/// Maximum bytes of an error body included in messages.
16const MAX_ERROR_BYTES: usize = 2 * 1024;
17
18/// A string that never appears in `Debug` output.
19#[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/// Shared HTTP settings.
44#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
45pub struct HttpSettings {
46    /// Bearer token (sent as `Authorization: Bearer ...`) unless `api_key_header` is set.
47    #[serde(default)]
48    pub api_key: Secret,
49    /// Send the key in this header instead (e.g. `api-key` for Azure).
50    #[serde(default)]
51    pub api_key_header: Option<String>,
52    /// Extra headers.
53    #[serde(default)]
54    pub headers: indexmap::IndexMap<String, String>,
55    /// Whole-request timeout in milliseconds (default 60 000).
56    #[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
75/// Build a reqwest client using rustls with the ring crypto provider.
76pub(crate) fn build_client(settings: &HttpSettings) -> Result<reqwest::Client, RagError> {
77    // reqwest is built without a bundled crypto provider; install ring once per process.
78    // An error only means a provider is already installed, which is fine.
79    let _already_installed = rustls::crypto::ring::default_provider().install_default();
80    reqwest::Client::builder()
81        // Credentials may travel in custom headers (`api-key`, `headers`), which
82        // reqwest does not strip on cross-host redirects; never follow redirects.
83        .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
103/// Send a JSON POST and decode a JSON response, mapping failures to [`RagError`].
104async 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// ---------------------------------------------------------------------------
151// Embeddings
152// ---------------------------------------------------------------------------
153
154/// Configuration of an OpenAI-compatible `/embeddings` endpoint.
155#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
156pub struct OpenAiEmbedderConfig {
157    /// API root, e.g. `https://api.openai.com/v1` or `http://localhost:11434/v1`.
158    #[serde(default = "default_openai_base")]
159    pub base_url: String,
160    pub model: String,
161    /// Requested output dimensions (models that support it).
162    #[serde(default)]
163    pub dimensions: Option<usize>,
164    /// Texts per request (default 64).
165    #[serde(default = "default_batch")]
166    pub batch_size: usize,
167    /// Prefix added to queries (e.g. `search_query: ` for nomic models).
168    #[serde(default)]
169    pub query_prefix: String,
170    /// Prefix added to documents (e.g. `search_document: `).
171    #[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/// Embedder for any OpenAI-compatible embeddings API (OpenAI, Azure, Ollama, vLLM, Jina, ...).
204#[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// ---------------------------------------------------------------------------
276// Generic retriever endpoint
277// ---------------------------------------------------------------------------
278
279/// Configuration of a remote retrieval endpoint.
280///
281/// Contract — request (`POST <url>`, JSON):
282/// ```json
283/// {"query": "...", "top_k": 4, "datasets": ["kb1"], "score_threshold": 0.5,
284///  "filter": {"logical_operator": "and", "conditions": [...]}, "rerank": false}
285/// ```
286/// Response:
287/// ```json
288/// {"records": [{"content": "...", "score": 0.83, "title": "...",
289///               "id": "...", "document_id": "...", "dataset_id": "...", "metadata": {}}]}
290/// ```
291/// Only `content` and `score` are required per record.
292#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
293pub struct HttpRetrieverConfig {
294    pub url: String,
295    #[serde(default, flatten)]
296    pub http: HttpSettings,
297}
298
299/// A [`Retriever`] that delegates to a remote RAG service.
300#[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// ---------------------------------------------------------------------------
370// Reranker
371// ---------------------------------------------------------------------------
372
373/// Configuration of a `/rerank` endpoint (Cohere, Jina, Voyage, vLLM, TEI...).
374#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
375pub struct HttpRerankerConfig {
376    /// API root, e.g. `https://api.cohere.com/v2` or `https://api.jina.ai/v1`.
377    pub base_url: String,
378    pub model: String,
379    #[serde(default, flatten)]
380    pub http: HttpSettings,
381}
382
383/// Reranker for Cohere/Jina/Voyage-compatible APIs.
384#[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            // `top_n` asks for every document; a partial answer means the response
429            // is not what this client understands.
430            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}