use serde::{Deserialize, Serialize};
fn rag_config_message(
key: &str,
english: impl std::fmt::Display,
args: &[(&str, String)],
) -> String {
match crate::i18n::startup_i18n() {
Some((locale, bundle)) => crate::i18n::t_with_args(locale, bundle, key, args),
None => english.to_string(),
}
}
#[derive(Clone, Deserialize, Serialize, confers::Config)]
#[config(env_prefix = "CRAWLRS__RAG__")]
pub struct RagSettings {
#[config(default = false)]
pub enabled: bool,
#[config(default = String::new())]
pub embedding_provider: String,
#[config(default = String::new())]
pub rerank_provider: String,
#[config(default = "models/BAAI-bge-small-en-v1.5".to_string())]
pub local_model_path: String,
#[config(default = "BAAI/bge-small-en-v1.5".to_string())]
pub local_model_name: String,
#[config(default = 384)]
pub local_dimensions: usize,
#[config(default = 256)]
pub local_cache_size: usize,
#[config(default = String::new())]
pub rerank_endpoint: String,
#[config(default = String::new())]
pub rerank_model: String,
#[config(default = "cohere".to_string())]
pub rerank_format: String,
pub(crate) rerank_api_key: Option<String>,
#[config(default = 10)]
pub rerank_timeout_seconds: u64,
#[config(default = 25)]
pub search_rerank_top_n: usize,
#[config(default = 5)]
pub rag_top_k: usize,
}
impl std::fmt::Debug for RagSettings {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("RagSettings")
.field("enabled", &self.enabled)
.field("embedding_provider", &self.embedding_provider)
.field("rerank_provider", &self.rerank_provider)
.field("local_model_path", &self.local_model_path)
.field("local_model_name", &self.local_model_name)
.field("local_dimensions", &self.local_dimensions)
.field("local_cache_size", &self.local_cache_size)
.field("rerank_endpoint", &self.rerank_endpoint)
.field("rerank_model", &self.rerank_model)
.field("rerank_format", &self.rerank_format)
.field("rerank_api_key", &"[REDACTED]")
.field("rerank_timeout_seconds", &self.rerank_timeout_seconds)
.field("search_rerank_top_n", &self.search_rerank_top_n)
.field("rag_top_k", &self.rag_top_k)
.finish()
}
}
impl RagSettings {
pub fn rerank_api_key(&self) -> Option<&str> {
self.rerank_api_key.as_deref()
}
pub fn validate_providers(&self) -> Result<(), String> {
if !self.enabled {
return Ok(());
}
self.validate_embedding_provider()?;
self.validate_rerank_provider()?;
self.validate_retrieval_limits()?;
Ok(())
}
fn validate_embedding_provider(&self) -> Result<(), String> {
match self.embedding_provider.as_str() {
"" => {}
"local" => {
#[cfg(not(feature = "rag-local"))]
return Err(rag_config_message(
"rag-config-embedding-provider-local-feature",
"rag.embedding_provider = \"local\" requires the rag-local feature (vecboost); \
rebuild with --features rag-local",
&[],
));
}
other => {
return Err(rag_config_message(
"rag-config-embedding-provider-invalid",
format!(
"invalid rag.embedding_provider value \"{other}\" (supported: \"\"/local)"
),
&[("value", other.to_string())],
));
}
}
Ok(())
}
fn validate_rerank_provider(&self) -> Result<(), String> {
match self.rerank_provider.as_str() {
"" => {}
"local" => {
#[cfg(not(feature = "rag-local"))]
return Err(rag_config_message(
"rag-config-rerank-provider-local-feature",
"rag.rerank_provider = \"local\" requires the rag-local feature (vecboost); \
rebuild with --features rag-local, or use \"http\"",
&[],
));
}
"http" => {
if self.rerank_endpoint.trim().is_empty() {
return Err(rag_config_message(
"rag-config-rerank-endpoint-empty",
"rag.rerank_endpoint cannot be empty when rag.rerank_provider = \"http\"",
&[],
));
}
match self.rerank_format.as_str() {
"cohere" => {
if self.rerank_model.trim().is_empty() {
return Err(rag_config_message(
"rag-config-rerank-model-empty",
"rag.rerank_model cannot be empty when rag.rerank_format = \"cohere\"",
&[],
));
}
}
"tei" => {}
other => {
return Err(rag_config_message(
"rag-config-rerank-format-invalid",
format!("invalid rag.rerank_format value \"{other}\" (supported: cohere/tei)"),
&[("value", other.to_string())],
));
}
}
}
other => {
return Err(rag_config_message(
"rag-config-rerank-provider-invalid",
format!(
"invalid rag.rerank_provider value \"{other}\" (supported: \"\"/local/http)"
),
&[("value", other.to_string())],
));
}
}
Ok(())
}
fn validate_retrieval_limits(&self) -> Result<(), String> {
if self.search_rerank_top_n == 0 || self.search_rerank_top_n > 100 {
return Err(rag_config_message(
"rag-config-search-rerank-top-n",
"rag.search_rerank_top_n must be within 1..=100",
&[],
));
}
if self.rag_top_k == 0 || self.rag_top_k > 50 {
return Err(rag_config_message(
"rag-config-rag-top-k",
"rag.rag_top_k must be within 1..=50",
&[],
));
}
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_rag_default_all_disabled() {
let settings = RagSettings::default();
assert!(!settings.enabled);
assert_eq!(settings.embedding_provider, "");
assert_eq!(settings.rerank_provider, "");
assert_eq!(settings.local_dimensions, 384);
assert_eq!(settings.rerank_format, "cohere");
assert_eq!(settings.search_rerank_top_n, 25);
assert_eq!(settings.rag_top_k, 5);
settings
.validate_providers()
.expect("default must be valid");
}
#[test]
fn test_rag_debug_redacts_keys() {
let settings = RagSettings {
enabled: true,
rerank_api_key: Some("jina-secret".to_string()),
..RagSettings::default()
};
let debug = format!("{settings:?}");
assert!(debug.contains("[REDACTED]"), "Debug must redact api keys");
assert!(!debug.contains("jina-secret"));
}
#[test]
fn test_rag_disabled_skips_provider_validation() {
let settings = RagSettings {
enabled: false,
embedding_provider: "bogus".to_string(),
rerank_endpoint: String::new(),
..RagSettings::default()
};
settings
.validate_providers()
.expect("disabled skips checks");
}
#[test]
fn test_rag_enabled_rejects_unknown_provider() {
let settings = RagSettings {
enabled: true,
embedding_provider: "bogus".to_string(),
..RagSettings::default()
};
let err = settings
.validate_providers()
.expect_err("unknown provider must fail");
assert!(err.contains("embedding_provider"), "got: {err}");
}
#[test]
fn test_rag_http_rerank_requires_endpoint_and_model() {
let settings = RagSettings {
enabled: true,
rerank_provider: "http".to_string(),
..RagSettings::default()
};
let err = settings
.validate_providers()
.expect_err("http rerank without endpoint must fail");
assert!(err.contains("rerank_endpoint"), "got: {err}");
let settings = RagSettings {
enabled: true,
rerank_provider: "http".to_string(),
rerank_endpoint: "https://api.jina.ai/v1/rerank".to_string(),
..RagSettings::default()
};
let err = settings
.validate_providers()
.expect_err("cohere format without model must fail");
assert!(err.contains("rerank_model"), "got: {err}");
}
#[test]
fn test_rag_http_rerank_tei_needs_no_model() {
let settings = RagSettings {
enabled: true,
rerank_provider: "http".to_string(),
rerank_endpoint: "http://localhost:8080/rerank".to_string(),
rerank_format: "tei".to_string(),
..RagSettings::default()
};
settings.validate_providers().expect("tei needs no model");
}
#[test]
fn test_rag_local_provider_feature_gated() {
let settings = RagSettings {
enabled: true,
embedding_provider: "local".to_string(),
..RagSettings::default()
};
#[cfg(feature = "rag-local")]
settings
.validate_providers()
.expect("local provider valid when rag-local compiled");
#[cfg(not(feature = "rag-local"))]
{
let err = settings.validate_providers().expect_err("must fail");
assert!(err.contains("rag-local"), "got: {err}");
}
}
#[test]
fn test_rag_top_n_bounds() {
let settings = RagSettings {
enabled: true,
search_rerank_top_n: 0,
..RagSettings::default()
};
assert!(settings.validate_providers().is_err());
}
}