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

{zeusdb_vector_database-0.0.2 → 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.2 → zeusdb_vector_database-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zeusdb-vector-database
-Version: 0.0.2
+Version: 0.0.4
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Requires-Dist: numpy>=2.2.6,<3.0.0
@@ -17,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>
@@ -57,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
@@ -70,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
@@ -123,31 +132,104 @@ 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
 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/>
 
+### ➕ 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
 
@@ -215,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.2 → zeusdb_vector_database-0.0.4}/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
@@ -51,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
@@ -104,31 +113,104 @@ 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
 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/>
 
+### ➕ 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
 
@@ -196,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.2 → zeusdb_vector_database-0.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zeusdb-vector-database"
-version = "0.0.2"
+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.2 → zeusdb_vector_database-0.0.4}/src/zeusdb_vector_database/__init__.py

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

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

@@ -382,6 +382,16 @@ 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"
@@ -1029,8 +1100,9 @@ dependencies = [
 
 [[package]]
 name = "zeusdb-vector-database"
-version = "0.0.2"
+version = "0.0.4"
 dependencies = [
  "hnsw_rs",
+ "numpy",
  "pyo3",
 ]

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

@@ -1,6 +1,6 @@
 [package]
 name = "zeusdb-vector-database"
-version = "0.0.2"
+version = "0.0.4"
 edition = "2021"
 resolver = "2" # <-- Avoid compiling unnecessary features from dependencies.
 
@@ -12,6 +12,7 @@ crate-type = ["cdylib"]
 [dependencies]
 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