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