fornix 0.2.0

Knowledge storage, retrieval, and graph infrastructure for cognitive systems
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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

//! Hybrid search result types.

use std::collections::HashMap;

/// Breakdown of how a hybrid score was computed.
#[derive(Debug, Clone, Default)]
pub struct ScoreBreakdown {
    /// The BM25 component score, if available.
    pub bm25: Option<f32>,
    /// The vector component score, if available.
    pub vector: Option<f32>,
    /// The final hybrid score after fusion.
    pub hybrid: f32,
    /// Label identifying the fusion path used.
    pub fusion_path: String,
}

/// Decomposition of the confidence score.
#[derive(Debug, Clone)]
pub struct ConfidenceComponents {
    /// Relative position of this result's score in the full result set.
    pub percentile: f32,
    /// Score gap between this result and the next one, normalised.
    pub margin: f32,
    /// Whether both BM25 and vector agreed on this result (1.0 = yes, 0.5 = no).
    pub agreement: f32,
}

/// A single hybrid search result.
#[derive(Debug, Clone)]
pub struct HybridResult {
    /// The document identifier.
    pub id: String,
    /// BM25 score for this document, if it appeared in BM25 results.
    pub bm25_score: Option<f32>,
    /// Vector similarity score for this document, if it appeared in vector results.
    pub vector_score: Option<f32>,
    /// The combined hybrid score after fusion.
    pub hybrid_score: f32,
    /// Per-component score breakdown for observability.
    pub score_breakdown: ScoreBreakdown,
    /// Confidence score in `[0.0, 1.0]`, computed after fusion.
    pub confidence_score: Option<f32>,
    /// Detailed confidence components, populated alongside `confidence_score`.
    pub confidence_components: Option<ConfidenceComponents>,
    /// Document metadata carried through from the source adapters.
    pub metadata: HashMap<String, serde_json::Value>,
}

impl HybridResult {
    /// Construct a result with the minimum required fields.
    pub fn new(
        id: impl Into<String>,
        hybrid_score: f32,
        bm25_score: Option<f32>,
        vector_score: Option<f32>,
        fusion_path: impl Into<String>,
    ) -> Self {
        let breakdown = ScoreBreakdown {
            bm25: bm25_score,
            vector: vector_score,
            hybrid: hybrid_score,
            fusion_path: fusion_path.into(),
        };
        Self {
            id: id.into(),
            bm25_score,
            vector_score,
            hybrid_score,
            score_breakdown: breakdown,
            confidence_score: None,
            confidence_components: None,
            metadata: HashMap::new(),
        }
    }

    /// Returns `true` if this result appeared in both BM25 and vector results.
    pub fn has_both_sources(&self) -> bool {
        self.bm25_score.is_some() && self.vector_score.is_some()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn result(hybrid: f32, bm25: Option<f32>, vec: Option<f32>) -> HybridResult {
        HybridResult::new("id", hybrid, bm25, vec, "rrf")
    }

    #[test]
    fn new_sets_all_fields() {
        let r = result(0.8, Some(0.5), Some(0.9));
        assert_eq!(r.id, "id");
        assert!((r.hybrid_score - 0.8).abs() < 1e-6);
        assert_eq!(r.bm25_score, Some(0.5));
        assert_eq!(r.vector_score, Some(0.9));
        assert_eq!(r.score_breakdown.fusion_path, "rrf");
    }

    #[test]
    fn has_both_sources_true_when_both_present() {
        assert!(result(0.5, Some(0.3), Some(0.7)).has_both_sources());
    }

    #[test]
    fn has_both_sources_false_when_only_bm25() {
        assert!(!result(0.5, Some(0.3), None).has_both_sources());
    }

    #[test]
    fn has_both_sources_false_when_only_vector() {
        assert!(!result(0.5, None, Some(0.7)).has_both_sources());
    }

    #[test]
    fn confidence_is_none_by_default() {
        assert!(result(0.5, Some(0.3), Some(0.7)).confidence_score.is_none());
    }

    #[test]
    fn breakdown_carries_component_scores() {
        let r = result(0.8, Some(0.6), Some(0.9));
        assert_eq!(r.score_breakdown.bm25, Some(0.6));
        assert_eq!(r.score_breakdown.vector, Some(0.9));
        assert!((r.score_breakdown.hybrid - 0.8).abs() < 1e-6);
    }

    #[test]
    fn metadata_is_empty_by_default() {
        assert!(result(0.5, None, None).metadata.is_empty());
    }
}