stratadb is the Python SDK for Strata: it links the engine in your process and opens a file-backed (or in-memory) database directly — SQLite-shaped, not a server. It speaks the exact same command surface, value shapes, and error codes as the strata CLI and the MCP server, so learning one channel is learning all of them.

Availability: stratadb 1.0.0 is the V1 line, and its version tracks the engine (stratadb.__version__ equals the engine version). The V1 wheels are rolling out to PyPI.

Install

pip install stratadb

No Rust toolchain required — wheels are prebuilt (abi3, one per platform, Python 3.9+). The base wheel runs cloud inference on CPU; GPU-accelerated local models come from a companion wheel (stratadb[cuda]). See installation for the extras and platform matrix.

Quickstart

import stratadb

db = stratadb.open("./app-data")      # durable (creates if absent)
# db = stratadb.open(cache=True)      # ephemeral, in-memory

# Key-value — values are bytes; str is encoded as UTF-8
db.kv.put("greeting", "hello")
db.kv.get("greeting")                    # b"hello"

# JSON documents, addressed by path
db.json.set("user:1", "$", {"name": "Ada", "roles": ["admin"]})
db.json.get("user:1", "$.name")          # "Ada"

# Vectors — similarity search with metadata filters
from stratadb import filters
db.vectors.create_collection("notes", dimension=3)
db.vectors.upsert("notes", "n1", [0.1, 0.2, 0.3], metadata={"kind": "note"})
hits = db.vectors.query("notes", [0.1, 0.2, 0.3], k=5,
                        filter=filters.eq("kind", "note"))

# Events (append-only, hash-chained) and graph
db.events.append("signup", {"user": "ada"})
db.graphs.create("social")
db.graphs.add_node("social", "ada")
db.graphs.add_node("social", "grace")   # both endpoints must exist first
db.graphs.add_edge("social", "ada", "follows", "grace")

db.close()   # or use it as a context manager (below)

stratadb.open() never opens the current directory implicitly — pass a path, set STRATA_DB (stratadb.from_env()), or use cache=True, or it raises InvalidArgumentError. It is also a context manager:

with stratadb.open("./app-data") as db:
    db.kv.put("k", "v")

How it is built

Three layers, so the ergonomics are handwritten but the surface can’t drift from the engine:

1. Namespaces — the handwritten, ergonomic API (db.kv, db.json, db.ai, …).
2. Generated core — one typed method and model per command, generated from the engine’s IDL and drift-guarded in CI.
3. PyO3 binding — a thin native layer that links the engine in process.

Because the middle layer is generated from the same IDL that produces the command reference, the SDK and the docs describe one surface.

In this section

• Installation — wheels, the [cuda]/[gpu] extras, and py.typed type checking.
• Namespaces — the data-plane API: the ten namespaces, db.at() scoping, as_of, and filters.
• Inference (db.ai) — chat, embeddings, reranking, structured outputs, and tools.
• Errors — the typed exception hierarchy; recover by code.
• Agent integration — agents_guide(), mcp_config(), and the raw command escape hatch.