CoderDayton · CoderDayton · Mar 8, 2026 · Mar 8, 2026 · Mar 8, 2026 · Mar 8, 2026
diff --git a/.bandit b/.bandit
diff --git a/.env.example b/.env.example
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
diff --git a/.github/workflows/update-sponsors.yml b/.github/workflows/update-sponsors.yml
diff --git a/.gitignore b/.gitignore
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,6 +1,13 @@
 repos:
   - repo: local
     hooks:
+      - id: version-sync
+        name: version sync check
+        entry: python3 scripts/check_version_sync.py
+        language: system
+        files: ^(pyproject\.toml|src/simplevecdb/__init__\.py)$
+        pass_filenames: false
+
       - id: ruff
         name: ruff
         entry: uv run ruff check . --fix

diff --git a/.python-version b/.python-version
@@ -1 +1 @@
-3.10
+3.12
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,62 @@ 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.3.0] - 2026-03-08
+
+### Breaking Changes
+
+- **Integration dependencies are now optional.** LangChain and LlamaIndex packages are no longer installed by default. Install with `pip install simplevecdb[integrations]` to use them. Existing users upgrading from v2.2.x will see a clear ImportError with migration instructions.
+
+### Added
+
+- **`[integrations]` optional extra** — Install LangChain and LlamaIndex dependencies only when needed, reducing default install footprint
+- **Runtime import guards** in integration modules with v2.3.0 migration messaging
+- **Lazy `__getattr__` loading** in `integrations/__init__.py` — integration classes are only imported when accessed
+- **Input validation guards** on search methods:
+  - `similarity_search`, `similarity_search_batch`, `keyword_search`, `hybrid_search` now reject `k <= 0`
+  - `add_texts` validates length consistency of `metadatas`, `embeddings`, `ids`, and `parent_ids` against `texts`
+- **NaN/Inf validation** for float values in metadata filters (`utils.validate_filter`)
+- **Empty list rejection** for list filter values
+- **Double-close protection** on `VectorDB` with `_closed` flag
+- **Context manager protocol** (`__enter__`/`__exit__`) on `VectorDB`
+- **Table name validation** in `check_migration` (defense-in-depth against SQL injection)
+- **Graceful per-future error handling** in `search_collections`
+- **Adaptive batch search threshold** — queries below `USEARCH_BATCH_THRESHOLD` (10) use sequential search to avoid batch overhead
+
+### Changed
+
+- **Python dev target changed to 3.12** (`.python-version`), `requires-python` remains `>= "3.10"`
+- **Version bumped to 2.3.0**
+- **Performance: MMR search vectorized** — pre-normalize embeddings once, use `sel_matrix @ emb` matrix-vector multiply instead of Python inner loop, O(1) `list.pop` replaces O(n) `list.remove`, hoist `1 - lambda_mult` loop invariant
+- **Performance: merged SQL round-trips in MMR** — new `get_documents_and_embeddings_by_ids` fetches text, metadata, and embeddings in a single query (previously two separate SELECTs)
+- **Performance: `get_parent` collapsed** from 2 sequential SELECTs to 1 self-JOIN
+- **Performance: `add_documents` ID recovery** — skip redundant `SELECT ORDER BY DESC` when explicit IDs are provided; removed unnecessary `list(texts)` copy
+- **Performance: FLOAT serialization** — `np.asarray().tobytes()` replaces `struct.pack` with per-element Python loop (single C memcpy)
+- **Performance: `np.array` → `np.asarray`** on every search and insert path to avoid unnecessary copies
+- **Performance: SQL placeholder strings** — `",".join(["?"] * len(ids))` replaces generator expression across all 9 call sites
+- **Performance: batched numpy conversion** in `add_texts` — single `np.asarray` call instead of per-item conversion
+- **Performance: compact JSON separators** in catalog serialization
+- **Performance: deduplicated `.tolist()` calls** in search engine
+- **Performance: `np.unique(ravel())`** for batch key collection in `similarity_search_batch`
+- **Performance: usearch upsert** — skip contains-check loop on empty index, cache `int(key)` once per iteration
+- **Performance: cluster table DDL** — `_cluster_table_ready` flag skips `CREATE TABLE IF NOT EXISTS` on repeated calls; cached `_cluster_table_name`
+- **`_normalize_key`** now delegates to `_derive_key` instead of duplicating PBKDF2 logic
+- **HNSW defaults** in `usearch_index.py` now sourced from `constants.py` (removed local duplicates)
+- **Collection name regex** uses `constants.COLLECTION_NAME_PATTERN` instead of hardcoded pattern
+- **`VectorDB` defaults** for `distance_strategy` and `quantization` sourced from `constants.DEFAULT_DISTANCE_STRATEGY` / `constants.DEFAULT_QUANTIZATION`
+- **`_batched` utility** moved from `core.py` to `utils.py` for reuse; now used in `catalog.py` batch updates
+- **`auto_tag`** uses `defaultdict(list)` instead of manual if-not-in pattern
+- **`import random`** hoisted to module level in `utils.py` (was inside retry loop)
+- **Streaming placeholder bug fixed** — `_process_streaming_batch` now correctly detects `None` placeholders (previously used empty list `[]`, preventing auto-embedding replacement)
+- **README updated** to document `pip install simplevecdb[integrations]` installation
+
+### Removed
+
+- LangChain and LlamaIndex packages from core `[project.dependencies]` (moved to `[project.optional-dependencies] integrations`)
+- Duplicated HNSW default constants from `usearch_index.py` (now single source in `constants.py`)
+- Unused `struct` import from `quantization.py`
+- Unused `itertools` import from `core.py`
+
 ## [2.2.1] - 2026-01-27
 
 ### Changed
@@ -429,6 +485,7 @@ Benchmarks on i9-13900K & RTX 4090 with 10k vectors (384-dim):
 - **Documentation**: https://coderdayton.github.io/simplevecdb/
 - **License**: MIT
 
+[2.3.0]: https://github.com/coderdayton/simplevecdb/releases/tag/v2.3.0
 [2.2.1]: https://github.com/coderdayton/simplevecdb/releases/tag/v2.2.1
 [2.2.0]: https://github.com/coderdayton/simplevecdb/releases/tag/v2.2.0
 [2.1.0]: https://github.com/coderdayton/simplevecdb/releases/tag/v2.1.0

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/LICENSE b/LICENSE
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@ SimpleVecDB brings **Chroma-like simplicity** to a single **SQLite file**. Built
 - **Blazing Fast** — 10-100x faster search via usearch HNSW. Adaptive: brute-force for <10k vectors (perfect recall), HNSW for larger collections.
 - **Truly Portable** — Runs anywhere SQLite runs: Linux, macOS, Windows, even WASM.
 - **Async Ready** — Full async/await support for web servers and concurrent workloads.
-- **Batteries Included** — Optional FastAPI embeddings server + LangChain/LlamaIndex integrations.
+- **Batteries Included** — Optional FastAPI embeddings server + LangChain/LlamaIndex integrations via `[integrations]` extra.
 - **Production Ready** — Hybrid search (BM25 + vector), metadata filtering, multi-collection support, and automatic hardware acceleration.
 
 ### When to Choose SimpleVecDB
@@ -49,6 +49,9 @@ SimpleVecDB brings **Chroma-like simplicity** to a single **SQLite file**. Built
 # 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]"
 ```
@@ -58,7 +61,6 @@ pip install "simplevecdb[server]"
 - Clustering (K-means, MiniBatch K-means, HDBSCAN)
 - Encryption (SQLCipher AES-256)
 - Async support
-- LangChain & LlamaIndex integrations
 
 **Verify Installation:**
 
@@ -147,6 +149,10 @@ See [Setup Guide](ENV_SETUP.md) for configuration: model registry, rate limits,
 
 Best for: Existing RAG pipelines, framework-based workflows.
 
+```bash
+pip install "simplevecdb[integrations]"
+```
+
 ```python
 from simplevecdb.integrations.langchain import SimpleVecDBVectorStore
 from langchain_openai import OpenAIEmbeddings
@@ -316,7 +322,7 @@ Supports K-means, MiniBatch K-means, and HDBSCAN. See [Clustering Guide](https:/
 | **Quantization**          | ✅     | FLOAT32, FLOAT16, INT8, BIT for 2-32x compression            |
 | **Parallel Operations**   | ✅     | `threads` parameter for add/search                           |
 | **Metadata Filtering**    | ✅     | SQL `WHERE` clause support                                   |
-| **Framework Integration** | ✅     | LangChain \& LlamaIndex adapters                             |
+| **Framework Integration** | ✅     | LangChain \& LlamaIndex adapters via `[integrations]` extra  |
 | **Hardware Acceleration** | ✅     | Auto-detects CUDA/MPS/CPU + SIMD via usearch                 |
 | **Local Embeddings**      | ✅     | HuggingFace models via `[server]` extras                     |
 | **Built-in Encryption**   | ✅     | SQLCipher AES-256 at-rest encryption via `[encryption]` extras |

diff --git a/SECURITY.md b/SECURITY.md
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
diff --git a/docs/ENV_SETUP.md b/docs/ENV_SETUP.md
diff --git a/docs/LICENSE b/docs/LICENSE
diff --git a/docs/LICENSE b/docs/LICENSE
diff --git a/docs/api/async.md b/docs/api/async.md
diff --git a/docs/api/config.md b/docs/api/config.md
diff --git a/docs/api/core.md b/docs/api/core.md
diff --git a/docs/api/embeddings.md b/docs/api/embeddings.md
diff --git a/docs/api/encryption.md b/docs/api/encryption.md
diff --git a/docs/api/engine/catalog.md b/docs/api/engine/catalog.md
diff --git a/docs/api/engine/quantization.md b/docs/api/engine/quantization.md
diff --git a/docs/api/engine/search.md b/docs/api/engine/search.md
diff --git a/docs/api/integrations.md b/docs/api/integrations.md
diff --git a/docs/api/types.md b/docs/api/types.md
diff --git a/docs/benchmarks.md b/docs/benchmarks.md
diff --git a/docs/examples.md b/docs/examples.md
diff --git a/docs/guides/clustering.md b/docs/guides/clustering.md
diff --git a/docs/index.md b/docs/index.md
diff --git a/examples/auto_embed.py b/examples/auto_embed.py
diff --git a/examples/backend_benchmark.py b/examples/backend_benchmark.py
diff --git a/examples/embeddings/perf_benchmark.py b/examples/embeddings/perf_benchmark.py
diff --git a/examples/quant_benchmark.py b/examples/quant_benchmark.py
diff --git a/examples/rag/langchain_rag.ipynb b/examples/rag/langchain_rag.ipynb
diff --git a/examples/rag/llama_rag.ipynb b/examples/rag/llama_rag.ipynb
diff --git a/examples/rag/ollama_rag.ipynb b/examples/rag/ollama_rag.ipynb
diff --git a/examples/smoke_test.py b/examples/smoke_test.py
diff --git a/mkdocs.yml b/mkdocs.yml
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "simplevecdb"
-version = "2.2.1"
+version = "2.3.0"
 description = "Dead-simple local vector database powered by usearch HNSW."
 authors = [{ name = "Dayton Dunbar", email = "coderdayton14@gmail.com" }]
 license = { text = "MIT" }
@@ -15,14 +15,16 @@ dependencies = [
     "hdbscan>=0.8.33",          # Density-based clustering
     "sqlcipher3-binary>=0.5.0", # Encryption support
     "cryptography>=41.0",       # Encryption utilities
-    "langchain-core>=1.0.7",    # LangChain integration
-    "langchain-openai>=1.0.3",  # LangChain OpenAI support
-    "llama-index>=0.14.8",      # LlamaIndex integration
-    "llama-index-llms-ollama>=0.9.0",      # LlamaIndex Ollama support
-    "llama-index-llms-openai-like>=0.5.3", # LlamaIndex OpenAI-like support
 ]
 
 [project.optional-dependencies]
+integrations = [
+    "langchain-core>=1.0.7",
+    "langchain-openai>=1.0.3",
+    "llama-index>=0.14.8",
+    "llama-index-llms-ollama>=0.9.0",
+    "llama-index-llms-openai-like>=0.5.3",
+]
 server = [
     "fastapi>=0.115",
     "uvicorn[standard]>=0.30",
@@ -66,9 +68,9 @@ markers = [
 ]
 
 [tool.ruff]
-target-version = "py310"
+target-version = "py312"
 exclude = ["exploration", "docs", "htmlcov", "site"]
 
 [tool.mypy]
-python_version = "3.10"
+python_version = "3.12"
 exclude = ["exploration", "docs", "htmlcov", "site"]
diff --git a/src/simplevecdb/__init__.py b/src/simplevecdb/__init__.py
@@ -11,13 +11,15 @@
 from .core import VectorDB, VectorCollection, get_optimal_batch_size
 from .async_core import AsyncVectorDB, AsyncVectorCollection
 from .config import config
-from .integrations.langchain import SimpleVecDBVectorStore
-from .integrations.llamaindex import SimpleVecDBLlamaStore
+try:
+    from .integrations import SimpleVecDBVectorStore, SimpleVecDBLlamaStore
+except ImportError:
+    pass
 from .logging import get_logger, configure_logging, log_operation
 from .utils import DatabaseLockedError, retry_on_lock, validate_filter
 from .encryption import EncryptionError, EncryptionUnavailableError
 
-__version__ = "2.2.1"
+__version__ = "2.3.0"
 __all__ = [
     # Core classes
     "VectorDB",

diff --git a/src/simplevecdb/async_core.py b/src/simplevecdb/async_core.py
diff --git a/src/simplevecdb/config.py b/src/simplevecdb/config.py
diff --git a/src/simplevecdb/constants.py b/src/simplevecdb/constants.py