Built by the Winnex technical team, winnex-madhava is a pip-installable engine with a native C++20 core that delivers a mathematical guarantee: a per-document Cauchy-Schwarz proof. Its value is not query speed — it is the combination of per-document proof + extremely fast build + determinism.
winnex-madhava is the deterministic vector search engine built by the Winnex technical team — the mathematics, the three modes, the real use cases, and the design trade-offs that define where each mode is the right tool.
The system is (current version ~1.8.x) a vector search engine that:
This is different from HNSW/IVF/PQ, which are heuristic/probabilistic and offer no per-document proof. The guarantee is verifiable — the public Kaggle notebooks and the PyPI package report 0 bound violations consistently across every run.
There are three main modes:
Bound / cascade (default) — scan with bound-based pruning (CPU, int8 quantized).
Speed (GPU/CPU) — exact scan via fused QKᵀ + top-k (OpenCL by default, CUDA optional). Literally an accelerated exact scan.
Hybrid (MadHybrid) — clustering + per-cell bound (sublinear, recall trade-off like any IVF).
The mathematics, the three modes, and the guarantees that define winnex-madhava — as documented and maintained by the Winnex technical team.
For any query q and candidate vector v, the Cauchy-Schwarz inequality bounds the raw inner product:
⟨v, q⟩ ≤ ⟨Pv, Pq⟩ + ‖v − PᵀPv‖ · ‖q − PᵀPq‖
where P is a QR-orthogonalized (Modified Gram-Schmidt) random projection. Because
‖v − q‖² = ‖v‖² + ‖q‖² − 2·⟨v, q⟩
the bound on ⟨v, q⟩ becomes a lower bound on L2²:
‖v − q‖² ≥ ‖v‖² + ‖q‖² − 2·UB(⟨v, q⟩)
Stage 1 computes this lower bound for every vector and keeps the top-k1 by smallest L2². Any vector pruned here is mathematically proven not to be in the exact top-K. Bound violations = 0 by construction.
Stage 2 (optional) applies a tighter bound B2 on the k1 survivors. Post-filter computes the exact metric on the surviving top-k2, so the result is the true top-K of the surviving set. Because Stage 1/2 never prune a real neighbor, the post-filter recovers everything a perfect scan would find.
The residual ‖v − PᵀPv‖ is computed on the real float32 projection, not the int8-quantized one — this is what the inequality requires, and it is what makes the bound exact rather than approximate.
import numpy as np
import winnex_madhava
corpus = np.random.randint(0, 256, size=(100_000, 128), dtype=np.uint8)
engine = winnex_madhava.build_engine(corpus, dim=128, k=10)
print(f"indexed {engine.num_vectors()} vectors in {engine.build_seconds():.2f}s")
query = corpus[0].astype(np.float32)
result = engine.search(query)
print(result.indices) # top-K dataset ids
print(result.latency_ms) # milliseconds
print(result.bound_violations) # always 0 — the guarantee
The default path is the bound + post-filter scan: Stage 1 computes the Cauchy-Schwarz lower bound for every vector, prunes only what is provably outside the top-K, and an exact post-filter closes the ranking. It is the mode that delivers the per-document proof and the 0-violation guarantee on CPU (int8).
Input contract: uint8 corpus (0–255). For float32 embeddings, use hybrid=True or speed=True.
Real use case — e-discovery with a defensible record. A law firm under FRCP Rule 26 must prove it did not miss a relevant document in production. With default mode over a 1M-document uint8 corpus, every excluded document carries a certificate UB(v) < worst — the retrieval recovers 99.6% of the exact top-10 with 0 bound violations, and each exclusion is recomputable in court. Latency (45.8 ms) is the honest price of the proof; the build is 2.0 s vs HNSW 159 s.
Why it matters: this is the only mode where the answer "we did not miss a relevant document" is a mathematical statement, not a probabilistic guess. It is what HNSW/IVF cannot offer.
corpus_u8 = np.random.randint(0, 256, size=(1_000_000, 128), dtype=np.uint8) engine = winnex_madhava.build_engine(corpus_u8, dim=128, k=10) res = engine.search(query_f32) print(res.indices, res.bound_violations) # always 0 — the guarantee
The same engine can run in hybrid mode: the corpus is clustered into nlist cells, a query is routed to the nprobe most-similar cells, and each cell runs the identical bounded engine. Query cost becomes sublinear (nprobe × cell_size instead of N) while keeping the bound guarantee.
Corpus type is auto-detected: float32 → pure-Python bound cell; uint8 → native C++ MadhavaL2 per cell. Switch with a single flag.
Real use case — news classification at scale. A news aggregator serving 209,527 categorized articles needs sub-linear search with a guarantee. With hybrid=True, nprobe=5, MadHybrid reaches the same NDCG@10 as the exact FlatIP baseline while running 4× faster per query (8.0 ms vs 32.3 ms) and building 14× faster than HNSW (12.9 s vs 180.8 s) — same recall, proof per cell, and rebuildable every minute as articles arrive.
Why it matters: hybrid trades recall for speed (like any IVF index). On structured data (news categories), recall@10 ≈ 1.0 at nprobe=3–8; on uniform data, use default mode. Ideal for large, clustered corpora and streaming/rebuild-heavy workloads.
embeddings = np.random.randn(50_000, 128).astype(np.float32)
embeddings /= np.linalg.norm(embeddings, axis=1, keepdims=True)
eng = winnex_madhava.build_engine(
embeddings, k=10, hybrid=True, nlist=64, nprobe=5, metric="cosine",
)
res = eng.search(embeddings[0].astype(np.float32), k=10)
The GPU path (OpenCL) runs the QKᵀ matmul as a single fused kernel (qkt_fused_topk) that also computes the per-row top-k — no intermediate scores[N] matrix is materialized.
M work-groups per query keep all GPU compute units active even for a single query — the reason single-query latency dropped 47.8ms → 2.41ms (20×) at 1M. Coalesced memory access makes the scan memory-bound at ~448 GB/s.
| Query mode | GPU (OpenCL) 1M | CPU 1M | Notes |
|---|---|---|---|
| single-query | 2.41 ms | 9.56 ms | GPU 4× faster |
| batch (100 q) | 1.55 ms/q | ~9 ms/q | GPU 6× faster |
Real use case — regulated RAG answer generation. A bank's RAG must retrieve the exact top-10 clauses over a 1M-document legal corpus on every user question, with no approximate miss. With speed=True, each retrieval is an exact scan returning the true top-10 in 2.41 ms single-query, or 1.55 ms/query in batch — fast enough for interactive chat, and provably complete, so the LLM never builds an answer on a missing document.
Why it matters: use speed=True with metric="l2" (or "cosine") for an exact scan on GPU — the fastest correct path per query. For throughput (batch), search_batch amortizes the kernel launch; at 1M it sustains ~600–640 QPS.
eng = winnex_madhava.build_engine(corpus_u8, dim=128, k=10, speed=True) res = eng.search(query_f32) # exact scan, GPU (OpenCL)
Searches 100M vectors (12.8 GB) without ever loading the raw corpus into RAM. The corpus is memory-mapped (np.memmap), the C++ core builds int8-quantized projections in streaming blocks, and only those compressed projections (~19 GB at 100M) live in RAM.
The key knob is k2_max (default 2000): it caps Stage-2 survivors, so the exact Stage-3 scoring is bounded at large scale — the bigann_stream V3 optimization, with no recall cost.
Real use case — 100M-vector corpus on a 31 GB machine. A government audit body holds 100M documents (12.8 GB) but only 31 GB of RAM. Loading the raw corpus float32 would need ~51 GB and OOM. Streaming mmaps the corpus, keeps only the ~19 GB of int8 projections in RAM, and indexes 100M in 342 s (~5.7 min) with 0 bound violations — searchable immediately, without buying a bigger machine.
Why it matters: this is what lets winnex-madhava index corpora that would OOM a float32 in-memory index — on RAM/CPU-constrained infrastructure, or on very large corpora that change continuously.
base = np.memmap("base.u8bin", dtype=np.uint8, mode="r", shape=(100_000_000, 128))
engine = winnex_madhava.build_engine(
base, dim=128, metric="cosine",
k1_fraction=0.05, k2_fraction=0.01,
k2_max=2000, postfilter=True,
)
res = engine.search(query_f32)
print(res.indices, res.bound_violations) # 0 violations — the guarantee
Free for evaluation and non-production work — study, test, prototype, benchmark. This is the recommended way to start.
Not free for commercial / production use (a "Search Service" exposing the functionality to third parties). That requires a commercial license from Winnex.
Change date: converts to GPL v2.0 or later on the change date. Commercial licensing via pay@winnex.ai (ISV embedding, database vendor, platform company, internal production).
Real use case — evaluation before procurement. A law firm's CTO wants to verify the completeness guarantee before buying. The recommended path is free evaluation: pip install winnex-madhava, run the shipped benchmark CLI on their own corpus, and reproduce the 0 bound-violation guarantee. Only when it moves to production serving (a "Search Service" for third parties) does a commercial license apply — the same pattern Winnex follows for banks, ISVs, and database vendors.
Why it matters for adoption: BSL 1.1 is source-available, not OSI open-source — a real consideration for a CTO evaluating a long-term dependency. Evaluation is free; production requires a commercial license.
Three public, reproducible references — each read with attention to its methodological limitations.
winnex-madhava-benchmark-glove
100k words, 200D, uint8 quantized.
Conclusion: the engine works correctly on real embeddings and reaches the exact-scan ceiling.
winnex-madhava-pip-200-queries
BIGANN-100M dataset (uint8, 128D).
On subsets the official GT (generated in the 1B space) has partial coverage, so the ceiling is not 1.0. No method (exact or approximate) can exceed that ceiling.
winnex-madhava-1-7-real-benchmark-vs-hnsw-ivf-pq
Winnex's technical team discovered (and documented) that the official GT of the shurangwu/bigann-100m dataset is not aligned with that dataset's base.u8bin (different vector order). Recall vs official GT was 0.0. The team abandoned the official GT and switched to the local exact scan as the ceiling — the mathematically correct reference.
| Method | R@10 (vs local ceiling) | Latency (ms) | Build (s) | Efficiency |
|---|---|---|---|---|
| Ceiling (local exact scan) | 1.0000 | — | ~3 | 100% |
| Madhava bound (int8 5%/1%) | 0.9960 | 45.8 | 2.0 | 100% (0 vio) |
| Madhava speed GPU (exact) | 1.0000 | 6.14 | 1.5 | 100% |
| Madhava speed GPU batch | 1.0000 | 3.09 | 1.5 | 100% |
| HNSW(ef=128) | 0.9760 | 0.56 | 159 | 98% |
| HNSW(ef=64) | 0.9330 | 0.34 | 159 | 94% |
| IVF(nlist=4000, np=50) | 0.9250 | 0.75 | 61 | 93% |
| IVF(nlist=4000, np=10) | 0.6840 | 0.29 | 61 | 69% |
| IVF-PQ | 0.4780 | 0.23 | 10 | 48% |
Madhava bound recovers 99.6% of the exact top-10 with proof of 0 violations.
Speed GPU is an exact scan and reaches 100% of the ceiling in ~3–6 ms.
HNSW/IVF are far faster per query, but lose recall and offer no guarantee.
Methodology: the benchmark reference is the local exact scan as the ceiling — the mathematically valid standard, independent of the GT file. Winnex documented the GT-validity correction and re-ran the numbers against the valid reference; the figures on this page reflect that methodology.
What the engine delivers — and where each capability matters in practice.
Unique among popular ANN indexes. Useful in compliance, audit, legal discovery, medical records, regulated RAG (EU AI Act, LGPD, HIPAA, etc.). Every excluded document carries a UB(v) < worst certificate.
1–200 s at 10M–100M vs minutes/hours for HNSW. Ideal for corpora that change frequently, or streaming / continuous ingestion. Building 1M in 2.0 s vs HNSW 159 s (~77×).
Same query + same data = same result. Reproducible, auditable, verifiable by any auditor or court.
Can index 100M without loading the corpus into RAM (12.8 GB mmap, 0 violations, ~342 s build).
C++20 + Python bindings, OpenCL (vendor-neutral), AVX2, CI tests, a detailed changelog, and honest fixes of metric and GT bugs.
The trade-off sections make the price of the guarantee explicit — the conditions under which each mode is the right tool.
A truck does not lose to a race car because it is slower — it carries what the race car cannot carry. winnex-madhava does not compete on the speed track. It competes on the road where the cargo is regulatory responsibility, the risk of a million-dollar fine, and the demand for proof in court.
The race car wins on the track. When the question is "how fast can you return an answer?", HNSW wins — sub-ms, and the README says so plainly. The race car is built for one thing: speed at the expense of certainty.
The truck wins where the cargo matters. When the question is "can you prove the answer is complete?", the race car has no cargo bay. The truck's cargo is the per-document Cauchy-Schwarz proof — the guarantee that no relevant document was missed.
A truck's value is not lap time — it is how fast it can reload and get back on the road. That is exactly where winnex-madhava dominates: while the race car (HNSW) needs 159 seconds to rebuild a 1M index, the truck does it in 2.0 seconds — about 77× faster. When the cargo (your corpus) changes every 1–60 seconds, the truck keeps moving; the race car is stuck in the pit for an hour.
| Race car — HNSW / IVF | Truck — winnex-madhava | |
|---|---|---|
| Track | Latency (sub-ms, high QPS) | Proof, audit, frequent rebuild |
| Cargo bay (guarantee) | None — probabilistic | Per-document proof, 0 violations |
| Build 1M | 159 s | 2.0 s (77×) |
| Recall vs exact ceiling | HNSW 97.6% · IVF 92.5% · IVF-PQ 47.8% | 99.6–100% |
| Determinism | No (random graphs) | Yes |
| Audit trail | None | Per-document certificate |
| Best when | Millions of QPS, approximation OK | Proof + fast rebuild required |
The honest reading: the race car is faster on the track, and for pure-speed workloads without compliance needs, HNSW is the right tool — we do not dispute that. But a race car has no cargo bay: it cannot prove completeness, and its index rebuild is a liability when data changes fast. The truck does not try to beat the race car on the track. It carries the load the race car physically cannot — mathematical certainty and fast rebuild — and that is the whole point.
Every engine is a set of choices. winnex-madhava chooses mathematical certainty as its core; these are the deliberate trade-offs that follow, and the conditions under which each mode is the right tool.
The bound engine scans with a mathematical bound before pruning — so latency is tens to hundreds of ms (or seconds at 100M). The speed GPU path brings an exact scan to a few ms, and for workloads where sub-ms latency is the only requirement, an approximate index is the right tool.
Bound mode is an intelligent scan with pruning, not a heuristic graph. On uniform/random data the pruning is less effective and latency approaches brute-force; on structured data (text embeddings, categories) it is highly effective. When the requirement is completeness, that is the point.
The default mode expects uint8 (0–255); for float32 embeddings, hybrid=True or speed=True are the designed paths. Each mode has a defined contract — documented and enforced by the API.
The engine is young (1.x, August 2026) and under active development by the Winnex technical team (Goiânia, Brazil). Distribution is BSL 1.1 — free for evaluation and study, commercial license for production — the standard pattern for source-available infrastructure seeking regulated-enterprise adoption.
A note on the BIGANN benchmark methodology. Winnex initially reported recall against the official BIGANN GT file. A rigorous audit showed that file is not aligned with the dataset's reordered base — its ids point to the wrong vectors. Winnex corrected the methodology to the local exact scan as the ceiling, which is the mathematically valid reference, and documented the correction transparently. The numbers on this page reflect that corrected methodology.
There is no single "best" tool — there is the right tool for each requirement.
winnex-madhava is the right tool wherever "fast but unprovable" is a liability. The design pays more latency per query than an approximate index in exchange for a mathematical proof per document and a much faster build.
| Use case | Why winnex-madhava |
|---|---|
| Regulated retrieval (legal discovery, medical records, financial compliance, government audits) | Every excluded document carries a proof it could not be in the top-K. Defensible in court. |
| Continuous ingestion / dynamic RAG (corpus changes frequently) | Build is ~10–1000× faster than HNSW — no painful rebuilds. Rebuild the whole index on every ingestion. |
| Batch processing | Scan everything with bounds; throughput over latency. |
| RAM/CPU-constrained environments | Int8-quantized projections use ~4× less memory than float32 (18.6 GB for 100M×128D). |
| RAG that must not silently drop a relevant document | Deterministic recall ceiling reachable; 0 bound violations. |
| Auditability / compliance (EU AI Act, LGPD, HIPAA) | Deterministic (same input → same output), per-document audit trail. |
hybrid=True or speed=True.search_exact scan is faster and simpler.| Use case | Best tool | Why |
|---|---|---|
| Minimum latency (sub-ms, high QPS) | Well-tuned HNSW / IVF | Speed |
| Fast exact scan | Madhava speed GPU | Exact + accelerated |
| Completeness proof / audit | winnex-madhava (bound) | Only one with per-document proof |
| Frequent rebuild / streaming / dynamic RAG | winnex-madhava | 10–1000× faster build |
| Very uniform data / latency-critical | HNSW or simple exact scan | Bound loses efficiency |
Conclusion: winnex-madhava is engineered by the Winnex technical team around a single design principle: mathematical certainty. The Cauchy-Schwarz + QR mathematics, the C++ implementation, and the corrected benchmark methodology all serve that principle — and the 0 bound-violation guarantee holds by construction.
It is not a universal replacement for every index: for pure sub-ms latency with acceptable approximation, an approximate index is the right tool. winnex-madhava is the right tool wherever proof matters — when you must show you did not miss a relevant document, or when the index must be rebuilt continuously.
In the end, it comes back to the truck: the race car wins the lap, the truck carries the cargo. winnex-madhava does not race HNSW on the speed track — it carries the guarantee and the fast rebuild that the race car physically cannot. In a regulated environment, that cargo is not optional: it is the difference between a defensible answer and a fine.