Thanks for sharing, even if docs seems a little overstated and misleading

This project is definitely AI-generated (at least the README is) so how have you ground-truth'd this statement?

Then I started asking a simple question: why can’t nearest neighbor methods be both fast and competitive with stronger tabular models in real production settings?

That question led me down a much deeper path than I expected.

First, I realized there isn’t just “KNN.” There are many variations: weighted distances, metric learning, approximate search structures, indexing strategies, pruning heuristics, and hybrid pipelines. I also discovered that most fast approaches trade accuracy for speed, and many accurate ones assume large training time, heavy indexing, or GPU-based vector engines.

I wanted something CPU-focused, predictable, and deployable.

Some of the key things I learned along the way:

Feature importance matters a lot more than I initially thought. Treating all features equally is one of the biggest weaknesses of classical KNN. Noise and irrelevant dimensions directly hurt distance quality.

The curse of dimensionality is not theoretical — it’s painfully practical. In high dimensions, naive distance metrics degrade quickly.

Scaling and normalization are not optional details. They fundamentally shape the geometry of the space.

Inference time often matters more than raw accuracy. In many real-world systems, predictable latency is more valuable than squeezing out 0.5% extra accuracy.

Memory footprint is a first-class concern. Nearest neighbor methods store the dataset; this forces you to think carefully about representation and pruning.

GBMs are not “just models.” They’re systems. After studying gradient boosting more closely, I started seeing it less as a single model and more as a structured system with layered feature selection, residual fitting, and region partitioning. That perspective changed how I thought about improving KNN.

I began experimenting with:

Learned feature weighting to reduce noise.

Feature pruning to reduce dimensional effects.

Vectorized distance computation on CPU.

Integrating approximate neighbor search while preserving final exact scoring.

Structuring the algorithm more like a deployable system rather than a classroom algorithm.

One big realization: no model dominates under every dataset and constraint. There is no universal winner. Performance depends heavily on feature quality, data size, dimensionality, and latency requirements.

Building this forced me to think less about “which algorithm is best” and more about:

What constraints does production impose?

Where is the real bottleneck: compute, memory, or data geometry?

How do we balance accuracy, latency, and simplicity?

I’m still exploring this space and would really appreciate feedback from people who’ve worked on large-scale similarity search or production ML systems.

If anyone has suggestions on:

Better CPU vectorization strategies,

Lessons from deploying nearest-neighbor systems at scale,

Or papers I should study on metric learning / scalable distance methods,

I’d love to learn more.

I’ve put the current implementation on GitHub for anyone curious, but I’m mainly interested in discussion and technical feedback.