second-brain-api 0.13.5

HTTP API server for second-brain: REST endpoints for recall, remember, and ingest
Documentation
//! Startup of the search indexes and the embedding and rerank models, and the
//! timers that unload idle models.

use std::path::Path;
use std::sync::{Arc, RwLock};
use std::time::Duration;

use second_brain_core::embedding::{Activations, Embedder};
use second_brain_core::index::{IndexClaim, Indexes};
use second_brain_core::model_cache::DEFAULT_RERANK_MODEL;
use second_brain_core::residency;
use second_brain_core::retrieval::Reranker;
use second_brain_core::sealed::{SealError, SealKeys, seal_error};
use second_brain_core::sqlite_store::SqliteStore;

/// The reader is what `AppState` and every recall call see; the writer is
/// private to the drain loop. Splitting them means recall never contends
/// with the drain loop for anything heavier than the brief `reload_view`
/// call the loop makes on the reader after each successful drain.
pub struct IndexHandles {
    pub reader: Arc<RwLock<Indexes>>,
    pub writer: Indexes,
    pub claim: IndexClaim,
}

/// `on_rebuild` hears how many memories a rebuild covers before it starts.
pub fn open_index_handles(
    dir: &Path,
    store: &SqliteStore,
    keys: Option<&SealKeys>,
    on_rebuild: impl FnOnce(usize),
) -> anyhow::Result<IndexHandles> {
    let claim = IndexClaim::acquire(dir)?;
    let mut writer = match keys {
        Some(keys) => open_keyed_or_discard(dir, keys)?,
        None => Indexes::open(dir)?,
    };
    if writer.consistent_with(store)? {
        tracing::info!("search indexes consistent at {}", dir.display());
        // `rebuild` persists as its last step, but the "already consistent"
        // branch never mutates, so a brand-new index (nothing on disk yet,
        // trivially consistent with an empty store) would otherwise leave
        // `open_readonly` below with no files to open.
        writer.persist()?;
    } else {
        tracing::info!("rebuilding search indexes at {}", dir.display());
        match store.indexable_count() {
            Ok(n) => on_rebuild(n),
            Err(e) => tracing::warn!("cannot count the memories to rebuild: {e:#}"),
        }
        let n = writer.rebuild(store)?;
        tracing::info!("search indexes rebuilt: {n} memories");
        residency::release_free_heap();
    }
    let reader = match keys {
        Some(_) => writer.shared_reader()?,
        None => Indexes::open_readonly(dir)?,
    };
    Ok(IndexHandles {
        reader: Arc::new(RwLock::new(reader)),
        writer,
        claim,
    })
}

/// Opens sealed indexes, or starts them empty when their files open under
/// none of `keys` (a store restored without the files' key): they are
/// rebuilt from the store, which holds every embedding.
fn open_keyed_or_discard(dir: &Path, keys: &SealKeys) -> anyhow::Result<Indexes> {
    match Indexes::open_keyed(dir, keys) {
        Err(e) if seal_error(&e).is_some_and(|cause| *cause != SealError::KeyRequired) => {
            tracing::warn!(
                "search indexes at {} do not open under the store's keys, rebuilding them: {e:#}",
                dir.display()
            );
            for name in Indexes::FILE_NAMES {
                let path = dir.join(name);
                if path.is_dir() {
                    std::fs::remove_dir_all(&path)?;
                } else if path.exists() {
                    std::fs::remove_file(&path)?;
                }
            }
            Indexes::open_keyed(dir, keys)
        }
        other => other,
    }
}

/// A rerank pool of 1 (the old default) serializes every concurrent recall
/// behind one session; `evals/rerank-cost-curve.md` reproduced the result
/// of that under ordinary eval load: a queued request timed out at 30s.
/// `Reranker`'s intra-op thread count is already sized per-session as
/// `cores / pool_size` (see `crates/core/src/retrieval/rerank.rs`), so a
/// larger pool does not add CPU throughput the machine doesn't have, and
/// wave 1's measurement found oversubscribed sessions just contend for the
/// same cores. What a larger pool buys is concurrency headroom: enough
/// sessions that an ordinary burst of overlapping recalls queues briefly
/// instead of erroring. Capping at 4 keeps that headroom without loading
/// more model copies into memory than a handful of concurrent clients would
/// ever need.
fn rerank_pool_size() -> usize {
    match std::env::var("SECOND_BRAIN_RERANK_POOL") {
        Ok(v) => v
            .parse::<usize>()
            .unwrap_or_else(|_| {
                panic!("invalid SECOND_BRAIN_RERANK_POOL '{v}': expected a positive integer")
            })
            .max(1),
        Err(_) => {
            let cores = std::thread::available_parallelism()
                .map(|n| n.get())
                .unwrap_or(1);
            cores.clamp(1, 4)
        }
    }
}

pub fn load_embedder() -> Option<Arc<Embedder>> {
    match Embedder::with_sessions_and_activations(1, Activations::Released) {
        Ok(e) => {
            tracing::info!("embedding model loaded");
            Some(Arc::new(e))
        }
        Err(e) => {
            tracing::warn!("embedding model unavailable: {e}");
            None
        }
    }
}

pub fn load_reranker(indexes_open: bool) -> Option<Arc<Reranker>> {
    let rerank_model = std::env::var("SECOND_BRAIN_RERANK_MODEL")
        .unwrap_or_else(|_| DEFAULT_RERANK_MODEL.to_string());
    if !indexes_open || rerank_model == "off" {
        None
    } else {
        let pool_size = rerank_pool_size();
        match Reranker::with_sessions(&rerank_model, pool_size) {
            Ok(r) => {
                tracing::info!("rerank model {rerank_model} loaded ({pool_size} sessions)");
                Some(Arc::new(r))
            }
            Err(e) => {
                tracing::warn!("rerank model {rerank_model} unavailable: {e:#}");
                None
            }
        }
    }
}

/// Must run inside the tokio runtime.
pub fn spawn_idle_unload(embedder: Option<Arc<Embedder>>, reranker: Option<Arc<Reranker>>) {
    if let Some(emb) = embedder {
        tokio::spawn(async move {
            let mut interval = tokio::time::interval(Duration::from_secs(60));
            loop {
                interval.tick().await;
                emb.drop_if_idle(300);
            }
        });
    }

    if let Some(r) = reranker {
        tokio::spawn(async move {
            let mut interval = tokio::time::interval(Duration::from_secs(60));
            loop {
                interval.tick().await;
                r.drop_if_idle(300);
            }
        });
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use second_brain_core::schema::{Memory, MemoryType};
    use second_brain_core::store::Store;

    #[test]
    fn a_held_claim_refuses_a_second_daemon_until_dropped() {
        let dir = tempfile::tempdir().unwrap();
        let store = SqliteStore::in_memory("m".to_string()).unwrap();
        let first = open_index_handles(dir.path(), &store, None, |_| {}).unwrap();
        let err = open_index_handles(dir.path(), &store, None, |_| {})
            .err()
            .unwrap();
        assert!(
            format!("{err:#}").contains("held by another daemon"),
            "{err:#}"
        );
        drop(first);
        open_index_handles(dir.path(), &store, None, |_| {}).unwrap();
    }

    #[test]
    fn a_rebuild_is_announced_with_its_size_and_a_consistent_open_is_not() {
        let dir = tempfile::tempdir().unwrap();
        let store = SqliteStore::in_memory("m".to_string()).unwrap();
        for content in ["first note", "second note"] {
            let m = Memory::new(
                content.to_string(),
                MemoryType::Semantic,
                "test".to_string(),
                String::new(),
            );
            store.store_memory(&m).unwrap();
        }

        let mut announced = None;
        drop(open_index_handles(dir.path(), &store, None, |n| announced = Some(n)).unwrap());
        assert_eq!(announced, Some(2));

        let mut again = None;
        drop(open_index_handles(dir.path(), &store, None, |n| again = Some(n)).unwrap());
        assert_eq!(again, None);
    }
}