Frequently Asked Questions (FAQ)

[arnavk23]

Welcome to Annie! Here you'll find answers to common and advanced questions about installing, using, and contributing to Annie — the Rust-powered k-NN library for Python.

If your question isn’t here, open a Discussion or email maxprogrammer007 or arnavk23. We love to help!

Table of Contents

• About Annie
• Installation & Setup
• Using Annie
• Advanced Usage & Development
• Contributing
• Roadmap & Future Plans
• Troubleshooting
• Contact & Community

About Annie

What is Annie?

A Rust-powered brute-force k-NN index with Python bindings — designed to be:

• Fast (SIMD + parallelism)
• Easy to use (Pythonic API)
• Safe (thread-safe wrapper)
• Exact (not approximate) — but with plans for ANN support!

Why the name "Annie"?

From “Approximate Nearest Neighbor Index.” Even though Annie is currently exact brute-force, we kept the name for its simplicity and to reflect planned ANN backends.

How is Annie different from FAISS, Annoy, etc.?

Feature	Annie	FAISS	Annoy	scikit-learn
Language	Rust	C++	C++	Python
Exact k-NN	✅	✅	❌	✅
Approximate k-NN	Planned	✅	✅	Limited
GPU	Planned	✅	❌	❌
Python bindings	✅	✅	✅	✅

Installation & Setup

How do I install?

pip install rust-annie

Do I need Rust?

No — if installing from PyPI.

Yes — if building from source:

git clone https://github.com/Programmers-Paradise/Annie
cd Annie
pip install maturin
maturin develop --release

Which Python versions?

Python 3.8–3.12 (tested in CI).

Using Annie

How do I create an index?

from rust_annie import AnnIndex, Distance
index = AnnIndex(dim=128, metric=Distance.COSINE)

How do I add data?

import numpy as np
vecs = np.random.rand(1000,128).astype(np.float32)
ids  = np.arange(1000, dtype=np.int64)
index.add(vecs, ids)

Search for nearest neighbors:

query = np.random.rand(128).astype(np.float32)
labels, distances = index.search(query, k=5)

Batch search:

queries = np.random.rand(32,128).astype(np.float32)
labels, distances = index.search_batch(queries, k=5)

Supported distances:

• Distance.EUCLIDEAN
• Distance.COSINE
• Distance.MANHATTAN
• Distance CHEBYSHEV

Save & load:

index.save("index.bin")
loaded = AnnIndex.load("index.bin")

Thread safety:

Use: from rust_annie import ThreadSafeAnnIndex
This wrapper releases the Python GIL.

Advanced Usage & Development

Does Annie use SIMD?

Yes, SIMD accelerates dot products & norms.

Parallelism?

Yes, via Rust’s Rayon.

Exact or approximate?

Exact brute-force now; ANN (HNSW/FAISS) planned.

Data shape & dtype:

Vectors: float32 NumPy array, shape (N, dim)
IDs: int64 NumPy array, shape (N,)

Contributing

How to help?

• Write docs / type hints
• Add new distance metrics
• Test on ARM, Windows, etc.
• Implement approximate search

Tests:

cargo test # Rust tests
pytest # Python tests

Troubleshooting

ImportError?

Use pip install rust-annie
Confirm Python ≥ 3.8
pip install maturin & maturin develop if building locally

Build errors on Windows?

Install Visual Studio Build Tools
Update Rust toolchain: rustup update

“Search is slow”

Batch queries help
Overhead dominates for very small N (<1k)

Contact & Community

• Discussions: GitHub Discussions
• Issues: File an Issue

If you find Annie useful, star ⭐ the repo and join us in building the fastest Rust+Python k-NN!!

[NikshayYadav]

Thanks, will sure test it! :)

[NikshayYadav]

https://github.com/NiksheyYadav