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

Pending first publish: the package is not on PyPI yet — everything is prepared (maturin wheel config, one abi3 wheel per platform), and publishing waits on the first release tag (docs/PLAN.md §6). Until then, build from source — Python 3.11–3.14 (the floor is 3.11; CI exercises 3.14/3.13/3.12/3.11 on every wheel platform), Rust ≥ 1.88, and a C toolchain:

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

The wheel is abi3 (cp311), so one wheel per platform covers every Python ≥ 3.11. Planned platform matrix: linux-x64 / linux-arm64 / macos-arm64 / windows-x64.

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, deterministic output, executed on every CI leg:

File What it shows
quickstart.py open, insert 3 docs, kNN vector query, print
hybrid.py filter + vector + BM25, RRF fusion, MMR rerank, limit
vector_index.py in-memory / on-disk / binary-quantized HNSW vs exact, reopen
text_search.py BM25 ranking, English + CJK (bigram segmentation)
graph.py link/neighbors/traverse + the delete cascade
geo.py radius / bbox / nearest-k over real coordinates (haversine km) 
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:
Newer release available (0.4.1)

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.3.4.tar.gz (74.9 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.3.4-cp311-abi3-win_amd64.whl (1.2 MB view details)

Uploaded CPython 3.11+Windows x86-64

corvid_python-0.3.4-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.3.4-cp311-abi3-manylinux_2_34_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.34+ ARM64

corvid_python-0.3.4-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.3.4.tar.gz.

File metadata

  • Download URL: corvid_python-0.3.4.tar.gz
  • Upload date:
  • Size: 74.9 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.3.4.tar.gz
Algorithm Hash digest
SHA256 81280fded025fea97e467a5fd90678ecf78d84b548dbbd0c4d4015da24e8621c
MD5 8a4e4973f737cd05acd0db9346d00afd
BLAKE2b-256 064315fdb25c7eb9edae4a08e656d1a4215dad85f93895313f5412f2fde9eca7

See more details on using hashes here.

Provenance

The following attestation bundles were made for corvid_python-0.3.4.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.3.4-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for corvid_python-0.3.4-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 bf19dbe5423eb83a53417a36261842cd8cb47e8e8365968fe6dc9b5f88c087b2
MD5 2047feacb070dcbdfadafe7e71914d06
BLAKE2b-256 2eeb31f32cd4f3a42b7476dbb743d07e147dea4a0f0c2e17440cbc9d9e4be987

See more details on using hashes here.

Provenance

The following attestation bundles were made for corvid_python-0.3.4-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.3.4-cp311-abi3-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for corvid_python-0.3.4-cp311-abi3-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 ef9402343b44a5dab34c0e04be516b680d030c2237bd9998370cc71697c131dd
MD5 94dfe5fc38c6363ffc8ec1c547c044c7
BLAKE2b-256 a7d825e39898bf6134fdcd617b1dcda4e6fb79c0d2a77257708ad285571944c7

See more details on using hashes here.

Provenance

The following attestation bundles were made for corvid_python-0.3.4-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.3.4-cp311-abi3-manylinux_2_34_aarch64.whl.

File metadata

File hashes

Hashes for corvid_python-0.3.4-cp311-abi3-manylinux_2_34_aarch64.whl
Algorithm Hash digest
SHA256 72fa22448ce2048a3b34b311bb7fd4a7c6e6ffe14f14c3ab082eaea2b4f5f1a5
MD5 e933aea99a6fafd9f79bd97c76d15792
BLAKE2b-256 a5aaaf7eab4b4e99262ad8fc552f685fb5aaf252ec65d6a6be048f25f1e79742

See more details on using hashes here.

Provenance

The following attestation bundles were made for corvid_python-0.3.4-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.3.4-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for corvid_python-0.3.4-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 961051f08bddf10c27477f9c973b8c0ef1958c900df44dcdf85816968b4cb670
MD5 88e003aef8412eb603f81c38bc0905da
BLAKE2b-256 280fd4b204ceceb402eca3150bb9145a59b6b4943759c6ae50a1fe73549d417a

See more details on using hashes here.

Provenance

The following attestation bundles were made for corvid_python-0.3.4-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

0.4.1

5 files

0.4.0

5 files

This release

0.3.4 This release

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