fix(retrieval): raise relevance-budget floor 0.25 -> 0.50 so moderate lock loads don't under-serve relevance (#1023)

[robotrocketscience]

What

Raises RELEVANCE_BUDGET_FLOOR_FRACTION (the relevance reservation under lock saturation, #1015) from 0.25 to 0.50. Closes #1023.

Why (R&D sweep on a real lock-saturated store: 24 locks = 3491 tok vs 1500 budget)

fraction	reserved	avg relevance hits	avg total tokens
0.25 (old)	375	8.0	3825
0.50 (new)	750	16.2	4182
0.75	1125	23.2	4545

Because the never-trimmed locks already exceed the budget, the total injection is ~3500+ tokens regardless — the fraction only decides how much more relevance to add. 0.25 → 0.50 doubles relevance coverage (8 → 16 hits) for ~9% more total tokens. Verified end-to-end in the live hook on the real store: non-lock relevance hits went 4 → 8. Diminishing BM25-relevance past ~0.5 (hits 9–16 rank below 1–8) makes it the knee, not 0.75/1.0.

Behavior-change note

This widens the engagement regime: the floor engages once locked_used > budget × (1 − fraction), i.e. locks > 50% of budget (was > 75%). Moderately-locked stores now reserve 0.5 × budget for relevance and may exceed the nominal budget by up to that floor — the intended trade (never go blind to the query). Locks remain never-trimmed (#379); lock-light corpora (locks < 50% budget, e.g. LoCoMo) stay byte-identical.

Tests

• New test_floor_engages_at_moderate_lock_load: locks ~62% of budget → relevance surfaces and total output exceeds the budget (the signal that distinguishes 0.5 from 0.25, where the cap would have held).
• Existing floor tests + broad retrieval/budget/lock/rank/cluster/compression sweep: 715 passed, byte-identical contracts intact.

Summary by CodeRabbit

• Changed
  • Increased the minimum relevance budget reserved during lock-heavy retrieval, so more query-relevant results can still surface under moderate load.
  • Improved behavior when locks consume a large share of the token budget, helping preserve useful non-lock matches while keeping locks intact.
• Tests
  • Added coverage for moderate lock saturation to verify the new budget floor engages as expected.

[sourcery-ai]

Sorry @robotrocketscience, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Warning

Review limit reached

@robotrocketscience, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 53 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e3da9e25-8014-4308-8489-4ed38640c518

📥 Commits

Reviewing files that changed from the base of the PR and between 5bec07c and a811dc0.

📒 Files selected for processing (1)

• tests/test_relevance_budget_floor.py

📝 Walkthrough

Walkthrough

RELEVANCE_BUDGET_FLOOR_FRACTION in src/aelfrice/retrieval.py is increased from 0.25 to 0.50, with updated comments. A new regression test validates floor engagement at moderate lock load. A changelog entry documents the change.

Changes

Relevance Budget Floor Increase

Layer / File(s)	Summary
Constant update and changelog src/aelfrice/retrieval.py, CHANGELOG/v3.md	RELEVANCE_BUDGET_FLOOR_FRACTION changed from 0.25 to 0.50 with revised comments; changelog records the new floor value and its effects on hit counts and token totals.
Regression test tests/test_relevance_budget_floor.py	Adds import of _belief_tokens and test_floor_engages_at_moderate_lock_load, which asserts the floor engages at >= 0.5, returns multiple relevant non-lock beliefs, and that summed token cost exceeds DEFAULT_TOKEN_BUDGET.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• robotrocketscience/aelfrice#1015: Originally introduced RELEVANCE_BUDGET_FLOOR_FRACTION and tests/test_relevance_budget_floor.py; this PR directly tunes the constant added there.

Suggested labels

attn:review

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states the main retrieval change and matches the PR scope.
Description check	✅ Passed	The description covers the change, rationale, behavior impact, and tests, though it uses custom headings.
Linked Issues check	✅ Passed	The code raises the floor to 0.50 and adds a test for moderate lock load, matching #1023.
Out of Scope Changes check	✅ Passed	The changelog, code, and test additions all support the floor tuning; no unrelated changes stand out.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/relevance-floor-fraction

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/test_relevance_budget_floor.py`:
- Around line 67-88: The regression test is too loose because it only checks
RELEVANCE_BUDGET_FLOOR_FRACTION >= 0.5 and relies on an approximate lock load,
so it won’t catch drift in the knee. Tighten
test_floor_engages_at_moderate_lock_load by measuring the locked token total
produced by the inserted locked beliefs and asserting it falls in the intended
50%-75% budget window before calling retrieve; if this test is meant to freeze
the tuning, also pin RELEVANCE_BUDGET_FLOOR_FRACTION to exactly 0.5.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7f177e74-823f-4b28-b679-24db3b745094

📥 Commits

Reviewing files that changed from the base of the PR and between c80126d and 5bec07c.

📒 Files selected for processing (3)

• CHANGELOG/v3.md
• src/aelfrice/retrieval.py
• tests/test_relevance_budget_floor.py

[github-actions]

merge-train: merged a811dc0 → main via FF push.