second-brain-api 0.13.5

HTTP API server for second-brain: REST endpoints for recall, remember, and ingest
Documentation
mod consolidate;
mod correct;
mod delete;
mod devices;
mod digest;
mod ingest;
mod maintenance;
mod memory;
mod notes;
mod pair;
mod project_names;
mod raw_answer;
mod recall;
mod recovery;
mod rerank_budget;
mod status;
mod sync;

use std::sync::Arc;

use axum::http::StatusCode;
use axum::response::IntoResponse;
use axum::routing::{delete, get, post};
use axum::{Json, Router};
use second_brain_core::schema::{Memory, MemoryType, Scope, Tier};
use serde::Serialize;

use crate::AppState;

use consolidate::{consolidate_batch, consolidate_cleanup, consolidate_store, daily_memories};
use correct::correct;
use devices::{list_devices, remove_device};
use digest::digest;
use ingest::{ingest, reingest};
use maintenance::{
    backfill_project_paths, maintenance_backup, maintenance_plaintext_copy, maintenance_repair,
    maintenance_vacuum,
};
use memory::{associate, forget, get_memory, remember, traverse};
use notes::{list_notes, write_note};
use pair::{pair_close, pair_join, pair_start, pair_status, pair_stop_waiting};
use recall::{context, recall};
use recovery::{new_recovery_phrase, recovery_offered, recovery_state, remove_recovery_phrase};
use status::{health, health_report, list_projects, status};
use sync::{
    record_push_report, set_sync_state, sync_accept_hello, sync_ack, sync_compact, sync_export,
    sync_hello, sync_import, sync_peer_in, sync_prune_relations, sync_push_report, sync_snapshot,
    sync_snapshot_apply, sync_snapshot_status, sync_status, sync_version,
};

pub fn router() -> Router<Arc<AppState>> {
    Router::new()
        .route("/health", get(health))
        .route("/v1/recall", post(recall))
        .route("/v1/remember", post(remember))
        .route("/v1/associate", post(associate))
        .route("/v1/correct", post(correct))
        .route("/v1/memory/{id}", get(get_memory))
        .route("/v1/memory/{id}", delete(forget))
        .route("/v1/delete", post(delete::delete_scope))
        .route("/v1/delete/{key}", get(delete::delete_status))
        .route("/v1/context", post(context))
        .route("/v1/ingest", post(ingest))
        .route("/v1/reingest", post(reingest))
        .route("/v1/consolidate/batch", get(consolidate_batch))
        .route("/v1/consolidate/store", post(consolidate_store))
        .route("/v1/consolidate/cleanup", post(consolidate_cleanup))
        .route(
            "/v1/consolidate/near-duplicates",
            get(crate::near_duplicates::list),
        )
        .route(
            "/v1/consolidate/near-duplicates/review",
            post(crate::near_duplicates::review),
        )
        .route(
            "/v1/consolidate/near-duplicates/reopen",
            post(crate::near_duplicates::reopen),
        )
        .route("/v1/consolidate/merge", post(crate::near_duplicates::merge))
        .route("/v1/daily/memories", post(daily_memories))
        .route("/v1/graph/traverse", get(traverse))
        .route("/v1/status", get(status))
        .route("/v1/health", get(health_report))
        .route("/v1/maintenance/repair", post(maintenance_repair))
        .route("/v1/maintenance/vacuum", post(maintenance_vacuum))
        .route("/v1/maintenance/backup", post(maintenance_backup))
        .route("/v1/redaction", get(crate::stored_redaction::report))
        .route(
            "/v1/maintenance/refile-nested-projects",
            post(crate::repairs::refile_nested_projects),
        )
        .route(
            "/v1/maintenance/restore-explicit",
            post(crate::repairs::restore_explicit),
        )
        .route(
            "/v1/maintenance/refile-stray-projects",
            post(crate::repairs::refile_stray_projects),
        )
        .route("/v1/sync/version", get(sync_version))
        .route("/v1/sync/export", post(sync_export))
        .route("/v1/sync/import", post(sync_import))
        .route("/v1/sync/status", get(sync_status))
        .route("/v1/sync/prune-relations", post(sync_prune_relations))
        .route("/v1/sync/compact", post(sync_compact))
        .route("/v1/sync/state", post(set_sync_state))
        .route("/v1/backfill-project-paths", post(backfill_project_paths))
        .route(
            "/v1/backfill-session-at",
            post(crate::repairs::backfill_session_at),
        )
        .route("/v1/projects", get(list_projects))
        .route("/v1/notes", post(write_note).get(list_notes))
        .route("/v1/digest", get(digest))
        .route("/v1/sync/hello", post(sync_hello))
        .route("/v1/sync/accept-hello", post(sync_accept_hello))
        .route("/v1/sync/ack", post(sync_ack))
        .route("/v1/sync/peer-in", post(sync_peer_in))
        .route(
            "/v1/sync/push-report",
            get(sync_push_report).post(record_push_report),
        )
        .route("/v1/devices", get(list_devices))
        .route("/v1/devices/remove", post(remove_device))
        .route(
            "/v1/keys/recovery",
            get(recovery_state).post(new_recovery_phrase),
        )
        .route("/v1/keys/recovery/offered", post(recovery_offered))
        .route("/v1/keys/recovery/remove", post(remove_recovery_phrase))
        .route("/v1/pair/start", post(pair_start))
        .route("/v1/pair/status", get(pair_status))
        .route("/v1/pair/close", post(pair_close))
        .route("/v1/pair/join", post(pair_join))
        .route("/v1/pair/stop-waiting", post(pair_stop_waiting))
        .route("/v1/sync/snapshot", post(sync_snapshot))
        .route(
            "/v1/sync/snapshot/apply",
            post(sync_snapshot_apply).layer(axum::extract::DefaultBodyLimit::disable()),
        )
        .route("/v1/sync/snapshot/status", get(sync_snapshot_status))
        .route(
            "/v1/maintenance/plaintext-copy",
            post(maintenance_plaintext_copy),
        )
}

#[derive(Serialize)]
struct MemoryResponse {
    id: String,
    content: String,
    memory_type: String,
    confidence: f32,
    source: String,
    created_at: String,
    score: Option<f32>,
    /// The score membership was judged on: cross-encoder or cosine.
    #[serde(skip_serializing_if = "Option::is_none")]
    relevance: Option<f32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    project_path: Option<String>,
    machine_id: String,
    machine_name: String,
    tier: Tier,
    #[serde(skip_serializing_if = "Option::is_none")]
    superseded_by: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    retired_reason: Option<String>,
    /// Always present, null when no evidence of the session survives, so a
    /// client can tell an unknown date from a daemon that predates the field.
    session_at: Option<String>,
    /// When this memory replaced a wrong one through a correction.
    #[serde(skip_serializing_if = "Option::is_none")]
    corrected_at: Option<String>,
    /// Null only for a memory written before authors were recorded.
    author: Option<String>,
    scope: Scope,
}

pub(crate) fn internal_error(e: impl std::fmt::Display + 'static) -> axum::response::Response {
    if crate::clock_gate::is_untrusted(&e) {
        return crate::write_gate::clock_held();
    }
    (
        StatusCode::INTERNAL_SERVER_ERROR,
        Json(serde_json::json!({"error": e.to_string()})),
    )
        .into_response()
}

fn to_response(
    m: Memory,
    score: Option<f32>,
    relevance: Option<f32>,
    machine_names: &std::collections::HashMap<String, String>,
) -> MemoryResponse {
    let machine_name = machine_names
        .get(&m.machine_id)
        .cloned()
        .unwrap_or_default();
    MemoryResponse {
        id: m.id.to_string(),
        content: m.content,
        memory_type: format!("{:?}", m.memory_type).to_lowercase(),
        confidence: m.confidence,
        source: m.source,
        created_at: m.created_at.to_rfc3339(),
        score,
        relevance,
        project_path: m.project_path,
        machine_id: m.machine_id,
        machine_name,
        tier: m.tier,
        superseded_by: m.superseded_by.map(|id| id.to_string()),
        retired_reason: m.retired_reason,
        session_at: m.session_at.map(|t| t.to_rfc3339()),
        corrected_at: None,
        author: m.author,
        scope: m.scope,
    }
}

const MEMORY_TYPES: [MemoryType; 8] = [
    MemoryType::Episodic,
    MemoryType::Semantic,
    MemoryType::Procedural,
    MemoryType::Decision,
    MemoryType::Architecture,
    MemoryType::Debugging,
    MemoryType::Task,
    MemoryType::Question,
];

fn memory_type_name(t: MemoryType) -> String {
    format!("{t:?}").to_lowercase()
}

/// The serde name of a `MemoryType`, or a message naming every accepted
/// value so a caller with a typo learns the vocabulary instead of getting
/// an unfiltered answer.
fn parse_memory_type(s: &str) -> Result<MemoryType, String> {
    MEMORY_TYPES
        .into_iter()
        .find(|t| memory_type_name(*t) == s)
        .ok_or_else(|| {
            let valid: Vec<String> = MEMORY_TYPES.into_iter().map(memory_type_name).collect();
            format!(
                "unknown memory_type '{s}'; valid values: {}",
                valid.join(", ")
            )
        })
}

fn error_response(status: StatusCode, message: impl std::fmt::Display) -> axum::response::Response {
    (
        status,
        Json(serde_json::json!({"error": message.to_string()})),
    )
        .into_response()
}

fn bad_request(message: impl std::fmt::Display) -> axum::response::Response {
    error_response(StatusCode::BAD_REQUEST, message)
}

pub(crate) fn retry_write<F, T>(mut op: F) -> anyhow::Result<T>
where
    F: FnMut() -> anyhow::Result<T>,
{
    let mut last_err = None;
    for attempt in 0..5u32 {
        match op() {
            Ok(v) => return Ok(v),
            Err(e) => {
                last_err = Some(e);
                std::thread::sleep(std::time::Duration::from_millis(50 * 2u64.pow(attempt)));
            }
        }
    }
    Err(last_err.unwrap())
}