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