Metadata-Version: 2.4
Name: smart-knn
Version: 0.2.2
Summary: A modern, weighted k-nearest neighbors algorithm with learned feature importance and fast CPU inference.
Author-email: Jashwanth Thatipamula <thatipamulajashwanthgoud@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/thatipamula-jashwanth/smart-knn
Project-URL: Documentation, https://thatipamula-jashwanth.github.io/SmartEco/
Project-URL: Repository, https://github.com/thatipamula-jashwanth/smart-knn
Project-URL: Issues, https://github.com/thatipamula-jashwanth/smart-knn/issues
Keywords: machine-learning,knn,nearest-neighbors,weighted-knn,interpretable-ml,cpu-ml,fast-inference,numba,regression,classification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: scikit-learn>=1.2
Requires-Dist: faiss-cpu>=1.8.0
Requires-Dist: joblib>=1.2
Requires-Dist: numba>=0.60
Dynamic: license-file

<p align="center">
  <img src="smart_knn/logo/SmartKNN.png" alt="SmartKNN logo" width="160" />
</p>

<h1 align="center">SmartKNN</h1>

<p align="center">
A modern, weighted nearest-neighbor learning algorithm with learned feature importance and adaptive neighbor search.
</p>

<p align="center">
  <a href="https://thatipamula-jashwanth.github.io/SmartEco/">
    <img src="https://img.shields.io/badge/Website-SmartEco-blue?style=flat-square" alt="Website"/>
  </a>
  <a href="https://pypi.org/project/smart-knn/">
    <img src="https://img.shields.io/pypi/v/smart-knn?style=flat-square" alt="PyPI version"/>
  </a>
  <a href="https://pypi.org/project/smart-knn/">
    <img src="https://img.shields.io/badge/Python-3.8%2B-blue?style=flat-square" alt="Python versions"/>
  </a>
  <a href="https://github.com/thatipamula-jashwanth/smart-knn/actions">
    <img src="https://img.shields.io/github/actions/workflow/status/thatipamula-jashwanth/smart-knn/ci-tests.yml?style=flat-square" alt="CI status"/>
  </a>
  <a href="https://opensource.org/licenses/MIT">
    <img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="MIT License"/>
  </a>
</p>

## Overview

**SmartKNN** is a nearest-neighbor–based learning method that belongs to the
broader **KNN family** of algorithms.

It is designed to address common limitations observed in classical KNN
approaches, including:

- uniform treatment of all features  
- sensitivity to noisy or weakly informative dimensions  
- limited scalability as dataset size grows  

SmartKNN incorporates **data-driven feature importance estimation**,
**dimension suppression**, and **adaptive neighbor search strategies**.
Depending on dataset characteristics, it can operate using either a
brute-force search or an approximate nearest-neighbor (ANN) backend, while
exposing a consistent, **scikit-learn–compatible API**.

The method supports both **regression** and **classification** tasks and
prioritizes **robustness**, **predictive accuracy**, and **practical inference latency**
across a range of dataset sizes.

---

## Key Capabilities

- **Learned feature weighting**
  - MSE relevance
  - Mutual Information
  - Random Forest importance  
  *(method configurable depending on task and dataset)*
- **Automatic preprocessing**
  - normalization
  - NaN / Inf handling
  - feature masking
- **Distance-weighted neighbor voting**
- **Brute-force and ANN backends**
  - designed to scale to large datasets (hardware and tuning dependent)
  - optional GPU-accelerated neighbor search
- **Vectorized NumPy with Numba acceleration**
- **Scikit-learn–compatible API**

---

## Installation

```bash
pip install smart-knn
```

---

## Documentation

- https://thatipamula-jashwanth.github.io/SmartEco/

Detailed documentation and design notes are maintained externally.
This repository README is intentionally kept concise.

---
## Examples

Runnable examples are available in the **examples/ directory**:
```
python examples/regression_example.py
python examples/classification_example.py
```

---
## Benchmarks & CI

- Comprehensive benchmark suites for regression and classification
- GitHub Actions CI for tests and benchmarks
- Reproducible, engineering-focused evaluation

Benchmark details are documented in **benchmarks/README.md**.

---
## Project Status

- SmartKNN v2 is stable
- API is frozen for the v2.x series (backward-compatible improvements only)
- Actively maintained
- Open to research and engineering collaboration

---
## License

**SmartKNN** is released under the **MIT License**.
See **LICENSE** for details.
