corvid-python

Python binding for corvid — an embedded database with typed values, vector/text/hybrid search, graph edges, geo, TTL, and schemas. The engine is compiled in (a Rust pyo3 crate pinned to an exact corvid release tag) and exposed as idiomatic synchronous OOP: Db, Collection, a fluent Query builder, and field() predicates. No SQL, no JSON, no serialization on the data path — values map natively (see the value mapping below).

Its correctness story is the engine's golden suite: the same 267-line fixture files the C ABI smoke harness runs are replayed against this binding's public API on every CI run (tests/test_golden.py).

Install

pip install corvid-python

Published to PyPI by the release workflow (maturin-built abi3 wheels, one cp311 wheel per platform covering every Python ≥ 3.11; the matrix ships linux-x64 / linux-arm64 / macos-arm64 / windows-x64). To build from source instead — Python 3.11–3.14 (CI exercises 3.14/3.13/3.12/3.11), Rust ≥ 1.88, and a C toolchain:

pip install maturin
maturin develop --release    # into the active venv

Usage

from array import array

from corvid import Db, field

db = Db.open("app.redb")               # or Db.open_memory()
docs = db.collection("docs")

docs.insert("p1", {
    "title": "rust embedded database",
    "kind": "doc",
    "v": array("f", [1.0, 0.0]),
})

# hybrid retrieval: filter + vector + BM25, fused (RRF) + reranked (MMR)
rows = (
    docs.query()
    .filter(field("kind").eq("doc"))
    .vector("v", array("f", [1.0, 0.0]), 10, "cosine")
    .text("title", "rust database", 10)
    .fuse_rrf(60)
    .rerank_mmr(1.0)
    .limit(5)
    .run()
)                                      # [Row(key, score, document), ...]

for row in rows:
    print(row.key, row.score, row.document["title"])

# predicates everywhere (queries and deletes)
docs.delete_where(field("kind").eq("draft"))

# scalar/compound/text/geo/vector indexes (incl. quantized + PQ + on-disk)
docs.create_vector_index("v", "cosine")

# TTL, graph, geo, schema, CAS, bulk writes, dump/backup/compact …
docs.close()
db.close()

Every failure raises a native CorvidError with the engine error code (the C ABI's frozen 1–19 table, exported as ErrorCode) and the engine message. Type stubs ship in-package (py.typed) — the public API is fully typed.

Examples

Six runnable programs in examples/ — one per concept, with deterministic output, executed on every CI leg: the quickstart (open, insert, kNN), hybrid (filter + vector + BM25, RRF fusion, MMR rerank), vector-index (in-memory / on-disk / binary-quantized HNSW vs exact, across a reopen), text-search (BM25, English + CJK bigram segmentation), graph (link/neighbors/traverse + the delete cascade), and geo (radius / bbox / nearest-k over real coordinates).

maturin develop && python examples/hybrid.py

Value mapping

Python engine
None, bool, str Null / Bool / Text
int Int (full i64 — out-of-range ints raise code 12)
float Float
bytes / bytearray Bytes
array('f') Vector (other typecodes are rejected)
list / tuple Array
dict (str keys) Map

Reading back: Int → int (arbitrary precision — no ±2^53 boundary, unlike the JS binding's number/BigInt split), Float → float with f64 bits preserved exactly — NaN payloads, -0.0, and ±inf all round-trip bit-exactly (CPython floats are unboxed C doubles; pyo3 copies them by value — the fidelity corner where V8 canonicalizes NaN payloads at the N-API boundary; Python has no such caveat). Vector → array('f') (f32-exact both directions), Map → dict in the engine's key order. Keys are str (UTF-8) or bytes (non-UTF-8 keys come back as bytes).

Python marks the Int/Float distinction natively (2 is an int, 2.0 a float), so the mapping is a clean bijection — there is no Int/Float collapse and no typed-float escape hatch (the JS binding needs CorvidFloat for CAS/unique/group-key corners).

Surface manifest (docs/SURFACE.tsv)

Every construct of the engine's public surface (the radar-enforced list the engine publishes as scripts/bindings/surface.tsv at each release tag) is resolved in docs/SURFACE.tsv: the Python API exposing it plus the test that proves it (golden fixture line references), or N/A + reason where the v1 binding deliberately does not expose it. scripts/surface-gate.sh fails CI when a line is unresolved, a cell is empty, or the N/A count drifts from the committed baseline — so an engine pin bump that changes the surface lands in this gate, not in a user's bug report.

Development

python -m venv .venv && source .venv/bin/activate
pip install maturin pytest
maturin develop               # build the native extension
pytest tests                  # the golden suite (267 fixture lines)
cargo fmt --check             # + cargo clippy --all-targets -- -D warnings

The plan — architecture ruling (engine compiled in via pyo3 vs Python-side ctypes/cffi FFI), the full OOP surface, the value contract, and follow-up tasks — is docs/PLAN.md.

License

MIT.

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 smrocky from gravatar.com smrocky

Credits

Author: corvid-db

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Tags

database embedded vector search ai

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

corvid_python-0.4.1.tar.gz (74.8 kB view details)

Uploaded Source

Built Distributions

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

corvid_python-0.4.1-cp311-abi3-win_amd64.whl (1.2 MB view details)

Uploaded CPython 3.11+Windows x86-64

corvid_python-0.4.1-cp311-abi3-manylinux_2_34_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.34+ x86-64

corvid_python-0.4.1-cp311-abi3-manylinux_2_34_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.34+ ARM64

corvid_python-0.4.1-cp311-abi3-macosx_11_0_arm64.whl (1.1 MB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

File details

Details for the file corvid_python-0.4.1.tar.gz.

File metadata

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

File hashes

Hashes for corvid_python-0.4.1.tar.gz
Algorithm Hash digest
SHA256 c094f9d8a22eabfb6d051ad8ded34f8be32f507c4ec3cd434175466315fba0a9
MD5 090d5213c64877e26e5d626b41e8dd3c
BLAKE2b-256 15c59fba2ab1391d8431558c88e3376d3f5bd3af0b62e3c34cc703f0d18ef38b

See more details on using hashes here.

Provenance

The following attestation bundles were made for corvid_python-0.4.1.tar.gz:

Publisher: release.yml on corvid-db/corvid-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 corvid_python-0.4.1-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for corvid_python-0.4.1-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 1eea2cc741fd44a437ebee863dcdd205f112641a87e46bc15690a39a03681fb4
MD5 7499d99a2933632dac6b36ad324d47dd
BLAKE2b-256 759e9d97de8fbe144c71dc55a36e936304ada1c432f04e46c58a6923394fa551

See more details on using hashes here.

Provenance

The following attestation bundles were made for corvid_python-0.4.1-cp311-abi3-win_amd64.whl:

Publisher: release.yml on corvid-db/corvid-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 corvid_python-0.4.1-cp311-abi3-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for corvid_python-0.4.1-cp311-abi3-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 c134e987d5a4affa133deced1392c3fea8f9da821c057d728a1c4e1e26593289
MD5 6cb1e36089e1d14d99f267e30d26ed0d
BLAKE2b-256 39f70befdc66b8ffbcc5d3c50d1c45e77a719da4c83d52230012fe02952fe319

See more details on using hashes here.

Provenance

The following attestation bundles were made for corvid_python-0.4.1-cp311-abi3-manylinux_2_34_x86_64.whl:

Publisher: release.yml on corvid-db/corvid-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 corvid_python-0.4.1-cp311-abi3-manylinux_2_34_aarch64.whl.

File metadata

File hashes

Hashes for corvid_python-0.4.1-cp311-abi3-manylinux_2_34_aarch64.whl
Algorithm Hash digest
SHA256 5e1e019a126646244db8fc7475b46d02bc910a6f7a3691627449b81e379120a6
MD5 9c9701ba132a5ad4e630c8f0650581e9
BLAKE2b-256 5c7cd33d3240115cb0abe85e83f46afea1fcaea3298e0ed408e6e8d751d6b0b5

See more details on using hashes here.

Provenance

The following attestation bundles were made for corvid_python-0.4.1-cp311-abi3-manylinux_2_34_aarch64.whl:

Publisher: release.yml on corvid-db/corvid-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 corvid_python-0.4.1-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for corvid_python-0.4.1-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 caf72d510ebe965fa91be90d041b029077572b03a91983ddcf8de6ec05d756ff
MD5 6476c985e9e7f9a3cc5c34da5cb4baab
BLAKE2b-256 7c3ac7d5e062dfb43e8baefa93501efbe7cde91a2c7b39e4b9b700aa2fe0b0b4

See more details on using hashes here.

Provenance

The following attestation bundles were made for corvid_python-0.4.1-cp311-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on corvid-db/corvid-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

0.4.1 This release

5 files

0.4.0

5 files

0.3.4

5 files

0.3.3

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page