rag_plusplus_core/
lib.rs

1//! RAG++ Core Library
2//!
3//! High-performance retrieval engine for memory-conditioned candidate selection.
4//!
5//! # Overview
6//!
7//! RAG++ retrieves outcome-annotated trajectories and provides statistical priors
8//! for downstream conditioning. It does NOT train models - pure retrieval + statistics.
9//!
10//! # Invariants
11//!
12//! - INV-001: Record immutability after creation
13//! - INV-002: Welford numerical stability
14//! - INV-003: WAL-before-buffer for durability
15//! - INV-004: Index-record consistency
16//!
17//! # Modules
18//!
19//! - `types`: Core data structures (MemoryRecord, QueryBundle, PriorBundle)
20//! - `stats`: Outcome statistics with Welford's algorithm
21//! - `error`: Error types and Result aliases
22//! - `index`: Vector index implementations (Flat, HNSW)
23//! - `filter`: Metadata filter expressions and evaluation
24//! - `store`: Record storage (in-memory, persistent)
25//! - `wal`: Write-ahead log for durability
26//! - `buffer`: Write buffering for batched operations
27//! - `retrieval`: Query execution and reranking
28//! - `cache`: Query result caching
29//! - `observability`: Metrics and tracing
30//! - `eval`: Evaluation metrics and benchmarking
31//! - `api`: Public API contracts and traits
32//! - `trajectory`: Trajectory memory algorithms (DAG traversal, phase inference, salience)
33//! - `distance`: Vector distance operations with SIMD and batch support
34
35#![deny(unsafe_code)]  // deny instead of forbid to allow SIMD module override
36#![warn(clippy::all, clippy::pedantic, clippy::nursery)]
37#![allow(clippy::module_name_repetitions)]
38
39pub mod api;
40pub mod buffer;
41pub mod cache;
42pub mod distance;
43pub mod error;
44pub mod eval;
45pub mod filter;
46pub mod index;
47pub mod observability;
48pub mod retrieval;
49pub mod stats;
50pub mod store;
51pub mod trajectory;
52pub mod types;
53pub mod wal;
54
55// Re-exports for convenience
56pub use buffer::{BufferStats, WriteBuffer, WriteBufferConfig};
57pub use cache::{CacheConfig, CacheKey, CacheStats, QueryCache};
58pub use error::{Error, Result};
59pub use filter::{CompiledFilter, FilterEvaluator, FilterExpr, FilterOp, FilterValue};
60pub use index::{
61    DistanceType, FlatIndex, FusedResult, FusionConfig, FusionStrategy, HNSWConfig, HNSWIndex,
62    IndexConfig, IndexInfo, IndexRegistry, MultiIndexResult, MultiIndexResults, ParallelSearchConfig,
63    ParallelSearcher, ResultsAggregator, ScoreFusion, SearchResult, SharedRegistry, VectorIndex,
64    parallel_add_batch, rrf_fuse, rrf_fuse_top_k, shared_registry,
65};
66pub use stats::OutcomeStats;
67pub use store::{InMemoryStore, RecordStore, SharedStore};
68pub use types::{MemoryRecord, PriorBundle, QueryBundle, RecordId, VectorRef};
69pub use observability::{Metrics, MetricsConfig, QuerySpan, SpanContext};
70pub use retrieval::{QueryEngine, QueryEngineConfig, QueryRequest, QueryResponse, Reranker, RerankerConfig, RerankerType};
71pub use wal::{WalConfig, WalEntry, WalEntryType, WalReader, WalWriter};
72pub use eval::{Evaluator, EvaluationSummary, QueryEvaluation, Benchmarker, BenchmarkResult};
73
74// Trajectory memory algorithms
75pub use trajectory::{
76    TrajectoryGraph, Episode, Edge, EdgeType, NodeId as EpisodeId,
77    PathSelectionPolicy, TraversalOrder, BranchInfo, PathResult,
78    TrajectoryPhase, PhaseInferencer, PhaseConfig, TurnFeatures, PhaseTransition,
79    SalienceScorer, SalienceConfig, SalienceFactors, TurnSalience, CorpusSalienceStats, Feedback,
80    TrajectoryCoordinate, NormalizedCoordinate, compute_trajectory_coordinates,
81    // 5D coordinates (TPO extension with complexity dimension)
82    TrajectoryCoordinate5D, NormalizedCoordinate5D,
83    Ring, RingNode, EpisodeRing, build_weighted_ring,
84    // Dual ring for IRCP/RCP
85    DualRing, DualRingNode, build_dual_ring, build_dual_ring_with_attention,
86    ConservationMetrics, ConservationViolation, ConservationConfig, ConservationTracker,
87    weighted_centroid, weighted_covariance,
88    // Path quality (TPO integration)
89    PathQuality, PathQualityWeights, PathQualityFactors,
90};
91
92// Backward compatibility - deprecated in favor of TrajectoryPhase
93#[allow(deprecated)]
94pub use trajectory::ConversationPhase;
95
96// Distance operations with batch support
97pub use distance::{
98    l2_distance, l2_distance_squared, inner_product, cosine_similarity, cosine_distance,
99    norm, norm_squared, normalize, normalize_in_place,
100    normalize_batch, normalize_batch_flat, compute_norms_batch, find_unnormalized,
101    l2_distance_fast, inner_product_fast, cosine_similarity_fast, cosine_distance_fast,
102    norm_fast, normalize_in_place_fast, normalize_batch_flat_fast, compute_norms_batch_fast,
103    normalize_batch_parallel, compute_distance, compute_distance_for_heap,
104    // Trajectory-weighted distance (TPO integration)
105    trajectory_weighted_cosine, trajectory_weighted_cosine_5d, trajectory_weighted_l2,
106    trajectory_weighted_inner_product, trajectory_weighted_distance, TrajectoryDistanceConfig,
107};
108
109// Public API contracts
110pub use api::{
111    RetrievalRequest, RetrievalResponse, PriorBundle as ApiPriorBundle,
112    RankedCandidate, FilterExpression, FilterValue as ApiFilterValue,
113    IngestRecord, MetadataValue as ApiMetadataValue,
114    RetrievalEngine, Corpus, VectorSearcher, SearchHit,
115    RAGBuilder, IndexType,
116};
rag_plusplus_core/lib.rs

rag_plusplus_core/
lib.rs
