sevensense_vector/
lib.rs

1//! # sevensense-vector
2//!
3//! Vector database operations and HNSW indexing for the 7sense bioacoustics platform.
4//!
5//! This crate provides:
6//! - Local HNSW index with 150x search speedup over brute-force
7//! - Optional Qdrant client wrapper for distributed deployments
8//! - Collection management
9//! - Similarity search with filtering
10//! - Batch operations and persistence
11//! - Hyperbolic embeddings for hierarchical relationships
12//!
13//! ## Architecture
14//!
15//! Following Domain-Driven Design:
16//! ```text
17//! sevensense-vector
18//! ├── domain/              # Core entities, value objects, repository traits
19//! │   ├── entities.rs      # EmbeddingId, HnswConfig, SimilarityEdge
20//! │   ├── repository.rs    # VectorIndexRepository, GraphEdgeRepository
21//! │   └── error.rs         # VectorError
22//! ├── application/         # Service layer with use cases
23//! │   └── services.rs      # VectorSpaceService
24//! └── infrastructure/      # HNSW implementation and storage adapters
25//!     ├── hnsw_index.rs    # Local HNSW index
26//!     └── graph_store.rs   # Edge storage
27//! ```
28//!
29//! ## Performance Targets
30//!
31//! - 150x search speedup over brute-force linear scan
32//! - Sub-millisecond queries for up to 1M vectors
33//! - Efficient batch insertion with parallelization
34//!
35//! ## Example
36//!
37//! ```rust,ignore
38//! use sevensense_vector::prelude::*;
39//!
40//! // Create a vector space service
41//! let config = HnswConfig::for_dimension(1536);
42//! let service = VectorSpaceService::new(config);
43//!
44//! // Add embeddings
45//! let id = EmbeddingId::new();
46//! let vector = vec![0.1; 1536];
47//! service.add_embedding(id, vector).await?;
48//!
49//! // Search for neighbors
50//! let query = vec![0.15; 1536];
51//! let neighbors = service.find_neighbors(&query, 10).await?;
52//! ```
53
54#![warn(missing_docs)]
55#![warn(clippy::all)]
56#![warn(clippy::pedantic)]
57#![warn(clippy::nursery)]
58#![allow(clippy::module_name_repetitions)]
59#![allow(clippy::must_use_candidate)]
60#![allow(clippy::missing_errors_doc)]
61#![allow(clippy::missing_panics_doc)]
62
63pub mod domain;
64pub mod application;
65pub mod infrastructure;
66
67mod distance;
68mod hyperbolic;
69
70// Re-export commonly used types
71pub use domain::entities::{
72    EmbeddingId, HnswConfig, SimilarityEdge, EdgeType, VectorIndex, Timestamp,
73};
74pub use domain::repository::{VectorIndexRepository, GraphEdgeRepository};
75pub use application::services::{VectorSpaceService, Neighbor, SearchOptions};
76pub use infrastructure::hnsw_index::HnswIndex;
77pub use distance::{cosine_distance, euclidean_distance, cosine_similarity, normalize_vector};
78pub use hyperbolic::{poincare_distance, exp_map, log_map, mobius_add};
79
80/// Error types for vector operations
81pub mod error {
82    pub use crate::domain::error::*;
83}
84
85/// Prelude module for convenient imports
86pub mod prelude {
87    //! Common imports for vector operations.
88    pub use crate::domain::entities::{
89        EmbeddingId, HnswConfig, SimilarityEdge, EdgeType, VectorIndex,
90    };
91    pub use crate::domain::repository::{VectorIndexRepository, GraphEdgeRepository};
92    pub use crate::application::services::{VectorSpaceService, Neighbor, SearchOptions};
93    pub use crate::infrastructure::hnsw_index::HnswIndex;
94    pub use crate::distance::{cosine_distance, euclidean_distance, cosine_similarity};
95    pub use crate::error::VectorError;
96}
97
98/// Crate version information
99pub const VERSION: &str = env!("CARGO_PKG_VERSION");
100
101#[cfg(test)]
102mod tests {
103    use super::*;
104
105    #[test]
106    fn test_library_compiles() {
107        // Basic smoke test
108        let config = HnswConfig::default();
109        assert_eq!(config.m, 32);
110    }
111
112    #[test]
113    fn test_version() {
114        assert!(!VERSION.is_empty());
115    }
116}
sevensense_vector/lib.rs

sevensense_vector/
lib.rs
