π End-to-end encrypted cloud for everything.
Dart 2faandroidauthye2eeencryptionend-to-end-encryptionfluttergolanggoogle-photosgoogle-photos-alternativeiosopensourcephotosprivacyprivacy-toolstypescriptzero-knowledge
vecdb: add flutter_rust_bridge binding surface
laurenspriemf8065310be26
diff --git a/rust/bindings/frb/photos/src/api/mod.rs b/rust/bindings/frb/photos/src/api/mod.rsindex 4e197eeb58..2318426ef8 100644--- a/rust/bindings/frb/photos/src/api/mod.rs+++ b/rust/bindings/frb/photos/src/api/mod.rs@@ -8,3 +8,4 @@ pub mod map_cluster_api;pub mod ml_indexing_api;pub mod motion_photo_api;pub mod usearch_api;+pub mod vecdb_api;diff --git a/rust/bindings/frb/photos/src/api/vecdb_api.rs b/rust/bindings/frb/photos/src/api/vecdb_api.rsnew file mode 100644index 0000000000..1f39af12f4--- /dev/null+++ b/rust/bindings/frb/photos/src/api/vecdb_api.rs@@ -0,0 +1,509 @@+use std::path::Path;++use ente_ml::vecdb;+use flutter_rust_bridge::frb;++#[derive(Clone, Debug)]+pub enum RustVecDbError {+ Io { message: String },+ Corrupt { message: String },+ Locked { message: String },+ ReadOnly { message: String },+ InvalidKey { message: String },+ InvalidVector { message: String },+ DimensionMismatch { message: String },+ InvalidDimensions { message: String },+ UnboundedSearch { message: String },+ LengthMismatch { message: String },+}++impl From<vecdb::VecDbError> for RustVecDbError {+ fn from(value: vecdb::VecDbError) -> Self {+ let message = value.to_string();+ match value {+ vecdb::VecDbError::Io { .. } => Self::Io { message },+ vecdb::VecDbError::Corrupt(_) => Self::Corrupt { message },+ vecdb::VecDbError::Locked(_) => Self::Locked { message },+ vecdb::VecDbError::ReadOnly => Self::ReadOnly { message },+ vecdb::VecDbError::InvalidKey(_) => Self::InvalidKey { message },+ vecdb::VecDbError::InvalidVector(_) => Self::InvalidVector { message },+ vecdb::VecDbError::DimensionMismatch { .. } => Self::DimensionMismatch { message },+ vecdb::VecDbError::InvalidDimensions(_) => Self::InvalidDimensions { message },+ vecdb::VecDbError::UnboundedSearch => Self::UnboundedSearch { message },+ }+ }+}++#[derive(Clone, Debug)]+pub struct VecDbMatch {+ pub key: String,+ pub distance: f32,+}++#[derive(Clone, Debug)]+pub struct VecDbKeyMatches {+ pub key: String,+ pub matches: Vec<VecDbMatch>,+}++#[derive(Clone, Debug)]+pub struct VecDbStats {+ pub live_count: usize,+ pub dead_count: usize,+ pub dims: usize,+ pub log_bytes: u64,+ pub records_since_snapshot: usize,+ pub approximate_memory_bytes: usize,+}++fn to_api_match(entry: vecdb::Match) -> VecDbMatch {+ VecDbMatch {+ key: entry.key,+ distance: entry.distance,+ }+}++#[frb(opaque)]+pub struct VecDb {+ inner: vecdb::VecDb,+}++impl VecDb {+ #[frb(sync)]+ pub fn new(file_path: String, dimensions: usize) -> Result<Self, RustVecDbError> {+ Ok(Self {+ inner: vecdb::VecDb::open(Path::new(&file_path), dimensions)?,+ })+ }++ pub fn open_read_only(file_path: String, dimensions: usize) -> Result<Self, RustVecDbError> {+ Ok(Self {+ inner: vecdb::VecDb::open_read_only(Path::new(&file_path), dimensions)?,+ })+ }++ pub fn search(+ &self,+ query: Vec<f32>,+ limit: Option<usize>,+ max_distance: Option<f32>,+ exact: bool,+ allowed_keys: Option<Vec<String>>,+ ) -> Result<Vec<VecDbMatch>, RustVecDbError> {+ let params = vecdb::SearchParams {+ limit,+ max_distance,+ exact,+ allowed_keys,+ };+ self.run_search(&query, ¶ms)+ }++ fn run_search(+ &self,+ query: &[f32],+ params: &vecdb::SearchParams,+ ) -> Result<Vec<VecDbMatch>, RustVecDbError> {+ let matches = self.inner.search(query, params)?;+ Ok(matches.into_iter().map(to_api_match).collect())+ }++ pub fn add_vector(&mut self, key: String, vector: Vec<f32>) -> Result<(), RustVecDbError> {+ Ok(self.inner.add(&key, &vector)?)+ }++ pub fn bulk_add_vectors(+ &mut self,+ keys: Vec<String>,+ vectors: Vec<Vec<f32>>,+ ) -> Result<(), RustVecDbError> {+ if keys.len() != vectors.len() {+ return Err(RustVecDbError::LengthMismatch {+ message: format!(+ "keys length {} does not match vectors length {}",+ keys.len(),+ vectors.len()+ ),+ });+ }+ let entries: Vec<(String, Vec<f32>)> = keys.into_iter().zip(vectors).collect();+ Ok(self.inner.bulk_add(&entries)?)+ }++ pub fn search_vectors(+ &self,+ query: Vec<f32>,+ count: usize,+ exact: bool,+ ) -> Result<Vec<VecDbMatch>, RustVecDbError> {+ self.search(query, Some(count), None, exact, None)+ }++ pub fn bulk_search_vectors(+ &self,+ queries: Vec<Vec<f32>>,+ count: usize,+ exact: bool,+ ) -> Result<Vec<Vec<VecDbMatch>>, RustVecDbError> {+ let params = vecdb::SearchParams {+ limit: Some(count),+ max_distance: None,+ exact,+ allowed_keys: None,+ };+ queries+ .iter()+ .map(|query| self.run_search(query, ¶ms))+ .collect()+ }++ pub fn search_vectors_within_distance(+ &self,+ query: Vec<f32>,+ max_distance: f32,+ exact: bool,+ ) -> Result<Vec<VecDbMatch>, RustVecDbError> {+ self.search(query, None, Some(max_distance), exact, None)+ }++ pub fn approx_search_vectors_within_similarity(+ &self,+ query: Vec<f32>,+ minimum_similarity: f32,+ ) -> Result<Vec<VecDbMatch>, RustVecDbError> {+ self.search(query, None, Some(1.0 - minimum_similarity), false, None)+ }++ pub fn approx_filtered_search_vectors_within_distance(+ &self,+ query: Vec<f32>,+ allowed_keys: Vec<String>,+ count: usize,+ max_distance: f32,+ ) -> Result<Vec<VecDbMatch>, RustVecDbError> {+ self.search(+ query,+ Some(count),+ Some(max_distance),+ false,+ Some(allowed_keys),+ )+ }++ pub fn bulk_approx_filtered_search_vectors_within_distance(+ &self,+ queries: Vec<Vec<f32>>,+ allowed_keys: Vec<String>,+ count: usize,+ max_distance: f32,+ ) -> Result<Vec<Vec<VecDbMatch>>, RustVecDbError> {+ let params = vecdb::SearchParams {+ limit: Some(count),+ max_distance: Some(max_distance),+ exact: false,+ allowed_keys: Some(allowed_keys),+ };+ queries+ .iter()+ .map(|query| self.run_search(query, ¶ms))+ .collect()+ }++ pub fn bulk_search_keys(+ &self,+ potential_keys: Vec<String>,+ count: usize,+ exact: bool,+ ) -> Result<Vec<VecDbKeyMatches>, RustVecDbError> {+ let params = vecdb::SearchParams {+ limit: Some(count),+ max_distance: None,+ exact,+ allowed_keys: None,+ };+ let mut results = Vec::new();+ for key in potential_keys {+ let Some(vector) = self.inner.get(&key) else {+ continue;+ };+ let matches = self.run_search(&vector, ¶ms)?;+ results.push(VecDbKeyMatches { key, matches });+ }+ Ok(results)+ }++ pub fn contains_vector(&self, key: String) -> bool {+ self.inner.contains(&key)+ }++ pub fn get_vector(&self, key: String) -> Option<Vec<f32>> {+ self.inner.get(&key)+ }++ pub fn bulk_get_vectors(&self, keys: Vec<String>) -> Vec<Option<Vec<f32>>> {+ keys.iter().map(|key| self.inner.get(key)).collect()+ }++ pub fn remove_vector(&mut self, key: String) -> Result<usize, RustVecDbError> {+ Ok(usize::from(self.inner.remove(&key)?))+ }++ pub fn bulk_remove_vectors(&mut self, keys: Vec<String>) -> Result<usize, RustVecDbError> {+ Ok(self.inner.bulk_remove(&keys)?)+ }++ pub fn flush(&mut self) -> Result<(), RustVecDbError> {+ Ok(self.inner.flush()?)+ }++ pub fn reset_index(&mut self) -> Result<(), RustVecDbError> {+ Ok(self.inner.reset()?)+ }++ pub fn delete_index(self) -> Result<(), RustVecDbError> {+ Ok(self.inner.delete()?)+ }++ pub fn get_index_stats(&self) -> VecDbStats {+ let stats = self.inner.stats();+ VecDbStats {+ live_count: stats.live_count,+ dead_count: stats.dead_count,+ dims: stats.dims,+ log_bytes: stats.log_bytes,+ records_since_snapshot: stats.records_since_snapshot,+ approximate_memory_bytes: stats.approximate_memory_bytes,+ }+ }++ pub fn len(&self) -> usize {+ self.inner.len()+ }++ pub fn is_empty(&self) -> bool {+ self.inner.is_empty()+ }+}++#[cfg(test)]+mod tests {+ use std::path::PathBuf;+ use std::sync::atomic::{AtomicU32, Ordering};++ use super::*;++ const DIMS: usize = 8;++ static TEST_DIR_COUNTER: AtomicU32 = AtomicU32::new(0);++ struct TestDir(PathBuf);++ impl TestDir {+ fn create() -> Self {+ let sequence = TEST_DIR_COUNTER.fetch_add(1, Ordering::Relaxed);+ let path = std::env::temp_dir().join(format!(+ "ente-photos-frb-vecdb-{}-{sequence}",+ std::process::id()+ ));+ let _ = std::fs::remove_dir_all(&path);+ std::fs::create_dir_all(&path).unwrap();+ Self(path)+ }++ fn db_path(&self) -> String {+ self.0.join("db").to_str().unwrap().to_string()+ }+ }++ impl Drop for TestDir {+ fn drop(&mut self) {+ let _ = std::fs::remove_dir_all(&self.0);+ }+ }++ fn basis(axis: usize) -> Vec<f32> {+ let mut vector = vec![0.0; DIMS];+ vector[axis] = 1.0;+ vector+ }++ fn key(name: &str) -> String {+ name.to_string()+ }++ #[test]+ fn add_search_stats_round_trip() {+ let dir = TestDir::create();+ let mut db = VecDb::new(dir.db_path(), DIMS).unwrap();+ db.add_vector(key("a"), basis(0)).unwrap();+ db.bulk_add_vectors(vec![key("b"), key("c")], vec![basis(1), basis(2)])+ .unwrap();+ assert!(db.contains_vector(key("a")));+ assert!(!db.contains_vector(key("missing")));+ assert_eq!(db.get_vector(key("b")).unwrap(), basis(1));+ assert!(db.get_vector(key("missing")).is_none());+ assert_eq!(+ db.bulk_get_vectors(vec![key("c"), key("missing")]),+ vec![Some(basis(2)), None]+ );+ let matches = db.search_vectors(basis(0), 2, true).unwrap();+ assert_eq!(matches[0].key, "a");+ assert!(matches[0].distance.abs() < 1.0e-6);+ let bulk = db+ .bulk_search_vectors(vec![basis(1), basis(2)], 1, false)+ .unwrap();+ assert_eq!(bulk.len(), 2);+ assert_eq!(bulk[0][0].key, "b");+ assert_eq!(bulk[1][0].key, "c");+ let filtered = db+ .approx_filtered_search_vectors_within_distance(+ basis(0),+ vec![key("b"), key("c")],+ 3,+ 2.0,+ )+ .unwrap();+ assert!(filtered.iter().all(|found| found.key != "a"));+ assert_eq!(filtered.len(), 2);+ let within = db+ .search_vectors_within_distance(basis(0), 0.5, true)+ .unwrap();+ assert_eq!(within.len(), 1);+ assert_eq!(within[0].key, "a");+ let stats = db.get_index_stats();+ assert_eq!(stats.live_count, 3);+ assert_eq!(stats.dead_count, 0);+ assert_eq!(stats.dims, DIMS);+ assert!(stats.log_bytes > 32);+ assert!(stats.approximate_memory_bytes > 0);+ assert_eq!(db.len(), 3);+ assert!(!db.is_empty());+ db.flush().unwrap();+ assert_eq!(db.get_index_stats().records_since_snapshot, 0);+ let mut read_only = VecDb::open_read_only(dir.db_path(), DIMS).unwrap();+ assert_eq!(read_only.len(), 3);+ assert!(matches!(+ read_only.add_vector(key("x"), basis(3)),+ Err(RustVecDbError::ReadOnly { .. })+ ));+ assert_eq!(db.remove_vector(key("a")).unwrap(), 1);+ assert_eq!(db.remove_vector(key("a")).unwrap(), 0);+ assert_eq!(+ db.bulk_remove_vectors(vec![key("b"), key("nope")]).unwrap(),+ 1+ );+ assert_eq!(db.len(), 1);+ db.reset_index().unwrap();+ assert!(db.is_empty());+ db.add_vector(key("again"), basis(3)).unwrap();+ db.delete_index().unwrap();+ assert!(!PathBuf::from(dir.db_path()).exists());+ }++ #[test]+ fn bulk_add_rejects_length_mismatch() {+ let dir = TestDir::create();+ let mut db = VecDb::new(dir.db_path(), DIMS).unwrap();+ let error = db+ .bulk_add_vectors(vec![key("a")], vec![basis(0), basis(1)])+ .unwrap_err();+ assert!(matches!(error, RustVecDbError::LengthMismatch { .. }));+ assert!(db.is_empty());+ }++ #[test]+ fn similarity_threshold_conversion_edges() {+ let dir = TestDir::create();+ let mut db = VecDb::new(dir.db_path(), DIMS).unwrap();+ db.add_vector(key("a"), basis(0)).unwrap();+ db.add_vector(key("b"), basis(1)).unwrap();+ let close = db+ .approx_search_vectors_within_similarity(basis(0), 0.5)+ .unwrap();+ assert_eq!(close.len(), 1);+ assert_eq!(close[0].key, "a");+ let all = db+ .approx_search_vectors_within_similarity(basis(0), -1.0)+ .unwrap();+ assert_eq!(all.len(), 2);+ for degenerate in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY, 2.0] {+ assert!(+ db.approx_search_vectors_within_similarity(basis(0), degenerate)+ .unwrap()+ .is_empty()+ );+ }+ }++ #[test]+ fn bulk_filtered_search_stays_query_aligned() {+ let dir = TestDir::create();+ let mut db = VecDb::new(dir.db_path(), DIMS).unwrap();+ db.bulk_add_vectors(+ vec![key("a"), key("b"), key("c")],+ vec![basis(0), basis(1), basis(2)],+ )+ .unwrap();+ let queries = vec![basis(0), basis(1), basis(5)];+ let aligned = db+ .bulk_approx_filtered_search_vectors_within_distance(+ queries.clone(),+ vec![key("a"), key("b"), key("absent")],+ 2,+ 0.5,+ )+ .unwrap();+ assert_eq!(aligned.len(), 3);+ assert_eq!(aligned[0].len(), 1);+ assert_eq!(aligned[0][0].key, "a");+ assert_eq!(aligned[1].len(), 1);+ assert_eq!(aligned[1][0].key, "b");+ assert!(aligned[2].is_empty());+ let empty_allowed = db+ .bulk_approx_filtered_search_vectors_within_distance(+ queries.clone(),+ Vec::new(),+ 2,+ 0.5,+ )+ .unwrap();+ assert_eq!(empty_allowed.len(), 3);+ assert!(empty_allowed.iter().all(|matches| matches.is_empty()));+ for degenerate_distance in [f32::NAN, f32::INFINITY, -0.5] {+ let degenerate = db+ .bulk_approx_filtered_search_vectors_within_distance(+ queries.clone(),+ vec![key("a")],+ 2,+ degenerate_distance,+ )+ .unwrap();+ assert_eq!(degenerate.len(), 3);+ assert!(degenerate.iter().all(|matches| matches.is_empty()));+ }+ let unfiltered = db.search(basis(0), Some(3), None, false, None).unwrap();+ assert_eq!(unfiltered.len(), 3);+ let filtered_empty = db+ .search(basis(0), Some(3), None, false, Some(Vec::new()))+ .unwrap();+ assert!(filtered_empty.is_empty());+ }++ #[test]+ fn bulk_search_keys_includes_self_match_and_skips_absent() {+ let dir = TestDir::create();+ let mut db = VecDb::new(dir.db_path(), DIMS).unwrap();+ db.bulk_add_vectors(vec![key("a"), key("b")], vec![basis(0), basis(1)])+ .unwrap();+ let results = db+ .bulk_search_keys(vec![key("missing"), key("b"), key("a")], 2, true)+ .unwrap();+ assert_eq!(results.len(), 2);+ assert_eq!(results[0].key, "b");+ assert_eq!(results[0].matches[0].key, "b");+ assert!(results[0].matches[0].distance.abs() < 1.0e-6);+ assert_eq!(results[0].matches.len(), 2);+ assert_eq!(results[1].key, "a");+ assert_eq!(results[1].matches[0].key, "a");+ }+}