keo 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. keo-0.1.0/.gitignore +25 -0
  2. keo-0.1.0/LICENSE +21 -0
  3. keo-0.1.0/PKG-INFO +186 -0
  4. keo-0.1.0/README.md +166 -0
  5. keo-0.1.0/assets/logo.svg +42 -0
  6. keo-0.1.0/configs/datasets/glove100.yaml +25 -0
  7. keo-0.1.0/configs/experiments/smoke.yaml +18 -0
  8. keo-0.1.0/pyproject.toml +47 -0
  9. keo-0.1.0/src/keo/__init__.py +3 -0
  10. keo-0.1.0/src/keo/algos/__init__.py +6 -0
  11. keo-0.1.0/src/keo/algos/adapters/__init__.py +0 -0
  12. keo-0.1.0/src/keo/algos/adapters/_faiss_worker.py +163 -0
  13. keo-0.1.0/src/keo/algos/adapters/_worker_client.py +64 -0
  14. keo-0.1.0/src/keo/algos/adapters/faiss_cpu.py +84 -0
  15. keo-0.1.0/src/keo/algos/adapters/faiss_official.py +120 -0
  16. keo-0.1.0/src/keo/algos/adapters/flash_kmeans.py +76 -0
  17. keo-0.1.0/src/keo/algos/adapters/registry.py +57 -0
  18. keo-0.1.0/src/keo/algos/base.py +40 -0
  19. keo-0.1.0/src/keo/algos/emeans.py +324 -0
  20. keo-0.1.0/src/keo/algos/init.py +25 -0
  21. keo-0.1.0/src/keo/algos/ivf_cells.py +190 -0
  22. keo-0.1.0/src/keo/algos/laws.py +110 -0
  23. keo-0.1.0/src/keo/algos/lloyd.py +154 -0
  24. keo-0.1.0/src/keo/algos/omeans.py +181 -0
  25. keo-0.1.0/src/keo/algos/revival.py +105 -0
  26. keo-0.1.0/src/keo/analysis/__init__.py +3 -0
  27. keo-0.1.0/src/keo/analysis/figures.py +659 -0
  28. keo-0.1.0/src/keo/bench/__init__.py +7 -0
  29. keo-0.1.0/src/keo/bench/experiment.py +214 -0
  30. keo-0.1.0/src/keo/bench/provenance.py +33 -0
  31. keo-0.1.0/src/keo/bench/runner.py +328 -0
  32. keo-0.1.0/src/keo/bench/schema.py +79 -0
  33. keo-0.1.0/src/keo/bench/store.py +78 -0
  34. keo-0.1.0/src/keo/cli.py +256 -0
  35. keo-0.1.0/src/keo/config.py +114 -0
  36. keo-0.1.0/src/keo/data/__init__.py +13 -0
  37. keo-0.1.0/src/keo/data/download.py +131 -0
  38. keo-0.1.0/src/keo/data/prep.py +150 -0
  39. keo-0.1.0/src/keo/metrics/__init__.py +3 -0
  40. keo-0.1.0/src/keo/metrics/core.py +82 -0
  41. keo-0.1.0/src/keo/paths.py +40 -0
  42. keo-0.1.0/src/keo/runtime.py +58 -0
  43. keo-0.1.0/tests/test_adapters.py +136 -0
  44. keo-0.1.0/tests/test_bench.py +325 -0
  45. keo-0.1.0/tests/test_config.py +70 -0
  46. keo-0.1.0/tests/test_download_and_cli.py +93 -0
  47. keo-0.1.0/tests/test_emeans.py +152 -0
  48. keo-0.1.0/tests/test_figures.py +238 -0
  49. keo-0.1.0/tests/test_gate_phase2.py +50 -0
  50. keo-0.1.0/tests/test_gate_phase3.py +56 -0
  51. keo-0.1.0/tests/test_gate_phase4.py +71 -0
  52. keo-0.1.0/tests/test_gate_phase5.py +71 -0
  53. keo-0.1.0/tests/test_glove_real.py +31 -0
  54. keo-0.1.0/tests/test_ivf_cells.py +174 -0
  55. keo-0.1.0/tests/test_laws.py +82 -0
  56. keo-0.1.0/tests/test_lloyd.py +140 -0
  57. keo-0.1.0/tests/test_metrics.py +56 -0
  58. keo-0.1.0/tests/test_omeans.py +184 -0
  59. keo-0.1.0/tests/test_prep.py +70 -0
  60. keo-0.1.0/tests/test_revival.py +99 -0
keo-0.1.0/.gitignore ADDED
@@ -0,0 +1,25 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ .pytest_cache/
5
+ .coverage
6
+ htmlcov/
7
+ dist/
8
+ build/
9
+ *.egg-info/
10
+ .DS_Store
11
+
12
+ # documentation and source papers: kept locally, not committed
13
+ /docs/
14
+
15
+ # data files: downloaded datasets and stored result rows (large / regenerable)
16
+ /data/
17
+ *.hdf5
18
+ *.h5
19
+ *.npy
20
+ *.npz
21
+ *.parquet
22
+ results/**/rows/
23
+ results/cache/
24
+ RELEASING.md
25
+
keo-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rajveer Rathod
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
keo-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,186 @@
1
+ Metadata-Version: 2.5
2
+ Name: keo
3
+ Version: 0.1.0
4
+ Summary: KEO: reproducible benchmark of K-means (Lloyd), E-means and O-means
5
+ License: MIT
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.10
8
+ Requires-Dist: faiss-cpu>=1.8
9
+ Requires-Dist: h5py>=3.10
10
+ Requires-Dist: matplotlib>=3.8
11
+ Requires-Dist: numpy>=1.26
12
+ Requires-Dist: pandas>=2.1
13
+ Requires-Dist: pyarrow>=14
14
+ Requires-Dist: pyyaml>=6
15
+ Requires-Dist: scikit-learn>=1.4
16
+ Requires-Dist: scipy>=1.11
17
+ Requires-Dist: torch>=2.2
18
+ Requires-Dist: typer>=0.12
19
+ Description-Content-Type: text/markdown
20
+
21
+ <p align="center">
22
+ <img src="https://raw.githubusercontent.com/rajveer43/keo/main/assets/logo.svg" alt="KEO logo: a ninja cat above three clusters of dots, next to the letters K, E, O" width="420">
23
+ </p>
24
+
25
+ # KEO
26
+
27
+ **A reproducible benchmark of k-means, e-means and o-means on data neither method was evaluated on.**
28
+
29
+ **What KEO stands for.** KEO is named after Keo, the ninja cat from the *Ninja Hattori* cartoon series, and it spells out the three clustering algorithms the framework compares: **K**-means, **E**-means and **O**-means. In the logo, the masked ninja cat stands over three clusters of points, each with its centroid ringed, and the letters K, E and O use one colour per algorithm, the same colours as every figure.
30
+
31
+ KEO compares three large-scale clustering algorithms under one protocol, one set of metrics and one result store, and tests whether the headline claims of the e-means and o-means papers hold outside the datasets they were developed on.
32
+
33
+ | | Algorithm | Summary | Source |
34
+ |---|---|---|---|
35
+ | **K** | k-means (Lloyd) | Full-batch alternation of exact assignment and centroid mean update. | Lloyd (1982) |
36
+ | **E** | e-means | Mini-batch k-means with exponential-moving-average updates, a cosine step schedule, scaling laws for batch size and step size, and dead-cluster revival. Reported to match Lloyd in a fraction of the epochs. | Bessa et al., Meta FAIR, 2026 |
37
+ | **O** | o-means | e-means with a two-level inverted-file index built over the centroids, so each point is compared with a small subset of them instead of all `k`. | Bajaj, Nupur, Garg, 2026 |
38
+
39
+ ## Contents
40
+
41
+ - [Research question](#research-question)
42
+ - [Dataset](#dataset)
43
+ - [Installation](#installation)
44
+ - [Quick start](#quick-start)
45
+ - [Method](#method)
46
+ - [Project status](#project-status)
47
+ - [Limitations](#limitations)
48
+ - [Documentation](#documentation)
49
+ - [Repository layout](#repository-layout)
50
+ - [References](#references)
51
+
52
+ ## Research question
53
+
54
+ Do the reported gains of e-means (matching k-means quality in roughly 1.4–2.6 epochs) and o-means (further reducing assignment cost as `k` grows) hold on a dataset that was not used to design or tune them, and under what conditions do they break down?
55
+
56
+ ## Dataset
57
+
58
+ **GloVe-100**: 1,183,514 word vectors in 100 dimensions, with 10,000 provided query vectors, taken from ANN-Benchmarks (`glove-100-angular`). It appears in neither paper's list of evaluation datasets (checked against those two papers only). Vectors are L2-normalised by default. The download is checksum-verified (SHA-256).
59
+
60
+ ## Installation
61
+
62
+ Requires Python 3.10 or newer (developed and tested on 3.12).
63
+
64
+ ```bash
65
+ pip install keo
66
+ ```
67
+
68
+ To work on the code, clone the repository and use [uv](https://docs.astral.sh/uv/):
69
+
70
+ ```bash
71
+ git clone https://github.com/rajveer43/keo.git
72
+ cd keo
73
+ uv sync
74
+ ```
75
+
76
+ ## Quick start
77
+
78
+ ```bash
79
+ keo download glove100 # ~460 MB, checksum-verified
80
+ keo smoke # end-to-end run on a small subset, about 10 seconds
81
+ keo figures smoke # figures in results/smoke/figures/
82
+ keo adapters # which official implementations can run on this machine
83
+ ```
84
+
85
+ From a source checkout, prefix commands with `uv run` and run the tests with `uv run pytest`.
86
+
87
+ Where files go: in a source checkout, `data/` and `results/` sit next to the code. After `pip install`, datasets are cached in `~/.cache/keo/data` and results are written to `./results` in the directory you run from. Set `KEO_DATA_DIR`, `KEO_RESULTS_DIR` or `KEO_CONFIGS_DIR` to override.
88
+
89
+ Run a configured experiment, or preview it first:
90
+
91
+ ```bash
92
+ keo run <name-or-path.yaml> --dry-run
93
+ keo run <name-or-path.yaml>
94
+ keo status <name>
95
+ keo figures <name> --theme both
96
+ ```
97
+
98
+ Each result cell is stored under a content hash of its configuration, so an interrupted run resumes where it stopped and completed cells are never recomputed.
99
+
100
+ ## Method
101
+
102
+ **Two implementations, never mixed.** Every algorithm exists twice:
103
+
104
+ - `reference`: our own PyTorch (CPU) implementation, written from the papers.
105
+ - `official`: the authors' released code (Faiss `contrib/e_means` and related adapters), run in an isolated worker process.
106
+
107
+ Each result row records which one produced it. Quality is compared across both; wall-clock time is compared only within one implementation.
108
+
109
+ **Metrics.**
110
+
111
+ - MSE: mean squared L2 distance to the assigned centroid, computed with exact assignment in float64, on both training and held-out points.
112
+ - Relative MSE (the *gap*): error relative to k-means run for 25 iterations from the same starting centroids and seed.
113
+ - Cluster health: dead clusters (fewer than 10 points), empty clusters, and the Faiss imbalance factor.
114
+ - Cost: counted distance computations, split into assignment and index maintenance, reported both as actually performed and as the nominal cell arithmetic. This is hardware independent.
115
+ - Wall-clock fit time, within one implementation only.
116
+
117
+ **e-means recipe.** `recipe="official"` (default) uses the constants shipped in the official code; `recipe="paper"` uses the values in the paper text. The two differ slightly. All headline results use `official`.
118
+
119
+ **Figures.** Six figures are generated from the stored result rows, each with a CSV of exactly the plotted numbers and a light and dark variant. Headlines are computed from the data rather than written by hand. See [docs/FIGURES.md](docs/FIGURES.md).
120
+
121
+ ## Project status
122
+
123
+ | Phase | Scope | State |
124
+ |---|---|---|
125
+ | 0–2 | Specification, data pipeline, metrics, k-means | Complete |
126
+ | 3–4 | e-means and o-means reference implementations | Complete |
127
+ | 5 | Adapters for the official implementations | Complete |
128
+ | 6 | Result store, resumable runner, figures | Complete |
129
+ | 7 | Main run on the full grid | Not started |
130
+ | 8 | Analysis and report (`keo analyze`, `keo report`) | Not started; commands are stubs |
131
+ | 9 | Ablations, scaling-law transfer, secondary track | Not started |
132
+ | 10 | Hardening and packaging | Not started |
133
+
134
+ The test suite has 179 tests, all passing. The `smoke` experiment (26 cells) runs cleanly end to end.
135
+
136
+ **Implementation agreement.** On GloVe subsets, our e-means matches the official implementation within about 0.2% on held-out error. The remainder is most likely remainder-batch handling (see assumptions A2 and A52 in [docs/ASSUMPTIONS.md](docs/ASSUMPTIONS.md)); this has not been isolated.
137
+
138
+ **No benchmark results are claimed yet.** Numbers visible in `results/smoke/` come from two repeats at `k = 512` and exist to verify the pipeline, not to answer the research question.
139
+
140
+ ## Limitations
141
+
142
+ - **o-means is partly reconstructed.** Its paper is unreleased, so our version is built from the project page and every unspecified detail is a recorded assumption. Conclusions about o-means describe this reconstruction.
143
+ - **No GPU in the reference environment.** Wall-clock claims from the papers concern GPU execution and cannot be tested on the development machine (Apple M4, CPU only). Quality and operation counts can be.
144
+ - **CPU time is not representative for o-means.** Index maintenance is cheap on a GPU and relatively costly on a CPU, so CPU wall-clock should not be read as a verdict on the method.
145
+ - **One dataset so far.** Findings are about GloVe-100 and will not necessarily transfer.
146
+ - **Dataset novelty is a bounded claim.** GloVe-100 was checked against the two papers' dataset lists, not against all prior work.
147
+
148
+ ## License
149
+
150
+ Code is released under the [MIT License](LICENSE). The GloVe vectors are not redistributed; they are downloaded from ANN-Benchmarks and remain under their own terms.
151
+
152
+ ## Documentation
153
+
154
+ | File | Contents |
155
+ |---|---|
156
+ | [docs/SPEC.md](docs/SPEC.md) | Algorithms, formulas and experimental protocol, tied to the source papers |
157
+ | [docs/ASSUMPTIONS.md](docs/ASSUMPTIONS.md) | Register of every point where the papers were silent, and the decision taken |
158
+ | [docs/FIGURES.md](docs/FIGURES.md) | What each figure answers, how it is built, and the palette validation record |
159
+ | [docs/MASTER_PROMPT.md](docs/MASTER_PROMPT.md) | The original build brief (archived; has since diverged) |
160
+
161
+ `docs/` is excluded from version control (see `.gitignore`) and is kept locally.
162
+
163
+ ## Repository layout
164
+
165
+ ```
166
+ configs/ Dataset and experiment definitions (YAML)
167
+ src/keo/
168
+ algos/ k-means, e-means, o-means, scaling laws, revival, IVF cells; adapters/ for official code
169
+ bench/ Experiment schema, resumable runner, result store, provenance
170
+ metrics/ MSE, gap, cluster health, operation counting
171
+ analysis/ Figure generation
172
+ data/ Download, verification, preparation
173
+ tests/ Unit tests and per-phase gate tests
174
+ results/ Run outputs (smoke, exploratory)
175
+ docs/ Specification, assumptions, figure guide (local only)
176
+ ```
177
+
178
+ ## References
179
+
180
+ - **e-means**: Bessa et al., *e-means: outperforming k-means (in one-tenth the epochs)*. [arXiv:2611.09501](https://arxiv.org/abs/2611.09501) · [project page](https://e-means.github.io) · code in Faiss `contrib/e_means`
181
+ - **o-means**: Bajaj, Nupur, Garg, *o-means: index the centroids, don't scan them*. Project page, November 2026; paper not yet released.
182
+ - **Flash-KMeans** (GPU k-means baseline): [arXiv:2603.09229](https://arxiv.org/abs/2603.09229)
183
+ - **Faiss**: Douze et al., *The Faiss library*. [arXiv:2401.08281](https://arxiv.org/abs/2401.08281)
184
+ - **VQ-VAE** (origin of the moving-average update): van den Oord et al. [arXiv:1711.00937](https://arxiv.org/abs/1711.00937)
185
+ - **ANN-Benchmarks**: Aumüller et al. [arXiv:1807.05614](https://arxiv.org/abs/1807.05614) · **GloVe**: Pennington et al. [nlp.stanford.edu/projects/glove](https://nlp.stanford.edu/projects/glove/) · **VIBE**: [arXiv:2505.17810](https://arxiv.org/abs/2505.17810)
186
+ - **Classics**: Lloyd (1982); Arthur and Vassilvitskii, *k-means++* (2007); Sculley, *Web-scale k-means clustering* (2010)
keo-0.1.0/README.md ADDED
@@ -0,0 +1,166 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/rajveer43/keo/main/assets/logo.svg" alt="KEO logo: a ninja cat above three clusters of dots, next to the letters K, E, O" width="420">
3
+ </p>
4
+
5
+ # KEO
6
+
7
+ **A reproducible benchmark of k-means, e-means and o-means on data neither method was evaluated on.**
8
+
9
+ **What KEO stands for.** KEO is named after Keo, the ninja cat from the *Ninja Hattori* cartoon series, and it spells out the three clustering algorithms the framework compares: **K**-means, **E**-means and **O**-means. In the logo, the masked ninja cat stands over three clusters of points, each with its centroid ringed, and the letters K, E and O use one colour per algorithm, the same colours as every figure.
10
+
11
+ KEO compares three large-scale clustering algorithms under one protocol, one set of metrics and one result store, and tests whether the headline claims of the e-means and o-means papers hold outside the datasets they were developed on.
12
+
13
+ | | Algorithm | Summary | Source |
14
+ |---|---|---|---|
15
+ | **K** | k-means (Lloyd) | Full-batch alternation of exact assignment and centroid mean update. | Lloyd (1982) |
16
+ | **E** | e-means | Mini-batch k-means with exponential-moving-average updates, a cosine step schedule, scaling laws for batch size and step size, and dead-cluster revival. Reported to match Lloyd in a fraction of the epochs. | Bessa et al., Meta FAIR, 2026 |
17
+ | **O** | o-means | e-means with a two-level inverted-file index built over the centroids, so each point is compared with a small subset of them instead of all `k`. | Bajaj, Nupur, Garg, 2026 |
18
+
19
+ ## Contents
20
+
21
+ - [Research question](#research-question)
22
+ - [Dataset](#dataset)
23
+ - [Installation](#installation)
24
+ - [Quick start](#quick-start)
25
+ - [Method](#method)
26
+ - [Project status](#project-status)
27
+ - [Limitations](#limitations)
28
+ - [Documentation](#documentation)
29
+ - [Repository layout](#repository-layout)
30
+ - [References](#references)
31
+
32
+ ## Research question
33
+
34
+ Do the reported gains of e-means (matching k-means quality in roughly 1.4–2.6 epochs) and o-means (further reducing assignment cost as `k` grows) hold on a dataset that was not used to design or tune them, and under what conditions do they break down?
35
+
36
+ ## Dataset
37
+
38
+ **GloVe-100**: 1,183,514 word vectors in 100 dimensions, with 10,000 provided query vectors, taken from ANN-Benchmarks (`glove-100-angular`). It appears in neither paper's list of evaluation datasets (checked against those two papers only). Vectors are L2-normalised by default. The download is checksum-verified (SHA-256).
39
+
40
+ ## Installation
41
+
42
+ Requires Python 3.10 or newer (developed and tested on 3.12).
43
+
44
+ ```bash
45
+ pip install keo
46
+ ```
47
+
48
+ To work on the code, clone the repository and use [uv](https://docs.astral.sh/uv/):
49
+
50
+ ```bash
51
+ git clone https://github.com/rajveer43/keo.git
52
+ cd keo
53
+ uv sync
54
+ ```
55
+
56
+ ## Quick start
57
+
58
+ ```bash
59
+ keo download glove100 # ~460 MB, checksum-verified
60
+ keo smoke # end-to-end run on a small subset, about 10 seconds
61
+ keo figures smoke # figures in results/smoke/figures/
62
+ keo adapters # which official implementations can run on this machine
63
+ ```
64
+
65
+ From a source checkout, prefix commands with `uv run` and run the tests with `uv run pytest`.
66
+
67
+ Where files go: in a source checkout, `data/` and `results/` sit next to the code. After `pip install`, datasets are cached in `~/.cache/keo/data` and results are written to `./results` in the directory you run from. Set `KEO_DATA_DIR`, `KEO_RESULTS_DIR` or `KEO_CONFIGS_DIR` to override.
68
+
69
+ Run a configured experiment, or preview it first:
70
+
71
+ ```bash
72
+ keo run <name-or-path.yaml> --dry-run
73
+ keo run <name-or-path.yaml>
74
+ keo status <name>
75
+ keo figures <name> --theme both
76
+ ```
77
+
78
+ Each result cell is stored under a content hash of its configuration, so an interrupted run resumes where it stopped and completed cells are never recomputed.
79
+
80
+ ## Method
81
+
82
+ **Two implementations, never mixed.** Every algorithm exists twice:
83
+
84
+ - `reference`: our own PyTorch (CPU) implementation, written from the papers.
85
+ - `official`: the authors' released code (Faiss `contrib/e_means` and related adapters), run in an isolated worker process.
86
+
87
+ Each result row records which one produced it. Quality is compared across both; wall-clock time is compared only within one implementation.
88
+
89
+ **Metrics.**
90
+
91
+ - MSE: mean squared L2 distance to the assigned centroid, computed with exact assignment in float64, on both training and held-out points.
92
+ - Relative MSE (the *gap*): error relative to k-means run for 25 iterations from the same starting centroids and seed.
93
+ - Cluster health: dead clusters (fewer than 10 points), empty clusters, and the Faiss imbalance factor.
94
+ - Cost: counted distance computations, split into assignment and index maintenance, reported both as actually performed and as the nominal cell arithmetic. This is hardware independent.
95
+ - Wall-clock fit time, within one implementation only.
96
+
97
+ **e-means recipe.** `recipe="official"` (default) uses the constants shipped in the official code; `recipe="paper"` uses the values in the paper text. The two differ slightly. All headline results use `official`.
98
+
99
+ **Figures.** Six figures are generated from the stored result rows, each with a CSV of exactly the plotted numbers and a light and dark variant. Headlines are computed from the data rather than written by hand. See [docs/FIGURES.md](docs/FIGURES.md).
100
+
101
+ ## Project status
102
+
103
+ | Phase | Scope | State |
104
+ |---|---|---|
105
+ | 0–2 | Specification, data pipeline, metrics, k-means | Complete |
106
+ | 3–4 | e-means and o-means reference implementations | Complete |
107
+ | 5 | Adapters for the official implementations | Complete |
108
+ | 6 | Result store, resumable runner, figures | Complete |
109
+ | 7 | Main run on the full grid | Not started |
110
+ | 8 | Analysis and report (`keo analyze`, `keo report`) | Not started; commands are stubs |
111
+ | 9 | Ablations, scaling-law transfer, secondary track | Not started |
112
+ | 10 | Hardening and packaging | Not started |
113
+
114
+ The test suite has 179 tests, all passing. The `smoke` experiment (26 cells) runs cleanly end to end.
115
+
116
+ **Implementation agreement.** On GloVe subsets, our e-means matches the official implementation within about 0.2% on held-out error. The remainder is most likely remainder-batch handling (see assumptions A2 and A52 in [docs/ASSUMPTIONS.md](docs/ASSUMPTIONS.md)); this has not been isolated.
117
+
118
+ **No benchmark results are claimed yet.** Numbers visible in `results/smoke/` come from two repeats at `k = 512` and exist to verify the pipeline, not to answer the research question.
119
+
120
+ ## Limitations
121
+
122
+ - **o-means is partly reconstructed.** Its paper is unreleased, so our version is built from the project page and every unspecified detail is a recorded assumption. Conclusions about o-means describe this reconstruction.
123
+ - **No GPU in the reference environment.** Wall-clock claims from the papers concern GPU execution and cannot be tested on the development machine (Apple M4, CPU only). Quality and operation counts can be.
124
+ - **CPU time is not representative for o-means.** Index maintenance is cheap on a GPU and relatively costly on a CPU, so CPU wall-clock should not be read as a verdict on the method.
125
+ - **One dataset so far.** Findings are about GloVe-100 and will not necessarily transfer.
126
+ - **Dataset novelty is a bounded claim.** GloVe-100 was checked against the two papers' dataset lists, not against all prior work.
127
+
128
+ ## License
129
+
130
+ Code is released under the [MIT License](LICENSE). The GloVe vectors are not redistributed; they are downloaded from ANN-Benchmarks and remain under their own terms.
131
+
132
+ ## Documentation
133
+
134
+ | File | Contents |
135
+ |---|---|
136
+ | [docs/SPEC.md](docs/SPEC.md) | Algorithms, formulas and experimental protocol, tied to the source papers |
137
+ | [docs/ASSUMPTIONS.md](docs/ASSUMPTIONS.md) | Register of every point where the papers were silent, and the decision taken |
138
+ | [docs/FIGURES.md](docs/FIGURES.md) | What each figure answers, how it is built, and the palette validation record |
139
+ | [docs/MASTER_PROMPT.md](docs/MASTER_PROMPT.md) | The original build brief (archived; has since diverged) |
140
+
141
+ `docs/` is excluded from version control (see `.gitignore`) and is kept locally.
142
+
143
+ ## Repository layout
144
+
145
+ ```
146
+ configs/ Dataset and experiment definitions (YAML)
147
+ src/keo/
148
+ algos/ k-means, e-means, o-means, scaling laws, revival, IVF cells; adapters/ for official code
149
+ bench/ Experiment schema, resumable runner, result store, provenance
150
+ metrics/ MSE, gap, cluster health, operation counting
151
+ analysis/ Figure generation
152
+ data/ Download, verification, preparation
153
+ tests/ Unit tests and per-phase gate tests
154
+ results/ Run outputs (smoke, exploratory)
155
+ docs/ Specification, assumptions, figure guide (local only)
156
+ ```
157
+
158
+ ## References
159
+
160
+ - **e-means**: Bessa et al., *e-means: outperforming k-means (in one-tenth the epochs)*. [arXiv:2611.09501](https://arxiv.org/abs/2611.09501) · [project page](https://e-means.github.io) · code in Faiss `contrib/e_means`
161
+ - **o-means**: Bajaj, Nupur, Garg, *o-means: index the centroids, don't scan them*. Project page, November 2026; paper not yet released.
162
+ - **Flash-KMeans** (GPU k-means baseline): [arXiv:2603.09229](https://arxiv.org/abs/2603.09229)
163
+ - **Faiss**: Douze et al., *The Faiss library*. [arXiv:2401.08281](https://arxiv.org/abs/2401.08281)
164
+ - **VQ-VAE** (origin of the moving-average update): van den Oord et al. [arXiv:1711.00937](https://arxiv.org/abs/1711.00937)
165
+ - **ANN-Benchmarks**: Aumüller et al. [arXiv:1807.05614](https://arxiv.org/abs/1807.05614) · **GloVe**: Pennington et al. [nlp.stanford.edu/projects/glove](https://nlp.stanford.edu/projects/glove/) · **VIBE**: [arXiv:2505.17810](https://arxiv.org/abs/2505.17810)
166
+ - **Classics**: Lloyd (1982); Arthur and Vassilvitskii, *k-means++* (2007); Sculley, *Web-scale k-means clustering* (2010)
@@ -0,0 +1,42 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 200" width="600" height="200" role="img" aria-labelledby="t d">
2
+ <title id="t">KEO logo</title>
3
+ <desc id="d">A ninja cat wearing an eye mask above three small clusters of dots, next to the letters K, E and O in blue, orange and green.</desc>
4
+ <defs>
5
+ <clipPath id="head">
6
+ <path d="M44 28 L84 54 Q100 50 116 54 L156 28 L162 88 Q162 132 100 138 Q38 132 38 88 Z"/>
7
+ </clipPath>
8
+ </defs>
9
+
10
+ <!-- plate: dark so the logo reads on light and dark pages -->
11
+ <rect width="600" height="200" rx="44" fill="#1a1a19"/>
12
+
13
+ <!-- ninja cat -->
14
+ <path d="M44 28 L84 54 Q100 50 116 54 L156 28 L162 88 Q162 132 100 138 Q38 132 38 88 Z" fill="#efeeea"/>
15
+ <path d="M52 40 L76 56 L56 66 Z M148 40 L124 56 L144 66 Z" fill="#d9d7d0"/>
16
+ <rect x="30" y="70" width="140" height="28" fill="#26262a" clip-path="url(#head)"/>
17
+ <path d="M58 84 Q72 73 86 84 Q72 95 58 84 Z M114 84 Q128 73 142 84 Q128 95 114 84 Z" fill="#fcfcfb"/>
18
+ <ellipse cx="72" cy="84" rx="2.6" ry="7" fill="#1a1a19"/>
19
+ <ellipse cx="128" cy="84" rx="2.6" ry="7" fill="#1a1a19"/>
20
+ <path d="M94 106 L106 106 L100 113 Z" fill="#eb6834"/>
21
+ <g fill="none" stroke="#1a1a19" stroke-width="2" stroke-linecap="round">
22
+ <path d="M100 113 Q100 121 92 121 M100 113 Q100 121 108 121"/>
23
+ <path d="M52 110 L78 112 M52 120 L78 117 M148 110 L122 112 M148 120 L122 117" stroke="#8a8984" stroke-width="1.6"/>
24
+ </g>
25
+
26
+ <!-- three clusters: centroid ring + member points -->
27
+ <g stroke-width="2" fill="none">
28
+ <circle cx="52" cy="168" r="6" stroke="#3987e5"/>
29
+ <circle cx="100" cy="168" r="6" stroke="#d95926"/>
30
+ <circle cx="148" cy="168" r="6" stroke="#199e70"/>
31
+ </g>
32
+ <g fill="#3987e5"><circle cx="40" cy="163" r="2.8"/><circle cx="63" cy="161" r="2.8"/><circle cx="46" cy="177" r="2.8"/><circle cx="62" cy="176" r="2.8"/></g>
33
+ <g fill="#d95926"><circle cx="88" cy="163" r="2.8"/><circle cx="111" cy="161" r="2.8"/><circle cx="94" cy="177" r="2.8"/><circle cx="110" cy="176" r="2.8"/></g>
34
+ <g fill="#199e70"><circle cx="136" cy="163" r="2.8"/><circle cx="159" cy="161" r="2.8"/><circle cx="142" cy="177" r="2.8"/><circle cx="158" cy="176" r="2.8"/></g>
35
+
36
+ <!-- K E O: one colour per algorithm, drawn as paths so no font is needed -->
37
+ <g transform="translate(20 0)" fill="none" stroke-width="16" stroke-linecap="round" stroke-linejoin="round">
38
+ <path d="M246 52 V148 M298 52 L246 100 L300 148" stroke="#3987e5"/>
39
+ <path d="M388 52 H340 V148 H388 M340 100 H378" stroke="#d95926"/>
40
+ <circle cx="466" cy="100" r="48" stroke="#199e70"/>
41
+ </g>
42
+ </svg>
@@ -0,0 +1,25 @@
1
+ # Track A (primary) dataset. Not used by either source paper (see README section 2).
2
+ name: glove100
3
+ description: GloVe-100 word embeddings (ann-benchmarks, angular)
4
+ source:
5
+ type: url
6
+ url: http://ann-benchmarks.com/glove-100-angular.hdf5
7
+ filename: glove-100-angular.hdf5
8
+ format: hdf5
9
+ train_key: train
10
+ eval_key: test
11
+ # Trust-on-first-use: ann-benchmarks publishes no checksum. Pinned from the first download
12
+ # on 2026-11-16 (see docs/ASSUMPTIONS.md A31). Empty string = not pinned yet.
13
+ sha256: "544af1d5e84e112cd4749571dcfd8ca109818a572f850af75a3a09e093a953c4"
14
+ expected_bytes: 485413888
15
+ d: 100
16
+ n_train: 1183514
17
+ n_eval: 10000
18
+ normalize: true # L2-normalise (A24); verified/decided after `keo data-info`
19
+ split:
20
+ val_fraction: 0.5 # provided queries -> val/test (A25)
21
+ seed: 0
22
+ # Experiment defaults (consumed from Phase 6 on)
23
+ k_grid: [4096, 16384, 32768]
24
+ n_subset_grid: [100000, 300000, 1000000, null] # null = full train
25
+ min_points_per_cluster: 8 # keep n/k >= 8 [E App. B.1]
@@ -0,0 +1,18 @@
1
+ # Smoke test: GloVe-100 subset, tiny grid, CPU only, must finish in < 5 minutes (Phase 6 gate).
2
+ # o-means uses cell_size 8 here (k=512 with the default 128 would give nlist = nprobe = 16 = exact search; A42).
3
+ name: smoke
4
+ dataset: glove100
5
+ n: [50000]
6
+ k: [512]
7
+ seeds: [0, 1]
8
+ baseline_iterations: 25
9
+ warmup: true
10
+ train_eval_subset: null
11
+ runs:
12
+ - {algo: lloyd, backend: reference, budgets: [1, 2, 3, 5, 10, 25]}
13
+ - {algo: emeans, backend: reference, budgets: [1, 2]}
14
+ - {algo: omeans, backend: reference, budgets: [1, 2], params: {cell_size: 8}}
15
+ # official implementations: run when available, otherwise listed in skipped.json with the reason
16
+ - {algo: lloyd, backend: official, budgets: [25]}
17
+ - {algo: emeans, backend: official, budgets: [1, 2]}
18
+ - {algo: omeans, backend: official, budgets: [1, 2]}
@@ -0,0 +1,47 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.21"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "keo"
7
+ version = "0.1.0"
8
+ description = "KEO: reproducible benchmark of K-means (Lloyd), E-means and O-means"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { text = "MIT" }
12
+ dependencies = [
13
+ "numpy>=1.26",
14
+ "scipy>=1.11",
15
+ "scikit-learn>=1.4",
16
+ "torch>=2.2",
17
+ "pandas>=2.1",
18
+ "pyarrow>=14",
19
+ "h5py>=3.10",
20
+ "pyyaml>=6",
21
+ "matplotlib>=3.8",
22
+ "typer>=0.12",
23
+ "faiss-cpu>=1.8",
24
+ ]
25
+
26
+ [project.scripts]
27
+ keo = "keo.cli:app"
28
+
29
+ [dependency-groups]
30
+ dev = ["pytest>=8", "pytest-cov>=5"]
31
+
32
+ [tool.hatch.build.targets.sdist]
33
+ include = ["src", "tests", "configs", "assets/logo.svg", "README.md", "pyproject.toml", "LICENSE"]
34
+
35
+ [tool.hatch.build.targets.wheel]
36
+ packages = ["src/keo"]
37
+
38
+ [tool.hatch.build.targets.wheel.force-include]
39
+ "configs" = "keo/_configs"
40
+
41
+ [tool.pytest.ini_options]
42
+ testpaths = ["tests"]
43
+ addopts = "-q"
44
+ markers = [
45
+ "data: needs the downloaded dataset files (skipped if absent)",
46
+ "slow: long-running test",
47
+ ]
@@ -0,0 +1,3 @@
1
+ """KEO: benchmark of K-means (Lloyd), E-means and O-means."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,6 @@
1
+ from keo.algos.base import Budget, Clusterer, FitResult
2
+ from keo.algos.emeans import EMeans
3
+ from keo.algos.lloyd import Lloyd
4
+ from keo.algos.omeans import OMeans
5
+
6
+ __all__ = ["Budget", "Clusterer", "EMeans", "FitResult", "Lloyd", "OMeans"]
File without changes