Skip to main content

ANNexDB: Python bindings for ANNex

ANNex website

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.

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)

Table of built distributions (wheels) for ANNexDB 0.3.0
File Actions
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 10.12+ universal2 (ARM64, x86-64), macOS 10.12+ x86-64, macOS 11.0+ ARM64 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 log

Release 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 log

Release 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 log

Release 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 log

Security 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.

Select from 4 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.3.0 This release

4 release files Full provenance

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