Skip to main content

second_brain_api/routes/
mod.rs

1mod consolidate;
2mod correct;
3mod delete;
4mod devices;
5mod digest;
6mod ingest;
7mod maintenance;
8mod memory;
9mod notes;
10mod pair;
11mod project_names;
12mod raw_answer;
13mod recall;
14mod recovery;
15mod rerank_budget;
16mod status;
17mod sync;
18
19use std::sync::Arc;
20
21use axum::http::StatusCode;
22use axum::response::IntoResponse;
23use axum::routing::{delete, get, post};
24use axum::{Json, Router};
25use second_brain_core::schema::{Memory, MemoryType, Scope, Tier};
26use serde::Serialize;
27
28use crate::AppState;
29
30use consolidate::{consolidate_batch, consolidate_cleanup, consolidate_store, daily_memories};
31use correct::correct;
32use devices::{list_devices, remove_device};
33use digest::digest;
34use ingest::{ingest, reingest};
35use maintenance::{
36    backfill_project_paths, maintenance_backup, maintenance_plaintext_copy, maintenance_repair,
37    maintenance_vacuum,
38};
39use memory::{associate, forget, get_memory, remember, traverse};
40use notes::{list_notes, write_note};
41use pair::{pair_close, pair_join, pair_start, pair_status, pair_stop_waiting};
42use recall::{context, recall};
43use recovery::{new_recovery_phrase, recovery_offered, recovery_state, remove_recovery_phrase};
44use status::{health, health_report, list_projects, status};
45use sync::{
46    record_push_report, set_sync_state, sync_accept_hello, sync_ack, sync_compact, sync_export,
47    sync_hello, sync_import, sync_peer_in, sync_prune_relations, sync_push_report, sync_snapshot,
48    sync_snapshot_apply, sync_snapshot_status, sync_status, sync_version,
49};
50
51pub fn router() -> Router<Arc<AppState>> {
52    Router::new()
53        .route("/health", get(health))
54        .route("/v1/recall", post(recall))
55        .route("/v1/remember", post(remember))
56        .route("/v1/associate", post(associate))
57        .route("/v1/correct", post(correct))
58        .route("/v1/memory/{id}", get(get_memory))
59        .route("/v1/memory/{id}", delete(forget))
60        .route("/v1/delete", post(delete::delete_scope))
61        .route("/v1/delete/{key}", get(delete::delete_status))
62        .route("/v1/context", post(context))
63        .route("/v1/ingest", post(ingest))
64        .route("/v1/reingest", post(reingest))
65        .route("/v1/consolidate/batch", get(consolidate_batch))
66        .route("/v1/consolidate/store", post(consolidate_store))
67        .route("/v1/consolidate/cleanup", post(consolidate_cleanup))
68        .route(
69            "/v1/consolidate/near-duplicates",
70            get(crate::near_duplicates::list),
71        )
72        .route(
73            "/v1/consolidate/near-duplicates/review",
74            post(crate::near_duplicates::review),
75        )
76        .route(
77            "/v1/consolidate/near-duplicates/reopen",
78            post(crate::near_duplicates::reopen),
79        )
80        .route("/v1/consolidate/merge", post(crate::near_duplicates::merge))
81        .route("/v1/daily/memories", post(daily_memories))
82        .route("/v1/graph/traverse", get(traverse))
83        .route("/v1/status", get(status))
84        .route("/v1/health", get(health_report))
85        .route("/v1/maintenance/repair", post(maintenance_repair))
86        .route("/v1/maintenance/vacuum", post(maintenance_vacuum))
87        .route("/v1/maintenance/backup", post(maintenance_backup))
88        .route("/v1/redaction", get(crate::stored_redaction::report))
89        .route(
90            "/v1/maintenance/refile-nested-projects",
91            post(crate::repairs::refile_nested_projects),
92        )
93        .route(
94            "/v1/maintenance/restore-explicit",
95            post(crate::repairs::restore_explicit),
96        )
97        .route(
98            "/v1/maintenance/refile-stray-projects",
99            post(crate::repairs::refile_stray_projects),
100        )
101        .route("/v1/sync/version", get(sync_version))
102        .route("/v1/sync/export", post(sync_export))
103        .route("/v1/sync/import", post(sync_import))
104        .route("/v1/sync/status", get(sync_status))
105        .route("/v1/sync/prune-relations", post(sync_prune_relations))
106        .route("/v1/sync/compact", post(sync_compact))
107        .route("/v1/sync/state", post(set_sync_state))
108        .route("/v1/backfill-project-paths", post(backfill_project_paths))
109        .route(
110            "/v1/backfill-session-at",
111            post(crate::repairs::backfill_session_at),
112        )
113        .route("/v1/projects", get(list_projects))
114        .route("/v1/notes", post(write_note).get(list_notes))
115        .route("/v1/digest", get(digest))
116        .route("/v1/sync/hello", post(sync_hello))
117        .route("/v1/sync/accept-hello", post(sync_accept_hello))
118        .route("/v1/sync/ack", post(sync_ack))
119        .route("/v1/sync/peer-in", post(sync_peer_in))
120        .route(
121            "/v1/sync/push-report",
122            get(sync_push_report).post(record_push_report),
123        )
124        .route("/v1/devices", get(list_devices))
125        .route("/v1/devices/remove", post(remove_device))
126        .route(
127            "/v1/keys/recovery",
128            get(recovery_state).post(new_recovery_phrase),
129        )
130        .route("/v1/keys/recovery/offered", post(recovery_offered))
131        .route("/v1/keys/recovery/remove", post(remove_recovery_phrase))
132        .route("/v1/pair/start", post(pair_start))
133        .route("/v1/pair/status", get(pair_status))
134        .route("/v1/pair/close", post(pair_close))
135        .route("/v1/pair/join", post(pair_join))
136        .route("/v1/pair/stop-waiting", post(pair_stop_waiting))
137        .route("/v1/sync/snapshot", post(sync_snapshot))
138        .route(
139            "/v1/sync/snapshot/apply",
140            post(sync_snapshot_apply).layer(axum::extract::DefaultBodyLimit::disable()),
141        )
142        .route("/v1/sync/snapshot/status", get(sync_snapshot_status))
143        .route(
144            "/v1/maintenance/plaintext-copy",
145            post(maintenance_plaintext_copy),
146        )
147}
148
149#[derive(Serialize)]
150struct MemoryResponse {
151    id: String,
152    content: String,
153    memory_type: String,
154    confidence: f32,
155    source: String,
156    created_at: String,
157    score: Option<f32>,
158    /// The score membership was judged on: cross-encoder or cosine.
159    #[serde(skip_serializing_if = "Option::is_none")]
160    relevance: Option<f32>,
161    #[serde(skip_serializing_if = "Option::is_none")]
162    project_path: Option<String>,
163    machine_id: String,
164    machine_name: String,
165    tier: Tier,
166    #[serde(skip_serializing_if = "Option::is_none")]
167    superseded_by: Option<String>,
168    #[serde(skip_serializing_if = "Option::is_none")]
169    retired_reason: Option<String>,
170    /// Always present, null when no evidence of the session survives, so a
171    /// client can tell an unknown date from a daemon that predates the field.
172    session_at: Option<String>,
173    /// When this memory replaced a wrong one through a correction.
174    #[serde(skip_serializing_if = "Option::is_none")]
175    corrected_at: Option<String>,
176    /// Null only for a memory written before authors were recorded.
177    author: Option<String>,
178    scope: Scope,
179}
180
181pub(crate) fn internal_error(e: impl std::fmt::Display + 'static) -> axum::response::Response {
182    if crate::clock_gate::is_untrusted(&e) {
183        return crate::write_gate::clock_held();
184    }
185    (
186        StatusCode::INTERNAL_SERVER_ERROR,
187        Json(serde_json::json!({"error": e.to_string()})),
188    )
189        .into_response()
190}
191
192fn to_response(
193    m: Memory,
194    score: Option<f32>,
195    relevance: Option<f32>,
196    machine_names: &std::collections::HashMap<String, String>,
197) -> MemoryResponse {
198    let machine_name = machine_names
199        .get(&m.machine_id)
200        .cloned()
201        .unwrap_or_default();
202    MemoryResponse {
203        id: m.id.to_string(),
204        content: m.content,
205        memory_type: format!("{:?}", m.memory_type).to_lowercase(),
206        confidence: m.confidence,
207        source: m.source,
208        created_at: m.created_at.to_rfc3339(),
209        score,
210        relevance,
211        project_path: m.project_path,
212        machine_id: m.machine_id,
213        machine_name,
214        tier: m.tier,
215        superseded_by: m.superseded_by.map(|id| id.to_string()),
216        retired_reason: m.retired_reason,
217        session_at: m.session_at.map(|t| t.to_rfc3339()),
218        corrected_at: None,
219        author: m.author,
220        scope: m.scope,
221    }
222}
223
224const MEMORY_TYPES: [MemoryType; 8] = [
225    MemoryType::Episodic,
226    MemoryType::Semantic,
227    MemoryType::Procedural,
228    MemoryType::Decision,
229    MemoryType::Architecture,
230    MemoryType::Debugging,
231    MemoryType::Task,
232    MemoryType::Question,
233];
234
235fn memory_type_name(t: MemoryType) -> String {
236    format!("{t:?}").to_lowercase()
237}
238
239/// The serde name of a `MemoryType`, or a message naming every accepted
240/// value so a caller with a typo learns the vocabulary instead of getting
241/// an unfiltered answer.
242fn parse_memory_type(s: &str) -> Result<MemoryType, String> {
243    MEMORY_TYPES
244        .into_iter()
245        .find(|t| memory_type_name(*t) == s)
246        .ok_or_else(|| {
247            let valid: Vec<String> = MEMORY_TYPES.into_iter().map(memory_type_name).collect();
248            format!(
249                "unknown memory_type '{s}'; valid values: {}",
250                valid.join(", ")
251            )
252        })
253}
254
255fn error_response(status: StatusCode, message: impl std::fmt::Display) -> axum::response::Response {
256    (
257        status,
258        Json(serde_json::json!({"error": message.to_string()})),
259    )
260        .into_response()
261}
262
263fn bad_request(message: impl std::fmt::Display) -> axum::response::Response {
264    error_response(StatusCode::BAD_REQUEST, message)
265}
266
267pub(crate) fn retry_write<F, T>(mut op: F) -> anyhow::Result<T>
268where
269    F: FnMut() -> anyhow::Result<T>,
270{
271    let mut last_err = None;
272    for attempt in 0..5u32 {
273        match op() {
274            Ok(v) => return Ok(v),
275            Err(e) => {
276                last_err = Some(e);
277                std::thread::sleep(std::time::Duration::from_millis(50 * 2u64.pow(attempt)));
278            }
279        }
280    }
281    Err(last_err.unwrap())
282}