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.4.0.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.4.0-cp311-abi3-win_amd64.whl (1.2 MB view details)

Uploaded CPython 3.11+Windows x86-64

corvid_python-0.4.0-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.0-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.0-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.0.tar.gz.

File metadata

  • Download URL: corvid_python-0.4.0.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.4.0.tar.gz
Algorithm Hash digest
SHA256 0e8d0431f2f117193daf4c1ed2e337682310eff45899ea4de09293ed69bee1dc
MD5 2616d8c43df87d58903fe8723349c475
BLAKE2b-256 5df357cfb23a5cdd1e6f552ddcccb2353cb0492fab2e61be01e17156044dafbd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for corvid_python-0.4.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 5457e935b6c5e8e90f739b6419cb1096e171c7d096895c6fdbb7cbd0d1937dee
MD5 13f2bdb0dfc6c2d91069b412b94a03b8
BLAKE2b-256 185c77a81f32a74335cc63b16d0862c3a21a29cb37b6774c3d187c90c0c69d04

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for corvid_python-0.4.0-cp311-abi3-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 e9d46afa3fafeeb62d88cfc75707c7da3a8d91f0810e162342c6e340aff9c773
MD5 7c95059468ce1a1f182b19433b85be1f
BLAKE2b-256 9d7f81067fdd8bbc5d673280350c731fab40527df08ed92f3397c27c1961ffab

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for corvid_python-0.4.0-cp311-abi3-manylinux_2_34_aarch64.whl
Algorithm Hash digest
SHA256 847a8ed9e0499c716b6466c8e6ffacf9f1b984e55bb78ecaa3bf42d85c594f79
MD5 acf00dae4f350b7860fdfe62da40f6af
BLAKE2b-256 bdf2a2cd9ce0b96994526385bfcd3e6969f9405c5e74922d82a6d2aec99dd377

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for corvid_python-0.4.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ddf44424c372a575676a9919ca51dec02cdad72c75188cb44b18e33c557db433
MD5 e6d7ebc4c5819e1cac1cf7f4c68c086d
BLAKE2b-256 86cea5973ca24ccae27013b72780313c426baac56d7dccc0f785c7ab736aebe8

See more details on using hashes here.

Provenance

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

This release

0.4.0 This release

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