Add all-candidates path resolution mode

Author: shisoft

src/apps/wikidata/cli.rs

@@ -130,6 +130,9 @@ pub enum QueryCommands {
         /// Maximum path depth (default: 8)
         #[arg(long, default_value = "8")]
         max_depth: usize,
+        /// Search all resolved endpoint candidates instead of stopping at the best match
+        #[arg(long, default_value_t = false)]
+        all_candidates: bool,
     },
     /// Find top-k shortest simple paths, or all simple paths within bounds
     Paths {
@@ -143,6 +146,9 @@ pub enum QueryCommands {
         /// Maximum number of paths to return; omit to enumerate all paths within bounds
         #[arg(long)]
         limit: Option<usize>,
+        /// Search all resolved endpoint candidates instead of stopping at the best match
+        #[arg(long, default_value_t = false)]
+        all_candidates: bool,
     },
     /// Find structurally similar entities (Jaccard / common-neighbor similarity)
     Similar {
@@ -169,3 +175,53 @@ pub enum QueryCommands {
     /// Start interactive mode (same as the top-level `interactive` command)
     Interactive,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{Cli, Commands, QueryCommands};
+    use clap::Parser;
+
+    #[test]
+    fn path_query_accepts_all_candidates_flag() {
+        let cli = Cli::parse_from([
+            "wikidata_cli",
+            "query",
+            "--server-url",
+            "http://localhost:9090",
+            "path",
+            "Bill Gates",
+            "Microsoft",
+            "--all-candidates",
+        ]);
+
+        match cli.command {
+            Commands::Query {
+                query_command: QueryCommands::Path { all_candidates, .. },
+                ..
+            } => assert!(all_candidates),
+            _ => panic!("unexpected command shape"),
+        }
+    }
+
+    #[test]
+    fn paths_query_accepts_all_candidates_flag() {
+        let cli = Cli::parse_from([
+            "wikidata_cli",
+            "query",
+            "--server-url",
+            "http://localhost:9090",
+            "paths",
+            "Bill Gates",
+            "Microsoft",
+            "--all-candidates",
+        ]);
+
+        match cli.command {
+            Commands::Query {
+                query_command: QueryCommands::Paths { all_candidates, .. },
+                ..
+            } => assert!(all_candidates),
+            _ => panic!("unexpected command shape"),
+        }
+    }
+}

src/apps/wikidata/interactive.rs

@@ -121,19 +121,36 @@ impl InteractiveQueryMode {
             "path" => {
                 let tparts: Vec<&str> = rest.split_whitespace().collect();
                 if tparts.len() < 2 {
-                    println!("Usage: path <from_id> <to_id>");
+                    println!("Usage: path <from_id> <to_id> [--all-candidates]");
                 } else {
-                    self.cmd_path(tparts[0], tparts[1]).await?;
+                    self.cmd_path(
+                        tparts[0],
+                        tparts[1],
+                        tparts
+                            .iter()
+                            .skip(2)
+                            .any(|arg| Self::is_all_candidates_flag(arg)),
+                    )
+                    .await?;
                 }
             }
             "paths" => {
                 let tparts: Vec<&str> = rest.split_whitespace().collect();
                 if tparts.len() < 2 {
-                    println!("Usage: paths <from_id> <to_id> [max_depth] [limit]");
+                    println!(
+                        "Usage: paths <from_id> <to_id> [max_depth] [limit] [--all-candidates]"
+                    );
                 } else {
-                    let max_depth: usize = tparts.get(2).and_then(|s| s.parse().ok()).unwrap_or(8);
-                    let limit = tparts.get(3).and_then(|s| s.parse().ok());
-                    self.cmd_paths(tparts[0], tparts[1], max_depth, limit)
+                    let positionals: Vec<&str> = tparts
+                        .iter()
+                        .copied()
+                        .filter(|arg| !Self::is_all_candidates_flag(arg))
+                        .collect();
+                    let max_depth: usize =
+                        positionals.get(2).and_then(|s| s.parse().ok()).unwrap_or(8);
+                    let limit = positionals.get(3).and_then(|s| s.parse().ok());
+                    let all_candidates = tparts.iter().any(|arg| Self::is_all_candidates_flag(arg));
+                    self.cmd_paths(tparts[0], tparts[1], max_depth, limit, all_candidates)
                         .await?;
                 }
             }
@@ -182,8 +199,12 @@ impl InteractiveQueryMode {
         println!("  traverse <id> [depth]            Graph traversal (depth=1: show connections;");
         println!("                                   depth>1: show subgraph structure)");
         println!("  subgraph <id> [depth]            Extract bounded subgraph");
-        println!("  path <from> <to>                 Find shortest path between two entities");
-        println!("  paths <from> <to> [depth] [limit] Find top-k shortest simple paths");
+        println!(
+            "  path <from> <to> [--all-candidates]                 Find shortest path between two entities"
+        );
+        println!(
+            "  paths <from> <to> [depth] [limit] [--all-candidates] Find top-k shortest simple paths"
+        );
         println!("  similar <id>                     Structurally similar entities (Jaccard,");
         println!("                                   based on shared graph connections)");
         println!("  dsl <json>                       Execute a raw /v1/dsl/query JSON request");
@@ -651,7 +672,12 @@ impl InteractiveQueryMode {
 
     // ── path ─────────────────────────────────────────────────────────────────
 
-    async fn cmd_path(&self, from: &str, to: &str) -> Result<(), Box<dyn std::error::Error>> {
+    async fn cmd_path(
+        &self,
+        from: &str,
+        to: &str,
+        all_candidates: bool,
+    ) -> Result<(), Box<dyn std::error::Error>> {
         let t = Instant::now();
         let req = ShortestPathRequest {
             database: None,
@@ -667,6 +693,7 @@ impl InteractiveQueryMode {
             },
             select: Some(vec!["id".to_string(), "label".to_string()]),
             edge_select: Some(vec!["property_id".to_string()]),
+            all_candidates,
         };
         let result = self.client.dsl_path(req).await?;
         println!(
@@ -688,6 +715,7 @@ impl InteractiveQueryMode {
         to: &str,
         max_depth: usize,
         limit: Option<usize>,
+        all_candidates: bool,
     ) -> Result<(), Box<dyn std::error::Error>> {
         let t = Instant::now();
         let req = PathsRequest {
@@ -706,6 +734,7 @@ impl InteractiveQueryMode {
             limit,
             select: Some(vec!["id".to_string(), "label".to_string()]),
             edge_select: Some(vec!["property_id".to_string()]),
+            all_candidates,
         };
         let result = self.client.dsl_paths(req).await?;
         println!(
@@ -731,6 +760,10 @@ impl InteractiveQueryMode {
         Ok(())
     }
 
+    fn is_all_candidates_flag(arg: &str) -> bool {
+        matches!(arg, "--all-candidates" | "all_candidates")
+    }
+
     // ── similar (structural Jaccard — shared graph connections) ──────────────
 
     async fn cmd_similar(&self, id: &str) -> Result<(), Box<dyn std::error::Error>> {

src/bin/wikidata_cli.rs

@@ -647,6 +647,7 @@ async fn run_query_command(
             from_id,
             to_id,
             max_depth,
+            all_candidates,
         } => {
             let req = ShortestPathRequest {
                 database: None,
@@ -662,6 +663,7 @@ async fn run_query_command(
                 },
                 select: Some(vec!["id".to_string(), "label".to_string()]),
                 edge_select: Some(vec!["property_id".to_string()]),
+                all_candidates,
             };
             let t = Instant::now();
             let result = client.dsl_path(req).await?;
@@ -682,6 +684,7 @@ async fn run_query_command(
             to_id,
             max_depth,
             limit,
+            all_candidates,
         } => {
             let req = PathsRequest {
                 database: None,
@@ -699,6 +702,7 @@ async fn run_query_command(
                 limit,
                 select: Some(vec!["id".to_string(), "label".to_string()]),
                 edge_select: Some(vec!["property_id".to_string()]),
+                all_candidates,
             };
             let t = Instant::now();
             let result = client.dsl_paths(req).await?;

src/dsl/graph/exec_path.rs

@@ -58,18 +58,38 @@ pub async fn execute_path(
     let coordinator = runtime.search_coordinator();
     let server_id = runtime.server_id();
     let (starts, goals, reverse_path) = select_shortest_path_search_plan(&from_ids, &to_ids);
+    let best = if query.all_candidates {
+        let mut best: Option<(usize, Vec<Id>)> = None;
+        for &goal in goals {
+            let mut result = run_bfs(
+                &coordinator,
+                server_id,
+                starts,
+                &[goal],
+                &query,
+                runtime,
+                reverse_path,
+            )
+            .await?;
 
-    // BfsSearchConfig accepts a single goal. Run repeated BFS searches against
-    // the smaller endpoint set and reverse the resulting path when we search
-    // from the destination side.
-    let mut best: Option<(usize, Vec<Id>)> = None;
-
-    for &goal in goals {
+            if result.found {
+                if reverse_path {
+                    result.path.reverse();
+                }
+                let hops = result.path.len().saturating_sub(1);
+                let is_better = best.as_ref().map_or(true, |(prev, _)| hops < *prev);
+                if is_better {
+                    best = Some((hops, result.path));
+                }
+            }
+        }
+        best
+    } else {
         let mut result = run_bfs(
             &coordinator,
             server_id,
             starts,
-            goal,
+            goals,
             &query,
             runtime,
             reverse_path,
@@ -80,13 +100,11 @@ pub async fn execute_path(
             if reverse_path {
                 result.path.reverse();
             }
-            let hops = result.path.len().saturating_sub(1);
-            let is_better = best.as_ref().map_or(true, |(prev, _)| hops < *prev);
-            if is_better {
-                best = Some((hops, result.path));
-            }
+            Some((result.path.len().saturating_sub(1), result.path))
+        } else {
+            None
         }
-    }
+    };
 
     let Some((hops, path_ids)) = best else {
         return Ok(ShortestPathResult {
@@ -165,7 +183,17 @@ pub async fn execute_paths(
         .await;
     }
 
-    let goal_set: HashSet<Id> = to_ids.iter().copied().collect();
+    let goal_set: HashSet<Id> = if query.all_candidates {
+        to_ids.iter().copied().collect()
+    } else if let Some(goal_id) = shortest_path_ids
+        .as_ref()
+        .and_then(|path| path.last())
+        .copied()
+    {
+        HashSet::from([goal_id])
+    } else {
+        to_ids.iter().copied().collect()
+    };
     let direction_variants = distributed_directions_for_edge_schemas(
         runtime,
         &query.edge_schema_ids,
@@ -268,14 +296,38 @@ async fn find_best_shortest_path_ids_for_paths(
     let coordinator = runtime.search_coordinator();
     let server_id = runtime.server_id();
     let (starts, goals, reverse_path) = select_shortest_path_search_plan(from_ids, to_ids);
-    let mut best: Option<(usize, Vec<Id>)> = None;
+    let best = if query.all_candidates {
+        let mut best: Option<(usize, Vec<Id>)> = None;
+        for &goal in goals {
+            let mut result = run_bfs_for_paths(
+                &coordinator,
+                server_id,
+                starts,
+                &[goal],
+                query,
+                runtime,
+                reverse_path,
+            )
+            .await?;
 
-    for &goal in goals {
+            if result.found {
+                if reverse_path {
+                    result.path.reverse();
+                }
+                let hops = result.path.len().saturating_sub(1);
+                let is_better = best.as_ref().map_or(true, |(prev, _)| hops < *prev);
+                if is_better {
+                    best = Some((hops, result.path));
+                }
+            }
+        }
+        best
+    } else {
         let mut result = run_bfs_for_paths(
             &coordinator,
             server_id,
             starts,
-            goal,
+            goals,
             query,
             runtime,
             reverse_path,
@@ -286,13 +338,11 @@ async fn find_best_shortest_path_ids_for_paths(
             if reverse_path {
                 result.path.reverse();
             }
-            let hops = result.path.len().saturating_sub(1);
-            let is_better = best.as_ref().map_or(true, |(prev, _)| hops < *prev);
-            if is_better {
-                best = Some((hops, result.path));
-            }
+            Some((result.path.len().saturating_sub(1), result.path))
+        } else {
+            None
         }
-    }
+    };
 
     Ok(best.map(|(_, path)| path))
 }
@@ -301,7 +351,7 @@ async fn run_bfs_for_paths(
     coordinator: &SearchCoordinator,
     server_id: u64,
     start: &[Id],
-    goal: Id,
+    goals: &[Id],
     query: &BoundPathsQuery,
     runtime: &Arc<MorpheusRuntime>,
     reverse_direction: bool,
@@ -326,7 +376,7 @@ async fn run_bfs_for_paths(
                 server_id,
                 BfsSearchConfig {
                     start: start.to_vec(),
-                    goal,
+                    goals: goals.to_vec(),
                     max_depth: query.max_depth as u32,
                     max_visited: query.max_visited,
                     expand_options: ExpandJobOptions {
@@ -408,7 +458,7 @@ async fn run_bfs(
     coordinator: &SearchCoordinator,
     server_id: u64,
     start: &[Id],
-    goal: Id,
+    goals: &[Id],
     query: &BoundShortestPathQuery,
     runtime: &Arc<MorpheusRuntime>,
     reverse_direction: bool,
@@ -433,7 +483,7 @@ async fn run_bfs(
                 server_id,
                 BfsSearchConfig {
                     start: start.to_vec(),
-                    goal,
+                    goals: goals.to_vec(),
                     max_depth: query.max_depth as u32,
                     max_visited: query.max_visited,
                     expand_options: ExpandJobOptions {