fastumap 0.1.6__tar.gz

fastumap-0.1.6/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build artifacts
+/dist/
+/build/
+/site/
+/public/
+
+# uv / venv
+.venv/
+uv.lock.bak
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.moon/cache/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+
+# Local session logs
+logs/
+
+# Cached benchmark datasets (MNIST etc.)
+/bench/data/
+
+# Local agent wiring: names the cabildo issues MCP, not a package dependency.
+# docs/issues/ IS tracked — the register is plain markdown.
+.mcp.json
+.claude/

fastumap-0.1.6/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to fastumap are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and versions follow SemVer.
+
+## [Unreleased]
+
+## [0.1.6] - 2026-08-23
+
+### Changed
+- Sparse input decision (#16): **not supported**. `umap_project`/`fit`/`transform` take a
+  dense numpy array; a `scipy.sparse` matrix now raises a clear `TypeError` pointing to
+  `.toarray()` instead of a cryptic failure. Rationale documented in README ("Sparse
+  input"): the blocked kNN uses dense BLAS matmul and the target workload is dense
+  encoder/CLS embeddings. Revisit if a sparse workload actually appears.
+
+## [0.1.5] - 2026-08-23
+
+### Added
+- `fit()` → `UMAPModel` and `transform(model, new)` (roadmap #13): place new points into an
+  existing layout without refitting — what makes a drift view incremental instead of a full
+  recompute per request. New points get their neighbours in the training set (`knn_between`),
+  a membership-weighted-average seed, then a fixed-tail optimiser (`optimize_transform`) that
+  moves only the new points while the training layout stays frozen. Deterministic, does not
+  mutate the base layout, and lands new points near same-cluster training points (>0.8 in
+  the test). `umap_project` is now `fit(...).embedding`. `compute_membership` gains
+  `exclude_self` (off for transform, where neighbours come from a different set).
+
+## [0.1.4] - 2026-08-23
+
+### Added
+- `metric="cosine"` on `umap_project` / `spectral_project` (roadmap #14) — the metric that
+  matters for text/CLS embeddings. Implemented as a blocked-brute-force cosine kNN
+  (`knn_cosine`): L2-normalise rows once, then the block dot product is cosine similarity,
+  distance = 1 − sim. Deterministic. A test shows it beats euclidean on directional
+  clusters (same direction, magnitudes spanning 0.1–10). `knn`/`knn_cosine` are the new
+  neighbour entry points; an unknown metric raises `ValueError`.
+
+## [0.1.3] - 2026-08-23
+
+### Changed
+- `optimize_layout` scatter: replace `np.add.at` with one per-dimension `np.bincount`
+  reduction (#19). ~31% faster at n=1000×1024 (7.7s → 5.3s single-thread), ~19% at
+  n=5000 (39.5s → 32.1s). overlap@15 unchanged within noise (n=1000 0.2338 → 0.2331,
+  n=2000 0.1387 → 0.1381); determinism preserved. Bytes differ from 0.1.2 (bincount sums
+  in a different float order), which is expected and does not affect quality.
+
+## [0.1.2] - 2026-08-23
+
+### Fixed
+- `compute_membership`: clamp the exponent argument at 0 before `np.exp` so the discarded
+  `np.where` branch no longer raises `overflow encountered in exp` at scale. Output is
+  value-identical (only the masked-out branch changed); determinism preserved.
+
+### Added
+- Peak-RSS ceiling test (roadmap #9): a subprocess measures peak RSS for a 5000 × 1024 fit
+  and asserts it stays under 200 MB. Measured ~102 MB added over the import+input baseline
+  (175 MB total peak), consistent with the 512-row blocked kNN never materialising n-by-n.
+
+## [0.1.1] - 2026-08-23
+
+### Added
+- `chunk_count` knob on `umap_project` / `optimize_layout` (roadmap #6). Default `1` keeps
+  the fast per-epoch snapshot update unchanged; higher values process each epoch's edges in
+  that many shuffled chunks so later chunks see earlier moves (partial in-epoch feedback),
+  trading speed for local overlap. Measured: overlap@15 at n=1000 rises 0.234 → 0.244
+  (chunk_count=10) → 0.248 (chunk_count=40 ≈ umap-learn), at ~5×/~10× cost; n=2000 0.139 →
+  0.147 (chunk_count=10). Stays deterministic.
+
+### Notes
+- #5 (per-edge negative-sample schedule) was measured neutral vs the flat rate and reverted.
+
+## [0.1.0] - 2026-08-22
+
+Initial port of a working single-file numpy+scipy UMAP into a typed, tested library.
+
+### Added
+- `umap_project(matrix, dimensions, ...)` — full fuzzy-simplicial-set UMAP in pure
+  numpy + scipy: blocked brute-force kNN, `smooth_knn_dist` (vectorised binary search),
+  fuzzy-union symmetrisation, spectral initialisation via `scipy.sparse.linalg.eigsh`,
+  `find_ab_params` via `scipy.optimize.curve_fit`, and a vectorised attract/repel SGD.
+- `spectral_project(matrix, dimensions, ...)` — the spectral initialisation alone.
+- Metrics: `neighbor_overlap`, `global_distance_correlation`, `random_layout`.
+- 2D and 3D output, both first-class.
+- Deterministic given a seed (pinned ARPACK start vector + seeded negative sampler).
+- Full type annotations, pyright strict.
+- musil-style CI: moon + uv + proto, OIDC Trusted Publishing to PyPI.

fastumap-0.1.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jorge Cardona
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastumap-0.1.6/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.5
+Name: fastumap
+Version: 0.1.6
+Summary: A numba-free UMAP in pure numpy + scipy: imports in milliseconds, no LLVM/JIT at runtime.
+Project-URL: Homepage, https://gitlab.com/jorgeecardona/fastumap
+Project-URL: Repository, https://gitlab.com/jorgeecardona/fastumap
+Project-URL: Changelog, https://gitlab.com/jorgeecardona/fastumap/-/blob/main/CHANGELOG.md
+Author-email: Jorge Cardona <jorgeecardona@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dimensionality-reduction,embedding,manifold-learning,numpy,scipy,umap,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# fastumap
+
+A numba-free UMAP in pure **numpy + scipy**. It exists for one reason: import cost.
+
+| | import (cold) | wheels added to image |
+|---|---:|---:|
+| `import umap` (umap-learn) | **~21 s** on a laptop; **148 s** at 0.5 vCPU ×4 | ~172 MB (llvmlite alone 113 MB) |
+| `import fastumap` | **~12 ms** | 0 MB (numpy + scipy already present) |
+
+umap-learn is excellent, but its kernels are numba, and numba compiles with LLVM at
+*import* time. numpy and scipy ship precompiled kernels, so they import in milliseconds.
+That is the whole thesis: **the problem is not numba, it is compilation at import time**,
+and a vectorised numpy implementation avoids it without giving up much quality.
+
+## Why this exists — the incident
+
+The first consumer is an internal ML-platform API on AWS Fargate: **0.5 vCPU, 4 granian
+workers, 2 GB**, shared with a Datadog sidecar. Every worker pays every import, and the
+cgroup meters CPU, so four numba compilations run through a half-vCPU straw at once:
+
+- `from umap import UMAP` cost ~4.1 CPU-seconds; `pynndescent` alone declares 46
+  eagerly-compiled `@njit` functions.
+- In that container the import took **148 s wall** (126 s and 206 s on two Fargate tasks).
+  The health check kills the container at ~120 s, so the service crash-looped and **never
+  served a request**. At 1 CPU it was 37.8 s, at 2 CPUs 16.1 s — compilation is serial, so
+  more cores barely help.
+- Baking a numba cache into the image did not fix it (11.9 s vs 12.0 s): the eager-signature
+  functions that dominate import have no `cache=True`.
+- `NUMBA_DISABLE_JIT=1` works but the pure-Python kernels are ~100× slower.
+
+fastumap imports in ~12 ms, four times over, and leaves the health-check budget intact.
+
+## Quality vs umap-learn
+
+Graded on separated Gaussian clusters (dimensions noted per table), against umap-learn on
+the same data. We assert we are *within a tolerance* of the reference, never that layouts
+match: different initialisation and update order rotate and reflect equally-good embeddings.
+
+<!-- QUALITY_TABLE -->
+**n=1000, 64-dim, 8 clusters, 3 seeds** (`make grade`):
+
+| layout | overlap@15 ↑ | global dist corr ↑ |
+|---|---:|---:|
+| fastumap | 0.236 ± 0.003 | **0.400 ± 0.086** |
+| umap-learn | **0.250 ± 0.003** | 0.206 ± 0.033 |
+| pca | 0.165 ± 0.001 | 0.843 ± 0.012 |
+| random | 0.015 ± 0.001 | −0.003 ± 0.003 |
+
+fastumap (default) trails umap-learn by ~0.014 on local neighbourhood overlap and is well
+ahead on global structure. Both beat PCA on local overlap and crush the random control.
+
+**Quality knob — `chunk_count`.** The optimiser defaults to a per-epoch snapshot update
+(`chunk_count=1`), the fast path the 0.5-vCPU service needs. Raising `chunk_count` processes
+each epoch's edges in that many shuffled chunks so later chunks see earlier moves (partial
+in-epoch feedback, toward umap-learn's in-place walk). It trades speed for local overlap:
+
+| chunk_count | overlap@15 (n=1000) | vs default | rel. cost |
+|---:|---:|---:|---:|
+| 1 (default) | 0.234 | — | 1× |
+| 10 | 0.244 | +0.010 | ~5× |
+| 40 | 0.248 | +0.014 (≈ umap-learn) | ~10× |
+
+`umap_project(x, 2, chunk_count=10)` closes most of the gap; it stays deterministic.
+
+### Real data — MNIST (`make bench`)
+
+Single-thread, 784-dim MNIST via `bench/mnist.py` (defaults, `chunk_count=1`):
+
+| n | method | wall-clock | overlap@15 ↑ | global dist corr ↑ |
+|---|---|---:|---:|---:|
+| 5000 | **fastumap** | 26 s | 0.333 | 0.310 |
+| 5000 | umap-learn | 73 s | 0.344 | 0.329 |
+| 5000 | pca | 2 s | 0.058 | 0.523 |
+| 10000 | **fastumap** | 72 s | 0.267 | 0.279 |
+| 10000 | umap-learn | 83 s | 0.274 | 0.286 |
+| 10000 | pca | 4 s | 0.039 | 0.471 |
+| 20000 | fastumap | 110 s | 0.188 | 0.323 |
+| 20000 | umap-learn | 31 s | 0.205 | 0.316 |
+| 20000 | pca | 10 s | 0.024 | 0.497 |
+
+fastumap stays within **0.01–0.02** overlap of umap-learn at every size, and beats PCA on
+local structure by a wide margin (PCA keeps global distances best, as a linear method does).
+On speed it wins at 5k and 10k. Two honest caveats: (1) wall-clock is measured in one
+process, so umap-learn's later fits reuse the numba compile paid on the first — its 20k time
+excludes the ~20 s compile a *fresh* process pays every time, which is the cost fastumap
+exists to avoid; (2) at 20k fastumap's brute-force O(n²) kNN and Python-loop SGD lose to
+pynndescent — the case the approximate-kNN backend (roadmap #15) addresses.
+
+Metrics:
+- **overlap@k** — share of each point's k input-space neighbours still among its k nearest
+  after projection. Chance is ~`k/(n-1)`; always read against the random control.
+- **global dist corr** — Spearman correlation of all pairwise distances, before vs after.
+
+## Install
+
+```bash
+pip install fastumap        # numpy + scipy, nothing else
+```
+
+## Use
+
+```python
+from fastumap import umap_project, spectral_project
+
+xy  = umap_project(embeddings, dimensions=2)                    # (n, 2)
+xyz = umap_project(embeddings, dimensions=3)                    # (n, 3)
+cos = umap_project(embeddings, dimensions=2, metric="cosine")  # for text/CLS embeddings
+init = spectral_project(embeddings, dimensions=2)              # just the spectral init
+```
+
+`metric` is `"euclidean"` (default) or `"cosine"`. Cosine is usually what you want for
+encoder/CLS embeddings — euclidean on unnormalised output is dominated by vector length,
+not the direction that carries the meaning.
+
+**Incremental placement.** Fit once, then place new points into the frozen layout without
+refitting — so a drift view stays stable instead of reshuffling every request:
+
+```python
+from fastumap import fit, transform
+
+model = fit(window, dimensions=2)      # UMAPModel; model.embedding is the layout
+new_xy = transform(model, new_points)  # (n_new, 2), placed against the fixed layout
+```
+
+Same input and seed give **bit-identical** output across processes (the layout must be
+stable across reloads so people can compare the picture over time). `umap_project` takes
+`n_neighbors`, `min_dist`, `spread`, `n_epochs`, `negative_sample_rate`, `random_state`,
+`metric`, and `chunk_count`.
+
+## Sparse input
+
+Not supported — `umap_project`/`fit` take a **dense** numpy array. The blocked kNN relies
+on dense BLAS matmul, and the target workload is dense encoder/CLS embeddings, so a native
+sparse distance path is out of scope. Passing a `scipy.sparse` matrix raises a `TypeError`
+telling you to densify first (`matrix.toarray()`). Revisit if a sparse workload actually
+shows up.
+
+## Guarantees (enforced by tests)
+
+- **numpy + scipy only** at runtime — no numba, llvmlite, scikit-learn, or compiled
+  extension of our own. A test asserts the JIT stack is never imported.
+- **Import under 200 ms** — a subprocess test measures it.
+- **Deterministic** — pinned ARPACK start vector, seeded negative sampler; identical bytes
+  across processes.
+- **Memory bounded** — the n-by-n distance matrix is never materialised (512-row blocked
+  kNN). At the worst case (5000 × 1024) the fit adds ~102 MB over the import+input baseline
+  (175 MB total peak); the test enforces a 200 MB ceiling.
+- **Time budgeted** — single-thread wall-clock ~5.3 s at 1000 × 1024, ~32 s at 5000 × 1024;
+  a CI test measures under a single-core cap and fails on a regression past a generous
+  ceiling (25 s / 120 s). The SGD dominates — the number is honest, not yet fast; speeding
+  it up further is tracked.
+- **2-D and 3-D**, both first-class. **Typed**, pyright strict.
+
+## Releasing
+
+CI (GitLab, moon + uv + proto) runs lint, format, typecheck, tests, build on every push.
+On `main` it runs `:release`: the same checks, then publishes to PyPI via **OIDC Trusted
+Publishing** (no stored token, pending publisher configured) whenever the version in
+`pyproject.toml` is not yet on PyPI — idempotent, so it is a no-op on every other pipeline.
+
+## Not affiliated with UMAP
+
+fastumap is an **independent reimplementation** of the UMAP algorithm
+([McInnes, Healy, Melville, arXiv:1802.03426](https://arxiv.org/abs/1802.03426);
+reference implementation [lmcinnes/umap](https://github.com/lmcinnes/umap)). It is not
+affiliated with or endorsed by the UMAP authors, and it is **not a drop-in replacement** —
+the public surface is deliberately small. MIT licensed.

fastumap-0.1.6/README.md

@@ -0,0 +1,167 @@
+# fastumap
+
+A numba-free UMAP in pure **numpy + scipy**. It exists for one reason: import cost.
+
+| | import (cold) | wheels added to image |
+|---|---:|---:|
+| `import umap` (umap-learn) | **~21 s** on a laptop; **148 s** at 0.5 vCPU ×4 | ~172 MB (llvmlite alone 113 MB) |
+| `import fastumap` | **~12 ms** | 0 MB (numpy + scipy already present) |
+
+umap-learn is excellent, but its kernels are numba, and numba compiles with LLVM at
+*import* time. numpy and scipy ship precompiled kernels, so they import in milliseconds.
+That is the whole thesis: **the problem is not numba, it is compilation at import time**,
+and a vectorised numpy implementation avoids it without giving up much quality.
+
+## Why this exists — the incident
+
+The first consumer is an internal ML-platform API on AWS Fargate: **0.5 vCPU, 4 granian
+workers, 2 GB**, shared with a Datadog sidecar. Every worker pays every import, and the
+cgroup meters CPU, so four numba compilations run through a half-vCPU straw at once:
+
+- `from umap import UMAP` cost ~4.1 CPU-seconds; `pynndescent` alone declares 46
+  eagerly-compiled `@njit` functions.
+- In that container the import took **148 s wall** (126 s and 206 s on two Fargate tasks).
+  The health check kills the container at ~120 s, so the service crash-looped and **never
+  served a request**. At 1 CPU it was 37.8 s, at 2 CPUs 16.1 s — compilation is serial, so
+  more cores barely help.
+- Baking a numba cache into the image did not fix it (11.9 s vs 12.0 s): the eager-signature
+  functions that dominate import have no `cache=True`.
+- `NUMBA_DISABLE_JIT=1` works but the pure-Python kernels are ~100× slower.
+
+fastumap imports in ~12 ms, four times over, and leaves the health-check budget intact.
+
+## Quality vs umap-learn
+
+Graded on separated Gaussian clusters (dimensions noted per table), against umap-learn on
+the same data. We assert we are *within a tolerance* of the reference, never that layouts
+match: different initialisation and update order rotate and reflect equally-good embeddings.
+
+<!-- QUALITY_TABLE -->
+**n=1000, 64-dim, 8 clusters, 3 seeds** (`make grade`):
+
+| layout | overlap@15 ↑ | global dist corr ↑ |
+|---|---:|---:|
+| fastumap | 0.236 ± 0.003 | **0.400 ± 0.086** |
+| umap-learn | **0.250 ± 0.003** | 0.206 ± 0.033 |
+| pca | 0.165 ± 0.001 | 0.843 ± 0.012 |
+| random | 0.015 ± 0.001 | −0.003 ± 0.003 |
+
+fastumap (default) trails umap-learn by ~0.014 on local neighbourhood overlap and is well
+ahead on global structure. Both beat PCA on local overlap and crush the random control.
+
+**Quality knob — `chunk_count`.** The optimiser defaults to a per-epoch snapshot update
+(`chunk_count=1`), the fast path the 0.5-vCPU service needs. Raising `chunk_count` processes
+each epoch's edges in that many shuffled chunks so later chunks see earlier moves (partial
+in-epoch feedback, toward umap-learn's in-place walk). It trades speed for local overlap:
+
+| chunk_count | overlap@15 (n=1000) | vs default | rel. cost |
+|---:|---:|---:|---:|
+| 1 (default) | 0.234 | — | 1× |
+| 10 | 0.244 | +0.010 | ~5× |
+| 40 | 0.248 | +0.014 (≈ umap-learn) | ~10× |
+
+`umap_project(x, 2, chunk_count=10)` closes most of the gap; it stays deterministic.
+
+### Real data — MNIST (`make bench`)
+
+Single-thread, 784-dim MNIST via `bench/mnist.py` (defaults, `chunk_count=1`):
+
+| n | method | wall-clock | overlap@15 ↑ | global dist corr ↑ |
+|---|---|---:|---:|---:|
+| 5000 | **fastumap** | 26 s | 0.333 | 0.310 |
+| 5000 | umap-learn | 73 s | 0.344 | 0.329 |
+| 5000 | pca | 2 s | 0.058 | 0.523 |
+| 10000 | **fastumap** | 72 s | 0.267 | 0.279 |
+| 10000 | umap-learn | 83 s | 0.274 | 0.286 |
+| 10000 | pca | 4 s | 0.039 | 0.471 |
+| 20000 | fastumap | 110 s | 0.188 | 0.323 |
+| 20000 | umap-learn | 31 s | 0.205 | 0.316 |
+| 20000 | pca | 10 s | 0.024 | 0.497 |
+
+fastumap stays within **0.01–0.02** overlap of umap-learn at every size, and beats PCA on
+local structure by a wide margin (PCA keeps global distances best, as a linear method does).
+On speed it wins at 5k and 10k. Two honest caveats: (1) wall-clock is measured in one
+process, so umap-learn's later fits reuse the numba compile paid on the first — its 20k time
+excludes the ~20 s compile a *fresh* process pays every time, which is the cost fastumap
+exists to avoid; (2) at 20k fastumap's brute-force O(n²) kNN and Python-loop SGD lose to
+pynndescent — the case the approximate-kNN backend (roadmap #15) addresses.
+
+Metrics:
+- **overlap@k** — share of each point's k input-space neighbours still among its k nearest
+  after projection. Chance is ~`k/(n-1)`; always read against the random control.
+- **global dist corr** — Spearman correlation of all pairwise distances, before vs after.
+
+## Install
+
+```bash
+pip install fastumap        # numpy + scipy, nothing else
+```
+
+## Use
+
+```python
+from fastumap import umap_project, spectral_project
+
+xy  = umap_project(embeddings, dimensions=2)                    # (n, 2)
+xyz = umap_project(embeddings, dimensions=3)                    # (n, 3)
+cos = umap_project(embeddings, dimensions=2, metric="cosine")  # for text/CLS embeddings
+init = spectral_project(embeddings, dimensions=2)              # just the spectral init
+```
+
+`metric` is `"euclidean"` (default) or `"cosine"`. Cosine is usually what you want for
+encoder/CLS embeddings — euclidean on unnormalised output is dominated by vector length,
+not the direction that carries the meaning.
+
+**Incremental placement.** Fit once, then place new points into the frozen layout without
+refitting — so a drift view stays stable instead of reshuffling every request:
+
+```python
+from fastumap import fit, transform
+
+model = fit(window, dimensions=2)      # UMAPModel; model.embedding is the layout
+new_xy = transform(model, new_points)  # (n_new, 2), placed against the fixed layout
+```
+
+Same input and seed give **bit-identical** output across processes (the layout must be
+stable across reloads so people can compare the picture over time). `umap_project` takes
+`n_neighbors`, `min_dist`, `spread`, `n_epochs`, `negative_sample_rate`, `random_state`,
+`metric`, and `chunk_count`.
+
+## Sparse input
+
+Not supported — `umap_project`/`fit` take a **dense** numpy array. The blocked kNN relies
+on dense BLAS matmul, and the target workload is dense encoder/CLS embeddings, so a native
+sparse distance path is out of scope. Passing a `scipy.sparse` matrix raises a `TypeError`
+telling you to densify first (`matrix.toarray()`). Revisit if a sparse workload actually
+shows up.
+
+## Guarantees (enforced by tests)
+
+- **numpy + scipy only** at runtime — no numba, llvmlite, scikit-learn, or compiled
+  extension of our own. A test asserts the JIT stack is never imported.
+- **Import under 200 ms** — a subprocess test measures it.
+- **Deterministic** — pinned ARPACK start vector, seeded negative sampler; identical bytes
+  across processes.
+- **Memory bounded** — the n-by-n distance matrix is never materialised (512-row blocked
+  kNN). At the worst case (5000 × 1024) the fit adds ~102 MB over the import+input baseline
+  (175 MB total peak); the test enforces a 200 MB ceiling.
+- **Time budgeted** — single-thread wall-clock ~5.3 s at 1000 × 1024, ~32 s at 5000 × 1024;
+  a CI test measures under a single-core cap and fails on a regression past a generous
+  ceiling (25 s / 120 s). The SGD dominates — the number is honest, not yet fast; speeding
+  it up further is tracked.
+- **2-D and 3-D**, both first-class. **Typed**, pyright strict.
+
+## Releasing
+
+CI (GitLab, moon + uv + proto) runs lint, format, typecheck, tests, build on every push.
+On `main` it runs `:release`: the same checks, then publishes to PyPI via **OIDC Trusted
+Publishing** (no stored token, pending publisher configured) whenever the version in
+`pyproject.toml` is not yet on PyPI — idempotent, so it is a no-op on every other pipeline.
+
+## Not affiliated with UMAP
+
+fastumap is an **independent reimplementation** of the UMAP algorithm
+([McInnes, Healy, Melville, arXiv:1802.03426](https://arxiv.org/abs/1802.03426);
+reference implementation [lmcinnes/umap](https://github.com/lmcinnes/umap)). It is not
+affiliated with or endorsed by the UMAP authors, and it is **not a drop-in replacement** —
+the public surface is deliberately small. MIT licensed.

fastumap-0.1.6/docs/issues/README.md

@@ -0,0 +1,83 @@
+# docs/issues — follow-ups with an owner-shaped edge
+
+One file per follow-up, self-contained, with YAML front matter. This folder is for work that is
+**known, scoped, and not being done right now** — the residue a session leaves behind when it lands
+its main change. Without a home, that residue lives in a chat log nobody re-reads, and "we should
+fix X" decays into nobody having ever owned X.
+
+**The files are the store.** No database, no second copy — an issue is markdown in git, readable and
+editable by hand. Everything derived (the index below above all) is *generated from* the files and
+is never authoritative. A duplicate store is a fault dimension; the way to avoid one is not to
+create it.
+
+## The rules that make one worth writing
+
+1. **Answerable cold.** Assume the reader has none of the author's context and no access to the
+   session that found it. Concrete instances, file:line, the actual commands.
+2. **Say what is MEASURED and what is INFERRED.** Separately, and in those words. An issue that
+   states an inference as a finding sends the next person to fix the wrong thing, and they will
+   believe you because you wrote it down.
+3. **Define done.** Not "improve X" — the specific observation that will be true afterwards, and
+   how to make it. `verify:` says which kind of evidence closes it, because they are different
+   claims: `test` (a red-then-green test is enough), `probe` (only sensing the real thing counts),
+   `inspect` (the artifact itself is the evidence).
+4. **Name what you deliberately did NOT do,** with the reason. Silence reads as an oversight and
+   gets re-litigated.
+5. **Close by marking it done,** with `fixed_in:` naming the sha that landed the fix. A register
+   that cannot say what fixed something has stopped being evidence.
+
+## The format
+
+```yaml
+---
+title: One line — the finding, not the fix
+status: open          # open | in-progress (name an owner) | blocked | done (needs fixed_in)
+scope: M              # XS | S | M | L | ?
+owner: null           # a handle, or null when unowned
+filed: 2026-08-22     # when it was filed; it never changes
+area: <one of the areas above>
+verify: probe         # test | probe | inspect — see rule 3
+blocked_by: null      # slug(s) of issues that must close first
+fixed_in: null        # the sha on the mainline; required once status is done
+---
+```
+
+**`blocked_by` is what makes the board honest.** `status: blocked` names a *person* who can unblock
+something; `blocked_by` names the *work* it waits on. Only the second can be computed, which is why
+"what can I pick up cold right now" is answerable at all.
+
+**Naming:** `DD-MM-YYYY-short-kebab-summary.md` — the date it was filed, then a slug.
+
+## Tooling — the folder checks itself
+
+Managed by `cabildo issues`. The CLI, the `issues` MCP server, and any pre-commit gate are one
+module, so the tool an agent calls and the gate that grades it cannot disagree.
+`docs/issues/config.toml` holds this folder's specifics.
+
+```bash
+cabildo issues                # what's ready, what's yours, what everything else waits on
+cabildo issues check          # the invariants; non-zero on problems
+cabildo issues reindex        # regenerate the index below
+cabildo issues show <slug>
+```
+
+## Open now
+
+<!-- BEGIN GENERATED INDEX — `cabildo issues reindex` -->
+| Issue | Area | Scope | Verify | Status | Waiting on |
+|---|---|---|---|---|---|
+| [#13 transform(): place new points into an existing layout without refit](22-08-2026-13-transform-place-new-points-into-an-existing-layout-without-refit.md) | capability | L | test | open | — |
+| [#14 Cosine metric (the one that matters for text embeddings)](22-08-2026-14-cosine-metric-the-one-that-matters-for-text-embeddings.md) | capability | M | test | open | — |
+| [#15 Approximate kNN behind an extra, for above ~50k points](22-08-2026-15-approximate-knn-behind-an-extra-for-above-50k-points.md) | capability | L | test | open | — |
+| [#16 Sparse input: decide whether to support it at all](22-08-2026-16-sparse-input-decide-whether-to-support-it-at-all.md) | capability | S | inspect | open | — |
+| [#11 Thread safety: concurrent projections from asyncio.to_thread](22-08-2026-11-thread-safety-concurrent-projections-from-asyncio-to-thread.md) | production | S | test | open | — |
+| [#12 Time-budget test at 1000 and 5000 points under a single-core cap](22-08-2026-12-time-budget-test-at-1000-and-5000-points-under-a-single.md) | production | M | test | open | — |
+| [#9 Memory ceiling test: peak RSS at 5000x1024 under a stated bound](22-08-2026-9-memory-ceiling-test-peak-rss-at-5000x1024-under-a-stated-bound.md) | production | S | test | open | — |
+| [#5 Match umap-learn's negative-sample schedule](22-08-2026-5-match-umap-learn-s-negative-sample-schedule.md) | quality | S | test | open | — |
+| [#6 Partial in-epoch feedback (shuffled chunks) in the optimiser](22-08-2026-6-partial-in-epoch-feedback-shuffled-chunks-in-the-optimiser.md) | quality | M | test | open | — |
+| [#7 Real-data benchmark: MNIST + Fashion-MNIST via cached downloader](22-08-2026-7-real-data-benchmark-mnist-fashion-mnist-via-cached-downloader.md) | quality | M | test | open | — |
+| [#17 README leads with the two numbers that justify the library](22-08-2026-17-readme-leads-with-the-two-numbers-that-justify-the-library.md) | release | S | inspect | open | — |
+| [#18 Publish to PyPI (OIDC Trusted Publishing), independent-reimplementation notice](22-08-2026-18-publish-to-pypi-oidc-trusted-publishing-independent-reimplementation-notice.md) | release | M | probe | open | — |
+
+_12 open — 12 open; 6 done. Generated; edit the files, then `cabildo issues reindex`._
+<!-- END GENERATED INDEX -->