Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! Embedding provider abstraction.
//!
//! Embedding implementations ship in M9:
//!
//! * [`OpenAiEmbedder`] — production: hits OpenAI's `/v1/embeddings`.
//! * [`VoyageEmbedder`] — production: hits Voyage's `/v1/embeddings`.
//! * [`GoogleEmbedder`](crate::google::GoogleEmbedder) — Gemini `embedContent`.
//! * [`SyntheticEmbedder`] — test-only: deterministic bag-of-words
//! embedding so integration tests can demonstrate semantic
//! retrieval without an API key.
//!
//! * [`LocalEmbedder`](crate::local::LocalEmbedder) — in-process
//! pure-Rust BERT (`all-MiniLM-L6-v2`), no key and no server; see
//! `docs/local-embeddings.md`.
use std::time::Duration;
use async_trait::async_trait;
use secrecy::{ExposeSecret, SecretString};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use tracing::debug;
use crate::error::{LlmError, LlmResult};
use crate::openai::normalize_openai_base;
use crate::response::{provider_error, response_json_limited, response_text_limited};
use crate::text::{truncate_for_embedding, truncate_with_ellipsis};
/// Conservative per-request input cap for OpenAI-compatible embedding APIs
/// (8192 token server limit; we stay well below with head truncation).
pub(crate) const OPENAI_EMBED_MAX_TOKENS: usize = 5000;
/// Provider-agnostic embedding API.
///
/// Implementations must be `Send + Sync` (the MCP server / hook
/// router stash an `Arc<dyn Embedder>` and use it from any tokio
/// task).
#[async_trait]
pub trait Embedder: Send + Sync {
/// Short identifier (e.g. `openai`, `voyage`, `synthetic`).
fn provider(&self) -> &'static str;
/// Model identifier (e.g. `text-embedding-3-small`). The exact string
/// sent on the wire — never suffixed or altered. See
/// [`Self::model_identity`] for the value that should be stored
/// alongside a vector or used to select eligible stored vectors.
fn model(&self) -> &str;
/// The `model` component of the stored/matched `(provider, model, dim)`
/// identity for a **document** embedding — distinct from [`Self::model`]
/// (the wire model name) whenever the effective document-side input
/// text is not what the model id alone implies. Defaults to
/// `self.model().to_string()`: providers with no such distinction (every
/// provider except the two below) are unaffected.
///
/// `OpenAiEmbedder`/`OpenAiCompatEmbedder` override this to fold in a
/// fingerprint of their configured `document_prefix` when it is
/// non-empty, so a page embedded under one document prefix is never
/// silently matched against, or mixed with, vectors embedded under a
/// different (or no) prefix — the same `(provider, model, dim)`
/// refuse-on-mismatch and stale-row machinery that already protects
/// against a plain model swap now also protects against a document
/// prefix change. An empty prefix reproduces `self.model()` exactly
/// (the pre-existing identity), so upgrading installs with no prefix
/// configured need no migration. The **query** prefix never affects
/// this: only the text actually embedded and stored needs a distinct
/// identity, and a query is never stored.
fn model_identity(&self) -> String {
self.model().to_string()
}
/// Vector dimensionality.
fn dim(&self) -> u32;
/// Embed one text. Returns a unit-normalised vector — callers can
/// dot-product directly to get cosine similarity.
async fn embed(&self, text: &str) -> LlmResult<Vec<f32>>;
/// Embed wiki page / document body (hybrid index writes).
async fn embed_document(&self, text: &str) -> LlmResult<Vec<f32>> {
self.embed(text).await
}
/// Embed a search query (hybrid retrieval).
async fn embed_query(&self, text: &str) -> LlmResult<Vec<f32>> {
self.embed(text).await
}
}
/// A search query embedded for the vector stream, with the stored-vector
/// identity it may be compared against.
#[derive(Debug, Clone)]
pub struct QueryVector {
/// The query embedding.
pub vector: Vec<f32>,
/// Provider of the eligible stored vectors.
pub provider: String,
/// Model identity of the eligible stored vectors. This is
/// [`Embedder::model_identity`], not [`Embedder::model`]: stored vectors
/// are keyed by the document identity, which a configured document
/// prefix folds in.
pub model: String,
/// Dimensionality of the eligible stored vectors.
pub dim: u32,
}
/// Embed `query` for hybrid retrieval, or `None` when the embedder fails.
///
/// The one place every search surface (`memory_query`, the web search) turns
/// a query into a vector, so they select the same stored vectors. A failure
/// degrades the search to FTS5 + entity + graph rather than failing it.
pub async fn embed_search_query(embedder: &dyn Embedder, query: &str) -> Option<QueryVector> {
// `embed_query`, not `embed`: an asymmetric embedder (configured
// query/document prefixes, or Google's RETRIEVAL_QUERY task type)
// must see this text on the query side, not the document side.
match embedder.embed_query(query).await {
Ok(vector) => Some(QueryVector {
vector,
provider: embedder.provider().to_string(),
model: embedder.model_identity(),
dim: embedder.dim(),
}),
Err(LlmError::CapacityBusy(_)) => {
debug!(
provider = embedder.provider(),
model = embedder.model(),
"embedding capacity stayed busy past the bounded query wait; \
degrading search to FTS5 + entity + graph"
);
None
}
Err(e) => {
tracing::warn!(
provider = embedder.provider(),
model = embedder.model(),
error = %e,
"embedder failed; degrading search to FTS5 + entity + graph"
);
None
}
}
}
/// OpenAI Embeddings API (`text-embedding-3-small` by default, 1536 dim).
pub struct OpenAiEmbedder {
client: reqwest::Client,
api_key: SecretString,
base_url: String,
model: String,
dim: u32,
query_prefix: String,
document_prefix: String,
}
impl OpenAiEmbedder {
/// Construct an embedder.
///
/// # Errors
/// Propagates any `reqwest::Error` thrown while building the HTTP
/// client.
pub fn new(api_key: SecretString, model: impl Into<String>, dim: u32) -> LlmResult<Self> {
// 120s tolerates a cold-load of the embedding model on Ollama
// (small model, but still up to ~30s on first request after
// unload). Subsequent requests with OLLAMA_KEEP_ALIVE warm are
// sub-second. When the embedder still fails, memory_query
// degrades gracefully to FTS5 + entity + graph (see server.rs).
let client = reqwest::Client::builder()
.redirect(crate::redirect::same_origin_redirects())
.timeout(Duration::from_secs(120))
.build()?;
Ok(Self {
client,
api_key,
base_url: "https://api.openai.com".into(),
model: model.into(),
dim,
query_prefix: String::new(),
document_prefix: String::new(),
})
}
/// Override the base URL (for tests against a wiremock).
#[must_use]
pub fn with_base_url(mut self, url: impl Into<String>) -> Self {
self.base_url = url.into();
self
}
/// Set the query/document prefixes prepended before embedding (see
/// [`OpenAiCompatEmbedder::with_prefixes`]). Empty strings are a no-op,
/// so this is safe to call unconditionally with the configured values.
#[must_use]
pub fn with_prefixes(
mut self,
query_prefix: impl Into<String>,
document_prefix: impl Into<String>,
) -> Self {
self.query_prefix = query_prefix.into();
self.document_prefix = document_prefix.into();
self
}
}
#[derive(Debug, Serialize)]
struct OpenAiEmbeddingRequest<'a> {
input: &'a str,
model: &'a str,
}
#[derive(Debug, Deserialize)]
struct OpenAiEmbeddingResponse {
data: Vec<OpenAiEmbeddingDatum>,
}
#[derive(Debug, Deserialize)]
struct OpenAiEmbeddingDatum {
embedding: Vec<f32>,
}
/// Parse OpenAI-compatible embedding responses, including OpenRouter error bodies.
pub(crate) fn parse_openai_embedding_values(body: &str, status: u16) -> LlmResult<Vec<f32>> {
let v: serde_json::Value = serde_json::from_str(body).map_err(|e| LlmError::Provider {
status,
body: truncate_with_ellipsis(&format!("openai embeddings json: {e}; body={body}"), 1024),
retry_after: None,
})?;
if let Some(err) = v.get("error") {
let msg = err
.get("message")
.and_then(|m| m.as_str())
.or_else(|| err.as_str())
.unwrap_or("unknown");
return Err(LlmError::Provider {
status,
body: truncate_with_ellipsis(msg, 1024),
retry_after: None,
});
}
if let Some(data) = v.get("data").and_then(|d| d.as_array()) {
let first = data.first().ok_or_else(|| LlmError::Provider {
status,
body: truncate_with_ellipsis(
&format!("openai embeddings data[] empty; body={body}"),
512,
),
retry_after: None,
})?;
let emb = first
.get("embedding")
.and_then(|e| e.as_array())
.ok_or_else(|| LlmError::Provider {
status,
body: truncate_with_ellipsis(
&format!("missing embedding array in data[0]; body={body}"),
512,
),
retry_after: None,
})?;
let mut out = Vec::with_capacity(emb.len());
for n in emb {
let f = n.as_f64().ok_or_else(|| LlmError::Provider {
status,
body: truncate_with_ellipsis(
&format!("non-numeric embedding value in data[0]; body={body}"),
512,
),
retry_after: None,
})?;
out.push(f as f32);
}
if !out.is_empty() {
return Ok(out);
}
}
// Strict OpenAI shape fallback.
let parsed: OpenAiEmbeddingResponse =
serde_json::from_value(v).map_err(|e| LlmError::Provider {
status,
body: truncate_with_ellipsis(
&format!("openai embeddings shape: {e}; body={body}"),
1024,
),
retry_after: None,
})?;
let first = parsed.data.into_iter().next().ok_or_else(|| {
LlmError::UnexpectedShape(format!(
"openai response had no data[0]; body={}",
truncate_with_ellipsis(body, 512)
))
})?;
Ok(first.embedding)
}
/// Retried statuses for every remote embedder's request: a rate limit and a
/// transient "out of capacity" answer. Everything else — other 4xx and
/// 5xx — is handled exactly as before: no retry.
fn is_retryable_embedding_status(status: u16) -> bool {
matches!(status, 429 | 503)
}
/// Cap for a single wait taken from `Retry-After`; larger values are
/// clamped so one bad header cannot stall a call for minutes.
const MAX_RETRY_AFTER_SECS: u64 = 32;
/// Total wait budget for one embedding call: the worst case of the
/// previous fixed backoff (2+4+8+16+32). When the next wait would push
/// the call past this, the loop gives up and returns the error of the
/// last status, so search (`embed_search_query`) and the inline
/// write-page embed never wait longer than a 429 storm already could.
const MAX_RETRY_WAIT_BUDGET: Duration = Duration::from_secs(62);
/// Decide the wait before the next attempt of a remote embedding request
/// (every HTTP embedder shares this policy), or give up.
///
/// Only 429 and 503 are retriable ([`is_retryable_embedding_status`]).
/// `attempt` is the 1-based index of the attempt being decided: up to
/// five new attempts are allowed, and attempt 6 is already past the
/// budget of retries. A whole-second `Retry-After` header (e.g.
/// `Retry-After: 5`) is honoured, clamped to [`MAX_RETRY_AFTER_SECS`];
/// a missing header, a non-whole-second value (the HTTP-date form is not
/// supported) or an unparseable one falls back to the historical
/// `2^attempt` seconds (2, 4, 8, 16, 32). `None` means the call should
/// stop and report the last status: a non-retriable status, more than
/// five new attempts, or `waited + delay` exceeding
/// [`MAX_RETRY_WAIT_BUDGET`].
pub(crate) fn retry_delay(
status: reqwest::StatusCode,
retry_after: Option<&reqwest::header::HeaderValue>,
attempt: u32,
waited: Duration,
) -> Option<Duration> {
if !is_retryable_embedding_status(status.as_u16()) || attempt > 5 {
return None;
}
let delay = match retry_after
.and_then(|h| h.to_str().ok())
.and_then(|s| s.parse::<u64>().ok())
{
Some(secs) => Duration::from_secs(secs.min(MAX_RETRY_AFTER_SECS)),
None => Duration::from_secs(2u64.saturating_pow(attempt)),
};
(waited + delay <= MAX_RETRY_WAIT_BUDGET).then_some(delay)
}
/// Shared OpenAI-shape embedding request: head-truncate, POST
/// `/embeddings` (bearer auth only when a key is present — local
/// engines such as Ollama and LM Studio run keyless), retry 429 and 503
/// honouring `Retry-After`, parse, dim-check, unit-normalise.
async fn openai_style_embed(
client: &reqwest::Client,
base_url: &str,
api_key: Option<&SecretString>,
model: &str,
dim: u32,
text: &str,
) -> LlmResult<Vec<f32>> {
let input = truncate_for_embedding(text, OPENAI_EMBED_MAX_TOKENS);
let url = normalize_openai_base(base_url, "embeddings");
debug!(
url,
model,
input_chars = input.len(),
"POST openai/embeddings"
);
let req = OpenAiEmbeddingRequest {
input: &input,
model,
};
let mut attempt = 0u32;
let mut waited = Duration::ZERO;
loop {
let mut builder = client.post(&url);
if let Some(key) = api_key {
builder = builder.bearer_auth(key.expose_secret());
}
let resp = builder.json(&req).send().await?;
let status = resp.status();
// Read the header while the response is still owned here: nothing
// below may consume the body before the wait is decided.
let retry_after = resp.headers().get(reqwest::header::RETRY_AFTER);
if let Some(delay) = retry_delay(status, retry_after, attempt + 1, waited) {
attempt += 1;
waited += delay;
debug!(
attempt,
?delay,
status = status.as_u16(),
"openai embeddings 429/503; retrying"
);
tokio::time::sleep(delay).await;
continue;
}
// Client errors (e.g. input > 8192 tokens) are not retried.
if status.as_u16() == 400 {
return Err(provider_error(resp).await);
}
if !status.is_success() {
return Err(provider_error(resp).await);
}
let body = response_text_limited(resp).await?;
let values = parse_openai_embedding_values(&body, status.as_u16())?;
if values.len() as u32 != dim {
return Err(LlmError::UnexpectedShape(format!(
"expected dim {}, got {}",
dim,
values.len()
)));
}
return Ok(normalise(values));
}
}
#[async_trait]
impl Embedder for OpenAiEmbedder {
fn provider(&self) -> &'static str {
"openai"
}
fn model(&self) -> &str {
&self.model
}
fn model_identity(&self) -> String {
document_prefix_identity(&self.model, &self.document_prefix)
}
fn dim(&self) -> u32 {
self.dim
}
async fn embed(&self, text: &str) -> LlmResult<Vec<f32>> {
openai_style_embed(
&self.client,
&self.base_url,
Some(&self.api_key),
&self.model,
self.dim,
text,
)
.await
}
async fn embed_document(&self, text: &str) -> LlmResult<Vec<f32>> {
let prefixed = prepend_prefix(&self.document_prefix, text);
openai_style_embed(
&self.client,
&self.base_url,
Some(&self.api_key),
&self.model,
self.dim,
&prefixed,
)
.await
}
async fn embed_query(&self, text: &str) -> LlmResult<Vec<f32>> {
let prefixed = prepend_prefix(&self.query_prefix, text);
openai_style_embed(
&self.client,
&self.base_url,
Some(&self.api_key),
&self.model,
self.dim,
&prefixed,
)
.await
}
}
/// OpenAI-compatible embeddings endpoint (Ollama / LM Studio / vLLM /
/// OpenRouter). Same wire shape as [`OpenAiEmbedder`], but the base
/// URL is required, the API key is optional (local engines run
/// keyless), and vectors are stored under the distinct provider label
/// `openai-compat` so the `{provider, model, dim}` refuse-on-mismatch
/// check treats them as their own family.
pub struct OpenAiCompatEmbedder {
client: reqwest::Client,
api_key: Option<SecretString>,
base_url: String,
model: String,
dim: u32,
/// Prepended to every query text before embedding (before truncation).
/// Empty by default: symmetric models (most OpenAI-compatible servers)
/// see no behaviour change. Asymmetric models need a query-side
/// instruction the OpenAI-compatible `/v1/embeddings` wire format has
/// no field for — the client has to prepend it instead.
/// `nvidia/Nemotron-3-Embed-1B-BF16` and base E5 models use a simple
/// `"query: "` / `"passage: "` pair; `e5-mistral-7b-instruct` and
/// Qwen3-Embedding instead need a full task-instruction string with
/// different exact spacing each (documents plain for both — see
/// `ai-memory-cli/src/config.rs`'s `embedding_query_prefix` field doc
/// comment for the two exact templates). See `with_prefixes`.
query_prefix: String,
/// Document-side counterpart of `query_prefix` (e.g. `"passage: "` for
/// Nemotron-3-Embed / base E5 — not every model needs one).
document_prefix: String,
}
impl OpenAiCompatEmbedder {
/// Construct a compat embedder against `base_url`.
///
/// # Errors
/// Propagates any `reqwest::Error` thrown while building the HTTP
/// client.
pub fn new(
base_url: impl Into<String>,
api_key: Option<SecretString>,
model: impl Into<String>,
dim: u32,
) -> LlmResult<Self> {
// Same cold-load tolerance as OpenAiEmbedder: first request
// after an Ollama model unload can take ~30s.
let client = reqwest::Client::builder()
.redirect(crate::redirect::same_origin_redirects())
.timeout(Duration::from_secs(120))
.build()?;
Ok(Self {
client,
api_key,
base_url: base_url.into(),
model: model.into(),
dim,
query_prefix: String::new(),
document_prefix: String::new(),
})
}
/// Set the strings prepended to query / document text before embedding,
/// applied ahead of the existing truncation so truncation still bounds
/// the whole request body (prefix included). Pass empty strings for no
/// prefix (the default); safe to call unconditionally with a possibly
/// unset operator setting.
///
/// Publisher-specified prefixes are exact strings, often with a
/// significant trailing space (e.g. Nemotron-3-Embed / the E5 family
/// use `"query: "` and `"passage: "`) — callers must not trim them.
#[must_use]
pub fn with_prefixes(
mut self,
query_prefix: impl Into<String>,
document_prefix: impl Into<String>,
) -> Self {
self.query_prefix = query_prefix.into();
self.document_prefix = document_prefix.into();
self
}
}
#[async_trait]
impl Embedder for OpenAiCompatEmbedder {
fn provider(&self) -> &'static str {
"openai-compat"
}
fn model(&self) -> &str {
&self.model
}
fn model_identity(&self) -> String {
document_prefix_identity(&self.model, &self.document_prefix)
}
fn dim(&self) -> u32 {
self.dim
}
async fn embed(&self, text: &str) -> LlmResult<Vec<f32>> {
openai_style_embed(
&self.client,
&self.base_url,
self.api_key.as_ref(),
&self.model,
self.dim,
text,
)
.await
}
async fn embed_document(&self, text: &str) -> LlmResult<Vec<f32>> {
let prefixed = prepend_prefix(&self.document_prefix, text);
openai_style_embed(
&self.client,
&self.base_url,
self.api_key.as_ref(),
&self.model,
self.dim,
&prefixed,
)
.await
}
async fn embed_query(&self, text: &str) -> LlmResult<Vec<f32>> {
let prefixed = prepend_prefix(&self.query_prefix, text);
openai_style_embed(
&self.client,
&self.base_url,
self.api_key.as_ref(),
&self.model,
self.dim,
&prefixed,
)
.await
}
}
/// Voyage Embeddings API.
pub struct VoyageEmbedder {
client: reqwest::Client,
api_key: SecretString,
base_url: String,
model: String,
dim: u32,
}
impl VoyageEmbedder {
/// Construct a Voyage embedder.
///
/// # Errors
/// Propagates the HTTP client construction error.
pub fn new(api_key: SecretString, model: impl Into<String>, dim: u32) -> LlmResult<Self> {
// 120s tolerates a cold-load of the embedding model on Ollama
// (small model, but still up to ~30s on first request after
// unload). Subsequent requests with OLLAMA_KEEP_ALIVE warm are
// sub-second. When the embedder still fails, memory_query
// degrades gracefully to FTS5 + entity + graph (see server.rs).
let client = reqwest::Client::builder()
.redirect(crate::redirect::same_origin_redirects())
.timeout(Duration::from_secs(120))
.build()?;
Ok(Self {
client,
api_key,
base_url: "https://api.voyageai.com".into(),
model: model.into(),
dim,
})
}
/// Override the base URL.
#[must_use]
pub fn with_base_url(mut self, url: impl Into<String>) -> Self {
self.base_url = url.into();
self
}
}
/// Sent without a client-side cut: Voyage's `truncation` defaults to true and
/// shortens an over-long input to the model's own context (4k-32k tokens), so
/// the shared 8 KB head cut would only discard text the model can embed.
/// <https://docs.voyageai.com/docs/embeddings>
#[derive(Debug, Serialize)]
struct VoyageRequest<'a> {
input: [&'a str; 1],
model: &'a str,
}
#[derive(Debug, Deserialize)]
struct VoyageResponse {
data: Vec<VoyageDatum>,
}
#[derive(Debug, Deserialize)]
struct VoyageDatum {
embedding: Vec<f32>,
}
#[async_trait]
impl Embedder for VoyageEmbedder {
fn provider(&self) -> &'static str {
"voyage"
}
fn model(&self) -> &str {
&self.model
}
fn dim(&self) -> u32 {
self.dim
}
async fn embed(&self, text: &str) -> LlmResult<Vec<f32>> {
let url = normalize_openai_base(&self.base_url, "embeddings");
let req = VoyageRequest {
input: [text],
model: &self.model,
};
let mut attempt = 0u32;
let mut waited = Duration::ZERO;
let resp = loop {
let resp = self
.client
.post(&url)
.bearer_auth(self.api_key.expose_secret())
.json(&req)
.send()
.await?;
let status = resp.status();
let retry_after = resp.headers().get(reqwest::header::RETRY_AFTER);
let Some(delay) = retry_delay(status, retry_after, attempt + 1, waited) else {
break resp;
};
attempt += 1;
waited += delay;
debug!(
attempt,
?delay,
status = status.as_u16(),
"voyage embeddings 429/503; retrying"
);
tokio::time::sleep(delay).await;
};
let status = resp.status();
if !status.is_success() {
return Err(provider_error(resp).await);
}
let parsed: VoyageResponse = response_json_limited(resp).await?;
let first =
parsed.data.into_iter().next().ok_or_else(|| {
LlmError::UnexpectedShape("voyage response had no data[0]".into())
})?;
if first.embedding.len() as u32 != self.dim {
return Err(LlmError::UnexpectedShape(format!(
"expected dim {}, got {}",
self.dim,
first.embedding.len()
)));
}
Ok(normalise(first.embedding))
}
}
/// Deterministic synthetic embedder for tests.
///
/// Each whitespace-separated word in the text adds 1.0 to one
/// dimension chosen by the word's hash. Vectors are unit-normalised.
/// Similar text → similar vectors, which is enough to demonstrate
/// hybrid retrieval beats either ranker alone.
pub struct SyntheticEmbedder {
dim: u32,
}
impl SyntheticEmbedder {
/// Construct with the given dimensionality.
#[must_use]
pub const fn new(dim: u32) -> Self {
Self { dim }
}
}
#[async_trait]
impl Embedder for SyntheticEmbedder {
fn provider(&self) -> &'static str {
"synthetic"
}
fn model(&self) -> &str {
"bag-of-words-v1"
}
fn dim(&self) -> u32 {
self.dim
}
async fn embed(&self, text: &str) -> LlmResult<Vec<f32>> {
let mut v = vec![0.0_f32; self.dim as usize];
for word in text.split(|c: char| !c.is_alphanumeric()) {
if word.is_empty() {
continue;
}
let lower = word.to_ascii_lowercase();
let h = fnv1a(&lower) as usize;
let idx = h % v.len();
v[idx] += 1.0;
}
Ok(normalise(v))
}
}
/// Prepend `prefix` to `text` for an asymmetric embedding model, applied
/// BEFORE [`truncate_for_embedding`] so truncation always bounds the whole
/// request body (prefix included) rather than letting a prefix push the
/// text itself past the server's token limit. An empty prefix — the
/// default — returns `text` unchanged and borrowed, so the unset case
/// allocates nothing.
pub(crate) fn prepend_prefix<'a>(prefix: &str, text: &'a str) -> std::borrow::Cow<'a, str> {
if prefix.is_empty() {
std::borrow::Cow::Borrowed(text)
} else {
std::borrow::Cow::Owned(format!("{prefix}{text}"))
}
}
/// The `model` component of the stored embedding identity for a document
/// embedder configured with `document_prefix`. An empty prefix returns
/// `model` unchanged — the pre-existing identity, so an install with no
/// document prefix configured needs no migration. A non-empty prefix
/// appends a versioned SHA-256 fingerprint of the prefix bytes: `+dp1-`
/// followed by the first 16 hex characters (64 bits) of
/// `SHA-256(document_prefix)`. Not the raw prefix text itself, which
/// could be long, contain characters awkward in a stored column, or leak
/// an operator's exact instruction string into logs/admin output more
/// than necessary — and not a 32-bit hash (an earlier revision used
/// `fnv1a` truncated to 32 bits, which a search for a same-length ASCII
/// collision found in minutes: `"Document category 5hvhw0: "` and
/// `"Document category 1i4yh8i: "` both fingerprinted to `5c7f37a2`,
/// which would have silently mixed two different prefixes' vectors under
/// one identity — see `document_prefix_identity_does_not_collide_on_the_known_fnv32_pair`
/// below). SHA-256 truncated to 64 bits keeps the collision probability
/// negligible for the small number of prefixes one deployment actually
/// configures over time, without needing the full 256-bit digest in a
/// column meant to stay human-scannable. The `dp1` version tag lets a
/// future change to this scheme be distinguished from today's rather than
/// risking a silent collision with an old identity under a new one.
pub(crate) fn document_prefix_identity(model: &str, document_prefix: &str) -> String {
if document_prefix.is_empty() {
return model.to_string();
}
let digest = format!("{:x}", Sha256::digest(document_prefix.as_bytes()));
format!("{model}+dp1-{}", &digest[..16])
}
/// Unit-normalise so dot-product equals cosine similarity.
pub(crate) fn normalise(mut v: Vec<f32>) -> Vec<f32> {
let norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();
if norm > 0.0 {
for x in &mut v {
*x /= norm;
}
}
v
}
fn fnv1a(s: &str) -> u64 {
let mut h: u64 = 0xcbf2_9ce4_8422_2325;
for &b in s.as_bytes() {
h ^= u64::from(b);
h = h.wrapping_mul(0x100_0000_01b3);
}
h
}
/// Cosine similarity between two same-dim unit vectors. (= dot product
/// after normalisation.)
#[must_use]
pub fn cosine(a: &[f32], b: &[f32]) -> f32 {
a.iter().zip(b).map(|(x, y)| x * y).sum()
}
#[cfg(test)]
mod tests {
use super::*;
fn header(value: &'static str) -> reqwest::header::HeaderValue {
reqwest::header::HeaderValue::from_static(value)
}
#[test]
fn retry_delay_honours_whole_second_retry_after_on_429_and_503() {
let five = Duration::from_secs(5);
assert_eq!(
retry_delay(
reqwest::StatusCode::from_u16(429).unwrap(),
Some(&header("5")),
1,
Duration::ZERO
),
Some(five)
);
assert_eq!(
retry_delay(
reqwest::StatusCode::from_u16(503).unwrap(),
Some(&header("5")),
1,
Duration::ZERO
),
Some(five)
);
}
#[test]
fn retry_delay_clamps_retry_after_to_the_per_wait_cap() {
let capped = Duration::from_secs(32);
assert_eq!(
retry_delay(
reqwest::StatusCode::from_u16(429).unwrap(),
Some(&header("120")),
1,
Duration::ZERO
),
Some(capped)
);
assert_eq!(
retry_delay(
reqwest::StatusCode::from_u16(503).unwrap(),
Some(&header("120")),
1,
Duration::ZERO
),
Some(capped)
);
}
#[test]
fn retry_delay_falls_back_to_exponential_backoff_without_a_valid_header() {
let status = reqwest::StatusCode::from_u16(503).unwrap();
// Missing header: the historical 2^attempt seconds.
assert_eq!(
retry_delay(status, None, 1, Duration::ZERO),
Some(Duration::from_secs(2))
);
assert_eq!(
retry_delay(status, None, 3, Duration::ZERO),
Some(Duration::from_secs(8))
);
assert_eq!(
retry_delay(status, None, 5, Duration::ZERO),
Some(Duration::from_secs(32))
);
// A non-whole-second value is not supported (HTTP-date form):
// same fallback as an absent header.
assert_eq!(
retry_delay(status, Some(&header("abc")), 1, Duration::ZERO),
Some(Duration::from_secs(2))
);
assert_eq!(
retry_delay(
status,
Some(&header("Wed, 21 Oct 2015 07:28:00 GMT")),
1,
Duration::ZERO
),
Some(Duration::from_secs(2))
);
}
#[test]
fn retry_delay_refuses_non_retriable_statuses() {
let header5 = Some(&header("5"));
for status in [400u16, 404, 500, 502] {
let code = reqwest::StatusCode::from_u16(status).unwrap();
assert_eq!(
retry_delay(code, header5, 1, Duration::ZERO),
None,
"status {status}"
);
assert_eq!(
retry_delay(code, None, 1, Duration::ZERO),
None,
"status {status}"
);
}
}
#[test]
fn retry_delay_stops_after_five_new_attempts() {
let status = reqwest::StatusCode::from_u16(503).unwrap();
assert_eq!(
retry_delay(status, Some(&header("0")), 5, Duration::from_secs(30)),
Some(Duration::ZERO),
"attempt 5 stays inside the attempt cap and the 62 s budget"
);
assert_eq!(
retry_delay(status, Some(&header("0")), 6, Duration::ZERO),
None
);
assert_eq!(retry_delay(status, None, 6, Duration::ZERO), None);
assert_eq!(retry_delay(status, None, 7, Duration::ZERO), None);
}
#[test]
fn retry_delay_gives_up_when_the_wait_budget_is_exhausted() {
let status = reqwest::StatusCode::from_u16(503).unwrap();
// 35 s already waited plus a 30 s Retry-After would reach 65 s.
assert_eq!(
retry_delay(status, Some(&header("30")), 1, Duration::from_secs(35)),
None
);
// A clamped 120 s header (32 s) after 32 s already waited: 64 s > 62 s.
assert_eq!(
retry_delay(status, Some(&header("120")), 2, Duration::from_secs(32)),
None
);
// Boundary control: the previous worst case (30 s waited + 32 s)
// still fits the budget, so behaviour is unchanged at the limit.
assert_eq!(
retry_delay(status, None, 5, Duration::from_secs(30)),
Some(Duration::from_secs(32))
);
}
#[test]
fn document_prefix_identity_is_unchanged_when_the_prefix_is_empty() {
// The legacy-identity guarantee: an install with no document
// prefix configured must key its vectors exactly as before this
// feature, so it needs no migration.
assert_eq!(
document_prefix_identity("nomic-embed-text", ""),
"nomic-embed-text"
);
}
#[test]
fn document_prefix_identity_changes_deterministically_with_the_prefix() {
let base = document_prefix_identity("nomic-embed-text", "passage: ");
assert_ne!(
base, "nomic-embed-text",
"a set prefix must not reuse the legacy identity"
);
assert!(base.starts_with("nomic-embed-text+dp1-"));
// Deterministic: the same (model, prefix) always produces the same
// identity, so pages embedded in different requests still land
// under one queryable identity.
assert_eq!(
base,
document_prefix_identity("nomic-embed-text", "passage: ")
);
}
#[test]
fn document_prefix_identity_distinguishes_different_prefixes() {
// Two distinct document prefixes on the same model must not
// collide — otherwise a prefix *change* would look like no change
// at all to the refuse-on-mismatch / stale-row machinery.
let a = document_prefix_identity("nomic-embed-text", "passage: ");
let b = document_prefix_identity("nomic-embed-text", "document: ");
assert_ne!(a, b);
}
/// Regression test for a real collision found in an earlier revision
/// of `document_prefix_identity`, which truncated `fnv1a` to 32 bits:
/// `"Document category 5hvhw0: "` and `"Document category 1i4yh8i: "`
/// both fingerprinted to `5c7f37a2` (verified independently in
/// Python), which would have silently mixed the two prefixes' vectors
/// under one stored identity. The SHA-256-based fingerprint here does
/// not collide on this pair (also independently verified: their first
/// 16 hex characters are `b32006f5a41f3d24` and `513594f86d5883fd`).
#[test]
fn document_prefix_identity_does_not_collide_on_the_known_fnv32_pair() {
let a = document_prefix_identity("nomic-embed-text", "Document category 5hvhw0: ");
let b = document_prefix_identity("nomic-embed-text", "Document category 1i4yh8i: ");
assert_ne!(
a, b,
"these two prefixes collided under the old 32-bit fnv1a fingerprint; \
the new SHA-256-based one must not repeat that collision"
);
}
#[test]
fn model_identity_defaults_to_model_for_providers_without_prefixes() {
// Providers that never got the document-prefix override (google,
// voyage, local, copilot, synthetic) must see byte-identical
// behaviour: `model_identity` defaults to `model().to_string()`.
let e = SyntheticEmbedder::new(8);
assert_eq!(e.model_identity(), e.model());
}
#[test]
fn openai_compat_embedder_model_identity_reflects_the_document_prefix() {
let unset = OpenAiCompatEmbedder::new("http://localhost:9/v1", None, "nomic-embed-text", 8)
.expect("embedder builds");
assert_eq!(unset.model_identity(), "nomic-embed-text");
let with_prefix =
OpenAiCompatEmbedder::new("http://localhost:9/v1", None, "nomic-embed-text", 8)
.expect("embedder builds")
.with_prefixes("query: ", "passage: ");
assert_ne!(with_prefix.model_identity(), "nomic-embed-text");
assert_eq!(
with_prefix.model_identity(),
document_prefix_identity("nomic-embed-text", "passage: ")
);
// The query prefix must NOT affect the stored identity — only
// documents are stored; a query is never persisted.
let query_only =
OpenAiCompatEmbedder::new("http://localhost:9/v1", None, "nomic-embed-text", 8)
.expect("embedder builds")
.with_prefixes("query: ", "");
assert_eq!(query_only.model_identity(), "nomic-embed-text");
}
#[test]
fn openai_embedder_model_identity_reflects_the_document_prefix() {
let unset =
OpenAiEmbedder::new(SecretString::from("k"), "text-embedding-3-small", 1536).unwrap();
assert_eq!(unset.model_identity(), "text-embedding-3-small");
let with_prefix =
OpenAiEmbedder::new(SecretString::from("k"), "text-embedding-3-small", 1536)
.unwrap()
.with_prefixes("query: ", "passage: ");
assert_ne!(with_prefix.model_identity(), "text-embedding-3-small");
}
/// Transport-level proof that `OpenAiEmbedder` (not just
/// `OpenAiCompatEmbedder`, covered in
/// `tests/suite/openai_compat_embedder.rs`) actually sends the
/// configured prefix on the wire — `with_prefixes` alone only proves
/// the fields are stored, not that `embed_query`/`embed_document` use
/// them in the real HTTP request body.
#[tokio::test]
async fn openai_embedder_sends_the_prefix_on_the_wire() {
use wiremock::matchers::{method, path};
use wiremock::{Mock, MockServer, Request, ResponseTemplate};
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/v1/embeddings"))
.respond_with(move |req: &Request| {
let body: serde_json::Value = serde_json::from_slice(&req.body).unwrap();
assert_eq!(body["input"], "query: find the runbook");
ResponseTemplate::new(200).set_body_json(serde_json::json!({
"data": [{ "embedding": vec![0.5_f32; 4] }],
}))
})
.expect(1)
.mount(&server)
.await;
let e = OpenAiEmbedder::new(SecretString::from("sk-test"), "text-embedding-3-small", 4)
.unwrap()
.with_base_url(server.uri())
.with_prefixes("query: ", "passage: ");
e.embed_query("find the runbook")
.await
.expect("embed_query succeeds");
}
/// Voyage truncates server side by default, so a long page goes out whole
/// rather than through the 8 KB head cut the other HTTP embedders need.
#[tokio::test]
async fn voyage_embedder_sends_a_long_input_whole() {
use wiremock::matchers::{method, path};
use wiremock::{Mock, MockServer, Request, ResponseTemplate};
let page = "word ".repeat(8_000);
let expected = page.clone();
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/v1/embeddings"))
.respond_with(move |req: &Request| {
let body: serde_json::Value = serde_json::from_slice(&req.body).unwrap();
assert_eq!(body["input"][0], expected.as_str());
ResponseTemplate::new(200).set_body_json(serde_json::json!({
"data": [{ "embedding": [0.6_f32, 0.8] }],
}))
})
.expect(1)
.mount(&server)
.await;
let e = VoyageEmbedder::new(SecretString::from("test-key"), "voyage-3-large", 2)
.unwrap()
.with_base_url(server.uri());
e.embed(&page).await.expect("voyage embed succeeds");
}
#[tokio::test]
async fn synthetic_embedder_produces_unit_vectors() {
let e = SyntheticEmbedder::new(64);
let v = e.embed("hello world hello").await.unwrap();
assert_eq!(v.len(), 64);
let norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();
assert!((norm - 1.0).abs() < 1e-5, "expected unit norm, got {norm}");
}
#[tokio::test]
async fn synthetic_similar_text_has_higher_cosine() {
let e = SyntheticEmbedder::new(256);
let a = e
.embed("retention sweep evicts stale episodic pages")
.await
.unwrap();
let close = e
.embed("the sweep evicts stale episodic pages")
.await
.unwrap();
let far = e
.embed("docker compose volumes and bind mounts")
.await
.unwrap();
let s_close = cosine(&a, &close);
let s_far = cosine(&a, &far);
assert!(
s_close > s_far,
"similar text should cosine higher than unrelated: close={s_close} far={s_far}"
);
}
#[tokio::test]
async fn synthetic_is_deterministic() {
let e = SyntheticEmbedder::new(64);
let a = e.embed("compile not retrieve").await.unwrap();
let b = e.embed("compile not retrieve").await.unwrap();
assert_eq!(a, b);
}
#[test]
fn parse_openai_embedding_accepts_data_array() {
let body = r#"{"data":[{"embedding":[0.1,0.2,0.3]}]}"#;
let v = parse_openai_embedding_values(body, 200).unwrap();
assert_eq!(v.len(), 3);
}
#[test]
fn parse_openai_embedding_accepts_openrouter_error() {
let body = r#"{"error":{"message":"Provider returned error","code":502}}"#;
let err = parse_openai_embedding_values(body, 502).unwrap_err();
assert!(matches!(err, LlmError::Provider { status: 502, .. }));
}
#[test]
fn parse_openai_embedding_rejects_non_numeric_values() {
let body = r#"{"data":[{"embedding":[0.1,"oops",0.3]}]}"#;
let err = parse_openai_embedding_values(body, 200).unwrap_err();
assert!(matches!(err, LlmError::Provider { status: 200, .. }));
}
#[test]
fn prepend_prefix_applies_publisher_instruction() {
// Nemotron-3-Embed / the E5 family: exact publisher strings,
// including the significant trailing space.
assert_eq!(
prepend_prefix("query: ", "find the release runbook"),
"query: find the release runbook"
);
assert_eq!(
prepend_prefix("passage: ", "the release runbook says..."),
"passage: the release runbook says..."
);
}
#[test]
fn prepend_prefix_unset_leaves_text_unchanged() {
// The default (empty prefix) must be a true no-op, byte for byte,
// and borrow rather than allocate.
let text = "unchanged text";
let out = prepend_prefix("", text);
assert_eq!(out, text);
assert!(matches!(out, std::borrow::Cow::Borrowed(_)));
}
#[test]
fn prefix_is_applied_before_truncation_so_it_still_bounds_the_whole_input() {
// A prefix pushes the *total* input closer to the cap; truncation
// must run on prefix+text together, never on text alone with the
// prefix appended afterwards (which could exceed the server limit).
let long_text = "x".repeat(50_000);
let prefixed = prepend_prefix("passage: ", &long_text);
let truncated = truncate_for_embedding(&prefixed, OPENAI_EMBED_MAX_TOKENS);
assert!(truncated.starts_with("passage: "));
assert!(truncated.len() <= 8_000, "must respect the hard byte cap");
assert!(truncated.ends_with('…'));
}
#[test]
fn openai_compat_embedder_defaults_to_no_prefix() {
// Construction without `with_prefixes` must be byte-identical to
// before this feature existed.
let e = OpenAiCompatEmbedder::new("http://localhost:9/v1", None, "nomic-embed-text", 8)
.expect("embedder builds");
assert_eq!(e.query_prefix, "");
assert_eq!(e.document_prefix, "");
}
#[test]
fn openai_compat_embedder_stores_configured_prefixes() {
let e = OpenAiCompatEmbedder::new(
"http://localhost:9/v1",
None,
"nvidia/Nemotron-3-Embed-1B-BF16",
2048,
)
.expect("embedder builds")
.with_prefixes("query: ", "passage: ");
assert_eq!(e.query_prefix, "query: ");
assert_eq!(e.document_prefix, "passage: ");
}
}