Upload README.md with huggingface_hub

README.md

@@ -19,6 +19,24 @@ Search projections for ANN-substituted attention on
 
 Code: [github.com/unixsysdev/ann-sparseattention](https://github.com/unixsysdev/ann-sparseattention)
 
+## Current status
+
+Research prototype. Trained projections work, runtime is a correctness
+prototype, eval envelope is narrow. Treat reported numbers as preliminary.
+
+**Validated:** 6-layer pilot on Qwen3-4B-Instruct-2507; WikiText-103 PPL
+preserved at K=128 (gap ≈ +0.7%); learned projections retrieve attention-
+relevant keys.
+
+**Not yet validated:** 34-layer / whole-model substitution; long-context
+tasks (LongBench, RULER, needle); wall-clock speedup vs FlashAttention/SDPA;
+KV-cache decode-mode integration; GPU-resident ANN kernel.
+
+**Runtime caveat:** the FAISS path here builds CPU indexes per batch and
+the gather step uses dense-style tensor expansion. Compute-reduction
+numbers below are *algorithmic scoring reductions, not measured wall-clock
+speedups.*
+
 ## What's in this repo
 
 Per-layer linear search projections `(W_Qs, W_Ks)` of shape `[2560, 64]`,
@@ -56,19 +74,18 @@ on positions 30-128 is on near-zero-weight tail and doesn't affect output.
 | 256 | 31.6% | 9.88 | **−0.79%** |
 | 512 | 40.8% | 9.67 | **−2.89%** |
 
-**ANN at K ≥ 256 produces lower perplexity than full attention** — the
-sparse-attention denoising effect. Full softmax is forced to spread small
-amounts of weight over a long tail of irrelevant keys; truncating to top-K
-and renormalizing puts the weight where it matters.
-
-The novelty is not "ANN beats attention" (denoising is a property of any
-hard top-K selection over softmax, see Top-k Attention / Reformer). What's
-distinctive is that this method produces the denoised top-K at *sub-linear
-cost* via off-the-shelf FAISS HNSW, vs. computing all `O(L²)` scores first.
-
-Sanity checks pass: same input sequences for `ppl_full` vs `ppl_ann`,
-intact causal mask in retrieval, single-softmax renormalization with no
-wrapper leakage between iterations.
+On this small WikiText slice, K ≥ 256 produced lower measured PPL than
+the full-attention reference. A plausible explanation is sparse-softmax
+denoising, but with 12 eval batches, sample noise, packed-boundary artifacts
+(pilot trained with packing on; default in the repo is now off), and
+partial-layer substitution acting like regularization are also candidates.
+Treating it as a hypothesis to confirm via an exact-topK oracle (full QK^T
+→ top-K → restricted attention) at the same K — that separates "denoising
+from any sparsity" from "denoising from learned projections."
+
+Code-level sanity checks pass: same input sequences for `ppl_full` vs
+`ppl_ann`, intact causal mask in retrieval, single softmax over retrieved
+K with no wrapper leakage between iterations.
 
 ### Compute / quality knobs (FLOP-counted)