conann 0.1.0

CPU-only Python package for the ConANN-modified FAISS bindings

conann Python package

conann/ is the publishable Python package source of truth for this project. It wraps the ConANN-modified FAISS CPU bindings under the Python distribution and import name conann.

The upstream C++ source of truth remains:

../conann-main/conann

This package builds wheels from that source, stages the generated Python files under src/conann, and publishes them as:

pip install conann-0.1.0-*.whl

import conann

index = conann.IndexFlatL2(32)

It intentionally does not provide a top-level import faiss alias. The bundled SWIG module names such as swigfaiss_avx2 stay internal to the conann package.

Repository Layout

conann/
  pyproject.toml        package metadata
  setup.py              wheel distribution hook
  scripts/              Linux build and verification scripts
  tests/                import and synthetic smoke tests
  tools/                staging tool for generated bindings
  src/conann/           generated package tree after staging

Generated build output is not source and should not be committed:

• build/
• dist/
• logs/
• results/
• venvs/
• src/conann/
• src/conann.egg-info/

Build Linux Wheels

Build the current selected Python:

scripts/build_local_wheel.sh

Build a specific pyenv Python:

scripts/build_one_python.sh 3.12.12

Build the full Linux matrix:

scripts/build_all_pythons.sh

Linux wheels are written to:

dist/linux_x86_64/

Windows Scripts

Windows packaging and verification scripts are also kept under this same root:

scripts/build_one_python_windows.ps1
scripts/build_all_pythons_windows.ps1
scripts/verify_wheels_windows.ps1
scripts/smoke_conann_wheel.py

The already-built release wheels are kept under this package root:

wheels/linux_x86_64/
wheels/win_amd64/

Verify Linux Wheels

Run install and runtime smoke tests across the Linux wheel matrix:

scripts/verify_wheels.sh

Verification artifacts are written to:

results/wheel_smoke_matrix.csv
results/wheel_smoke/

Basic Usage

import conann
import numpy as np

d = 32
nlist = 16
k = 5
rng = np.random.default_rng(123)

xb = rng.random((5000, d), dtype=np.float32)
xt = rng.random((2000, d), dtype=np.float32)
xq = rng.random((100, d), dtype=np.float32)

quantizer = conann.IndexFlatL2(d)
index = conann.IndexIVFFlat(quantizer, d, nlist, conann.METRIC_L2)
index.train(xt)
index.add(xb)

distances, labels = index.search(xq, k)

ConANN-specific IVF methods are exposed on supported IVF indexes:

calibration = index.calibrate_conann(
    alpha=0.2,
    k=k,
    xq=xq,
    ground_truth=labels,
    calib_sz=0.5,
    tune_sz=0.5,
    dataset_key="example",
)

distances, labels = index.search_conann(xq, calibration, k=k)
report = index.conann_time_report()
metrics = index.evaluate_conann(labels, labels)

Package metadata:

conann.__version__        # "0.1.0"
conann.__faiss_version__  # "1.9.0"

Current Support

• Linux x86_64: cp310, cp311, cp312, cp313, cp314
• Windows win_amd64: release wheels are currently kept in ../conann_windows/
• CPU-only package path

Notes

• src/conann/ is generated by tools/stage_conann_package.py.
• The build depends on the ConANN-enabled FAISS fork under ../conann-main/conann.
• Existing release artifacts are mirrored under wheels/ and results/ in this directory so publishing and documentation can work from one root.
• Wheel publishing should use the wheels under wheels/linux_x86_64/ for Linux and wheels/win_amd64/ for Windows.
• This conann/ directory is the canonical package root. The existing release wheels were built earlier from working directories, but the repository metadata, scripts, and release notes should now be maintained from here.