second-brain-api 0.13.4

HTTP API server for second-brain: REST endpoints for recall, remember, and ingest
Documentation
pub mod alert;
pub mod asides;
pub mod associate;
pub mod at_rest;
pub mod auth;
pub mod backfill;
pub mod backup;
pub mod bootstrap;
pub mod clock_gate;
pub mod cold_pass;
pub mod device_access;
pub mod discovery;
pub mod eval;
pub mod file_modes;
pub mod footprint;
pub mod health;
pub mod heap;
pub mod identity_report;
pub mod ingest;
pub mod log_floor;
pub mod logging;
pub mod maintenance;
pub mod mentions;
pub mod models;
pub mod near_duplicates;
pub mod note_cover;
pub mod open_files;
pub mod pairing;
pub mod progress;
pub mod raw_index;
pub mod repairs;
pub mod routes;
pub mod self_update;
pub mod snapshot_merge;
pub mod sources;
pub mod startup;
pub mod store_compaction;
pub mod store_encryption;
pub mod stored_redaction;
pub mod sync_hello;
pub mod sync_import;
pub mod sync_loop;
pub mod value_metrics;
pub mod vaults;
pub mod watcher;
pub mod write_gate;
pub mod write_queue;

use std::sync::{Arc, RwLock};

use axum::extract::DefaultBodyLimit;
use axum::{Router, middleware};
use tower_http::trace::TraceLayer;

use second_brain_core::embedding::Embedder;
use second_brain_core::index::Indexes;
use second_brain_core::index::raw::RawIndex;
use second_brain_core::machine::MachineIdentity;
use second_brain_core::maintenance::MaintenanceSummary;
use second_brain_core::retrieval::{Reranker, RetrievalTunables};
use second_brain_core::sqlite_store::SqliteStore;
use second_brain_core::store::StoreAdmin;

pub struct AppState {
    pub store: Arc<dyn StoreAdmin>,
    /// Same store as `store`: Retriever::candidates and the outbox drain need
    /// the concrete SqliteStore, which the trait object cannot provide.
    pub sqlite: Arc<SqliteStore>,
    /// A read-only `Indexes` handle shared by every recall call; searches take
    /// the `RwLock` read side, which does not block other readers. The drain
    /// loop owns a separate read-write `Indexes` and only reaches into this
    /// lock's write side briefly, to call `reload_view` after persisting.
    /// None when index open/rebuild failed; recall then uses the legacy engine.
    pub indexes: Option<Arc<RwLock<Indexes>>>,
    /// Archived raws and transcript passages, searched only when nothing in
    /// `indexes` clears the abstention bar. The raw index thread writes it.
    pub raw_index: Option<Arc<RwLock<RawIndex>>>,
    /// The raw index's age bound and what it left out, for status.
    pub raw_coverage: Option<Arc<crate::raw_index::RawCoverage>>,
    /// Redacted copies of transcripts, which a delete removes; None when
    /// the archive directory could not be opened.
    pub archive: Option<Arc<second_brain_core::transcript_archive::TranscriptArchive>>,
    pub reranker: Option<Arc<Reranker>>,
    pub tunables: RetrievalTunables,
    pub embedder: Option<Arc<Embedder>>,
    pub machine: MachineIdentity,
    /// The most recent repair, scheduled or requested; `/v1/status` reports
    /// it without recomputing anything.
    pub maintenance: Arc<RwLock<Option<MaintenanceSummary>>>,
    /// Hands a repair request to the drain thread, the one owner of the
    /// writable indexes, so an on-demand repair never races the scheduled
    /// one. None when the indexes failed to open and no drain thread exists;
    /// the repair route then runs against the store alone.
    pub repair_tx: Option<std::sync::mpsc::Sender<maintenance::DrainRequest>>,
    /// `[distill] near_duplicate_threshold`: the default for the
    /// near-duplicates route and the threshold status counts at.
    pub near_duplicate_threshold: f32,
    /// The last near-duplicate count at `near_duplicate_threshold`, from a
    /// listing or a repair. Counting is a grouping pass over every live
    /// distillate (seconds on the Pi), so status reports this instead.
    pub near_duplicates: Arc<RwLock<Option<near_duplicates::NearDupCount>>>,
    pub health: Arc<health::Health>,
    pub gate: Arc<write_gate::WriteGate>,
    pub clock: Arc<clock_gate::ClockGate>,
    /// Holds the device key, which opens the identity key envelopes that
    /// seal and open sync records.
    pub data_dir: std::path::PathBuf,
    pub pairing: Arc<pairing::Pairing>,
    pub bootstrap: Arc<bootstrap::Bootstrap>,
    pub device_access: Arc<device_access::DeviceAccess>,
}

pub fn app(state: Arc<AppState>, api_token: String) -> Router {
    Router::new()
        .merge(routes::router())
        .layer(middleware::from_fn_with_state(
            state.clone(),
            write_gate::hold_writes,
        ))
        .layer(DefaultBodyLimit::max(64 * 1024 * 1024))
        .layer(middleware::from_fn_with_state(
            Arc::<str>::from(api_token),
            auth::require_token,
        ))
        .layer(TraceLayer::new_for_http())
        .with_state(state)
}

/// The retrieval settings the daemon serves recall with: `base` from config,
/// with abstention and source order on.
pub fn daemon_tunables(base: RetrievalTunables) -> RetrievalTunables {
    RetrievalTunables {
        abstain: true,
        source_order: true,
        ..base
    }
}

/// Extract the entity names a query refers to, using the same gazetteer
/// extraction the ingest path applies to transcripts. Matching extractors on
/// both sides is what lets query entities resolve to stored entity ids, so the
/// graph term in recall is conditioned on the query rather than raw
/// connectedness. Shared by the live recall route and the eval harness so both
/// measure the same ranking.
pub fn link_query_entities(text: &str) -> Vec<String> {
    second_brain_adapters::claude_code::extract_entities(text)
        .into_iter()
        .map(|e| e.name)
        .collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn the_daemon_abstains_and_orders_by_source_while_the_core_default_does_neither() {
        let base = RetrievalTunables {
            fuse_top: 7,
            ..RetrievalTunables::default()
        };
        assert!(!base.abstain && !base.source_order);
        let served = daemon_tunables(base);
        assert!(served.abstain && served.source_order);
        assert_eq!(served.fuse_top, 7, "config-driven settings pass through");
    }
}