simplevecdb 2.6.0__tar.gz → 2.6.2__tar.gz

simplevecdb-2.6.2/.github/FUNDING.yml

@@ -0,0 +1,5 @@
+github: [coderdayton]
+custom:
+  [
+    "https://ko-fi.com/xbbvii",
+  ]

simplevecdb-2.6.2/.gitignore

@@ -0,0 +1,74 @@
+# Python / uv
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.tox/
+.nox/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.cache/
+.hypothesis/
+cython_debug/
+
+# Coverage
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+htmlcov/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Environment / secrets
+.env
+.envrc
+.direnv/
+
+# Databases (SimpleVecDB writes WAL/SHM sidecars)
+*.db
+*.db-journal
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite3
+
+# Editor / IDE
+.vscode/
+.idea/
+.history/
+*.iml
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Docs build
+site/
+
+# Agentic CLI tools (per-developer state)
+.opencode/
+opencode.json
+.claude/
+.codex
+
+# Project-specific scratch
+simplevecdb_plan.md
+AGENTS.md
+NEXT_UPDATES.md
+pro_pack/
+
+
+# Local notes
+IMPORTANT.md

{simplevecdb-2.6.0 → simplevecdb-2.6.2}/CHANGELOG.md

@@ -5,6 +5,215 @@ All notable changes to SimpleVecDB will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.2] - 2026-06-06
+
+### Correctness and contract fixes
+
+Hardening of the index-rebuild, search, clustering, and integration layers
+surfaced by a code review. Two intentional behavior changes are noted under
+“Changed”.
+
+#### Fixed
+
+- **`rebuild_index` no longer bricks a collection on failure** — if building or
+  swapping the new HNSW index raises after the live index is closed, the
+  collection re-opens the intact on-disk index instead of holding a closed one.
+- **Catalog write lock released on connection error** — a raising
+  `connection.__enter__` no longer leaks the catalog lock (which could deadlock
+  the database).
+- **Max-Marginal-Relevance respects the distance metric** — MMR on `l2`
+  collections used a cosine-specific relevance formula that swamped the
+  diversity term; it now uses a bounded, metric-appropriate relevance.
+- **`similarity_search_batch` fills `k` under filters and accepts text queries**
+  — large filtered batches no longer silently under-deliver, and a text query in
+  a large batch behaves the same as in a small one.
+- **Clustering handles impossible `n_clusters`** — `ClusterEngine.cluster_vectors`
+  raises a clear error when `n_clusters` exceeds the number of vectors;
+  `Collection.cluster()` caps `n_clusters` to the number of vectors actually
+  clustered (the sample when `sample_size` is set, fixing a latent error when
+  `n_clusters > sample_size`).
+- **Metadata filter keys match literally** — a filter key containing a dot
+  (e.g. `{"a.b": x}`) now matches the literal top-level key `a.b` instead of the
+  nested JSON path `a → b`, consistent with the Python filter path. Keys
+  containing a double-quote are rejected.
+- **BIT-quantized vector retrieval unpacks correctly** — `UsearchIndex.get()`
+  (used by the MMR fallback) returned packed bytes for BIT indexes instead of
+  the unpacked ±1 float vectors; it now unpacks them.
+- **`rebuild_index` no longer blocks the database during the HNSW build** — the
+  expensive build runs without the shared lock (held only to snapshot and swap);
+  writes that land during the build are folded into the new index before the
+  swap.
+- **Embedding server caps request body size** — an ASGI middleware rejects
+  request bodies larger than the server's own accept limits before they are
+  buffered/parsed, closing an unauthenticated memory-exhaustion vector (only
+  relevant with the `[server]` extra exposed on a network). A missing
+  encryption salt sidecar now logs a warning instead of silently falling back
+  to the shared legacy salt.
+- **Robustness pass** — malformed FTS5 keyword queries raise `ValueError` instead
+  of a raw SQLite error; the cluster-state table is created eagerly so a
+  rolled-back first `save_cluster` cannot desync it; a non-integer
+  `EMBEDDING_BATCH_SIZE`/`EMBEDDING_SERVER_MAX_REQUEST_ITEMS` env value warns and
+  falls back instead of crashing import; `vacuum()` holds the DB lock; a failed
+  index add after the catalog commit is logged (divergence visibility); hybrid
+  search applies the Python metadata filter on the keyword side too (SQL/Python
+  parity); `logging.configure_logging` swaps handlers atomically.
+- **LangChain `asimilarity_search_with_score`** offloads to a thread instead of
+  blocking the event loop.
+
+#### Changed
+
+- **`AsyncVectorCollection.increment_metadata` now returns `int`** (1 if the row
+  existed and was updated, 0 otherwise), matching the synchronous API; it
+  previously discarded the value and returned `None`.
+- **LlamaIndex metadata filters fail loudly on unsupported shapes** — the
+  `SimpleVecDBLlamaStore` adapter now maps comparison operators
+  (`$gt/$gte/$lt/$lte/$ne/$in/$nin`) instead of silently treating them as
+  equality, and raises `NotImplementedError` for `OR`/`NOT` conditions and
+  unsupported operators rather than returning wrong results.
+- **LangChain relevance scoring now works** — `SimpleVecDBVectorStore` implements
+  `_select_relevance_score_fn`, so `similarity_search_with_relevance_scores` and
+  `as_retriever(search_type="similarity_score_threshold")` return metric-aware
+  `[0, 1]` relevance (higher = better). `similarity_search_with_score` still
+  returns the raw distance (FAISS/Chroma convention), now documented as such.
+
+### Clustering and hierarchy fixes
+
+Internal correctness and performance work on the clustering and hierarchy
+layers. No public API changes; existing databases are unaffected.
+
+#### Fixed
+
+- **`load_cluster` survives empty k-means clusters** — when k-means leaves a
+  requested cluster empty (common with duplicate vectors or `n_clusters` near
+  the number of distinct points), the stored `n_clusters` is smaller than the
+  number of centroid rows. The centroid reshape now derives its row count from
+  the stored buffer rather than `n_clusters`, which previously raised
+  `ValueError` on load.
+- **`assign_to_cluster` matches metadata keys literally** — a `metadata_key`
+  containing `.` or `[` is now matched as a literal top-level key (via
+  `json_each`) instead of being misread as a nested JSON path, which had caused
+  every already-assigned document to be re-assigned on each call.
+- **`cluster(algorithm="hdbscan", sample_size=…)` raises instead of silently
+  dropping documents** — HDBSCAN produces no centroids, so out-of-sample
+  documents cannot be assigned. The combination now raises a clear `ValueError`
+  rather than clustering only the sample.
+
+#### Performance
+
+- **BLAS-backed out-of-sample centroid assignment** — nearest-centroid
+  assignment uses the `‖c‖² − 2·x·c` expansion (a single matmul) instead of
+  materialising the dense `(n_vectors, n_centroids, dim)` broadcast temporary
+  that could exhaust memory on large collections.
+- **Unassigned-id lookup pushed into SQLite** — `assign_to_cluster(doc_ids=None)`
+  finds documents lacking the cluster key with one `json_each` query instead of
+  loading and JSON-parsing every row's text and metadata.
+- **Bounded ancestor-walk for cycle detection** — `set_parent` detects
+  parent/child cycles by walking the ancestor chain with a depth-bounded
+  recursive CTE instead of materialising the entire descendant subtree.
+
+## [2.6.1] - 2026-05-10
+
+### Storage, mutation, and eventing improvements
+
+This release closes ten long-standing gaps in the catalog layer with a coherent
+set of additive primitives. No public API breaks; existing 2.6.0 databases
+upgrade transparently (the new tables are created on first open).
+
+#### New features
+
+- **Native vector update via pending buffer** — `collection.update_embedding(id, vector)`
+  writes a row to a per-collection `_pending_vectors` overlay inside one SQL
+  transaction; the new vector becomes visible to reads immediately and is
+  promoted to the HNSW index on `collection.pending.flush()`. Removes the
+  HNSW remove+re-add churn previously required for in-place updates.
+- **Bulk vector math** — `collection.pending.update_many([(id, vec), …])` and
+  `collection.pending.blend_toward(ids, centroid, alpha)` for batched edits.
+- **Atomic transaction boundary** — `with db.transaction() as tx: …` and
+  `with collection.tx(): …` wrap a SAVEPOINT around catalog writes
+  (metadata, counters, edges, events, TTL, and `update_embedding`'s
+  pending overlay) so a raised exception rolls all SQL writes back.
+  Coarse vector mutations (`add_texts`, `delete`) are NOT rolled back —
+  use `update_embedding` + `pending.flush()` for vector changes that
+  must be commit-gated. Nested contexts share a single savepoint stack
+  via the new `_TxState` helper.
+- **Weighted directed edges** — new `collection.edges` namespace with
+  `add_edge / get_edges / update_edge / delete_edge / prune` over a
+  per-collection `_edges` table. Numeric columns (`weight`, `bonus`, `hits`,
+  `last_touch`) are addressable by the new range-filter grammar; deltas
+  (`dweight=+0.02, dhits=+1`) compile to a single atomic SQL UPDATE.
+- **Atomic counter increments** — `collection.increment_metadata(id, {"hits": 1, "drift": 0.02})`
+  applies a dict of numeric deltas to JSON metadata in one statement using
+  chained `json_set(... json_extract + ?)` calls. WAL-atomic; safe under
+  concurrent writers.
+- **Mongo-style range filters** — `filter={"score": {"$gt": 0.5, "$lte": 0.9}}`
+  on `similarity_search`, `keyword_search`, `hybrid_search`, `edges.get_edges`,
+  and `events.read`. Supported operators: `$eq $ne $gt $gte $lt $lte $in $nin
+  $exists $between`. Tuple shorthand (`("range", lo, hi)`, `(">", x)`) is
+  normalised into the operator-dict form.
+- **Append-only change feed** — every mutating method now appends one row to
+  a per-collection `_events` table (kind, doc_id, payload, monotonic seq).
+  `collection.events.read(since=, kind=, limit=)`,
+  `collection.events.subscribe(since=, poll_interval=)`, and
+  `collection.events.prune(before_seq=)` expose the feed; cross-process
+  visibility comes from the existing WAL mode.
+- **TTL / expiry hooks** — `collection.ttl.set(id, seconds=…, on_expire="delete"|"callback")`,
+  `collection.ttl.clear(id)`, and `collection.ttl.sweep()` over a
+  `_ttl` table; `start_background(interval=…)` runs the sweep in a daemon
+  thread (off by default).
+- **Incremental rebuild scheduler** — `collection.maintenance.rebuild_if_needed(max_pending=, max_deleted=)`
+  triggers a full `rebuild_index()` only when the configured pending /
+  tombstone / wall-time thresholds are crossed.
+- **Multi-process write safety** — added `PRAGMA busy_timeout=5000` and
+  `PRAGMA foreign_keys=ON` at every connection-open site (encrypted and
+  unencrypted). The native 5 s wait window reduces `DatabaseLockedError`
+  pressure under contention; foreign keys cascade-delete pending /
+  edges / TTL rows when a doc is deleted. The events table is
+  intentionally FK-less so the audit trail survives deletions.
+- **Async wrappers** — `AsyncVectorCollection` gains async equivalents of the
+  new methods (`update_embedding`, `flush_pending`, `increment_metadata`,
+  `add_edge`, `update_edge`, `delete_edge`, `get_edges`, `set_ttl`,
+  `clear_ttl`, `sweep_ttl`, `read_events`, `last_event_seq`,
+  `rebuild_if_needed`).
+
+#### New types & constants
+
+- `simplevecdb.types`: `Edge`, `Event`, `TTLEntry` frozen dataclasses.
+- `simplevecdb.constants`: `PENDING_FLUSH_DEFAULT_BATCH=1000`,
+  `EVENTS_POLL_INTERVAL_S=0.1`, `EVENTS_RETENTION_LIMIT=100_000`,
+  `TTL_SWEEP_DEFAULT_INTERVAL_S=60.0`, `REBUILD_PENDING_THRESHOLD=5_000`,
+  `REBUILD_TOMBSTONE_THRESHOLD=5_000`, `REBUILD_MIN_INTERVAL_S=3600.0`,
+  `SQLITE_BUSY_TIMEOUT_MS=5000`.
+
+#### Test coverage
+
+- `tests/unit/test_v26_1_features.py` — 25 tests covering the five must-have
+  primitives end-to-end: `update_embedding` + pending buffer + flush; edges
+  CRUD with atomic deltas, range filtering, and prune; `increment_metadata`
+  under 800-thread contention (exact total preserved); transaction rollback
+  and commit semantics; Mongo-style and tuple-shorthand range filters in
+  `similarity_search`; events append on every mutation; TTL sweep with
+  `delete` and `callback` paths; threshold-driven rebuild scheduler.
+
+#### Removed
+
+- **`sqlite-vec` dependency** dropped from `pyproject.toml`. The package was
+  never imported and the v1.x → v2.0 auto-migration code path could not have
+  worked without explicitly loading the extension at connection time.
+- **`MigrationRequiredError`**, **`VectorDB.check_migration()`**, and the
+  **`auto_migrate=`** constructor flag have been removed. Databases written
+  by `simplevecdb < 2.0.0` (sqlite-vec backend) are no longer auto-migrated
+  on open. To upgrade a v1.x database, dump the rows with a v1.x install and
+  re-ingest them through the v2 API; or stay on the last release that shipped
+  the migration path (anything ≤ v2.6.1's predecessor).
+- The catalog helpers `check_legacy_sqlite_vec`, `get_legacy_vectors`, and
+  `drop_legacy_vec_table` are gone alongside the migration entry point.
+
+#### Out of scope
+
+- No external pub/sub for events — polling only.
+- No multi-master writer support; single-writer + many readers remains the
+  recommended topology.
+
 ## [2.6.0] - 2026-05-06
 
 ### Review pass 3 — final correctness/security pass before tag

simplevecdb-2.6.2/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.4
+Name: simplevecdb
+Version: 2.6.2
+Summary: Dead-simple local vector database powered by usearch HNSW.
+Project-URL: Homepage, https://github.com/CoderDayton/simplevecdb
+Project-URL: Repository, https://github.com/CoderDayton/simplevecdb
+Project-URL: Issues, https://github.com/CoderDayton/simplevecdb/issues
+Project-URL: Changelog, https://github.com/CoderDayton/simplevecdb/blob/main/CHANGELOG.md
+Author-email: Dayton Dunbar <coderdayton14@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: embeddings,hnsw,langchain,llamaindex,rag,similarity-search,sqlite,usearch,vector-database,vectordb
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0
+Requires-Dist: hdbscan>=0.8.33
+Requires-Dist: numpy>=1.24
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: sqlcipher3-binary>=0.5.0
+Requires-Dist: usearch>=2.16.3
+Provides-Extra: examples
+Requires-Dist: ollama; extra == 'examples'
+Provides-Extra: integrations
+Requires-Dist: langchain-core>=1.0.7; extra == 'integrations'
+Requires-Dist: langchain-openai>=1.0.3; extra == 'integrations'
+Requires-Dist: llama-index-llms-ollama>=0.9.0; extra == 'integrations'
+Requires-Dist: llama-index-llms-openai-like>=0.5.3; extra == 'integrations'
+Requires-Dist: llama-index>=0.14.8; extra == 'integrations'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.115; extra == 'server'
+Requires-Dist: sentence-transformers>=5.0; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'server'
+Description-Content-Type: text/markdown
+
+# SimpleVecDB
+
+[![CI](https://github.com/coderdayton/simplevecdb/actions/workflows/ci.yml/badge.svg)](https://github.com/coderdayton/simplevecdb/actions)
+[![PyPI](https://img.shields.io/pypi/v/simplevecdb?color=blue)](https://pypi.org/project/simplevecdb/)
+[![License: MIT](https://img.shields.io/github/license/coderdayton/simplevecdb)](LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/coderdayton/simplevecdb?style=social)](https://github.com/coderdayton/simplevecdb)
+
+<a href='https://ko-fi.com/U7U01WTJF9' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi3.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
+
+**A local-first, embedded vector database backed by SQLite and usearch.**
+
+SimpleVecDB pairs **Chroma-like ergonomics** with a **file-based** store — a SQLite database for metadata and text alongside a `usearch` HNSW index per collection. It provides high-performance vector search, quantization, and hybrid retrieval with no separate services to run. It fits local RAG pipelines, offline agents, and any application that needs production-grade vector search without the operational overhead of a hosted database.
+
+## Why SimpleVecDB?
+
+- **Zero Infrastructure** — Local files on disk: a SQLite database plus a `usearch` index. No Docker, no Redis, no external services.
+- **High Performance** — usearch HNSW indexing with adaptive search: brute-force under 10k vectors (perfect recall), HNSW above that.
+- **Portable** — Runs anywhere SQLite runs: Linux, macOS, Windows, and WASM.
+- **Async Support** — A complete async/await surface with optional executor injection for thread-safe ONNX/usearch sharing.
+- **Integrations Included** — Optional FastAPI embeddings server and LangChain/LlamaIndex adapters via the `[integrations]` extra.
+- **Production Ready** — Hybrid search (BM25 + vector), metadata filtering, multi-collection support, and automatic hardware acceleration.
+
+### When to Choose SimpleVecDB
+
+| Use Case                       | SimpleVecDB           | Cloud Vector DB          |
+| :----------------------------- | :-------------------- | :----------------------- |
+| **Local RAG applications**     | ✅ Perfect fit        | ❌ Overkill + latency    |
+| **Offline-first agents**       | ✅ No internet needed | ❌ Requires connectivity |
+| **Prototyping & MVPs**         | ✅ Zero config        | ⚠️ Setup overhead        |
+| **Multi-tenant SaaS at scale** | ⚠️ Consider sharding  | ✅ Built for this        |
+| **Budget-conscious projects**  | ✅ $0/month           | ❌ $50-500+/month        |
+
+## Prerequisites
+
+**System Requirements:**
+
+- Python 3.10+
+- SQLite 3.35+ with FTS5 support (included in Python 3.8+ standard library)
+- 50MB+ disk space for core library, 500MB+ with `[server]` extras
+
+**Optional for GPU Acceleration:**
+
+- CUDA 11.8+ for NVIDIA GPUs
+- Metal Performance Shaders (MPS) for Apple Silicon
+
+> **Note:** If using custom-compiled SQLite, ensure `-DSQLITE_ENABLE_FTS5` is enabled for full-text search support.
+
+## Installation
+
+```bash
+# Standard installation (includes clustering, encryption)
+pip install simplevecdb
+
+# With LangChain & LlamaIndex integrations
+pip install "simplevecdb[integrations]"
+
+# With local embeddings server (adds 500MB+ models)
+pip install "simplevecdb[server]"
+```
+
+**What's included by default:**
+- Vector search with HNSW indexing
+- Clustering (K-means, MiniBatch K-means, HDBSCAN)
+- Encryption (SQLCipher AES-256)
+- Async support
+
+**Verify Installation:**
+
+```bash
+python -c "import simplevecdb; print(simplevecdb.__version__)"
+```
+
+## Quickstart
+
+SimpleVecDB is just a storage and search layer — it doesn't ship an LLM
+and won't generate embeddings for you. Bring whichever embedding source
+you already use; three common ones below.
+
+### Option 1: OpenAI embeddings
+
+```python
+from simplevecdb import VectorDB
+from openai import OpenAI
+
+client = OpenAI()
+db = VectorDB("notes.db")
+notes = db.collection("personal")
+
+def embed(text: str) -> list[float]:
+    return (
+        client.embeddings
+        .create(model="text-embedding-3-small", input=text)
+        .data[0].embedding
+    )
+
+entries = [
+    ("Cherry MX silent reds bottom out around 45g — quieter than browns", "keyboards"),
+    ("Sourdough hydration sweet spot is ~75% with this flour",            "baking"),
+    ("EXPLAIN ANALYZE showed seq scan; ANALYZE on the table fixed it",    "work"),
+    ("Passport renewal took 3 weeks, not the advertised 6–8",             "admin"),
+]
+
+notes.add_texts(
+    texts=[t for t, _ in entries],
+    embeddings=[embed(t) for t, _ in entries],
+    metadatas=[{"tag": tag} for _, tag in entries],
+)
+
+hits = notes.similarity_search(embed("how loud are silent reds"), k=2)
+for doc, score in hits:
+    print(f"{score:.3f}  {doc.page_content}")
+
+work = notes.similarity_search(
+    embed("query plan slow"),
+    k=5,
+    filter={"tag": "work"},
+)
+```
+
+### Option 2: Fully local (no network, no API key)
+
+```bash
+pip install "simplevecdb[server]"
+```
+
+```python
+from simplevecdb import VectorDB
+from simplevecdb.embeddings.models import embed_texts
+
+db = VectorDB("notes.db")
+notes = db.collection("personal")
+
+texts = [
+    "Cherry MX silent reds bottom out around 45g",
+    "Sourdough hydration sweet spot is ~75% with this flour",
+    "EXPLAIN ANALYZE showed seq scan; ANALYZE on the table fixed it",
+]
+notes.add_texts(texts=texts, embeddings=embed_texts(texts))
+
+vec = notes.similarity_search(embed_texts(["quieter switches"])[0], k=2)
+mixed = notes.hybrid_search("postgres slow query", k=3)
+```
+
+If you'd rather hit an HTTP endpoint than import the embedding models
+directly, the bundled server speaks the same shape as OpenAI's
+embeddings API:
+
+```bash
+simplevecdb-server --port 8000                # default model, auto warm-up
+simplevecdb-server --host 0.0.0.0 --port 9000
+simplevecdb-server --no-warmup                # skip the model preload
+simplevecdb-server --help
+```
+
+Server tuning (model registry, rate limits, API keys, CORS, CUDA) lives
+in the [Setup Guide](ENV_SETUP.md).
+
+### Option 3: LangChain or LlamaIndex
+
+Already using one of the major RAG frameworks? Use SimpleVecDB as the
+vector store:
+
+```bash
+pip install "simplevecdb[integrations]"
+```
+
+```python
+from simplevecdb.integrations.langchain import SimpleVecDBVectorStore
+from langchain_openai import OpenAIEmbeddings
+
+store = SimpleVecDBVectorStore(
+    db_path="notes.db",
+    embedding=OpenAIEmbeddings(model="text-embedding-3-small"),
+)
+
+store.add_texts([
+    "Cherry MX silent reds bottom out around 45g",
+    "EXPLAIN ANALYZE showed seq scan; ANALYZE on the table fixed it",
+])
+store.similarity_search("quieter switches", k=1)
+store.hybrid_search("postgres performance", k=3)
+```
+
+LlamaIndex is the same shape:
+
+```python
+from simplevecdb.integrations.llamaindex import SimpleVecDBLlamaStore
+from llama_index.embeddings.openai import OpenAIEmbedding
+
+store = SimpleVecDBLlamaStore(
+    db_path="notes.db",
+    embedding=OpenAIEmbedding(model="text-embedding-3-small"),
+)
+```
+
+End-to-end notebooks (including a fully local Ollama RAG) live in the
+[examples gallery](https://coderdayton.github.io/SimpleVecDB/examples/).
+
+## Feature Highlights
+
+A few of the things SimpleVecDB does well — see
+[`docs/Features.md`](docs/Features.md) for the comprehensive list.
+
+- **Vector + keyword + hybrid search** — cosine / L2 similarity, BM25
+  via SQLite FTS5, and Reciprocal Rank Fusion in one collection.
+- **Adaptive HNSW** — brute-force for <10k vectors (perfect recall),
+  `usearch` HNSW above that. Override per query with `exact=True/False`.
+- **Quantization** — `FLOAT32`, `FLOAT16`, `INT8`, `BIT` for 1×–32×
+  compression.
+- **Multi-collection + cross-collection search** — isolated namespaces in
+  one database, with merged ranked search across them.
+- **Mongo-style filters** — `$eq $ne $gt $gte $lt $lte $in $nin $exists
+  $between` on metadata, edges, and events.
+- **Memory primitives (v2.6.1)** — pending-vector buffer with atomic
+  flush, weighted directed edges, append-only event feed, TTL with
+  delete/callback sweep, and a threshold-driven rebuild scheduler.
+- **Atomic counters & transactions (v2.6.1)** — `increment_metadata` for
+  JSON deltas in one statement; SAVEPOINT-backed `db.transaction()` /
+  `collection.tx()` rolling all catalog writes back on error.
+- **Async, encryption, clustering, hierarchies** — full async surface
+  (with executor injection), SQLCipher AES-256, K-means / MiniBatch
+  K-means / HDBSCAN, parent/child relationships.
+- **Framework integrations** — drop-in `LangChain` and `LlamaIndex`
+  adapters via the `[integrations]` extra; optional FastAPI embeddings
+  server via `[server]`.
+
+For full method-level coverage, see [the Features doc](docs/Features.md)
+or the [API reference](https://coderdayton.github.io/SimpleVecDB/api/core).
+
+
+## Performance Benchmarks
+
+**10,000 vectors, 384 dimensions, k=10 search** — [Full benchmarks →](https://coderdayton.github.io/SimpleVecDB/benchmarks)
+
+| Quantization | Storage  | Query Time | Compression |
+| :----------- | :------- | :--------- | :---------- |
+| FLOAT32      | 36.0 MB  | 0.20 ms    | 1x          |
+| FLOAT16      | 28.7 MB  | 0.20 ms    | 2x          |
+| INT8         | 25.0 MB  | 0.16 ms    | 4x          |
+| BIT          | 21.8 MB  | 0.08 ms    | 32x         |
+
+**Key highlights:**
+- **3-34x faster** than brute-force for collections >10k vectors
+- **Adaptive search**: perfect recall for small collections, HNSW for large
+- **FLOAT16 recommended**: best balance of speed, memory, and precision
+
+## Documentation
+
+- **[Features](docs/Features.md)** — Comprehensive list of every capability, grouped by area
+- **[Setup Guide](https://coderdayton.github.io/SimpleVecDB/ENV_SETUP)** — Environment variables, server configuration, authentication
+- **[API Reference](https://coderdayton.github.io/SimpleVecDB/api/core)** — Complete class/method documentation with type signatures
+- **[Benchmarks](https://coderdayton.github.io/SimpleVecDB/benchmarks)** — Quantization strategies, batch sizes, hardware optimization
+- **[Integration Examples](https://coderdayton.github.io/SimpleVecDB/examples)** — RAG notebooks, Ollama workflows, production patterns
+- **[Contributing Guide](CONTRIBUTING.md)** — Development setup, testing, PR guidelines
+
+## Troubleshooting
+
+**Import Error: `sqlite3.OperationalError: no such module: fts5`**
+
+```bash
+# Your Python's SQLite was compiled without FTS5
+# Solution: Install Python from python.org (includes FTS5) or compile SQLite with:
+# -DSQLITE_ENABLE_FTS5
+```
+
+**Dimension Mismatch Error**
+
+```python
+# Ensure all vectors in a collection have identical dimensions
+collection = db.collection("docs", dim=384)  # Explicit dimension
+```
+
+**CUDA Not Detected (GPU Available)**
+
+```bash
+# Verify CUDA installation
+python -c "import torch; print(torch.cuda.is_available())"
+
+# Reinstall PyTorch with CUDA support
+pip install torch --index-url https://download.pytorch.org/whl/cu118
+```
+
+**Slow Queries on Large Datasets**
+
+- Enable quantization: `collection = db.collection("docs", quantization=Quantization.INT8)`
+- For >10k vectors, HNSW is automatic; tune with `rebuild_index(connectivity=32)`
+- Use `exact=False` to force HNSW even on smaller collections
+- Use metadata filtering to reduce search space
+
+## Roadmap
+
+What's on the near-term radar:
+
+- [ ] Incremental clustering (online learning)
+- [ ] Cluster visualization exports
+
+For shipped capabilities, see [`docs/Features.md`](docs/Features.md) and the
+release-by-release [Changelog](CHANGELOG.md). Vote on these or propose new
+ideas in [GitHub Discussions](https://github.com/coderdayton/simplevecdb/discussions).
+
+## Contributing
+
+Contributions are welcome — bug fixes, documentation improvements, and new feature proposals alike:
+
+1. Read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup
+2. Check existing [Issues](https://github.com/coderdayton/simplevecdb/issues) and [Discussions](https://github.com/coderdayton/simplevecdb/discussions)
+3. Open a PR with clear description and tests
+
+## Community & Support
+
+**Get Help:**
+
+- [GitHub Discussions](https://github.com/coderdayton/simplevecdb/discussions) — Q&A and feature requests
+- [GitHub Issues](https://github.com/coderdayton/simplevecdb/issues) — Bug reports
+
+**Stay Updated:**
+
+- [GitHub Releases](https://github.com/coderdayton/simplevecdb/releases) — Changelog and updates
+- [Examples Gallery](https://coderdayton.github.io/SimpleVecDB/examples/) — Community-contributed notebooks
+
+## Support the Project
+
+- **[Sponsor on Ko-fi](https://ko-fi.com/xbbvii)** — one-time donations
+- **Star the repository** — helps with visibility
+- **[Report issues](https://github.com/coderdayton/simplevecdb/issues)** — bug reports and feedback
+- **[Contribute](CONTRIBUTING.md)** — development setup and guidelines
+
+## License
+
+[MIT License](LICENSE) — Free for personal and commercial use.