feat(retrieval): composition plumbing — flag policy + placeholder flags + telemetry (#232) - #234
Merged
Merged
Conversation
… flag policy The v1.5.0 composition tracker (#154) standardises retrieval feature-flag names on the use_<lane>_<modifier> form. Rename: - kwarg bm25f_enabled -> use_bm25f_anchors - TOML key bm25f_enabled -> use_bm25f_anchors (constant BM25F_FLAG holds the new value; ENV_BM25F unchanged since the env-var name AELFRICE_BM25F still cleanly maps) - helper is_bm25f_enabled() -> resolve_use_bm25f_anchors() - retrieve_v2 use_bm25f -> use_bm25f_anchors (was already inconsistent with the other surfaces) #148 just landed in v1.5; no released users have the old flag name yet so a one-shot rename without an alias is safe. The default-OFF contract is unchanged. Tests + bm25.py docstring updated. Full suite green (1463 pass / 4 skip).
…ope) The v1.5.0 composition tracker stands up the unified retrieve() flag-resolution surface ahead of the v1.6 / v1.7 component waves: Placeholder flags (default-OFF, no-op at v1.5.0): - use_signed_laplacian -- v1.6 (issue #149) - use_heat_kernel -- v1.6 (issue #150) - use_posterior_ranking -- v1.6 (issue #151) -- partial form already shipped as posterior_weight at v1.3.0; this placeholder reserves the full name for the v1.6 composition wave - use_hrr_structural -- v1.7 (issue #152) Setting any placeholder True in [retrieval] of .aelfrice.toml emits a once-per-process stderr warning naming the flag and #154; no behavioural change. The fail-soft contract matches the rest of the config surface (malformed TOML never raises, just traces). Per-lane telemetry surface: - LaneTelemetry dataclass: locked / l25 / l1 / bfs counts (post- dedupe), bm25f_used (was the BM25F lane the L1 implementation), posterior_weight (resolved value). - last_lane_telemetry() returns the LaneTelemetry of the most recent retrieve() / retrieve_with_tiers() call in this process. - Populated at the end of both retrieve() and retrieve_with_tiers() with one assignment each. Zero overhead. Consumers: aelf doctor (v1.5.x surface), the v1.6+ benchmark gates that flip use_signed_laplacian / use_heat_kernel etc. default-on per their owning issues. No default-on flip in this PR. The benchmark gate that flips use_bm25f_anchors default-on lands separately once we have data.
tests/test_composition_tracker.py: - Placeholder warner emits one stderr line per use_<lane> flag set to true in .aelfrice.toml; the warning names the flag and references #154. - Warner is idempotent within a process (already-warned flag produces no new line on a second call). - Empty TOML produces no warnings; explicit False on a flag produces no warning either. - PLACEHOLDER_FLAGS constant matches the four v1.6/v1.7 lane names (regression guard against accidental drift). - LaneTelemetry populates correctly for the FTS5 default lane, flips bm25f_used=True when use_bm25f_anchors=True is opted in, and round-trips the resolved posterior_weight. 8 deterministic tests, all in-memory store. Full suite green (1471 pass / 4 skip).
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.
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:
refactor(retrieval): rename bm25f_enabled -> use_bm25f_anchors per #154 flag policyStandardises the v1.5 flag-name surface on
use_<lane>_<modifier>. Renames kwarg / TOML key / helper acrossretrieve(),retrieve_with_tiers(),retrieve_v2(),RetrievalCache.retrieve.AELFRICE_BM25Fenv var unchanged. [retrieval] Augmented BM25F (incoming-edge anchor text) + vectorized BM25 sparse matvec #148 just shipped so no released-flag breakage.feat(retrieval): placeholder flags + per-lane telemetryFour placeholder flags (default-OFF, no-op):
use_signed_laplacian,use_heat_kernel,use_posterior_ranking,use_hrr_structural. Setting any true in.aelfrice.tomlemits one stderr warning per process per flag, naming the flag and the tracker issue. AddsLaneTelemetrydataclass +last_lane_telemetry(); populated inretrieve()/retrieve_with_tiers()with one assignment each.test: composition-tracker placeholder flags + LaneTelemetry8 deterministic tests: warner once-per-process idempotency, empty-TOML quiet, explicit-False quiet,
PLACEHOLDER_FLAGSregression guard,LaneTelemetrypopulates for FTS5 default +use_bm25f_anchors=True, posterior_weight round-trip.Acceptance (per #232)
LaneTelemetrypopulates for both L1 lanes + posterior round-trip ✅mainclean and CI staging-gate revalidates).Out of scope
Note on rebase
Branch was 6 commits behind
mainafter #211 / #221 / #231 / #202 / #210 / #209 landed. Rebased ontogithub/mainwith no conflicts. Force-pushed.