Metadata-Version: 2.4
Name: eavec
Version: 0.1.0
Summary: SIMD-accelerated vector similarity search. 3-4x faster than FAISS at dim=384.
Author: Peter Lukka
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/petlukk/eavec
Project-URL: Repository, https://github.com/petlukk/eavec
Keywords: vector,search,simd,similarity,embedding,faiss
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Dynamic: license-file

# eavec

SIMD-accelerated vector similarity search. Pre-compiled kernels with a NumPy API.

```
pip install eavec
```

## Quick start

```python
import numpy as np
from eavec import batch_cosine, top_k

db = np.random.rand(100_000, 384).astype(np.float32)
query = np.random.rand(384).astype(np.float32)

scores = batch_cosine(query, db)
values, indices = top_k(scores, k=10)
```

## Why eavec?

- **3-4x faster than FAISS** at dim=384 (the most common embedding dimension)
- **8-27x faster than NumPy** depending on metric and dimension
- **Zero dependencies** beyond NumPy. No Rust, no LLVM, no compilation step.
- **Multi-threaded** batch operations release the GIL for true parallelism.

## API

### Single-pair operations

| Function | Signature | Returns |
|---|---|---|
| `dot(a, b)` | two 1D float32 arrays | `float` |
| `norm(a)` | one 1D float32 array | `float` |
| `cosine(a, b)` | two 1D float32 arrays | `float` |
| `l2_squared(a, b)` | two 1D float32 arrays | `float` |

### Batch operations

| Function | Signature | Returns |
|---|---|---|
| `batch_dot(query, db)` | query: 1D(dim,), db: 2D(n,dim) | 1D float32(n,) |
| `batch_cosine(query, db)` | query: 1D(dim,), db: 2D(n,dim) | 1D float32(n,) |
| `batch_l2(query, db)` | query: 1D(dim,), db: 2D(n,dim) | 1D float32(n,) |
| `normalize(db)` | db: 2D(n,dim) | 2D float32(n,dim) |
| `threshold_filter(scores, threshold)` | scores: 1D float32 | 1D int32 indices |
| `top_k(scores, k)` | scores: 1D float32, k: int | (values, indices) |

### Multi-threaded

| Function | Signature | Returns |
|---|---|---|
| `batch_dot_mt(query, db, num_threads=None)` | same + threads | 1D float32(n,) |
| `batch_cosine_mt(query, db, num_threads=None)` | same + threads | 1D float32(n,) |
| `batch_l2_mt(query, db, num_threads=None)` | same + threads | 1D float32(n,) |

## Platforms

- Linux x86_64 (AVX2)
- Linux aarch64 (NEON)
- Windows x86_64 (AVX2)

## How it works

eavec ships pre-compiled SIMD kernels built with [Ea](https://github.com/petlukk/eacompute), a SIMD kernel compiler. The kernels use dual-accumulator FMA with f32x8 vectors, restrict pointers for no-alias optimization, and explicit prefetch hints.

## License

Apache-2.0
