Metadata-Version: 2.4
Name: conann
Version: 0.1.0
Summary: CPU-only Python package for the ConANN-modified FAISS bindings
Author: ConANN contributors
License: MIT License
        
        Copyright (c) Facebook, Inc. and its affiliates.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: nearest-neighbor-search,ann,faiss,conann
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: packaging
Dynamic: license-file

# 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:

```text
../conann-main/conann
```

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

Supported runtime target: `Python 3.10+`.

```bash
pip install conann-0.1.0-*.whl
```

```python
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

```text
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:

```bash
scripts/build_local_wheel.sh
```

Build a specific pyenv Python:

```bash
scripts/build_one_python.sh 3.12.12
```

Build the full Linux matrix:

```bash
scripts/build_all_pythons.sh
```

Linux wheels are written to:

```text
dist/linux_x86_64/
```

## Windows Scripts

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

```text
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:

```text
wheels/linux_x86_64/
wheels/win_amd64/
```

## Verify Linux Wheels

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

```bash
scripts/verify_wheels.sh
```

Verification artifacts are written to:

```text
results/wheel_smoke_matrix.csv
results/wheel_smoke/
```

## Basic Usage

```python
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:

```python
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:

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

## Current Support

- Python runtime support: `3.10+`
- 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.
