sqlite_graphrag/commands/

recall.rs

//! Handler for the `recall` CLI subcommand.

use crate::cli::MemoryType;
use crate::errors::AppError;
use crate::graph::traverse_from_memories_with_hops;
use crate::i18n::errors_msg;
use crate::output::{self, JsonOutputFormat, RecallItem, RecallResponse};
use crate::paths::AppPaths;
use crate::storage::connection::open_ro;
use crate::storage::entities;
use crate::storage::memories;

/// Arguments for the `recall` subcommand.
///
/// When `--namespace` is omitted the query runs against the `global` namespace,
/// which is the default namespace used by `remember` when no `--namespace` flag
/// is provided. Pass an explicit `--namespace` value to search a different
/// isolated namespace.
#[derive(clap::Args)]
#[command(after_long_help = "EXAMPLES:\n  \
    # Semantic search for top 5 matches\n  \
    sqlite-graphrag recall \"authentication design\" --k 5\n\n  \
    # Disable automatic graph expansion\n  \
    sqlite-graphrag recall \"JWT tokens\" --k 3 --no-graph\n\n  \
    # Limit graph traversal depth and minimum edge weight\n  \
    sqlite-graphrag recall \"auth\" --k 5 --max-hops 2 --min-weight 0.3\n\n  \
    # Filter by memory type\n  \
    sqlite-graphrag recall \"deployment\" --type decision --k 10\n\n  \
    # Cap results by distance threshold\n  \
    sqlite-graphrag recall \"API design\" --k 5 --max-distance 0.8\n\n  \
NOTES:\n  \
    When --no-graph is active, graph traversal is skipped and every result has\n  \
    source=\"direct\". The source field is therefore redundant with --no-graph and\n  \
    may be ignored by callers in that mode.")]
pub struct RecallArgs {
    #[arg(
        allow_hyphen_values = true,
        required_unless_present = "print_schema",
        help = "Search query string (semantic vector search via sqlite-vec)"
    )]
    /// Search query text.
    pub query: Option<String>,
    /// Maximum number of direct vector matches to return.
    ///
    /// Note: this flag controls only `direct_matches`. Graph traversal results
    /// (`graph_matches`) are unbounded by default; use `--max-graph-results` to
    /// cap them independently. The `results` field aggregates both lists.
    /// Validated to the inclusive range `1..=4096` (the upper bound matches
    /// `sqlite-vec`'s knn limit; out-of-range values are rejected at parse time).
    #[arg(short = 'k', long, aliases = ["limit", "top-k"], default_value = "10", value_parser = crate::parsers::parse_k_range)]
    pub k: usize,
    /// Filter by memory.type. Note: distinct from graph entity_type
    /// (project/tool/person/file/concept/incident/decision/memory/dashboard/issue_tracker/organization/location/date)
    /// used in --entities-file.
    #[arg(long, value_enum)]
    pub r#type: Option<MemoryType>,
    /// Namespace scope.
    #[arg(long)]
    pub namespace: Option<String>,
    /// No graph.
    #[arg(long)]
    pub no_graph: bool,
    /// Disable -k cap and return all direct matches without truncation.
    ///
    /// When set, the `-k`/`--k` flag is ignored for `direct_matches` and the
    /// response includes every match above the distance threshold. Useful when
    /// callers need the complete set rather than a top-N preview.
    #[arg(long)]
    pub precise: bool,
    /// Max hops.
    #[arg(long, default_value = "2")]
    pub max_hops: u32,
    /// Min weight.
    #[arg(long, default_value = "0.3")]
    pub min_weight: f64,
    /// Cap the size of `graph_matches` to at most N entries.
    ///
    /// Defaults to unbounded (`None`) so existing pipelines see the same shape
    /// as in v1.0.22 and earlier. Set this when a query touches a dense graph
    /// neighbourhood and the caller only needs a top-N preview. Added in v1.0.23.
    #[arg(long, value_name = "N")]
    pub max_graph_results: Option<usize>,
    /// Filter results by maximum distance. Results with distance greater than this value
    /// are excluded. If all matches exceed this threshold, the command exits with code 4
    /// (`not found`) per the documented public contract.
    /// Default `1.0` disables the filter and preserves the top-k behavior.
    #[arg(long, alias = "min-distance", default_value = "1.0")]
    pub max_distance: f32,
    /// Output format.
    #[arg(long, value_enum, default_value_t = JsonOutputFormat::Json)]
    pub format: JsonOutputFormat,
    /// Path to the SQLite database file.
    #[arg(long)]
    pub db: Option<String>,
    /// Accept `--json` as a no-op because output is already JSON by default.
    #[arg(long, hide = true, help = "No-op; JSON is always emitted on stdout")]
    pub json: bool,
    /// Search across all namespaces instead of a single namespace.
    ///
    /// Cannot be combined with `--namespace`. When set, the query runs against
    /// every namespace and results include a `namespace` field to identify origin.
    #[arg(long, conflicts_with = "namespace")]
    pub all_namespaces: bool,
    /// G58 (v1.0.80): skip the live query embedding and use FTS5 BM25 +
    /// LIKE prefix exclusively. Useful in CI/CD with tight OAuth quota and
    /// in deterministic regression tests that need stable ranking.
    #[arg(
        long,
        help = "Skip live query embedding; use FTS5 BM25 + LIKE prefix only"
    )]
    pub fallback_fts_only: bool,
    /// Emit the JSON Schema for this command's stdout envelope and exit 0
    /// without opening the database or embedding (agent-native R-AN-01).
    #[arg(
        long,
        default_value_t = false,
        help = "Print JSON Schema for recall output and exit"
    )]
    pub print_schema: bool,
}

/// Run.
#[tracing::instrument(skip_all, level = "debug", name = "recall")]
pub fn run(
    args: RecallArgs,
    llm_backend: crate::cli::LlmBackendChoice,
    embedding_backend: crate::cli::EmbeddingBackendChoice,
) -> Result<(), AppError> {
    if args.print_schema {
        return crate::print_schema::emit(crate::print_schema::SchemaId::Recall);
    }
    let start = std::time::Instant::now();
    let _ = args.format;
    let query = args.query.as_deref().unwrap_or("").to_string();
    tracing::debug!(target: "recall", query = %query, k = args.k, "searching");

    // G20: reject graph-specific flags when --no-graph is active
    if args.no_graph {
        if args.max_hops != 2 {
            return Err(AppError::Validation(
                "--max-hops has no effect with --no-graph; remove one".to_string(),
            ));
        }
        if (args.min_weight - 0.3).abs() > f64::EPSILON {
            return Err(AppError::Validation(
                "--min-weight has no effect with --no-graph; remove one".to_string(),
            ));
        }
    }

    if query.trim().is_empty() {
        return Err(AppError::Validation(crate::i18n::validation::empty_query()));
    }
    // Resolve the list of namespaces to search:
    // - empty vec  => all namespaces (sentinel used by knn_search)
    // - single vec => one namespace (default or --namespace value)
    let namespaces: Vec<String> = if args.all_namespaces {
        Vec::new()
    } else {
        vec![crate::namespace::resolve_namespace(
            args.namespace.as_deref(),
        )?]
    };
    // Single namespace string used for graph traversal and error messages.
    let namespace_for_graph = namespaces
        .first()
        .cloned()
        .unwrap_or_else(|| "global".to_string());
    let paths = AppPaths::resolve(args.db.as_deref())?;

    crate::storage::connection::ensure_db_ready(&paths)?;

    output::emit_progress_i18n(
        "Computing query embedding...",
        "Calculando embedding da consulta...",
    );
    let conn = open_ro(&paths.db)?;
    // G58 (v1.0.80): when the live embedding fails (timeout, OAuth contention,
    // rate limit, missing CLI), fall back to FTS5 BM25 + LIKE prefix and
    // surface the degradation through `vec_degraded` + `vec_error` + `warning`
    // on the response envelope. The `--fallback-fts-only` flag forces the
    // skip without even attempting the embedding subprocess.
    // v1.0.84 (ADR-0042): tuple de 4 elementos. `backend_invoked` carrega
    // o discriminador do backend que efetivamente invocou o LLM (ou `None`
    // when the caller asked for `--fallback-fts-only` and never invoked the subprocess).
    let (embedding, vec_degraded, vec_error, backend_invoked) = if args.fallback_fts_only {
        (
            None,
            true,
            Some("fallback_fts_only requested".to_string()),
            None,
        )
    } else {
        // v1.0.82 (GAP-003): forward --llm-backend to embed_with_fallback.
        // v1.0.84 (ADR-0042): extrai o backend que efetivamente invocou o
        // LLM to populate `backend_invoked` in the response envelope.
        // v1.0.85 (G58 / ADR-0043): retry determinístico em OAuthQuota
        // (codex ↔ claude) e backoff 750ms em SlotExhausted antes de
        // accept degradation to pure FTS5.
        match crate::embedder::try_embed_query_with_embedding_choice(
            &paths.models,
            &query,
            embedding_backend,
            llm_backend,
        ) {
            Ok((v, backend)) => (Some(v), false, None, Some(backend.as_str())),
            Err(reason) => {
                let msg = reason.to_string();
                tracing::warn!(target: "recall", fallback_reason = %msg, reason_code = %reason.reason_code(), "live embedding failed; falling back to FTS5");
                (None, true, Some(msg), None)
            }
        }
    };

    let memory_type_str = args.r#type.map(|t| t.as_str());
    // When --precise is set, lift the -k cap so every match is returned; the
    // max_distance filter below will trim irrelevant results instead.
    let effective_k = if args.precise { 100_000 } else { args.k };

    // G58: if the embedding is unavailable, route the entire direct path
    // through FTS5 BM25 + LIKE prefix. Graph traversal is suppressed because
    // it depends on the KNN results to seed the expansion; without the
    // embedding, no seed exists.
    let (direct_matches, memory_ids): (Vec<RecallItem>, Vec<i64>) =
        if let Some(emb) = embedding.as_ref() {
            let knn_results =
                memories::knn_search(&conn, emb, &namespaces, memory_type_str, effective_k)?;
            let mut items: Vec<RecallItem> = Vec::with_capacity(knn_results.len());
            let mut memory_ids: Vec<i64> = Vec::with_capacity(knn_results.len());
            for (memory_id, distance) in knn_results {
                let row = {
                    let mut stmt = conn.prepare_cached(
                        "SELECT id, namespace, name, type, description, body, body_hash,
                            session_id, source, metadata, created_at, updated_at
                     FROM memories WHERE id=?1 AND deleted_at IS NULL",
                    )?;
                    stmt.query_row(rusqlite::params![memory_id], |r| {
                        Ok(memories::MemoryRow {
                            id: r.get(0)?,
                            namespace: r.get(1)?,
                            name: r.get(2)?,
                            memory_type: r.get(3)?,
                            description: r.get(4)?,
                            body: r.get(5)?,
                            body_hash: r.get(6)?,
                            session_id: r.get(7)?,
                            source: r.get(8)?,
                            metadata: r.get(9)?,
                            created_at: r.get(10)?,
                            updated_at: r.get(11)?,
                            deleted_at: None,
                        })
                    })
                    .ok()
                };
                if let Some(row) = row {
                    let snippet: String = row.body.chars().take(300).collect();
                    items.push(RecallItem {
                        memory_id: row.id,
                        name: row.name,
                        namespace: row.namespace,
                        memory_type: row.memory_type,
                        description: row.description,
                        snippet,
                        distance,
                        score: RecallItem::score_from_distance(distance),
                        source: "direct".to_string(),
                        graph_depth: None,
                    });
                    memory_ids.push(memory_id);
                }
            }
            (items, memory_ids)
        } else {
            // FTS5 BM25 + LIKE prefix fallback path. The same `fts_search` helper
            // is used as in `hybrid-search`; distance is approximated by
            // 1.0 / (rank + 1) so the score is in (0, 1] and comparable to the
            // vector path's `1.0 - distance`. Note: only the FIRST effective_k
            // results are kept to preserve the top-N contract.
            let fts_rows = memories::fts_search(
                &conn,
                &query,
                &namespace_for_graph,
                memory_type_str,
                effective_k,
            )?;
            let mut items: Vec<RecallItem> = Vec::with_capacity(fts_rows.len());
            for (rank, row) in fts_rows.into_iter().enumerate() {
                let dist = 1.0 - 1.0 / (rank as f32 + 1.0);
                let snippet: String = row.body.chars().take(300).collect();
                items.push(RecallItem {
                    memory_id: row.id,
                    name: row.name,
                    namespace: row.namespace,
                    memory_type: row.memory_type,
                    description: row.description,
                    snippet,
                    distance: dist,
                    score: RecallItem::score_from_distance(dist),
                    source: "fts_fallback".to_string(),
                    graph_depth: None,
                });
            }
            (items, Vec::new())
        };

    let mut graph_matches = Vec::with_capacity(8);
    if let Some(emb) = (!args.no_graph).then_some(()).and(embedding.as_ref()) {
        let entity_knn = entities::knn_search(&conn, emb, &namespace_for_graph, 5)?;
        let entity_ids: Vec<i64> = entity_knn.iter().map(|(id, _)| *id).collect();

        let all_seed_ids: Vec<i64> = memory_ids
            .iter()
            .chain(entity_ids.iter())
            .copied()
            .collect();

        if !all_seed_ids.is_empty() {
            let graph_memory_ids = traverse_from_memories_with_hops(
                &conn,
                &all_seed_ids,
                &namespace_for_graph,
                args.min_weight,
                args.max_hops,
            )?;

            for (graph_mem_id, hop) in graph_memory_ids {
                // v1.0.23: respect the optional cap on graph results so dense
                // neighbourhoods do not flood the response unintentionally.
                if let Some(cap) = args.max_graph_results {
                    if graph_matches.len() >= cap {
                        break;
                    }
                }
                let row = {
                    let mut stmt = conn.prepare_cached(
                        "SELECT id, namespace, name, type, description, body, body_hash,
                                session_id, source, metadata, created_at, updated_at
                         FROM memories WHERE id=?1 AND deleted_at IS NULL",
                    )?;
                    stmt.query_row(rusqlite::params![graph_mem_id], |r| {
                        Ok(memories::MemoryRow {
                            id: r.get(0)?,
                            namespace: r.get(1)?,
                            name: r.get(2)?,
                            memory_type: r.get(3)?,
                            description: r.get(4)?,
                            body: r.get(5)?,
                            body_hash: r.get(6)?,
                            session_id: r.get(7)?,
                            source: r.get(8)?,
                            metadata: r.get(9)?,
                            created_at: r.get(10)?,
                            updated_at: r.get(11)?,
                            deleted_at: None,
                        })
                    })
                    .ok()
                };
                if let Some(row) = row {
                    let snippet: String = row.body.chars().take(300).collect();
                    let graph_distance = 1.0 - 1.0 / (hop as f32 + 1.0);
                    graph_matches.push(RecallItem {
                        memory_id: row.id,
                        name: row.name,
                        namespace: row.namespace,
                        memory_type: row.memory_type,
                        description: row.description,
                        snippet,
                        distance: graph_distance,
                        score: RecallItem::score_from_distance(graph_distance),
                        source: "graph".to_string(),
                        graph_depth: Some(hop),
                    });
                }
            }
        }
    }

    // Filtrar por max_distance se < 1.0 (ativado). Se nenhum hit dentro do threshold, exit 4.
    if args.max_distance < 1.0 && !vec_degraded {
        let has_relevant = direct_matches
            .iter()
            .any(|item| item.distance <= args.max_distance);
        if !has_relevant {
            return Err(AppError::NotFound(errors_msg::no_recall_results(
                args.max_distance,
                &query,
                &namespace_for_graph,
            )));
        }
    }

    let results: Vec<RecallItem> = direct_matches
        .iter()
        .cloned()
        .chain(graph_matches.iter().cloned())
        .collect();

    let warning = if vec_degraded {
        Some(
            "live query embedding unavailable; results are FTS5 BM25 only (semantic relevance reduced)"
                .to_string(),
        )
    } else {
        None
    };

    output::emit_json(&RecallResponse {
        query,
        k: args.k,
        direct_matches,
        graph_matches,
        results,
        elapsed_ms: start.elapsed().as_millis() as u64,
        vec_degraded,
        vec_error: vec_error.clone(),
        warning,
        backend_invoked,
        vec_degraded_reason: if vec_degraded { vec_error } else { None },
    })?;

    Ok(())
}

#[cfg(test)]
mod tests {
    use crate::output::{RecallItem, RecallResponse};

    fn make_item(name: &str, distance: f32, source: &str) -> RecallItem {
        RecallItem {
            memory_id: 1,
            name: name.to_string(),
            namespace: "global".to_string(),
            memory_type: "fact".to_string(),
            description: "desc".to_string(),
            snippet: "snippet".to_string(),
            distance,
            score: RecallItem::score_from_distance(distance),
            source: source.to_string(),
            graph_depth: if source == "graph" { Some(0) } else { None },
        }
    }

    // Bug M-A5: every RecallItem carries a non-null cosine similarity score.
    #[test]
    fn recall_item_score_is_present_and_finite_for_direct_match() {
        let item = make_item("mem", 0.25, "direct");
        let json = serde_json::to_value(&item).expect("serialization failed");
        let score = json["score"].as_f64().expect("score must be a number");
        assert!(
            (0.0..=1.0).contains(&score),
            "score must be in [0, 1], got {score}"
        );
        assert!(
            (score - 0.75).abs() < 1e-6,
            "score must equal 1 - distance for canonical case"
        );
    }

    #[test]
    fn recall_item_score_clamps_distance_outside_unit_range() {
        // Pathological distances must not yield score outside [0, 1] or NaN.
        assert_eq!(RecallItem::score_from_distance(2.0), 0.0);
        assert_eq!(RecallItem::score_from_distance(-0.5), 1.0);
        assert_eq!(RecallItem::score_from_distance(f32::NAN), 0.0);
    }

    #[test]
    fn recall_response_serializes_required_fields() {
        let resp = RecallResponse {
            query: "rust memory".to_string(),
            k: 5,
            direct_matches: vec![make_item("mem-a", 0.12, "direct")],
            graph_matches: vec![],
            results: vec![make_item("mem-a", 0.12, "direct")],
            elapsed_ms: 42,
            vec_degraded: false,
            vec_error: None,
            warning: None,
            backend_invoked: None,
            vec_degraded_reason: None,
        };

        let json = serde_json::to_value(&resp).expect("serialization failed");
        assert_eq!(json["query"], "rust memory");
        assert_eq!(json["k"], 5);
        assert_eq!(json["elapsed_ms"], 42u64);
        assert!(json["direct_matches"].is_array());
        assert!(json["graph_matches"].is_array());
        assert!(json["results"].is_array());
    }

    #[test]
    fn recall_item_serializes_renamed_type() {
        let item = make_item("mem-test", 0.25, "direct");
        let json = serde_json::to_value(&item).expect("serialization failed");

        // The memory_type field is renamed to "type" in JSON
        assert_eq!(json["type"], "fact");
        assert_eq!(json["distance"], 0.25f32);
        assert_eq!(json["source"], "direct");
    }

    #[test]
    fn recall_response_results_contains_direct_and_graph() {
        let direct = make_item("d-mem", 0.10, "direct");
        let graph = make_item("g-mem", 0.0, "graph");

        let resp = RecallResponse {
            query: "query".to_string(),
            k: 10,
            direct_matches: vec![direct.clone()],
            graph_matches: vec![graph.clone()],
            results: vec![direct, graph],
            elapsed_ms: 10,
            vec_degraded: false,
            vec_error: None,
            warning: None,
            backend_invoked: None,
            vec_degraded_reason: None,
        };

        let json = serde_json::to_value(&resp).expect("serialization failed");
        assert_eq!(json["direct_matches"].as_array().unwrap().len(), 1);
        assert_eq!(json["graph_matches"].as_array().unwrap().len(), 1);
        assert_eq!(json["results"].as_array().unwrap().len(), 2);
        assert_eq!(json["results"][0]["source"], "direct");
        assert_eq!(json["results"][1]["source"], "graph");
    }

    #[test]
    fn recall_response_empty_serializes_empty_arrays() {
        let resp = RecallResponse {
            query: "nothing".to_string(),
            k: 3,
            direct_matches: vec![],
            graph_matches: vec![],
            results: vec![],
            elapsed_ms: 1,
            vec_degraded: false,
            vec_error: None,
            warning: None,
            backend_invoked: None,
            vec_degraded_reason: None,
        };

        let json = serde_json::to_value(&resp).expect("serialization failed");
        assert_eq!(json["direct_matches"].as_array().unwrap().len(), 0);
        assert_eq!(json["results"].as_array().unwrap().len(), 0);
    }

    #[test]
    fn graph_matches_distance_uses_hop_count_proxy() {
        // Verify the hop-count proxy formula: 1.0 - 1.0 / (hop + 1.0)
        // hop=0 → 0.0 (seed-level entity, identity distance)
        // hop=1 → 0.5
        // hop=2 → ≈ 0.667
        // hop=3 → 0.75
        let cases: &[(u32, f32)] = &[(0, 0.0), (1, 0.5), (2, 0.6667), (3, 0.75)];
        for &(hop, expected) in cases {
            let d = 1.0_f32 - 1.0 / (hop as f32 + 1.0);
            assert!(
                (d - expected).abs() < 0.001,
                "hop={hop} expected={expected} got={d}"
            );
        }
    }
}