ANNexDB: Python bindings for ANNex
annexdb.Index builds, saves, loads and searches an ANNex dense vector index from NumPy
arrays, with native HNSW search for single queries and threaded batches. Python 3.9+ and NumPy
are required. Embeddings are supplied by the caller.
These bindings cover dense vector search. Hybrid retrieval (BM25 + dense + sparse), payload
filters and multivector search live in the Rust API and in the
annex-multivector HTTP server.
Install
python -m pip install ANNexDB
To build from source, run this from the workspace root in an activated virtual environment:
python -m pip install 'maturin>=1.8,<2' numpy
maturin develop --release --manifest-path python/annex-py/Cargo.toml
Quickstart
import annexdb
import numpy as np
# One row per item: your embeddings, float32 and C-contiguous.
vectors = np.array(
[
[0.9, 0.1, 0.0, 0.0],
[0.8, 0.2, 0.1, 0.0],
[0.0, 0.1, 0.9, 0.2],
[0.1, 0.0, 0.8, 0.3],
],
dtype=np.float32,
)
index = annexdb.Index.build(vectors, metric="cosine") # row i gets id i
query = np.array([0.85, 0.15, 0.05, 0.0], dtype=np.float32)
ids, scores = index.search(query, k=3)
index.save("segment.bin") # a snapshot Rust can load too
index = annexdb.Index("segment.bin") # reload it later
ids, scores = index.search_batch(query[None, :], k=3, threads=4)
Index.build(vectors, *, ids=None, metric="cosine", m=16, ef_construct=200, level_cap=16, quantize=False)
takes a float32 array of shape [n, dim]; everything after vectors is keyword-only. ids is
an optional uint64 array of n unique ids; by default row i gets id i. metric is
"cosine", "dot" or "euclidean" (aliases "angular", "ip" and "l2"). m and
ef_construct are the usual HNSW build parameters, spelled as in the Rust API and the HTTP
server. quantize=True builds the SQ8 codes used by sq8_screen searches; they live in memory
and are not stored in the snapshot, so pass quantize=True again when loading. index.save(path)
writes a snapshot that Index(path) and Rust's Segment::load_from_path both load, and
index.metric() reports the metric. Snapshots written by the Rust library load the same way.
Search
Inputs must be C-contiguous float32 NumPy arrays with the index's dimension and finite values
(use array.astype(np.float32) for float64 data). Inputs are copied before releasing the GIL;
batch workers are capped to available hardware threads. Single searches return up to k
results. Batches have shape (queries, k) and pad missing matches with uint64's maximum
value and NaN. Empty batches and k=0 preserve these shapes. Combined batch output is limited
to 1 GiB; oversized shapes raise OverflowError before native allocation. Errors propagate to
Python rather than becoming empty result rows.
Scores
Scores follow the index metric, and which direction is closer depends on it:
| Metric | Score | Closer is |
|---|---|---|
cosine |
1 - cosine similarity |
lower |
dot |
dot product | higher |
euclidean |
squared Euclidean distance | lower |
Results are returned best first. SQ8 screening requires loading with quantize=True and
querying with sq8_screen=True. Runtime options scan_cap and patience keep the core search
meanings; results remain approximate (use ef at least the index size for exact results on
small indexes).
Tests
CI builds and installs the wheel on Linux and macOS, generates a deterministic Rust snapshot, and checks the Python results against an independent NumPy oracle. The build tests need no fixture; the snapshot-loading tests use one built by Rust:
cargo run -p annex-py --example make_test_fixture -- /tmp/annex-fixture.bin
ANNEX_TEST_SNAPSHOT=/tmp/annex-fixture.bin \
python -m unittest discover -s python/annex-py/tests -v
Metadata
Release files for ANNexDB 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| annexdb-0.3.0-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details for annexdb-0.3.0-cp39-abi3-win_amd64.whl |
| annexdb-0.3.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ x86-64 | Details for annexdb-0.3.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
| annexdb-0.3.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ ARM64 | Details for annexdb-0.3.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
| annexdb-0.3.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64, macOS 10.12+ universal2 (ARM64, x86-64), macOS 10.12+ x86-64 | Details for annexdb-0.3.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl |
Total release size: 3.2 MB
Release files / annexdb-0.3.0-cp39-abi3-win_amd64.whl
| Download URL | annexdb-0.3.0-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 516.5 kB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
d15401422e49baccda4828d78b8117eca3063d71de7d463022e58cf82c5b831d
|
|
BLAKE2b-256 checksum How to use checksums |
48dc656bd45c6652d928c9fd32b11c62d224806f5ad694ec17a086d825eb0c4d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.
Transparency logRelease files / annexdb-0.3.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | annexdb-0.3.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 704.7 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
fe9e4a3ea78bbc3eb82459e6463ce767ae77be6eda009fe4b92952b290df8d31
|
|
BLAKE2b-256 checksum How to use checksums |
999cba0976cda287663d4920bd1b84dbc38d62ef478a126b62b6bd5fb403f020
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.
Transparency logRelease files / annexdb-0.3.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | annexdb-0.3.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 699.7 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
bbb68404c5a9c39610e270e655c440903c92732b89c9e61458916e55e9da7ba1
|
|
BLAKE2b-256 checksum How to use checksums |
71f5102b2c559481f5c32cc1fa1d58fa655843ab9abf26fe09b85106f6435e50
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.
Transparency logRelease files / annexdb-0.3.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
| Download URL | annexdb-0.3.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl |
|---|---|
| Size | 1.3 MB |
| Tags | CPython 3.9 abi3 macOS 10.12+ universal2 (ARM64, x86-64) macOS 10.12+ x86-64 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
16c428ff52f37af7d7bb8e11613b8200b2c364d87a579ed8f3d3bc8d910cf08c
|
|
BLAKE2b-256 checksum How to use checksums |
d7afe9d3f16e139a3d0d9e9a443387854ba982f22832f6c26df0f93f4490d126
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.
Transparency logSecurity for ANNexDB 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 4 files in this release have been uploaded with provenance metadata.
Attestation for annexdb-0.3.0-cp39-abi3-win_amd64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.