vexra 1.1.1__tar.gz

vexra-1.1.1/Cargo.toml

@@ -0,0 +1,70 @@
+[workspace]
+resolver = "2"
+members = [
+    "crates/vexra-core",
+    "crates/vexra-storage",
+    "crates/vexra-index",
+    "crates/vexra-metadata",
+    "crates/vexra-query",
+    "crates/vexra-ffi",
+    "crates/vexra-cli",
+    "crates/vexra-server",
+    "crates/vexra-embedding",
+]
+
+[workspace.package]
+version = "1.0.0-rc1"
+edition = "2021"
+license = "MIT"
+repository = "https://github.com/embeddb/embeddb"
+authors = ["EmbedDB Contributors"]
+
+[workspace.dependencies]
+# Serialization
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+bytemuck = { version = "1", features = ["derive"] }
+
+# Error handling
+thiserror = "2"
+
+# Logging
+log = "0.4"
+tracing = "0.1"
+
+# Concurrency
+parking_lot = "0.12"
+arc-swap = "1"
+
+# CLI
+clap = { version = "4", features = ["derive"] }
+
+# Storage
+memmap2 = "0.9"
+crc32fast = "1"
+
+# Big arrays / SIMD
+rustix = "0.38"
+
+# Web server (Phase 2)
+# axum = "0.7"
+# tokio = { version = "1", features = ["full"] }
+# tower-http = { version = "0.5", features = ["cors", "fs"] }
+# rust-embed = "8"
+
+# ONNX (Phase 2, feature-gated)
+# ort = "2"
+
+# Text search (Phase 3)
+# tantivy = "0.22"
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+strip = true
+
+[profile.bench]
+opt-level = 3
+lto = true
+codegen-units = 1

vexra-1.1.1/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: vexra
+Version: 1.1.1
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: pytest>=7 ; extra == 'dev'
+Provides-Extra: dev
+Summary: Vexra Python SDK — embedded vector database
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/Mengxun326/embeddb
+Project-URL: Issues, https://github.com/Mengxun326/embeddb/issues
+
+# EmbedDB Python SDK
+
+Python bindings for EmbedDB — the embedded vector database.
+
+## Installation
+
+```bash
+pip install embeddb
+```
+
+## Quick Start
+
+```python
+import embeddb
+
+# Open or create a database
+db = embeddb.Database("data.embeddb")
+
+# Create a collection
+col = db.create_collection("docs", dimension=384, distance=embeddb.DistanceMetric.COSINE)
+
+# Insert vectors
+col.insert({"id": "doc1", "vector": [0.1] * 384, "metadata": {"title": "Hello"}})
+col.insert({"id": "doc2", "vector": [0.2] * 384, "metadata": {"title": "World"}})
+
+# Search
+results = col.search(vector=[0.15] * 384, top_k=10)
+for hit in results:
+    print(f"{hit.id}: {hit.score:.4f}")
+```
+
+## API
+
+### Database
+
+- `Database(path)` — Open or create a database
+- `db.create_collection(name, dimension, distance)` — Create a collection
+- `db.get_collection(name)` — Get an existing collection
+- `db.close()` — Close the database
+
+### Collection
+
+- `col.insert(doc)` — Insert a document `{"id": str, "vector": [float], "metadata": dict}`
+- `col.search(vector, top_k=10)` — Search for nearest neighbors
+
+### Distance Metrics
+
+- `DistanceMetric.COSINE` — Cosine distance
+- `DistanceMetric.EUCLIDEAN` — Euclidean (L2) distance
+- `DistanceMetric.DOT_PRODUCT` — Dot product similarity
+

vexra-1.1.1/README.md

@@ -0,0 +1,50 @@
+# EmbedDB Python SDK
+
+Python bindings for EmbedDB — the embedded vector database.
+
+## Installation
+
+```bash
+pip install embeddb
+```
+
+## Quick Start
+
+```python
+import embeddb
+
+# Open or create a database
+db = embeddb.Database("data.embeddb")
+
+# Create a collection
+col = db.create_collection("docs", dimension=384, distance=embeddb.DistanceMetric.COSINE)
+
+# Insert vectors
+col.insert({"id": "doc1", "vector": [0.1] * 384, "metadata": {"title": "Hello"}})
+col.insert({"id": "doc2", "vector": [0.2] * 384, "metadata": {"title": "World"}})
+
+# Search
+results = col.search(vector=[0.15] * 384, top_k=10)
+for hit in results:
+    print(f"{hit.id}: {hit.score:.4f}")
+```
+
+## API
+
+### Database
+
+- `Database(path)` — Open or create a database
+- `db.create_collection(name, dimension, distance)` — Create a collection
+- `db.get_collection(name)` — Get an existing collection
+- `db.close()` — Close the database
+
+### Collection
+
+- `col.insert(doc)` — Insert a document `{"id": str, "vector": [float], "metadata": dict}`
+- `col.search(vector, top_k=10)` — Search for nearest neighbors
+
+### Distance Metrics
+
+- `DistanceMetric.COSINE` — Cosine distance
+- `DistanceMetric.EUCLIDEAN` — Euclidean (L2) distance
+- `DistanceMetric.DOT_PRODUCT` — Dot product similarity

vexra-1.1.1/crates/vexra-core/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "vexra-core"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+description = "EmbedDB core: public API, Database and Collection handles"
+
+[dependencies]
+vexra-storage = { path = "../vexra-storage" }
+vexra-index = { path = "../vexra-index" }
+vexra-metadata = { path = "../vexra-metadata" }
+serde.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+log.workspace = true
+parking_lot.workspace = true
+
+[dev-dependencies]
+tempfile = "3"
+rand = "0.8"
+criterion = { version = "0.5", features = ["html_reports"] }
+
+[[bench]]
+name = "search_bench"
+harness = false

vexra-1.1.1/crates/vexra-core/benches/search_bench.rs

@@ -0,0 +1,185 @@
+//! EmbedDB benchmarks: Flat vs HNSW insert and search performance.
+//!
+//! Run with: cargo bench
+
+use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
+use vexra_core::collection::{Collection, IndexType};
+use vexra_core::config::{CollectionConfig, SearchQuery};
+use vexra_core::DistanceMetric;
+use vexra_index::flat::FlatIndex;
+use vexra_index::hnsw::graph::HnswGraph;
+use vexra_index::hnsw::HnswConfig;
+use vexra_index::{SearchResult, VectorIndex};
+use rand::Rng;
+use std::time::Duration;
+
+const DIM: usize = 128;
+
+/// Generate `n` random normalized vectors of dimension `DIM`.
+fn random_vectors(n: usize) -> Vec<Vec<f32>> {
+    let mut rng = rand::thread_rng();
+    (0..n)
+        .map(|_| (0..DIM).map(|_| rng.gen::<f32>()).collect())
+        .collect()
+}
+
+/// Build a random FlatIndex with `n` vectors.
+fn build_flat(n: usize) -> FlatIndex {
+    let mut idx = FlatIndex::new(DIM, DistanceMetric::Euclidean);
+    for (i, v) in random_vectors(n).into_iter().enumerate() {
+        idx.insert(i as u64, &v).unwrap();
+    }
+    idx
+}
+
+/// Build a random HNSW graph with `n` vectors.
+fn build_hnsw(n: usize) -> HnswGraph {
+    let config = HnswConfig::new(16).with_ef_construction(200);
+    let mut graph = HnswGraph::new(DIM, DistanceMetric::Euclidean, config);
+    for (i, v) in random_vectors(n).into_iter().enumerate() {
+        graph.insert(i as u64, &v).unwrap();
+    }
+    graph
+}
+
+// ---------------------------------------------------------------------------
+// Insert benchmarks
+// ---------------------------------------------------------------------------
+
+fn bench_insert_flat(c: &mut Criterion) {
+    let mut group = c.benchmark_group("insert_flat");
+    for n in [1000, 10000, 50000] {
+        group.throughput(Throughput::Elements(n as u64));
+        group.bench_with_input(BenchmarkId::from_parameter(n), &n, |b, &n| {
+            b.iter(|| build_flat(black_box(n)));
+        });
+    }
+}
+
+fn bench_insert_hnsw(c: &mut Criterion) {
+    let mut group = c.benchmark_group("insert_hnsw");
+    for n in [1000, 10000, 50000] {
+        group.throughput(Throughput::Elements(n as u64));
+        group.bench_with_input(BenchmarkId::from_parameter(n), &n, |b, &n| {
+            b.iter(|| build_hnsw(black_box(n)));
+        });
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Search benchmarks (100 queries, avg latency)
+// ---------------------------------------------------------------------------
+
+fn bench_search_flat(c: &mut Criterion) {
+    let mut group = c.benchmark_group("search_flat");
+    for n in [1000, 10000, 50000] {
+        let idx = build_flat(n);
+        let queries = random_vectors(100);
+        group.throughput(Throughput::Elements(100));
+        group.bench_with_input(BenchmarkId::from_parameter(n), &(idx, queries), |b, (idx, queries)| {
+            b.iter(|| {
+                for q in queries {
+                    black_box(idx.search(q, 10).unwrap());
+                }
+            });
+        });
+    }
+}
+
+fn bench_search_hnsw(c: &mut Criterion) {
+    let mut group = c.benchmark_group("search_hnsw");
+    for n in [1000, 10000, 50000] {
+        let graph = build_hnsw(n);
+        let queries = random_vectors(100);
+        group.throughput(Throughput::Elements(100));
+        group.bench_with_input(BenchmarkId::from_parameter(n), &(graph, queries), |b, (graph, queries)| {
+            b.iter(|| {
+                for q in queries {
+                    black_box(graph.search(q, 10).unwrap());
+                }
+            });
+        });
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Recall benchmark
+// ---------------------------------------------------------------------------
+
+fn bench_recall_hnsw(c: &mut Criterion) {
+    let mut group = c.benchmark_group("recall_hnsw");
+    let n = 10000;
+    let k = 10;
+
+    // Build both indexes
+    let flat = build_flat(n);
+    let hnsw = build_hnsw(n);
+    let queries = random_vectors(100);
+
+    // Compute ground truth with Flat (exact)
+    let ground_truth: Vec<Vec<SearchResult>> = queries
+        .iter()
+        .map(|q| flat.search(q, k).unwrap())
+        .collect();
+
+    group.bench_function("recall@10_vs_flat", |b| {
+        b.iter(|| {
+            let mut total_hits = 0usize;
+            let mut total = 0usize;
+            for (q, gt) in queries.iter().zip(ground_truth.iter()) {
+                let approx = hnsw.search(q, k).unwrap();
+                // Count intersection
+                let gt_ids: std::collections::HashSet<u64> = gt.iter().map(|r| r.id).collect();
+                total_hits += approx.iter().filter(|r| gt_ids.contains(&r.id)).count();
+                total += k;
+            }
+            let recall = total_hits as f64 / total as f64;
+            black_box(recall);
+        });
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Collection persistence benchmark
+// ---------------------------------------------------------------------------
+
+fn bench_persist_collection(c: &mut Criterion) {
+    let mut group = c.benchmark_group("persist_collection");
+    let n = 1000;
+
+    group.bench_function("insert_1000_persist", |b| {
+        b.iter(|| {
+            let dir = tempfile::tempdir().unwrap();
+            let path = dir.path().join("bench.embeddb");
+            let pc = std::sync::Arc::new(
+                vexra_storage::page_cache::PageCache::open(&path, Default::default()).unwrap(),
+            );
+            let config = CollectionConfig::new("bench", DIM);
+            let mut col = Collection::new_persistent(config, IndexType::Flat, pc).unwrap();
+            let vectors = random_vectors(n);
+            for (i, v) in vectors.iter().enumerate() {
+                col.insert(vexra_core::config::Document::with_vector(
+                    format!("doc_{}", i), v.clone(),
+                ))
+                .unwrap();
+            }
+            black_box(col.vector_count());
+        });
+    });
+}
+
+criterion_group!(
+    name = benches;
+    config = Criterion::default()
+        .sample_size(30)
+        .measurement_time(Duration::from_secs(10))
+        .warm_up_time(Duration::from_secs(2));
+    targets =
+        bench_insert_flat,
+        bench_search_flat,
+        bench_insert_hnsw,
+        bench_search_hnsw,
+        bench_recall_hnsw,
+        bench_persist_collection,
+);
+criterion_main!(benches);