vectorless 0.1.24

Hierarchical, reasoning-native document intelligence engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

// Copyright (c) 2026 vectorless developers
// SPDX-License-Identifier: Apache-2.0

//! Strategy trait definition.

use async_trait::async_trait;

use super::super::RetrievalContext;
use super::super::types::{NavigationDecision, QueryComplexity};
use crate::document::{DocumentTree, NodeId};

/// Result of evaluating a single node.
#[derive(Debug, Clone)]
pub struct NodeEvaluation {
    /// Relevance score (0.0 - 1.0).
    pub score: f32,
    /// Recommended action for this node.
    pub decision: NavigationDecision,
    /// Optional reasoning for the decision.
    pub reasoning: Option<String>,
}

impl Default for NodeEvaluation {
    fn default() -> Self {
        Self {
            score: 0.5,
            decision: NavigationDecision::ExploreMore,
            reasoning: None,
        }
    }
}

/// Capabilities of a retrieval strategy.
#[derive(Debug, Clone, Copy, Default)]
pub struct StrategyCapabilities {
    /// Whether this strategy uses LLM calls.
    pub uses_llm: bool,
    /// Whether this strategy uses embeddings.
    pub uses_embeddings: bool,
    /// Whether this strategy supports sufficiency checking.
    pub supports_sufficiency: bool,
    /// Typical latency in milliseconds.
    pub typical_latency_ms: u64,
}

/// Trait for retrieval strategies.
///
/// A strategy determines how to navigate the document tree
/// and score nodes for relevance to a query.
#[async_trait]
pub trait RetrievalStrategy: Send + Sync {
    /// Evaluate a single node's relevance to the query.
    ///
    /// This is the core method that determines how relevant
    /// a node is to the current query.
    async fn evaluate_node(
        &self,
        tree: &DocumentTree,
        node_id: NodeId,
        context: &RetrievalContext,
    ) -> NodeEvaluation;

    /// Evaluate multiple nodes in batch.
    ///
    /// Default implementation calls evaluate_node for each node,
    /// but strategies can override for efficiency (e.g., batch LLM calls).
    async fn evaluate_nodes(
        &self,
        tree: &DocumentTree,
        node_ids: &[NodeId],
        context: &RetrievalContext,
    ) -> Vec<NodeEvaluation> {
        let mut results = Vec::with_capacity(node_ids.len());
        for node_id in node_ids {
            results.push(self.evaluate_node(tree, *node_id, context).await);
        }
        results
    }

    /// Get the name of this strategy.
    fn name(&self) -> &str;

    /// Get the capabilities of this strategy.
    fn capabilities(&self) -> StrategyCapabilities;

    /// Check if this strategy is suitable for the given query complexity.
    fn suitable_for_complexity(&self, complexity: QueryComplexity) -> bool;

    /// Estimate the cost of evaluating a set of nodes.
    fn estimate_cost(&self, node_count: usize) -> StrategyCost {
        StrategyCost {
            llm_calls: if self.capabilities().uses_llm {
                node_count
            } else {
                0
            },
            tokens: if self.capabilities().uses_llm {
                node_count * 200
            } else {
                0
            },
        }
    }
}

/// Cost estimate for a strategy operation.
#[derive(Debug, Clone, Copy, Default)]
pub struct StrategyCost {
    /// Number of LLM calls.
    pub llm_calls: usize,
    /// Number of tokens.
    pub tokens: usize,
}