khive-retrieval 0.10.0

Hybrid retrieval composer (HNSW + BM25 + fusion + graph + cross-encoder) with deterministic scoring
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

// REASON: format_args! inlining would break compatibility with older Rust toolchains in CI
#![allow(clippy::uninlined_format_args)]
// REASON: benchmark helpers use hand-tuned constants close to Rust built-ins (e.g. 1.0/3.0)
#![allow(clippy::approx_constant)]

//! Hybrid search and ranking with deterministic scoring for khive.
//!
//! Combines HNSW vector search, BM25 keyword search, and RRF fusion into a unified
//! retrieval layer. All scores use `DeterministicScore` for cross-platform consistency.
//! See `docs/architecture.md` for module layout, design principles, ID bridging
//! strategies, and trait composition guide.

#![warn(missing_docs)]
#![warn(clippy::all)]

#[cfg(feature = "storage-adapters")]
pub mod adapters;
#[cfg(feature = "ann")]
#[doc(hidden)]
pub mod ann;
pub mod error;
pub mod eval;
pub mod hit;
pub mod hybrid;
pub mod materialization;
pub mod policy;
pub mod search_config;
pub mod timeout;

// Re-export adapter types
#[cfg(feature = "storage-adapters")]
pub use adapters::{StorageKeywordSearch, StorageVectorSearch};

// Re-export core types
pub use error::{ErrorKind, Result, RetrievalError};
pub use hit::{HybridSearchOutcome, RankScoreKind, SearchHit, SearchSignals, SearchSource};

#[cfg(feature = "bm25")]
pub use khive_bm25::{Bm25Config, Bm25Index, Bm25Stats, DocumentId, SearchContext};
pub use khive_fusion::{
    fuse, normalize_weights, reciprocal_rank_fusion, weighted_fusion, weights_are_normalized,
    FusionStrategy, DEFAULT_RRF_K,
};
#[cfg(feature = "hnsw")]
pub use khive_hnsw::{
    DistanceMetric, HnswCheckpointConfig, HnswConfig, HnswIndex, HnswSearchContext, HnswSnapshot,
    NodeId, RebuildStats, TombstoneStats,
};
// Formal proof: khive.Retrieval.HNSW.checkpoint_correctness
pub use hybrid::{
    fuse_search_results, fuse_search_results_checked, HybridConfig, HybridSearcher,
    IdentityReranker, KeywordSearch, Query, Reranker, VectorSearch,
};
#[cfg(feature = "checkpoint")]
pub use khive_hnsw::{HnswCheckpoint, HnswCheckpointStore};
// Native cross-encoder scaffold (ADR-042): the scorer trait and reranker are generic
// and carry no khive-inference dependency, so this seam ships behind `native-rerank`
// ahead of the model port. TODO(port-rerank): khive-inference model impl still deferred.
#[cfg(feature = "native-rerank")]
pub use hybrid::{CrossEncoderScorer, NativeCrossEncoderReranker, RerankDocumentResolver};
pub use materialization::{
    materialize_ranked_prefix, DropCounts, DropDiagnostic, DropReason, MaterializationDecision,
    MaterializationError, MaterializationLimitError, MaterializationLimits, MaterializedItem,
    MaterializedPrefix, RankedCandidate, MAX_MATERIALIZATION_CANDIDATES,
    MAX_MATERIALIZATION_DIAGNOSTICS, MAX_MATERIALIZATION_DROP_REASONS,
    MAX_MATERIALIZATION_LOADER_BATCH, MAX_MATERIALIZATION_OUTPUTS,
};
pub use policy::{filter_by_policy, filter_by_predicate, ClearanceLevel, SearchPolicy};
pub use search_config::SearchConfig;
pub use timeout::{
    search_with_cancellation, search_with_deadline, search_with_optional_timeout,
    search_with_timeout,
};

/// Re-exports from `lattice-embed`. Use these instead of depending on `lattice-embed` directly.
pub mod embed {
    // Core types and traits (always available, no feature gate needed)
    /// Result alias for embedding operations.
    pub use lattice_embed::Result as EmbedResult;
    pub use lattice_embed::{EmbedError, EmbeddingModel, EmbeddingService};

    // Native model implementations (pure Rust lattice-embed via "embed" feature)
    #[cfg(feature = "embed")]
    pub use lattice_embed::{CachedEmbeddingService, NativeEmbeddingService};
}