bump versions, update workflows, update examples

Author: nubskr

.github/workflows/e2e_tests.yml

@@ -8,6 +8,7 @@ on:
 
 env:
   CARGO_TERM_COLOR: always
+  WALRUS_QUIET: "1"
 
 jobs:
   e2e:

.github/workflows/integration_tests.yml

@@ -8,6 +8,7 @@ on:
 
 env:
   CARGO_TERM_COLOR: always
+  WALRUS_QUIET: "1"
 
 jobs:
   integration:

.github/workflows/lint.yml

@@ -8,6 +8,7 @@ on:
 
 env:
   CARGO_TERM_COLOR: always
+  WALRUS_QUIET: "1"
 
 jobs:
   fmt:

.github/workflows/regression_tests.yml

@@ -8,6 +8,7 @@ on:
 
 env:
   CARGO_TERM_COLOR: always
+  WALRUS_QUIET: "1"
 
 jobs:
   regression:

.github/workflows/unit_tests.yml

@@ -8,6 +8,7 @@ on:
 
 env:
   CARGO_TERM_COLOR: always
+  WALRUS_QUIET: "1"
 
 jobs:
   test:

CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to SatoriDB will be documented in this file.
 
+## [0.1.1] - 2025-12-23
+
+### Breaking Changes
+
+Complete public API redesign. The old `SatoriHandle` + `SatoriDbConfig` API is gone.
+
+### New API
+
+**Simple open:**
+```rust
+let db = SatoriDb::open("my_app")?;
+```
+
+**Builder for configuration:**
+```rust
+let db = SatoriDb::builder("my_app")
+    .workers(4)
+    .fsync_ms(100)
+    .data_dir("/custom/path")
+    .virtual_nodes(8)
+    .build()?;
+```
+
+**Core operations:**
+- `db.insert(id, vector)` — insert (rejects duplicates)
+- `db.delete(id)` — delete by ID
+- `db.query(vector, top_k)` — nearest neighbor search
+- `db.query_with_probes(vector, top_k, probes)` — query with custom probe count
+- `db.query_with_vectors(vector, top_k)` — query returning stored vectors
+- `db.get(ids)` — fetch vectors by ID
+- `db.stats()` — database statistics
+- `db.flush()` — flush pending writes
+
+**Async variants:** `insert_async`, `delete_async`, `query_async`, `get_async`
+
+### Improvements
+
+- **Auto-shutdown on Drop** — no manual shutdown required
+- **Duplicate ID rejection** — bloom filter optimization for fast duplicate detection
+- **Walrus logs suppressed by default** — set `WALRUS_QUIET=0` to enable
+
+### Removed
+
+- `SatoriDbConfig` struct
+- `SatoriHandle` direct access
+- `upsert_blocking`, `query_blocking` naming
+
 ## [0.1.0] - 2025-12-21
 
 Initial release.

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "satoridb"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"
 description = "Embedded vector database for approximate nearest neighbor search (experimental)."
 readme = "README.md"

Cargo.toml

@@ -11,33 +11,23 @@
 
 ![architecture](./assets/architecture.png)
 
-SatoriDB runs entirely in-process on a single node. It uses a **two-tier search** architecture:
+SatoriDB is a two-tier search system: a small "hot" index in RAM routes queries to "cold" vector data on disk. This lets us handle billion-scale datasets without holding everything in memory.
 
-1. **Routing (HNSW)**: A quantized HNSW index over bucket centroids finds the most relevant clusters in O(log N)
-2. **Scanning (Workers)**: CPU-pinned Glommio executors scan selected buckets in parallel using SIMD-accelerated L2 distance
+**Routing (Hot Tier)**
 
-We use a variant of [SPFresh](https://arxiv.org/pdf/2410.14452), Vectors are organized into **buckets** (clusters of similar vectors). A background rebalancer automatically splits buckets via k-means when they exceed a threshold, keeping search efficient as data grows. All data is persisted to walrus high performance storage engine and we use RocksDB indexes for point lookups.
+Quantized HNSW index over bucket centroids. Centroids are scalar-quantized (f32 → u8) so the whole routing index fits in RAM even at 500k+ buckets. When a query comes in, HNSW finds the top-K most relevant buckets in O(log N). We only search those, not the entire dataset.
 
-See [docs/architecture.md](docs/architecture.md) for detailed documentation including:
-- System overview and component diagrams
-- Two-tier search architecture
-- Storage layer (Walrus + RocksDB)
-- Rebalancer and clustering algorithms
-- Data flow diagrams
+**Scanning (Cold Tier)**
 
-```
-SatoriHandle ──▶ Router Manager ──▶ HNSW Index (centroids)
-      │                                   │
-      │         ┌─────────────────────────┘
-      │         ▼
-      │    Bucket IDs ──▶ Consistent Hash Ring
-      │                          │
-      ▼                          ▼
-  Workers ◀──────────────── bucket_id → shard
-      │
-      ▼
-  Walrus (storage) + RocksDB (indexes)
-```
+CPU-pinned Glommio workers scan selected buckets in parallel. Shared-nothing: each worker has its own io_uring ring, LRU cache, and pre-allocated heap. No cross-core synchronization on the query path. SIMD everywhere: L2 distance, dot products, quantization, k-means assignments all have AVX2/AVX-512 paths. Cache misses stream from disk without blocking.
+
+**Clustering & Rebalancing**
+
+Vectors are grouped into buckets (clusters) via k-means. A background rebalancer automatically splits buckets when they exceed ~2000 vectors, keeping bucket sizes predictable. Predictable sizes = predictable query latency. Inspired by [SPFresh](https://arxiv.org/pdf/2410.14452).
+
+**Storage**
+
+Walrus handles bulk vector storage (append-only, io_uring, topic-per-bucket). RocksDB indexes handle point lookups (fetch-by-id, duplicate detection). See [docs/architecture.md](docs/architecture.md) for the full deep-dive.
 
 ## Features
 
@@ -63,7 +53,11 @@ cargo add satoridb
 use satoridb::SatoriDb;
 
 fn main() -> anyhow::Result<()> {
-    let db = SatoriDb::open("my_app")?;
+    let db = SatoriDb::builder("my_app")
+        .workers(4)              // Worker threads (default: num_cpus)
+        .fsync_ms(100)           // Fsync interval (default: 200ms)
+        .data_dir("/tmp/mydb")   // Data directory
+        .build()?;
 
     db.insert(1, vec![0.1, 0.2, 0.3])?;
     db.insert(2, vec![0.2, 0.3, 0.4])?;
@@ -150,4 +144,4 @@ cargo build --release
 
 See [LICENSE](LICENSE).
 
-> **Note**: SatoriDB is in early development (v0.1.0). APIs may change between versions. See [CHANGELOG.md](CHANGELOG.md) for release notes.
+> **Note**: SatoriDB is in early development (v0.1.1). APIs may change between versions. See [CHANGELOG.md](CHANGELOG.md) for release notes.