khive_retrieval/
lib.rs

1// REASON: format_args! inlining would break compatibility with older Rust toolchains in CI
2#![allow(clippy::uninlined_format_args)]
3// REASON: field_reassign_with_default is needed by the shadow-validation builder pattern in persist
4#![allow(clippy::field_reassign_with_default)]
5// REASON: benchmark helpers use hand-tuned constants close to Rust built-ins (e.g. 1.0/3.0)
6#![allow(clippy::approx_constant)]
7
8//! Hybrid search and ranking with deterministic scoring for khive.
9//!
10//! Combines HNSW vector search, BM25 keyword search, and RRF fusion into a unified
11//! retrieval layer. All scores use `DeterministicScore` for cross-platform consistency.
12//! See `docs/architecture.md` for module layout, design principles, ID bridging
13//! strategies, and trait composition guide.
14
15#![warn(missing_docs)]
16#![warn(clippy::all)]
17
18#[cfg(feature = "storage-adapters")]
19pub mod adapters;
20#[cfg(feature = "ann")]
21#[doc(hidden)]
22pub mod ann;
23pub mod error;
24pub mod eval;
25pub mod hit;
26pub mod hybrid;
27pub mod materialization;
28pub mod metrics;
29#[cfg(feature = "persist")]
30pub mod persist;
31pub mod policy;
32pub mod query_ir;
33#[cfg(feature = "persist")]
34pub mod replay;
35pub mod search_config;
36pub mod timeout;
37#[cfg(feature = "persist")]
38pub mod weights;
39
40// Re-export adapter types
41#[cfg(feature = "storage-adapters")]
42pub use adapters::{StorageKeywordSearch, StorageVectorSearch};
43
44// Re-export core types
45pub use error::{ErrorKind, Result, RetrievalError};
46pub use hit::{HybridSearchOutcome, RankScoreKind, SearchHit, SearchSignals, SearchSource};
47
48#[cfg(feature = "bm25")]
49pub use khive_bm25::{Bm25Config, Bm25Index, Bm25Stats, DocumentId, SearchContext};
50pub use khive_fusion::{
51    fuse, normalize_weights, reciprocal_rank_fusion, weighted_fusion, weights_are_normalized,
52    FusionStrategy, DEFAULT_RRF_K,
53};
54#[cfg(feature = "hnsw")]
55pub use khive_hnsw::{
56    DistanceMetric, HnswCheckpointConfig, HnswConfig, HnswIndex, HnswSearchContext, HnswSnapshot,
57    NodeId, RebuildStats, TombstoneStats,
58};
59// Formal proof: khive.Retrieval.HNSW.checkpoint_correctness
60pub use hybrid::{
61    fuse_search_results, fuse_search_results_checked, DualIndexConfig, DualIndexRouter,
62    DualIndexStrategy, HybridConfig, HybridSearcher, IdentityReranker, KeywordSearch, Query,
63    Reranker, VectorSearch,
64};
65#[cfg(feature = "checkpoint")]
66pub use khive_hnsw::{HnswCheckpoint, HnswCheckpointStore};
67// Native cross-encoder scaffold (ADR-042): the scorer trait and reranker are generic
68// and carry no khive-inference dependency, so this seam ships behind `native-rerank`
69// ahead of the model port. TODO(port-rerank): khive-inference model impl still deferred.
70#[cfg(feature = "native-rerank")]
71pub use hybrid::{CrossEncoderScorer, NativeCrossEncoderReranker, RerankDocumentResolver};
72pub use materialization::{
73    materialize_ranked_prefix, DropCounts, DropDiagnostic, DropReason, MaterializationDecision,
74    MaterializationError, MaterializationLimitError, MaterializationLimits, MaterializedItem,
75    MaterializedPrefix, RankedCandidate, MAX_MATERIALIZATION_CANDIDATES,
76    MAX_MATERIALIZATION_DIAGNOSTICS, MAX_MATERIALIZATION_DROP_REASONS,
77    MAX_MATERIALIZATION_LOADER_BATCH, MAX_MATERIALIZATION_OUTPUTS,
78};
79pub use metrics::{MetricEvent, MetricValue, MetricsSink, NoopSink, RecordingSink};
80#[cfg(feature = "persist")]
81pub use persist::{
82    PersistError, PersistenceStats, RetrievalPersistence, ShadowMetrics, ShadowValidationConfig,
83    ShadowValidationResult,
84};
85pub use policy::{filter_by_policy, filter_by_predicate, ClearanceLevel, SearchPolicy};
86pub use query_ir::{FilterPredicate, FuseStrategy, QueryNode, RerankMethod};
87pub use search_config::SearchConfig;
88pub use timeout::{
89    search_with_cancellation, search_with_deadline, search_with_optional_timeout,
90    search_with_timeout,
91};
92
93/// Re-exports from `lattice-embed`. Use these instead of depending on `lattice-embed` directly.
94pub mod embed {
95    // Core types and traits (always available, no feature gate needed)
96    /// Result alias for embedding operations.
97    pub use lattice_embed::Result as EmbedResult;
98    pub use lattice_embed::{EmbedError, EmbeddingModel, EmbeddingService};
99
100    // Native model implementations (pure Rust lattice-embed via "embed" feature)
101    #[cfg(feature = "embed")]
102    pub use lattice_embed::{CachedEmbeddingService, NativeEmbeddingService};
103}
khive_retrieval/lib.rs

khive_retrieval/
lib.rs
