🐍 VantaDB Python SDK

Official Python bindings for VantaDB, an embedded, native-Rust database engine designed for persistent memory, hybrid retrieval and graph queries in local-first AI applications.

Why VantaDB instead of a plain vector store?

Most embedded vector databases (e.g. ChromaDB) index vectors and stop there. VantaDB ships the missing pieces agents actually need:

• Hybrid search with RRF fusion — dense vector ANN (HNSW) and lexical BM25 run together and fuse via Reciprocal Rank Fusion, so semantic misses get caught by keyword matches (and vice versa). One call (search), one ranked result set.
• Graph and memory in one engine — namespace-scoped memory records live next to a property graph with typed edges: BFS/DFS traversals, PageRank, cycle detection and topological sort, all queryable through IQL (query / query_structured).
• Explicit memory lifecycle — per-record TTL expiry (purge_expired) and atomic fact replacement (supersede) without delete/reinsert races.
• Built-in migration paths — bulk_import / bulk_import_bytes for fast ingestion, export_namespace / export_all for backup, and reindex_hnsw_from_text to rebuild indexes from stored payloads after schema or index changes.

📦 Installation

From PyPI (Recommended)

pip install vantadb-py

Note: The distribution name is vantadb-py and the canonical import is import vantadb (same as the Rust crate and the npm package). import vantadb_py remains available and is not broken.

Naming (ADR-041 anti-stutter): the canonical client name is Client (VantaDB was removed — use Client); canonical type names are Record, SearchHit/Hit, ListResult, Vector. Memory methods live under db.memory (get / list / search / delete); the flat Client keeps shared names (put / search / count / ...) that delegate to the same operations — db.search(...) ≡ db.memory.search(...).

From TestPyPI (Pre-release testing)

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ vantadb-py

From Source (Development)

Requires Rust and Maturin.

# Clone the repository
git clone https://github.com/ness-e/Vantadb.git
cd Vantadb/vantadb-python

# Compile and install into the active virtual environment
pip install maturin
maturin develop --release

🚀 Quickstart

import vantadb

# 1. Open or create an embedded database
db = vantadb.Client("./my_agent_memory", memory_limit_bytes=128 * 1024 * 1024)

# 2. Store persistent memory (payload + vector + metadata)
db.put(
    namespace="agent/session_1",
    key="fact_001",
    payload="The user prefers direct, technical answers.",
    metadata={"source": "chat", "priority": "high"},
    vector=[0.1, 0.2, 0.3, 0.4]  # Dense vector (e.g. embedding from a local model)
)

# 3. Retrieve the exact record
record = db.memory.get("agent/session_1", "fact_001")
print(record["payload"])

# 4. Hybrid search (vector + lexical)
# Note: The query vector must match the dimensionality of the stored vectors
query_vector = [0.15, 0.25, 0.35, 0.45]
results = db.search(
    namespace="agent/session_1",
    query_vector=query_vector,
    text_query="user preferences",
    top_k=5
)

for hit in results:
    print(f"Key: {hit.key}, Score: {hit.score:.4f}")

# 5. Resource monitoring (critical for local agents)
stats = db.operational_metrics()
print(f"Logical usage: {stats['hnsw_logical_bytes'] / 1024:.2f} KB")
print(f"Physical RSS: {stats['process_rss_bytes'] / 1024:.2f} KB")

# 6. Clean shutdown
db.close()

🔢 Real Embeddings

The vectors above are toy examples. VantaDB stores and searches any dense vector but does not generate embeddings — bring your own client (local Ollama or the OpenAI API):

import json, urllib.request

def embed(text: str) -> list[float]:
    req = urllib.request.Request(
        "http://localhost:11434/api/embed",
        data=json.dumps({"model": "nomic-embed-text", "input": text}).encode(),
        headers={"Content-Type": "application/json"},
    )
    return json.load(urllib.request.urlopen(req))["embeddings"][0]

db.put(
    namespace="agent/session_1",
    key="fact_002",
    payload="The user prefers direct, technical answers.",
    metadata={"source": "chat"},
    vector=embed("user tone preferences"),
)

Use one embedding model per namespace — stored and query vectors must share the same dimensionality. Full walkthrough: QUICKSTART → Real Embeddings.

Cross-SDK Search Parity

VantaDB exposes the same search capabilities across bindings, but the search() name carries different semantics per SDK. Read this before porting code between Python and TypeScript. The canonical method→domain map lives in docs/api/BINDINGS_NAMESPACES.md.

Porting hazard: search() in Python is namespace-scoped hybrid memory search, while search() in TypeScript takes an options object — read the table rows before porting. To get hybrid search in Python use search() / memory.search(); to get pure vector ANN in Python use search_vector() (in TypeScript use searchVector()).

🤖 Use Case: Memory for AI Agents

VantaDB is optimized to act as long-term memory for local autonomous agents (Claude, Gemini, LLaMA, etc.):

• Zero-Copy Persistence: Data survives agent restarts with no serialization overhead.
• Hybrid RRF search: Combines semantic similarity (vectors) with lexical matching (BM25) for precise context retrieval.
• Explicit Memory Control: memory_limit_bytes prevents the agent from collapsing the host device's RAM.
• Embedded: No external servers, no Docker, no network latency. Ideal for edge and offline devices.

🛠️ Development and Testing

# Run the SDK test suite
pytest tests/test_sdk.py -v

# Format Python code
black tests/ vantadb_python/

📜 License

Distributed under the VantaDB main project license. See the LICENSE at the repository root.