foxstash_core/
lib.rs

1//! Foxstash - Core library
2//!
3//! High-performance vector search and embedding generation for local-first AI.
4
5// Allow some clippy lints for now - will address in future cleanup
6#![allow(clippy::non_canonical_partial_ord_impl)]
7#![allow(clippy::manual_is_multiple_of)]
8#![allow(clippy::manual_div_ceil)]
9#![allow(clippy::derivable_impls)]
10#![allow(clippy::needless_range_loop)]
11#![allow(clippy::unused_enumerate_index)]
12
13pub mod embedding;
14pub mod index;
15pub mod storage;
16pub mod vector;
17
18use thiserror::Error;
19
20/// Result type for RAG operations
21pub type Result<T> = std::result::Result<T, RagError>;
22
23/// Error types for RAG operations
24#[derive(Debug, Error)]
25pub enum RagError {
26    #[error("Vector dimension mismatch: expected {expected}, got {actual}")]
27    DimensionMismatch { expected: usize, actual: usize },
28
29    #[error("Index error: {0}")]
30    IndexError(String),
31
32    #[error("Embedding error: {0}")]
33    EmbeddingError(String),
34
35    #[error("Storage error: {0}")]
36    StorageError(String),
37
38    #[error("IO error: {0}")]
39    IoError(#[from] std::io::Error),
40
41    #[error("Serialization error: {0}")]
42    SerializationError(#[from] bincode::Error),
43
44    #[error("Compression error: {0}")]
45    CompressionError(#[from] storage::compression::CompressionError),
46
47    #[error("Invalid input: {0}")]
48    InvalidInput(String),
49
50    #[error("Index not trained: {0}")]
51    NotTrained(String),
52
53    /// Raised when a caller asks a quantized index to rerank against full-precision vectors it
54    /// no longer has. `rerank_candidates: 0` *discards* the f32 vectors at build time — that is
55    /// the point of it, and the smallest index foxstash can build — so the pool cannot be
56    /// raised afterwards. See [`index::HNSWIndex::set_rerank_candidates`].
57    #[error(
58        "cannot rerank: this index was built with rerank_candidates = 0, which drops the \
59         full-precision vectors. Rebuild with rerank_candidates > 0 to enable reranking."
60    )]
61    FullPrecisionDropped,
62}
63
64/// Document with embedding
65#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
66pub struct Document {
67    pub id: String,
68    pub content: String,
69    pub embedding: Vec<f32>,
70    pub metadata: Option<serde_json::Value>,
71}
72
73/// Search result with similarity score
74#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
75pub struct SearchResult {
76    pub id: String,
77    pub content: String,
78    pub score: f32,
79    pub metadata: Option<serde_json::Value>,
80}
81
82// Re-export commonly used items
83pub use vector::{cosine_similarity, dot_product, l2_distance, normalize};
foxstash_core/lib.rs

foxstash_core/
lib.rs
