vectorless/retrieval/search/
trait.rs

1// Copyright (c) 2026 vectorless developers
2// SPDX-License-Identifier: Apache-2.0
3
4//! Search algorithm trait and common types.
5
6use async_trait::async_trait;
7
8use super::super::RetrievalContext;
9use super::super::types::{NavigationStep, SearchPath};
10use crate::document::DocumentTree;
11use crate::retrieval::pilot::Pilot;
12
13/// Result of a search operation.
14#[derive(Debug, Clone)]
15pub struct SearchResult {
16    /// Paths found during search.
17    pub paths: Vec<SearchPath>,
18    /// Navigation trace.
19    pub trace: Vec<NavigationStep>,
20    /// Number of nodes visited.
21    pub nodes_visited: usize,
22    /// Number of iterations performed.
23    pub iterations: usize,
24    /// Number of Pilot interventions.
25    pub pilot_interventions: usize,
26}
27
28impl Default for SearchResult {
29    fn default() -> Self {
30        Self {
31            paths: Vec::new(),
32            trace: Vec::new(),
33            nodes_visited: 0,
34            iterations: 0,
35            pilot_interventions: 0,
36        }
37    }
38}
39
40/// Configuration for search algorithms.
41#[derive(Debug, Clone)]
42pub struct SearchConfig {
43    /// Maximum number of results to return.
44    pub top_k: usize,
45    /// Beam width for multi-path search.
46    pub beam_width: usize,
47    /// Maximum iterations.
48    pub max_iterations: usize,
49    /// Minimum score to include a path.
50    pub min_score: f32,
51    /// Whether to include leaf nodes only.
52    pub leaf_only: bool,
53}
54
55impl Default for SearchConfig {
56    fn default() -> Self {
57        Self {
58            top_k: 5,
59            beam_width: 3,
60            max_iterations: 10,
61            min_score: 0.1,
62            leaf_only: false,
63        }
64    }
65}
66
67/// Trait for tree search algorithms.
68///
69/// Implementations provide different strategies for exploring
70/// the document tree to find relevant content.
71///
72/// # Pilot Integration
73///
74/// Search algorithms can optionally accept a [`Pilot`] for intelligent
75/// navigation guidance at key decision points. When a Pilot is provided,
76/// the algorithm consults it at:
77/// - Fork points (multiple candidates)
78/// - Low confidence situations
79/// - Backtracking decisions
80///
81/// When no Pilot is provided (None), the algorithm uses its default
82/// scoring mechanism.
83#[async_trait]
84pub trait SearchTree: Send + Sync {
85    /// Search the tree for relevant nodes.
86    ///
87    /// # Arguments
88    ///
89    /// * `tree` - The document tree to search
90    /// * `context` - Retrieval context with query information
91    /// * `config` - Search configuration
92    /// * `pilot` - Optional Pilot for navigation guidance
93    ///
94    /// # Returns
95    ///
96    /// A `SearchResult` with paths and trace information.
97    async fn search(
98        &self,
99        tree: &DocumentTree,
100        context: &RetrievalContext,
101        config: &SearchConfig,
102        pilot: Option<&dyn Pilot>,
103    ) -> SearchResult;
104
105    /// Search without Pilot (uses default algorithm scoring).
106    async fn search_without_pilot(
107        &self,
108        tree: &DocumentTree,
109        context: &RetrievalContext,
110        config: &SearchConfig,
111    ) -> SearchResult {
112        self.search(tree, context, config, None).await
113    }
114
115    /// Get the name of this search algorithm.
116    fn name(&self) -> &str;
117}
vectorless/retrieval/search/trait.rs

vectorless/retrieval/search/
trait.rs
