zeusdb-vector-database 0.0.3__tar.gz → 0.0.4__tar.gz

{zeusdb_vector_database-0.0.3 → zeusdb_vector_database-0.0.4}/NOTICE

@@ -6,6 +6,9 @@ This product includes software developed by:
 - The Python Software Foundation (https://www.python.org/psf/)
 - The Rust Project Developers (https://www.rust-lang.org/)
 - The PyO3 Project (https://pyo3.rs/)
+- Jean-pierreBoth (https://crates.io/crates/hnsw_rs/)
+
+Third-party components may be licensed under their respective terms. See LICENSES/ for full license texts.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

{zeusdb_vector_database-0.0.3 → zeusdb_vector_database-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zeusdb-vector-database
-Version: 0.0.3
+Version: 0.0.4
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Requires-Dist: numpy>=2.2.6,<3.0.0
@@ -75,13 +75,17 @@ ZeusDB leverages the HNSW (Hierarchical Navigable Small World) algorithm for spe
 
 | Metric | Description                          |
 |--------|--------------------------------------|
-| cosine | Cosine distance (1 - Cosine Similiarity) |
+| cosine | Cosine Distance (1 - Cosine Similiarity) |
 <!--
 | l2     | Euclidean distance                   |
 | dot    | Dot product                 |
 
 -->
 
+Scores vs Distances: 
+- Similarity Scores (higher = more similar)
+- Distances (lower = more similar)
+
 <br/>
 
 ## 📦 Installation
@@ -144,10 +148,23 @@ result = index.add(records)
 query_vec = [0.1, 0.2, 0.3, 0.1, 0.4, 0.2, 0.6, 0.7]
 
 # Query with no filter (all documents)
-print("\n--- Querying without filter (all documents) ---")
 results = index.query(vector=query_vec, filter=None, top_k=2)
-for doc_id, score in results:
-    print(f"{doc_id} (score={score:.4f})")
+print("\n--- Raw Results Format ---")
+print(results)
+
+print("\n--- Formatted Results ---")
+for i, res in enumerate(results, 1):
+    print(f"{i}. ID: {res['id']}, Score: {res['score']:.4f}, Metadata: {res['metadata']}")
+```
+
+*Results Output:*
+```
+--- Raw Results Format ---
+[{'id': 'doc_001', 'score': 0.0, 'metadata': {'author': 'Alice'}}, {'id': 'doc_003', 'score': 0.0009883458260446787, 'metadata': {'author': 'Alice'}}]
+
+--- Formatted Results ---
+1. ID: doc_001, Score: 0.0000, Metadata: {'author': 'Alice'}
+2. ID: doc_003, Score: 0.0010, Metadata: {'author': 'Alice'}
 ```
 
 <br/>
@@ -280,14 +297,15 @@ This pre-filters on the given metadata prior to conducting the similarity search
 ```python
 print("\n--- Querying with filter: author = 'Alice' ---")
 results = index.query(vector=query_vec, filter={"author": "Alice"}, top_k=5)
-for doc_id, score in results:
-    print(f"{doc_id} (score={score:.4f})")
+print(results)
 ```
 *Output*
 ```
-doc_001 (score=0.0000)
-doc_003 (score=0.0010)
-doc_005 (score=0.0011)
+[
+  {'id': 'doc_001', 'score': 0.0, 'metadata': {'author': 'Alice'}}, 
+  {'id': 'doc_003', 'score': 0.0009883458260446787, 'metadata': {'author': 'Alice'}}, 
+  {'id': 'doc_005', 'score': 0.0011433829786255956, 'metadata': {'author': 'Alice'}}
+]
 ```
 
 

{zeusdb_vector_database-0.0.3 → zeusdb_vector_database-0.0.4}/README.md

@@ -56,13 +56,17 @@ ZeusDB leverages the HNSW (Hierarchical Navigable Small World) algorithm for spe
 
 | Metric | Description                          |
 |--------|--------------------------------------|
-| cosine | Cosine distance (1 - Cosine Similiarity) |
+| cosine | Cosine Distance (1 - Cosine Similiarity) |
 <!--
 | l2     | Euclidean distance                   |
 | dot    | Dot product                 |
 
 -->
 
+Scores vs Distances: 
+- Similarity Scores (higher = more similar)
+- Distances (lower = more similar)
+
 <br/>
 
 ## 📦 Installation
@@ -125,10 +129,23 @@ result = index.add(records)
 query_vec = [0.1, 0.2, 0.3, 0.1, 0.4, 0.2, 0.6, 0.7]
 
 # Query with no filter (all documents)
-print("\n--- Querying without filter (all documents) ---")
 results = index.query(vector=query_vec, filter=None, top_k=2)
-for doc_id, score in results:
-    print(f"{doc_id} (score={score:.4f})")
+print("\n--- Raw Results Format ---")
+print(results)
+
+print("\n--- Formatted Results ---")
+for i, res in enumerate(results, 1):
+    print(f"{i}. ID: {res['id']}, Score: {res['score']:.4f}, Metadata: {res['metadata']}")
+```
+
+*Results Output:*
+```
+--- Raw Results Format ---
+[{'id': 'doc_001', 'score': 0.0, 'metadata': {'author': 'Alice'}}, {'id': 'doc_003', 'score': 0.0009883458260446787, 'metadata': {'author': 'Alice'}}]
+
+--- Formatted Results ---
+1. ID: doc_001, Score: 0.0000, Metadata: {'author': 'Alice'}
+2. ID: doc_003, Score: 0.0010, Metadata: {'author': 'Alice'}
 ```
 
 <br/>
@@ -261,14 +278,15 @@ This pre-filters on the given metadata prior to conducting the similarity search
 ```python
 print("\n--- Querying with filter: author = 'Alice' ---")
 results = index.query(vector=query_vec, filter={"author": "Alice"}, top_k=5)
-for doc_id, score in results:
-    print(f"{doc_id} (score={score:.4f})")
+print(results)
 ```
 *Output*
 ```
-doc_001 (score=0.0000)
-doc_003 (score=0.0010)
-doc_005 (score=0.0011)
+[
+  {'id': 'doc_001', 'score': 0.0, 'metadata': {'author': 'Alice'}}, 
+  {'id': 'doc_003', 'score': 0.0009883458260446787, 'metadata': {'author': 'Alice'}}, 
+  {'id': 'doc_005', 'score': 0.0011433829786255956, 'metadata': {'author': 'Alice'}}
+]
 ```
 
 

{zeusdb_vector_database-0.0.3 → zeusdb_vector_database-0.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zeusdb-vector-database"
-version = "0.0.3"
+version = "0.0.4"
 description = "Blazing-fast vector DB with real-time similarity search and metadata filtering."
 readme = "README.md"
 authors = [

{zeusdb_vector_database-0.0.3 → zeusdb_vector_database-0.0.4}/src/zeusdb_vector_database/__init__.py

@@ -1,7 +1,7 @@
 """
 ZeusDB Vector Database Module
 """
-__version__ = "0.0.3"
+__version__ = "0.0.4"
 
 from .vector_database import VectorDatabase # imports the VectorDatabase class from the vector_database.py file
 

{zeusdb_vector_database-0.0.3 → zeusdb_vector_database-0.0.4}/vdb-core/Cargo.lock

@@ -1100,7 +1100,7 @@ dependencies = [
 
 [[package]]
 name = "zeusdb-vector-database"
-version = "0.0.3"
+version = "0.0.4"
 dependencies = [
  "hnsw_rs",
  "numpy",

{zeusdb_vector_database-0.0.3 → zeusdb_vector_database-0.0.4}/vdb-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "zeusdb-vector-database"
-version = "0.0.3"
+version = "0.0.4"
 edition = "2021"
 resolver = "2" # <-- Avoid compiling unnecessary features from dependencies.
 

{zeusdb_vector_database-0.0.3 → zeusdb_vector_database-0.0.4}/vdb-core/src/hnsw_index.rs

@@ -526,15 +526,72 @@ impl HNSWIndex {
         Ok(result)
     }
 
-    /// Query the index for the k-nearest neighbors of a vector
-    #[pyo3(signature = (vector, filter=None, top_k=10, ef_search=None))]
+    // /// DEPRECIATED: This one returns a list of tuples (id, score)
+    // /// Query the index for the k-nearest neighbors of a vector
+    // #[pyo3(signature = (vector, filter=None, top_k=10, ef_search=None))]
+    // pub fn query(
+    //     &self,
+    //     vector: Vec<f32>,
+    //     filter: Option<HashMap<String, String>>,
+    //     top_k: usize,
+    //     ef_search: Option<usize>,
+    // ) -> PyResult<Vec<(String, f32)>> {
+    //     if vector.len() != self.dim {
+    //         return Err(PyErr::new::<pyo3::exceptions::PyValueError, _>(format!(
+    //             "Query vector dimension mismatch: expected {}, got {}",
+    //             self.dim, vector.len()
+    //         )));
+    //     }
+
+    //     // Get results from HNSW graph
+    //     let ef = ef_search.unwrap_or_else(|| std::cmp::max(2 * top_k, 100));
+    //     let results = self.hnsw.search(&vector, top_k, ef);
+
+    //     let mut filtered_results = Vec::new();
+
+    //     for neighbor in results {
+    //         let score = neighbor.distance;
+    //         let internal_id = neighbor.get_origin_id();
+            
+    //         if let Some(ext_id) = self.rev_map.get(&internal_id) {
+    //             // Apply filtering if provided
+    //             if let Some(ref filter_map) = filter {
+    //                 if let Some(meta) = self.vector_metadata.get(ext_id) {
+    //                     let mut matches = true;
+    //                     for (k, v) in filter_map {
+    //                         if meta.get(k) != Some(v) {
+    //                             matches = false;
+    //                             break;
+    //                         }
+    //                     }
+    //                     if !matches {
+    //                         continue;
+    //                     }
+    //                 } else {
+    //                     // No metadata, but filter required - skip
+    //                     continue;
+    //                 }
+    //             }
+    //             filtered_results.push((ext_id.clone(), score));
+    //         }
+    //     }
+
+    //     Ok(filtered_results)
+    // }
+
+
+    /// Search for the k-nearest neighbors of a vector
+    /// Returns actual Python dictionaries which most common for ML workflows
+    #[pyo3(signature = (vector, filter=None, top_k=10, ef_search=None, return_vector=false))]
     pub fn query(
         &self,
+        py: Python<'_>,
         vector: Vec<f32>,
         filter: Option<HashMap<String, String>>,
         top_k: usize,
         ef_search: Option<usize>,
-    ) -> PyResult<Vec<(String, f32)>> {
+        return_vector: bool,
+    ) -> PyResult<Vec<Py<PyDict>>> {
         if vector.len() != self.dim {
             return Err(PyErr::new::<pyo3::exceptions::PyValueError, _>(format!(
                 "Query vector dimension mismatch: expected {}, got {}",
@@ -542,99 +599,183 @@ impl HNSWIndex {
             )));
         }
 
-        // Get results from HNSW graph
         let ef = ef_search.unwrap_or_else(|| std::cmp::max(2 * top_k, 100));
         let results = self.hnsw.search(&vector, top_k, ef);
 
-        let mut filtered_results = Vec::new();
+        let mut output = Vec::with_capacity(results.len());
 
         for neighbor in results {
             let score = neighbor.distance;
             let internal_id = neighbor.get_origin_id();
-            
+
             if let Some(ext_id) = self.rev_map.get(&internal_id) {
-                // Apply filtering if provided
+                // Apply optional metadata filter
                 if let Some(ref filter_map) = filter {
                     if let Some(meta) = self.vector_metadata.get(ext_id) {
-                        let mut matches = true;
-                        for (k, v) in filter_map {
-                            if meta.get(k) != Some(v) {
-                                matches = false;
-                                break;
-                            }
-                        }
+                        let matches = filter_map.iter().all(|(k, v)| meta.get(k) == Some(v));
                         if !matches {
                             continue;
                         }
                     } else {
-                        // No metadata, but filter required - skip
-                        continue;
+                        continue; // no metadata to match against
+                    }
+                }
+
+                let dict = PyDict::new(py);
+                dict.set_item("id", ext_id)?;
+                dict.set_item("score", score)?;
+
+                let metadata = self.vector_metadata.get(ext_id).cloned().unwrap_or_default();
+                dict.set_item("metadata", metadata)?;
+
+                if return_vector {
+                    if let Some(vec) = self.vectors.get(ext_id) {
+                        dict.set_item("vector", vec.clone())?;
                     }
                 }
-                filtered_results.push((ext_id.clone(), score));
+
+                output.push(dict.into());
             }
         }
 
-        Ok(filtered_results)
+        Ok(output)
     }
 
-    /// Search with metadata included in results
-    #[pyo3(signature = (vector, filter=None, top_k=10, ef_search=None, include_metadata=false))]
-    pub fn search_with_metadata(
-        &self,
-        vector: Vec<f32>,
-        filter: Option<HashMap<String, String>>,
-        top_k: usize,
-        ef_search: Option<usize>,
-        include_metadata: bool,
-    ) -> PyResult<Vec<(String, f32, Option<HashMap<String, String>>)>> {
-        if vector.len() != self.dim {
-            return Err(PyErr::new::<pyo3::exceptions::PyValueError, _>(format!(
-                "Query vector dimension mismatch: expected {}, got {}",
-                self.dim, vector.len()
-            )));
-        }
 
-        let ef = ef_search.unwrap_or_else(|| std::cmp::max(2 * top_k, 100));
-        let results = self.hnsw.search(&vector, top_k, ef);
 
-        let mut filtered_results = Vec::new();
 
-        for neighbor in results {
-            let score = neighbor.distance;
-            let internal_id = neighbor.get_origin_id();
+
+
+
+
+
+    // /// DEPRECIATED: This one returns a list of tuples (id, score)
+    // /// Search with metadata included in results
+    // #[pyo3(signature = (vector, filter=None, top_k=10, ef_search=None, include_metadata=false))]
+    // pub fn search_with_metadata(
+    //     &self,
+    //     vector: Vec<f32>,
+    //     filter: Option<HashMap<String, String>>,
+    //     top_k: usize,
+    //     ef_search: Option<usize>,
+    //     include_metadata: bool,
+    // ) -> PyResult<Vec<(String, f32, Option<HashMap<String, String>>)>> {
+    //     if vector.len() != self.dim {
+    //         return Err(PyErr::new::<pyo3::exceptions::PyValueError, _>(format!(
+    //             "Query vector dimension mismatch: expected {}, got {}",
+    //             self.dim, vector.len()
+    //         )));
+    //     }
+
+    //     let ef = ef_search.unwrap_or_else(|| std::cmp::max(2 * top_k, 100));
+    //     let results = self.hnsw.search(&vector, top_k, ef);
+
+    //     let mut filtered_results = Vec::new();
+
+    //     for neighbor in results {
+    //         let score = neighbor.distance;
+    //         let internal_id = neighbor.get_origin_id();
             
-            if let Some(ext_id) = self.rev_map.get(&internal_id) {
-                // Apply filtering if provided
-                if let Some(ref filter_map) = filter {
-                    if let Some(meta) = self.vector_metadata.get(ext_id) {
-                        let mut matches = true;
-                        for (k, v) in filter_map {
-                            if meta.get(k) != Some(v) {
-                                matches = false;
-                                break;
-                            }
-                        }
-                        if !matches {
-                            continue;
-                        }
-                    } else {
-                        continue;
-                    }
-                }
+    //         if let Some(ext_id) = self.rev_map.get(&internal_id) {
+    //             // Apply filtering if provided
+    //             if let Some(ref filter_map) = filter {
+    //                 if let Some(meta) = self.vector_metadata.get(ext_id) {
+    //                     let mut matches = true;
+    //                     for (k, v) in filter_map {
+    //                         if meta.get(k) != Some(v) {
+    //                             matches = false;
+    //                             break;
+    //                         }
+    //                     }
+    //                     if !matches {
+    //                         continue;
+    //                     }
+    //                 } else {
+    //                     continue;
+    //                 }
+    //             }
+
+    //             let metadata = if include_metadata {
+    //                 self.vector_metadata.get(ext_id).cloned()
+    //             } else {
+    //                 None
+    //             };
+
+    //             filtered_results.push((ext_id.clone(), score, metadata));
+    //         }
+    //     }
+
+    //     Ok(filtered_results)
+    // }
+
+
+    // /// DEPRECIATED: Use `query()` instead. Have made query the single do all function.
+    // /// Search with metadata included in results
+    // #[pyo3(signature = (vector, filter=None, top_k=10, ef_search=None, include_metadata=true))]
+    // pub fn search_with_metadata(
+    //     &self,
+    //     py: Python<'_>,
+    //     vector: Vec<f32>,
+    //     filter: Option<HashMap<String, String>>,
+    //     top_k: usize,
+    //     ef_search: Option<usize>,
+    //     include_metadata: bool,
+    // ) -> PyResult<Vec<Py<PyDict>>> {
+    //     if vector.len() != self.dim {
+    //         return Err(PyErr::new::<pyo3::exceptions::PyValueError, _>(format!(
+    //             "Query vector dimension mismatch: expected {}, got {}",
+    //             self.dim, vector.len()
+    //         )));
+    //     }
+
+    //     let ef = ef_search.unwrap_or_else(|| std::cmp::max(2 * top_k, 100));
+    //     let results = self.hnsw.search(&vector, top_k, ef);
+
+    //     let mut output = Vec::with_capacity(results.len());
+
+    //     for neighbor in results {
+    //         let score = neighbor.distance;
+    //         let internal_id = neighbor.get_origin_id();
+
+    //         if let Some(ext_id) = self.rev_map.get(&internal_id) {
+    //             // Apply optional filtering
+    //             if let Some(ref filter_map) = filter {
+    //                 if let Some(meta) = self.vector_metadata.get(ext_id) {
+    //                     let matches = filter_map.iter().all(|(k, v)| meta.get(k) == Some(v));
+    //                     if !matches {
+    //                         continue;
+    //                     }
+    //                 } else {
+    //                     continue;
+    //                 }
+    //             }
+
+    //             let dict = PyDict::new(py);
+    //             dict.set_item("id", ext_id)?;
+    //             dict.set_item("score", score)?;
+
+    //             if include_metadata {
+    //                 let metadata = self.vector_metadata.get(ext_id).cloned().unwrap_or_default();
+    //                 dict.set_item("metadata", metadata)?;
+    //             } else {
+    //                 dict.set_item("metadata", PyDict::new(py))?;
+    //             }
+
+    //             output.push(dict.into());
+    //         }
+    //     }
+
+    //     Ok(output)
+    // }
+
+
+
+
+
+
 
-                let metadata = if include_metadata {
-                    self.vector_metadata.get(ext_id).cloned()
-                } else {
-                    None
-                };
 
-                filtered_results.push((ext_id.clone(), score, metadata));
-            }
-        }
 
-        Ok(filtered_results)
-    }
 
     /// Get vector by ID
     pub fn get_vector(&self, id: String) -> Option<Vec<f32>> {