stratadb — Strata for Python

The Python SDK for Strata: an embedded multi-model database for AI agents. SQLite-shaped, not a server — it links the engine in process and opens a file-backed (or in-memory) database directly.

Five primitives — key-value, JSON documents, vectors, an event log, and a graph — share one branch-aware, time-travelling storage substrate. The SDK speaks the exact same command surface, value shapes, and error codes as the strata CLI and MCP server, so learning one channel is learning all of them.

For coding agents — start here

Install with uv add stratadb (or pip install stratadb), then call stratadb.agents_guide() first. It returns the complete offline Python usage guide (every namespace, db.ai, provider keys, branches / time-travel, errors — all runnable Python), so you can learn the whole surface without probing it:

import stratadb
db = stratadb.open(cache=True)      # ephemeral; or open("./app-data") for durable
print(stratadb.agents_guide())      # the entire surface, offline — read this first
  • python -m stratadb.demo — a runnable, zero-setup tour that prints every primitive's real return shape (doubles as a smoke test).
  • stratadb.init("path/to/repo") — scaffold the Strata agent skill and an AGENTS.md stanza into a repo so the next agent starts warm.
  • npx skills add stratalab/strata-agent-skills — install the full Strata skill set (usage, branching, time travel) for Claude Code, Cursor, Codex, and friends. The same repo (strata-agent-skills) carries the one-command workspace setup (CLI + MCP registration + skills); its npm publish is pending, so use the skills command today.

Names & surfaces

Strata appears under a few names; here is what each string is and where it's used:

Surface Value Notes
PyPI package stratadb pip install stratadb
Python import import stratadb the SDK this README documents
CLI strata a separate binary (strata-core); not installed by this wheel
MCP server strata <db> mcp serve snippet via stratadb.mcp_config(path)
Agent skills npx skills add stratalab/strata-agent-skills one-command setup lives in the same repo (npm publish pending)
GitHub repo stratalab/strata-python this SDK
GitHub org stratalab
Website / docs stratadb.org

Install

uv add stratadb        # or: pip install stratadb

No Rust toolchain required — wheels are prebuilt (abi3, one per platform, Python 3.9+).

Quickstart

import stratadb

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

# Key-value — values are str | bytes (reads return bytes; misses return None)
db.kv.put("greeting", "hello")
db.kv.get("greeting")                    # b"hello"

# Structured data belongs in the JSON primitive (or json.dumps it into kv)
db.json.set("user:1", "$", {"name": "Ada", "roles": ["admin"]})
db.json.get("user:1", "$.name")          # "Ada"

# Listing methods return a Page: iterate (auto-paginates) or collect with .all()
db.json.keys(prefix="user:").all()       # ["user:1"]

# 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)
db.events.append("signup", {"user": "ada"})

# Graph
db.graphs.create("social")
db.graphs.add_node("social", "ada")
db.graphs.add_node("social", "grace")
db.graphs.add_edge("social", "ada", "follows", "grace")

db.close()   # or: with stratadb.open("./app-data") as db: ...

stratadb.open() never opens the current directory implicitly: pass a path, set STRATA_DB (stratadb.from_env()), or use cache=True.

Upgrading from pre-V1 (0.x)

V1 namespaced the flat 0.x methods. If an example uses Strata.open or db.kv_put, it predates V1 — the current equivalents:

pre-V1 (0.x) V1 (this SDK)
Strata.open("/path") stratadb.open("/path")
db.kv_put / kv_get / kv_delete / kv_list db.kv.put / .get / .delete / .keys()
db.json_set / json_get / json_delete db.json.set / .get / .delete
db.event_append / event_get / event_list db.events.append / .get / .list
db.vector_create_collection / vector_upsert / vector_search db.vectors.create_collection / .upsert / .query
db.state_set / state_get / state_cas removed — use db.kv or db.json (raises unsupported.sdk.state_removed)
db.transaction() / begin() / commit() removed — writes commit individually; use *_many batches for multi-write commits

Inference — db.ai

Chat, embeddings, and reranking over cloud providers (OpenAI, Anthropic, Google) or local GGUF models — an OpenAI-shaped surface. Strata is embedded and ships no keys: set OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_API_KEY, or strata config set openai.api_key sk-....

r = db.ai.chat("Explain embeddings in one sentence.",
               model="openai:gpt-4o-mini", max_tokens=60)
print(r.content)

# Structured output (JSON Schema)
r = db.ai.chat("Capital of France and its population?",
               model="anthropic:claude-haiku-4-5-20251001",
               json_schema={"type": "object",
                            "properties": {"capital": {"type": "string"},
                                           "population": {"type": "integer"}},
                            "required": ["capital", "population"]})

# Tool / function calling
r = db.ai.chat("What's the weather in Paris?", model="google:gemini-2.5-flash",
               tools=[{"type": "function",
                       "function": {"name": "get_weather",
                                    "parameters": {"type": "object",
                                                   "properties": {"city": {"type": "string"}},
                                                   "required": ["city"]}}}],
               tool_choice="required")
r.tool_calls          # [{'id': ..., 'function': {'name': 'get_weather', 'arguments': '{"city":"Paris"}'}}]

# Embeddings
e = db.ai.embed(["hello", "world"], model="openai:text-embedding-3-small")
e.vectors             # [[...], [...]]

# A model handle sets load params once
qwen = db.ai.model("local:qwen3", n_ctx=8192)
qwen.chat("Summarize: ...")

db.ai.capability("openai:gpt-4o-mini")   # supported features; no network call

Branches, spaces, and time travel

db.branches.fork("default", "experiment")   # copy-on-write branch
exp = db.at(branch="experiment")          # a scoped view over the same handle
exp.kv.put("k", "only-on-experiment")

receipt = db.kv.put("k", "v1")
db.kv.put("k", "v2")
db.kv.get("k", as_of=receipt.commit.timestamp)   # b"v1" — every read takes as_of

Errors

Every failure raises a typed stratadb.errors.StrataError subclass carrying a stable code, message, hint, and ref. Match on code, never on message:

from stratadb import errors

try:
    db.at(branch="ghost").kv.get("k")
except errors.NotFoundError as e:
    assert e.code == "not_found.engine.branch"
    print(e.ref)   # https://stratadb.org/e/not_found.engine.branch

Misses are not errors — reads return None.

For AI agents

  • stratadb.agents_guide() — the complete offline Python usage guide bundled in the wheel (the SDK-native counterpart to strata agents guide).
  • python -m stratadb.demo / stratadb.demo() — a runnable, zero-setup tour of every primitive with real printed output.
  • stratadb.init(repo_path=".") — scaffold .claude/skills/strata/SKILL.md and an AGENTS.md stanza into a repo (idempotent).
  • stratadb.agents_skill() — the Claude Code skill markdown (version-stamped).
  • stratadb.command_index() — the full command catalog bundled in the wheel.
  • stratadb.mcp_config(path) — the MCP client-config snippet (strata <path> mcp serve; needs the strata binary, a separate strata-core install).
  • db.execute(command: dict) -> dict — the raw command escape hatch (the same wire the CLI and MCP speak); the typed namespaces build on it.

Architecture

Three layers: handwritten ergonomic namespaces over a generated core (one typed method + model per command, generated from the engine's IDL) over a tiny PyO3 binding that links the engine in process. Data-plane only — generated fresh from the IDL, drift-guarded in CI.

Development

python -m venv .venv && source .venv/bin/activate
pip install maturin pytest
maturin develop            # builds the native binding into the venv
python tools/generate.py   # regenerates the typed core from idl/v1/
pytest

Local builds use a path dependency to a sibling ../strata-core checkout; releases pin the git rev in idl/v1/STRATA_CORE_REV (tools/release_prep.py).

License

MIT

Project links

Data verified by PyPI on Aug 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for anibjoshi from gravatar.com anibjoshi

Credits

Author: Strata Lab

GitHub Statistics

Data verified by PyPI on Aug 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.9

Provides Extra

dev

Tags

database embedded ai agents vector kv graph json

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

stratadb-1.0.3.tar.gz (308.9 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

stratadb-1.0.3-cp39-abi3-win_amd64.whl (9.5 MB view details)

Uploaded CPython 3.9+Windows x86-64

stratadb-1.0.3-cp39-abi3-musllinux_1_2_x86_64.whl (13.2 MB view details)

Uploaded CPython 3.9+musllinux: musl 1.2+ x86-64

stratadb-1.0.3-cp39-abi3-musllinux_1_2_aarch64.whl (12.7 MB view details)

Uploaded CPython 3.9+musllinux: musl 1.2+ ARM64

stratadb-1.0.3-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (12.2 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

stratadb-1.0.3-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (12.5 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

stratadb-1.0.3-cp39-abi3-macosx_11_0_arm64.whl (11.4 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

stratadb-1.0.3-cp39-abi3-macosx_10_12_x86_64.whl (12.0 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file stratadb-1.0.3.tar.gz.

File metadata

  • Download URL: stratadb-1.0.3.tar.gz
  • Upload date:
  • Size: 308.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for stratadb-1.0.3.tar.gz
Algorithm Hash digest
SHA256 071ce117be0fccdaed748a2731da3d57070266a274fcab38f8dd8a2e114f1446
MD5 c55955368a5a7114d6001dec7f0770ec
BLAKE2b-256 1cdb43cfc13c0dcf7d55c065c1cbb72c4a03b81277f5a9d660b7bbc188fe9752

See more details on using hashes here.

Provenance

The following attestation bundles were made for stratadb-1.0.3.tar.gz:

Publisher: release.yml on stratalab/strata-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stratadb-1.0.3-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: stratadb-1.0.3-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 9.5 MB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for stratadb-1.0.3-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 d75d167facc30166f798eeb53166e3cd009a7961658d19986f29d7fbb8bbb6c6
MD5 16762196ec4867101c0e5279b1d5d020
BLAKE2b-256 ddf2f5a07f2944055ad3aa68c2d9fbdac5d434da630656d92341f48dc9c6fe71

See more details on using hashes here.

Provenance

The following attestation bundles were made for stratadb-1.0.3-cp39-abi3-win_amd64.whl:

Publisher: release.yml on stratalab/strata-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stratadb-1.0.3-cp39-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for stratadb-1.0.3-cp39-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 5a597069cd719f1c4e165a4f2143a2a27d51f16283a45637923bd699e2f82afe
MD5 59dc830a3f42c4ec544c16bd8c7f87c1
BLAKE2b-256 2b7b7b968d685ab08791562067bbd0c42d29e40edac781616740685ba6731185

See more details on using hashes here.

Provenance

The following attestation bundles were made for stratadb-1.0.3-cp39-abi3-musllinux_1_2_x86_64.whl:

Publisher: release.yml on stratalab/strata-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stratadb-1.0.3-cp39-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for stratadb-1.0.3-cp39-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 6aa4d6515e532d565d69d242d3a89be2ba8a8efcadca87c9ad5baca2954d7fe2
MD5 909b9b9873216a42244e83b175a1f4cf
BLAKE2b-256 4b1da92b412890564f7b84e85bc159f0c640facc6e208fa325ff2271f940df09

See more details on using hashes here.

Provenance

The following attestation bundles were made for stratadb-1.0.3-cp39-abi3-musllinux_1_2_aarch64.whl:

Publisher: release.yml on stratalab/strata-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stratadb-1.0.3-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for stratadb-1.0.3-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 5fdaf1a788806c7ae1db579cf7eec2e1bd94eab316960faa480a2cacbb4db291
MD5 138beaa076cd343ed58b360699c8ba30
BLAKE2b-256 4983197df3a81e07b493e0aa3ec410daca38cc8cc6bb7587058e72e7dc619470

See more details on using hashes here.

Provenance

The following attestation bundles were made for stratadb-1.0.3-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on stratalab/strata-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stratadb-1.0.3-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for stratadb-1.0.3-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 32bd187c24147fc99842b8a586209582df2b91aa1b19f2f62d49af09a8b23fa8
MD5 64924188a1cc5903598c26f85f3efc09
BLAKE2b-256 cc3b556a681bf83c6602badca5518f39510478f4e89a4ecffd791b54b1d95efb

See more details on using hashes here.

Provenance

The following attestation bundles were made for stratadb-1.0.3-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on stratalab/strata-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stratadb-1.0.3-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for stratadb-1.0.3-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9fcadc4af5a867dabc0d6647b21ded04a726b4ec453565ea7a447ca8cebe2f8b
MD5 0e60ed2f6c5248be6ab51281e1286134
BLAKE2b-256 6463306b07438a22b2c1ad037aa406b2dd957d7785211bc901193388b71c34d3

See more details on using hashes here.

Provenance

The following attestation bundles were made for stratadb-1.0.3-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on stratalab/strata-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stratadb-1.0.3-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for stratadb-1.0.3-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 7de53462e5ce4715915bcc08fc763b1bb9b2963c5ddf67d6fda44540ba6329ba
MD5 768c8886ffef3fdad9670096f269fc92
BLAKE2b-256 1209a4d8a07415c09e073767149ba714f9b5ace452cc6819dd3b2930554c28d6

See more details on using hashes here.

Provenance

The following attestation bundles were made for stratadb-1.0.3-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on stratalab/strata-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.0.3 This release

8 files

1.0.2

8 files

1.0.1

8 files

1.0.0

8 files

0.14.5

21 files

0.14.4

21 files

0.14.3

21 files

0.14.2

21 files

0.14.1

21 files

0.14.0

21 files

0.13.2

21 files

0.13.1

21 files

0.13.0

21 files

0.12.11

21 files

0.12.10

21 files

0.12.9

21 files

0.12.8

21 files

0.12.7

21 files

0.12.6

21 files

0.12.5

21 files

0.6.0

21 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page