Skip to main content

second_brain_core/
config.rs

1use std::path::{Path, PathBuf};
2
3use anyhow::{Context, Result, bail};
4use serde::Deserialize;
5
6use crate::retrieval::{RetrievalTunables, blend};
7
8pub const CONFIG_FILE: &str = "config.toml";
9
10#[derive(Debug, Clone, Default, Deserialize)]
11#[serde(deny_unknown_fields)]
12pub struct Config {
13    pub llm: Option<LlmConfig>,
14    #[serde(default)]
15    pub cloud: CloudConfig,
16    #[serde(default)]
17    pub distill: DistillConfig,
18    #[serde(default)]
19    pub retrieval: RetrievalConfig,
20    #[serde(default)]
21    pub sources: SourcesConfig,
22    #[serde(default)]
23    pub maintenance: MaintenanceConfig,
24}
25
26/// Scheduled store repair (see `maintenance::repair`). The daemon runs it
27/// once at startup and again whenever `interval_secs` have passed since the
28/// last run, from the thread that owns the writable indexes.
29#[derive(Debug, Clone, Deserialize)]
30#[serde(deny_unknown_fields)]
31pub struct MaintenanceConfig {
32    #[serde(default = "default_true")]
33    pub enabled: bool,
34    #[serde(default = "default_maintenance_interval")]
35    pub interval_secs: u64,
36}
37
38#[derive(Debug, Clone, Deserialize)]
39#[serde(deny_unknown_fields)]
40pub struct LlmConfig {
41    // No default endpoint on purpose: the v0.5 hardcoded localhost:8081 default
42    // silently pointed every LLM stage at a dead machine for weeks.
43    pub endpoint: String,
44    pub model: String,
45    pub api_key_env: Option<String>,
46    #[serde(default = "default_context_budget")]
47    pub context_budget_tokens: usize,
48}
49
50#[derive(Debug, Clone, Deserialize)]
51#[serde(deny_unknown_fields)]
52pub struct CloudConfig {
53    pub vault_id: Option<String>,
54    #[serde(default)]
55    pub providers: Vec<ProviderConfig>,
56    #[serde(default = "default_data_shards")]
57    pub data_shards: usize,
58    #[serde(default = "default_total_shards")]
59    pub total_shards: usize,
60}
61
62#[derive(Debug, Clone, Deserialize)]
63#[serde(deny_unknown_fields)]
64pub struct ProviderConfig {
65    pub name: String,
66    pub endpoint: String,
67    pub bucket: String,
68    #[serde(default)]
69    pub region: Option<String>,
70    pub access_key_id: String,
71    pub secret_key_env: String,
72}
73
74#[derive(Debug, Clone, Deserialize)]
75#[serde(deny_unknown_fields)]
76pub struct DistillConfig {
77    #[serde(default = "default_min_idle_minutes")]
78    pub min_idle_minutes: u64,
79    #[serde(default = "default_archive_after_days")]
80    pub archive_after_days: u64,
81    /// Cosine at which two live distillates of one project and type are
82    /// offered for merging. On the live store (2026-09-23) pairs at 0.97 and
83    /// above were paraphrases of one fact, while 0.95 to 0.97 still held
84    /// pairs that disagree on a detail.
85    #[serde(default = "default_near_duplicate_threshold")]
86    pub near_duplicate_threshold: f32,
87}
88
89#[derive(Debug, Clone, Deserialize)]
90#[serde(deny_unknown_fields)]
91pub struct RetrievalConfig {
92    #[serde(default = "default_rerank_gate")]
93    pub rerank_gate: f32,
94    #[serde(default = "default_cosine_gate")]
95    pub cosine_gate: f32,
96    #[serde(default = "default_rerank_model")]
97    pub rerank_model: String,
98    #[serde(default = "default_true")]
99    pub rerank_enabled: bool,
100    /// How many fused candidates reach the reranker. Measured on the
101    /// distilled corpus (evals/fuse-top-distilled.md): 20 beats 10 on
102    /// recall@3 and MRR with the confidence interval clear of zero.
103    #[serde(default = "default_fuse_top")]
104    pub fuse_top: usize,
105    /// Cosine floor for a recall whose scope was scanned whole; see
106    /// `RetrievalTunables::exhausted_cosine_gate`.
107    #[serde(default = "default_exhausted_cosine_gate")]
108    pub exhausted_cosine_gate: f32,
109    /// See `RetrievalTunables::fusion_floor`.
110    #[serde(default = "default_fusion_floor")]
111    pub fusion_floor: usize,
112    /// See `RetrievalTunables::chunk_rerank`.
113    #[serde(default = "default_true")]
114    pub chunk_rerank: bool,
115    /// See `RetrievalTunables::rerank_whole_chunked`.
116    #[serde(default = "default_true")]
117    pub rerank_whole_chunked: bool,
118}
119
120impl RetrievalConfig {
121    /// The gates and fan-out the daemon ranks with. Candidate depths are
122    /// not configurable and keep their built-in values.
123    pub fn tunables(&self) -> RetrievalTunables {
124        RetrievalTunables {
125            fuse_top: self.fuse_top,
126            rerank_gate: self.rerank_gate,
127            cosine_gate: self.cosine_gate,
128            exhausted_cosine_gate: self.exhausted_cosine_gate,
129            fusion_floor: self.fusion_floor,
130            chunk_rerank: self.chunk_rerank,
131            rerank_whole_chunked: self.rerank_whole_chunked,
132            ..RetrievalTunables::default()
133        }
134    }
135}
136
137#[derive(Debug, Clone, Default, Deserialize)]
138#[serde(deny_unknown_fields)]
139pub struct SourcesConfig {
140    #[serde(default)]
141    pub obsidian_vaults: Vec<PathBuf>,
142    #[serde(default)]
143    pub codex_sessions: Option<PathBuf>,
144}
145
146fn default_context_budget() -> usize {
147    16000
148}
149fn default_data_shards() -> usize {
150    2
151}
152fn default_total_shards() -> usize {
153    3
154}
155fn default_min_idle_minutes() -> u64 {
156    60
157}
158fn default_archive_after_days() -> u64 {
159    7
160}
161fn default_near_duplicate_threshold() -> f32 {
162    0.97
163}
164fn default_rerank_gate() -> f32 {
165    0.30
166}
167fn default_cosine_gate() -> f32 {
168    blend::MIN_SIMILARITY
169}
170fn default_exhausted_cosine_gate() -> f32 {
171    blend::EXHAUSTED_MIN_SIMILARITY
172}
173fn default_fusion_floor() -> usize {
174    RetrievalTunables::default().fusion_floor
175}
176fn default_fuse_top() -> usize {
177    20
178}
179fn default_rerank_model() -> String {
180    "bge-reranker-v2-m3".to_string()
181}
182fn default_true() -> bool {
183    true
184}
185fn default_maintenance_interval() -> u64 {
186    21600
187}
188
189impl Default for CloudConfig {
190    fn default() -> Self {
191        Self {
192            vault_id: None,
193            providers: Vec::new(),
194            data_shards: default_data_shards(),
195            total_shards: default_total_shards(),
196        }
197    }
198}
199
200impl Default for DistillConfig {
201    fn default() -> Self {
202        Self {
203            min_idle_minutes: default_min_idle_minutes(),
204            archive_after_days: default_archive_after_days(),
205            near_duplicate_threshold: default_near_duplicate_threshold(),
206        }
207    }
208}
209
210impl Default for MaintenanceConfig {
211    fn default() -> Self {
212        Self {
213            enabled: true,
214            interval_secs: default_maintenance_interval(),
215        }
216    }
217}
218
219impl Default for RetrievalConfig {
220    fn default() -> Self {
221        Self {
222            rerank_gate: default_rerank_gate(),
223            cosine_gate: default_cosine_gate(),
224            rerank_model: default_rerank_model(),
225            rerank_enabled: true,
226            fuse_top: default_fuse_top(),
227            exhausted_cosine_gate: default_exhausted_cosine_gate(),
228            fusion_floor: default_fusion_floor(),
229            chunk_rerank: true,
230            rerank_whole_chunked: true,
231        }
232    }
233}
234
235impl Config {
236    pub fn parse(text: &str) -> Result<Self> {
237        let config: Config = toml::from_str(text).context("invalid config.toml")?;
238        config.validate()?;
239        Ok(config)
240    }
241
242    pub fn load(path: &Path) -> Result<Self> {
243        let text = std::fs::read_to_string(path)
244            .with_context(|| format!("cannot read config at {}", path.display()))?;
245        Self::parse(&text)
246    }
247
248    /// Loads ~/.second-brain/config.toml, falling back to all-default config
249    /// (no llm, no cloud) when the file does not exist so read-only commands
250    /// work on an unconfigured machine.
251    pub fn load_default() -> Result<Self> {
252        let path = crate::machine::data_dir()?.join(CONFIG_FILE);
253        if path.exists() {
254            Self::load(&path)
255        } else {
256            Ok(Self::default())
257        }
258    }
259
260    fn validate(&self) -> Result<()> {
261        if let Some(llm) = &self.llm {
262            if llm.endpoint.trim().is_empty() {
263                bail!("llm.endpoint must not be empty");
264            }
265            if llm.model.trim().is_empty() {
266                bail!("llm.model must not be empty");
267            }
268        }
269        if self.retrieval.fuse_top == 0 {
270            bail!("retrieval.fuse_top must be at least 1");
271        }
272        for (name, gate) in [
273            ("cosine_gate", self.retrieval.cosine_gate),
274            (
275                "exhausted_cosine_gate",
276                self.retrieval.exhausted_cosine_gate,
277            ),
278        ] {
279            if !(0.0..=1.0).contains(&gate) {
280                bail!("retrieval.{name} must be between 0 and 1 (got {gate})");
281            }
282        }
283        let dup = self.distill.near_duplicate_threshold;
284        if !(dup > 0.0 && dup <= 1.0) {
285            bail!("distill.near_duplicate_threshold must be above 0 and at most 1 (got {dup})");
286        }
287        let c = &self.cloud;
288        if c.data_shards == 0 || c.total_shards <= c.data_shards {
289            bail!(
290                "cloud erasure config requires 0 < data_shards < total_shards (got {}/{})",
291                c.data_shards,
292                c.total_shards
293            );
294        }
295        if !c.providers.is_empty() && c.providers.len() < c.total_shards {
296            bail!(
297                "{} cloud providers configured but total_shards = {}; one shard per provider is required",
298                c.providers.len(),
299                c.total_shards
300            );
301        }
302        Ok(())
303    }
304
305    pub fn llm(&self) -> Result<&LlmConfig> {
306        self.llm.as_ref().context(
307            "no LLM endpoint configured; add an [llm] section with endpoint and model \
308             to ~/.second-brain/config.toml (there is deliberately no default)",
309        )
310    }
311
312    pub fn cloud(&self) -> Result<&CloudConfig> {
313        if self.cloud.providers.is_empty() {
314            bail!(
315                "no cloud providers configured; add [[cloud.providers]] entries \
316                 to ~/.second-brain/config.toml"
317            );
318        }
319        Ok(&self.cloud)
320    }
321}