feat: port Plate FFT HRR primitives to public repo (#216) - #221
Merged
Conversation
Adds aelfrice.hrr — circular-convolution binding (FFT), correlation unbinding, vector superposition, cosine similarity, and a labeled CleanupMemory store for nearest-neighbor recovery. Pure algebra; no integration into retrieve(). Prereq for #152 (HRR structural-query lane). Numpy is already runtime as of v1.5.0 (BM25F sparse-matvec, #148); no dep-policy break. Tests cover the eight acceptance criteria from the issue plus four defensive corner cases (empty list, zero norm, empty store, zero probe). One AC threshold corrected from the issue body's stated "to within 1e-10" to a realistic >= 0.65 cosine-similarity bound: with random unit keys, unbind(k, bind(k, v)) yields v scaled per-frequency by |fft(k)|^2, giving empirical cosine ~0.71 (range 0.69-0.72 across seeds 0-9 at dim=2048). Cleanup memory recovers the true filler from the degraded vector — that is the standard HRR pipeline. Threshold sits well above the 1/sqrt(dim) ~ 0.022 noise floor and the two-pair cross-talk magnitude. HRRGraph (lab-side partitioned encoder) is intentionally out of scope — its responsibilities overlap with #152's HRRStructIndex and porting it now would make #152's PR harder to review.
This was referenced Apr 28, 2026
robotrocketscience
added a commit
that referenced
this pull request
Apr 28, 2026
…gs + telemetry (#232) (#234) Closes #232. Implements the v1.5 retrieval composition plumbing split off from #154 (#154 retargeted as the v1.7 default-on-flip tracker). ## What ships Three atomic commits: 1. **`refactor(retrieval): rename bm25f_enabled -> use_bm25f_anchors per #154 flag policy`** Standardises the v1.5 flag-name surface on `use_<lane>_<modifier>`. Renames kwarg / TOML key / helper across `retrieve()`, `retrieve_with_tiers()`, `retrieve_v2()`, `RetrievalCache.retrieve`. `AELFRICE_BM25F` env var unchanged. #148 just shipped so no released-flag breakage. 2. **`feat(retrieval): placeholder flags + per-lane telemetry`** Four placeholder flags (default-OFF, no-op): `use_signed_laplacian`, `use_heat_kernel`, `use_posterior_ranking`, `use_hrr_structural`. Setting any true in `.aelfrice.toml` emits one stderr warning per process per flag, naming the flag and the tracker issue. Adds `LaneTelemetry` dataclass + `last_lane_telemetry()`; populated in `retrieve()` / `retrieve_with_tiers()` with one assignment each. 3. **`test: composition-tracker placeholder flags + LaneTelemetry`** 8 deterministic tests: warner once-per-process idempotency, empty-TOML quiet, explicit-False quiet, `PLACEHOLDER_FLAGS` regression guard, `LaneTelemetry` populates for FTS5 default + `use_bm25f_anchors=True`, posterior_weight round-trip. ## Acceptance (per #232) - AC1: rename complete across all four surfaces ✅ - AC2: four placeholder flags resolve through env > kwarg > TOML > default ✅ - AC3: stderr warning idempotent per flag per process ✅ - AC4: `LaneTelemetry` populates for both L1 lanes + posterior round-trip ✅ - AC5: byte-identical regression tests preserved (full suite was green at HEAD pre-rebase: 1471 pass / 4 skip; this PR rebases onto current `main` clean and CI staging-gate revalidates). ## Out of scope - No default flips. No new retrieval algorithms. No benchmark gate. Tracked under #154 for the v1.7 wave. ## Note on rebase Branch was 6 commits behind `main` after #211 / #221 / #231 / #202 / #210 / #209 landed. Rebased onto `github/main` with no conflicts. Force-pushed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #216. Prereq for #152 (HRR structural-query lane), whose spec assumes
aelfrice.hrralready exists in the public repo.aelfrice.hrrwith the 5 Plate (1995) primitives (random_vector,bind,unbind,superpose,cosine_similarity) plusCleanupMemoryfor nearest-neighbor recovery.aelfrice-lab/.../src/aelfrice/hrr.pylines 1-112. TheHRRGraphpartitioned-encoder class is intentionally not ported — its responsibilities overlap with the structural index [retrieval] HRR structural-query lane (bind/probe over outgoing edges) #152 will build, so duplicating now would make [retrieval] HRR structural-query lane (bind/probe over outgoing edges) #152's PR harder to review.pyproject.tomldep change.Spec correction
Issue body's AC1 / AC4 stated
unbind(k, bind(k, v))recoversv"to within 1e-10 FFT noise." That is wrong for random Gaussian keys: the recovery isvscaled per-frequency by|fft(k)|², giving empirical cosine similarity ~0.71 (range 0.69-0.72 across seeds 0-9 at dim=2048), not ~1.0. Cleanup memory disambiguates the degraded vector — that's the standard HRR pipeline. Tests use a >=0.65 threshold which sits comfortably above both the noise floor and the two-pair cross-talk. Issue should be amended to reflect the realistic threshold; flagging here so the spec gets corrected before #152 lands.Test plan
uv run pytest tests/test_hrr.py -q— 11 pass.uv run pytest— full suite 1474 passed, 4 skipped (no regressions).uv run pyright src/aelfrice/hrr.py tests/test_hrr.py— clean.Out of scope
HRRGraph, sentence encoder, HRR-vs-FTS5 eval (lab-side scripts) — separate issues.