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

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

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: zeusdb-vector-database
-Version: 0.0.1
+Version: 0.0.3
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
-Requires-Dist: maturin>=1.8.7 ; extra == 'dev'
+Requires-Dist: numpy>=2.2.6,<3.0.0
+Requires-Dist: maturin>=1.9.0 ; extra == 'dev'
 Requires-Dist: pytest>=8.4.0 ; extra == 'dev'
 Provides-Extra: dev
 License-File: LICENSE
@@ -16,14 +17,17 @@ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 Project-URL: Repository, https://github.com/zeusdb/zeusdb-vector-database
 Project-URL: Bug Tracker, https://github.com/zeusdb/zeusdb-vector-database/issues
 
-# ZeusDB Vector Database
+<p align="center" width="100%">
+  <img src="https://github.com/user-attachments/assets/ad21baec-6f4c-445c-b423-88a081ca2b97" alt="zeusdb-vector-database-logo-cropped" />
+  <h1 align="center">ZeusDB Vector Database</h1>
+</p>
 
 <!-- <h2 align="center">Fast, Rust-powered vector database for similarity search</h2> -->
 <!--**Fast, Rust-powered vector database for similarity search** -->
 
 <!-- badges: start -->
 
-<div align="left">
+<div align="center">
   <table>
     <tr>
       <td><strong>Meta</strong></td>
@@ -56,6 +60,8 @@ ZeusDB leverages the HNSW (Hierarchical Navigable Small World) algorithm for spe
 
 🔥 High-performance Rust backend 
 
+📥 Supports multiple input formats using a single, easy-to-use Python method
+
 🗂️ Metadata-aware filtering at query time
 
 🐍 Simple and intuitive Python API
@@ -122,17 +128,16 @@ vdb = VectorDatabase()
 # Initialize and set up the database resources
 index = vdb.create_index_hnsw(dim = 8, space = "cosine", M = 16, ef_construction = 200, expected_size=5)
 
-# Upload vector records
-vectors = {
-    "doc_001": ([0.1, 0.2, 0.3, 0.1, 0.4, 0.2, 0.6, 0.7], {"author": "Alice"}),
-    "doc_002": ([0.9, 0.1, 0.4, 0.2, 0.8, 0.5, 0.3, 0.9], {"author": "Bob"}),
-    "doc_003": ([0.11, 0.21, 0.31, 0.15, 0.41, 0.22, 0.61, 0.72], {"author": "Alice"}),
-    "doc_004": ([0.85, 0.15, 0.42, 0.27, 0.83, 0.52, 0.33, 0.95], {"author": "Bob"}),
-    "doc_005": ([0.12, 0.22, 0.33, 0.13, 0.45, 0.23, 0.65, 0.71], {"author": "Alice"}),
-}
+# Upload vector records using the unified `add()` method
+records = [
+    {"id": "doc_001", "values": [0.1, 0.2, 0.3, 0.1, 0.4, 0.2, 0.6, 0.7], "metadata": {"author": "Alice"}},
+    {"id": "doc_002", "values": [0.9, 0.1, 0.4, 0.2, 0.8, 0.5, 0.3, 0.9], "metadata": {"author": "Bob"}},
+    {"id": "doc_003", "values": [0.11, 0.21, 0.31, 0.15, 0.41, 0.22, 0.61, 0.72], "metadata": {"author": "Alice"}},
+    {"id": "doc_004", "values": [0.85, 0.15, 0.42, 0.27, 0.83, 0.52, 0.33, 0.95], "metadata": {"author": "Bob"}},
+    {"id": "doc_005", "values": [0.12, 0.22, 0.33, 0.13, 0.45, 0.23, 0.65, 0.71], "metadata": {"author": "Alice"}},
+]
 
-for doc_id, (vec, meta) in vectors.items():
-    index.add_point(doc_id, vec, metadata=meta)
+result = index.add(records)
 
 # Perform a similarity search and print the top 2 results
 # Query Vector
@@ -141,12 +146,73 @@ 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_all:
+for doc_id, score in results:
     print(f"{doc_id} (score={score:.4f})")
 ```
 
 <br/>
 
+### ➕ Adding Vectors – Multiple Formats Supported
+
+ZeusDB Vector Database supports multiple intuitive ways to insert data using index.add(...). All formats accept optional metadata per record.
+
+#### ✅ Format 1 – Single Object
+
+```python
+index.add({
+    "id": "doc1",
+    "values": [0.1, 0.2],
+    "metadata": {"text": "hello"}
+})
+
+print(result.summary())     # ✅ 1 inserted, ❌ 0 errors
+print(result.is_success())  # True
+```
+
+#### ✅ Format 2 – List of Objects
+
+```python
+index.add([
+    {"id": "doc1", "values": [0.1, 0.2], "metadata": {"text": "hello"}},
+    {"id": "doc2", "values": [0.3, 0.4], "metadata": {"text": "world"}}
+])
+
+print(result.summary())       # ✅ 2 inserted, ❌ 0 errors
+print(result.vector_shape)    # (2, 2)
+print(result.errors)          # []
+```
+
+#### ✅ Format 3 – Separate Arrays
+
+```python
+index.add({
+    "ids": ["doc1", "doc2"],
+    "embeddings": [[0.1, 0.2], [0.3, 0.4]],
+    "metadatas": [{"text": "hello"}, {"text": "world"}]
+})
+print(result)  # BatchResult(inserted=2, errors=0, shape=(2, 2))
+```
+
+#### ✅ Format 4 – Using NumPy Arrays
+
+ZeusDB also supports NumPy arrays as input for seamless integration with scientific and ML workflows.
+
+```python
+import numpy as np
+
+data = [
+    {"id": "doc2", "values": np.array([0.1, 0.2, 0.3, 0.4], dtype=np.float32), "metadata": {"type": "blog"}},
+    {"id": "doc3", "values": np.array([0.5, 0.6, 0.7, 0.8], dtype=np.float32), "metadata": {"type": "news"}},
+]
+
+result = index.add(data)
+
+print(result.summary())   # ✅ 2 inserted, ❌ 0 errors
+```
+
+Each format is automatically parsed and validated internally, including support for NumPy arrays (np.ndarray). Errors and successes are returned in a structured BatchResult object for easy debugging and logging.
+
+<br/>
 
 ### 🧰 Additional functionality
 

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

@@ -1,11 +1,14 @@
-# ZeusDB Vector Database
+<p align="center" width="100%">
+  <img src="https://github.com/user-attachments/assets/ad21baec-6f4c-445c-b423-88a081ca2b97" alt="zeusdb-vector-database-logo-cropped" />
+  <h1 align="center">ZeusDB Vector Database</h1>
+</p>
 
 <!-- <h2 align="center">Fast, Rust-powered vector database for similarity search</h2> -->
 <!--**Fast, Rust-powered vector database for similarity search** -->
 
 <!-- badges: start -->
 
-<div align="left">
+<div align="center">
   <table>
     <tr>
       <td><strong>Meta</strong></td>
@@ -38,6 +41,8 @@ ZeusDB leverages the HNSW (Hierarchical Navigable Small World) algorithm for spe
 
 🔥 High-performance Rust backend 
 
+📥 Supports multiple input formats using a single, easy-to-use Python method
+
 🗂️ Metadata-aware filtering at query time
 
 🐍 Simple and intuitive Python API
@@ -104,17 +109,16 @@ vdb = VectorDatabase()
 # Initialize and set up the database resources
 index = vdb.create_index_hnsw(dim = 8, space = "cosine", M = 16, ef_construction = 200, expected_size=5)
 
-# Upload vector records
-vectors = {
-    "doc_001": ([0.1, 0.2, 0.3, 0.1, 0.4, 0.2, 0.6, 0.7], {"author": "Alice"}),
-    "doc_002": ([0.9, 0.1, 0.4, 0.2, 0.8, 0.5, 0.3, 0.9], {"author": "Bob"}),
-    "doc_003": ([0.11, 0.21, 0.31, 0.15, 0.41, 0.22, 0.61, 0.72], {"author": "Alice"}),
-    "doc_004": ([0.85, 0.15, 0.42, 0.27, 0.83, 0.52, 0.33, 0.95], {"author": "Bob"}),
-    "doc_005": ([0.12, 0.22, 0.33, 0.13, 0.45, 0.23, 0.65, 0.71], {"author": "Alice"}),
-}
+# Upload vector records using the unified `add()` method
+records = [
+    {"id": "doc_001", "values": [0.1, 0.2, 0.3, 0.1, 0.4, 0.2, 0.6, 0.7], "metadata": {"author": "Alice"}},
+    {"id": "doc_002", "values": [0.9, 0.1, 0.4, 0.2, 0.8, 0.5, 0.3, 0.9], "metadata": {"author": "Bob"}},
+    {"id": "doc_003", "values": [0.11, 0.21, 0.31, 0.15, 0.41, 0.22, 0.61, 0.72], "metadata": {"author": "Alice"}},
+    {"id": "doc_004", "values": [0.85, 0.15, 0.42, 0.27, 0.83, 0.52, 0.33, 0.95], "metadata": {"author": "Bob"}},
+    {"id": "doc_005", "values": [0.12, 0.22, 0.33, 0.13, 0.45, 0.23, 0.65, 0.71], "metadata": {"author": "Alice"}},
+]
 
-for doc_id, (vec, meta) in vectors.items():
-    index.add_point(doc_id, vec, metadata=meta)
+result = index.add(records)
 
 # Perform a similarity search and print the top 2 results
 # Query Vector
@@ -123,12 +127,73 @@ 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_all:
+for doc_id, score in results:
     print(f"{doc_id} (score={score:.4f})")
 ```
 
 <br/>
 
+### ➕ Adding Vectors – Multiple Formats Supported
+
+ZeusDB Vector Database supports multiple intuitive ways to insert data using index.add(...). All formats accept optional metadata per record.
+
+#### ✅ Format 1 – Single Object
+
+```python
+index.add({
+    "id": "doc1",
+    "values": [0.1, 0.2],
+    "metadata": {"text": "hello"}
+})
+
+print(result.summary())     # ✅ 1 inserted, ❌ 0 errors
+print(result.is_success())  # True
+```
+
+#### ✅ Format 2 – List of Objects
+
+```python
+index.add([
+    {"id": "doc1", "values": [0.1, 0.2], "metadata": {"text": "hello"}},
+    {"id": "doc2", "values": [0.3, 0.4], "metadata": {"text": "world"}}
+])
+
+print(result.summary())       # ✅ 2 inserted, ❌ 0 errors
+print(result.vector_shape)    # (2, 2)
+print(result.errors)          # []
+```
+
+#### ✅ Format 3 – Separate Arrays
+
+```python
+index.add({
+    "ids": ["doc1", "doc2"],
+    "embeddings": [[0.1, 0.2], [0.3, 0.4]],
+    "metadatas": [{"text": "hello"}, {"text": "world"}]
+})
+print(result)  # BatchResult(inserted=2, errors=0, shape=(2, 2))
+```
+
+#### ✅ Format 4 – Using NumPy Arrays
+
+ZeusDB also supports NumPy arrays as input for seamless integration with scientific and ML workflows.
+
+```python
+import numpy as np
+
+data = [
+    {"id": "doc2", "values": np.array([0.1, 0.2, 0.3, 0.4], dtype=np.float32), "metadata": {"type": "blog"}},
+    {"id": "doc3", "values": np.array([0.5, 0.6, 0.7, 0.8], dtype=np.float32), "metadata": {"type": "news"}},
+]
+
+result = index.add(data)
+
+print(result.summary())   # ✅ 2 inserted, ❌ 0 errors
+```
+
+Each format is automatically parsed and validated internally, including support for NumPy arrays (np.ndarray). Errors and successes are returned in a structured BatchResult object for easy debugging and logging.
+
+<br/>
 
 ### 🧰 Additional functionality
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "zeusdb-vector-database"
-version = "0.0.1"
+version = "0.0.3"
 description = "Blazing-fast vector DB with real-time similarity search and metadata filtering."
 readme = "README.md"
 authors = [
@@ -12,10 +12,12 @@ classifiers = [
     "Programming Language :: Rust",
     "Programming Language :: Python :: Implementation :: CPython",
 ]
-dependencies = []
+dependencies = [
+    "numpy>=2.2.6,<3.0.0"
+]
 
 [build-system]
-requires = ["maturin>=1.8.7,<2.0"]
+requires = ["maturin>=1.9.0,<2.0"]
 build-backend = "maturin"
 
 [tool.maturin]
@@ -28,7 +30,7 @@ include = ["LICENSE", "NOTICE", "README.md", "src/**"]
 
 [project.optional-dependencies]
 dev = [
-    "maturin >=1.8.7",
+    "maturin >=1.9.0",
     "pytest >=8.4.0",
 ]
 

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

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

zeusdb_vector_database-0.0.3/src/zeusdb_vector_database/vector_database.py

@@ -0,0 +1,50 @@
+"""
+vector_database.py
+
+Pure factory for creating vector indexes using Rust backend.
+Currently supports HNSW (Hierarchical Navigable Small World).
+"""
+from .zeusdb_vector_database import HNSWIndex
+
+class VectorDatabase:
+    """
+    Pure factory for creating vector indexes.
+    No state management - just creates and returns indexes.
+    """
+    
+    def __init__(self):
+        """Initialize VectorDatabase factory."""
+        pass
+
+    def create_index_hnsw(
+        self,
+        dim: int = 1536,
+        space: str = "cosine",
+        M: int = 16,
+        ef_construction: int = 200,
+        expected_size: int = 10000
+    ) -> HNSWIndex:
+        """
+        Creates a new HNSW (Hierarchical Navigable Small World) index.
+
+        Args:
+            dim: Vector dimension (default: 1536)
+            space: Distance metric, only 'cosine' supported (default: 'cosine')
+            M: Bidirectional links per node (default: 16, max: 256)
+            ef_construction: Construction candidate list size (default: 200)
+            expected_size: Expected number of vectors (default: 10000)
+
+        Returns:
+            HNSWIndex: Use this index directly for all operations
+
+        Example:
+            vdb = VectorDatabase()
+            index = vdb.create_index_hnsw(dim=1536, expected_size=10000)
+            index.add_point("doc1", vector, metadata)
+            results = index.query(query_vector, k=10)
+        """
+        try:
+            return HNSWIndex(dim, space, M, ef_construction, expected_size)
+        except Exception as e:
+            raise RuntimeError(f"Failed to create HNSW index: {e}") from e
+    

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

@@ -301,9 +301,9 @@ dependencies = [
 
 [[package]]
 name = "indexmap"
-version = "2.9.0"
+version = "2.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cea70ddb795996207ad57735b50c5982d8844f38ba9ee5f1aedcfb708a2aa11e"
+checksum = "fe4cd85333e22411419a0bcae1297d25e58c9443848b11dc6a86fefe8c78a661"
 dependencies = [
  "equivalent",
  "hashbrown",
@@ -375,13 +375,23 @@ checksum = "13dc2df351e3202783a1fe0d44375f7295ffb4049267b0f3018346dc122a1d94"
 
 [[package]]
 name = "mach2"
-version = "0.4.2"
+version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "19b955cdeb2a02b9117f121ce63aa52d08ade45de53e48fe6a38b39c10f6f709"
+checksum = "d640282b302c0bb0a2a8e0233ead9035e3bed871f0b7e81fe4a1ec829765db44"
 dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "matrixmultiply"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a06de3016e9fae57a36fd14dba131fccf49f74b40b7fbdb472f96e361ec71a08"
+dependencies = [
+ "autocfg",
+ "rawpointer",
+]
+
 [[package]]
 name = "memchr"
 version = "2.7.5"
@@ -423,6 +433,21 @@ dependencies = [
  "windows",
 ]
 
+[[package]]
+name = "ndarray"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "882ed72dce9365842bf196bdeedf5055305f11fc8c03dee7bb0194a6cad34841"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+]
+
 [[package]]
 name = "nix"
 version = "0.26.4"
@@ -436,6 +461,24 @@ dependencies = [
  "pin-utils",
 ]
 
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f"
+dependencies = [
+ "num-traits",
+]
+
 [[package]]
 name = "num-traits"
 version = "0.2.19"
@@ -455,6 +498,22 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "numpy"
+version = "0.25.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29f1dee9aa8d3f6f8e8b9af3803006101bb3653866ef056d530d53ae68587191"
+dependencies = [
+ "libc",
+ "ndarray",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "pyo3",
+ "pyo3-build-config",
+ "rustc-hash",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.3"
@@ -635,6 +694,12 @@ dependencies = [
  "getrandom",
 ]
 
+[[package]]
+name = "rawpointer"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
+
 [[package]]
 name = "rayon"
 version = "1.10.0"
@@ -693,6 +758,12 @@ version = "0.8.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2b15c43186be67a4fd63bee50d0303afffcef381492ebe2c5d87f324e1b8815c"
 
+[[package]]
+name = "rustc-hash"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "357703d41365b4b27c590e3ed91eabb1b663f07c4c084095e60cbed4362dff0d"
+
 [[package]]
 name = "same-file"
 version = "1.0.6"
@@ -736,9 +807,9 @@ checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
 
 [[package]]
 name = "syn"
-version = "2.0.103"
+version = "2.0.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e4307e30089d6fd6aff212f2da3a1f9e32f3223b1f010fb09b7c95f90f3ca1e8"
+checksum = "17b6f705963418cdb9927482fa304bc562ece2fdd4f616084c50b7023b435a40"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -1029,8 +1100,9 @@ dependencies = [
 
 [[package]]
 name = "zeusdb-vector-database"
-version = "0.0.1"
+version = "0.0.3"
 dependencies = [
  "hnsw_rs",
+ "numpy",
  "pyo3",
 ]

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

@@ -1,6 +1,6 @@
 [package]
 name = "zeusdb-vector-database"
-version = "0.0.1"
+version = "0.0.3"
 edition = "2021"
 resolver = "2" # <-- Avoid compiling unnecessary features from dependencies.
 
@@ -10,8 +10,9 @@ name = "zeusdb_vector_database" # <-- This is the name of the compiled Python mo
 crate-type = ["cdylib"]
 
 [dependencies]
-pyo3 = { version = "0.25.0", features = ["extension-module"] }
+pyo3 = { version = "0.25.1", features = ["extension-module"] }
 hnsw_rs = "0.3.2"
+numpy = "0.25.0"
 
 [profile.release]
 lto = true # <-- Enable Link-Time Optimization