Metadata-Version: 2.4
Name: cuknn
Version: 0.1.0
Summary: GPU accelerated K-Nearest Neighbors using CuPy
Author: Salvatore Calderaro
Project-URL: Homepage, https://github.com/salvatorecalderaro/cuKNN
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: tqdm
Dynamic: license-file

# CuPy-KNN ⚡
<p align="center">
  <img src="logo.png" alt="CuPy-KNN logo" width="600">
</p>
<p align="center">
GPU-Accelerated K-Nearest Neighbors using NVIDIA CUDA and CuPy
</p>

<p align="center">

![Python](https://img.shields.io/badge/python-3.9+-blue)
![CUDA](https://img.shields.io/badge/CUDA-GPU-green)
![License](https://img.shields.io/badge/license-MIT-orange)

</p>

## 🚀 Overview

**CuPy-KNN** is a GPU accelerated implementation of the
K-Nearest Neighbors algorithm powered by
[CuPy](https://cupy.dev/).

It provides a scikit-learn compatible API while exploiting NVIDIA GPUs
for large-scale nearest neighbor search.

Designed for:

- Machine Learning
- Deep Learning embeddings
- Computer Vision features
- Bioinformatics embeddings
- Large-scale similarity search

## ✨ Features

✅ GPU acceleration with CUDA  
✅ Batch-based distance computation  
✅ Multiple distance metrics:

- Euclidean
- Cosine
- Manhattan

✅ sklearn-like API

- `fit()`
- `predict()`
- `predict_proba()`
- `kneighbors()`

✅ Supports large datasets  
✅ Fully implemented with CuPy tensors

## 📦 Installation

Install from PyPI:

```bash
pip install cuknn
```

For CUDA-enabled systems install CuPy first:

```bash
pip install cupy-cuda12x
```

or select the version matching your CUDA installation.

## ⚡ Quick Start

```python
from cuknn import KNN

from sklearn.datasets import make_classification
from sklearn.model_selection import train_test_split


X, y = make_classification(
    n_samples=100000,
    n_features=512,
    n_classes=5
)


X_train, X_test, y_train, y_test = train_test_split(
    X,
    y
)


model = KNN(
    k=5,
    distance="euclidean",
    batch_size=1024
)


model.fit(
    X_train,
    y_train
)


prediction = model.predict(
    X_test
)

```

## 📚 Citation

If you use cuKNN in your research:

```
@software{cupy_knn,
 author = {Calderaro, Salvatore},
 title = {cuKNN: GPU Accelerated K-Nearest Neighbors},
 year = {2026}
}
```
