Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG/v3.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- **HRR structural-query lane goes live on the production `retrieve()` path ([#1107](https://github.com/robotrocketscience/aelfrice/issues/1107), Phase 5; [#152](https://github.com/robotrocketscience/aelfrice/issues/152)).** The marker-routed structural lane — which detects a `<KIND>:<target_id>` query (an uppercase edge type followed by a target belief id), bypasses the BM25F + heat-kernel textual stack, and returns the graph-connected beliefs an HRR probe ranks for that edge — was resolver-default-ON in `retrieve_v2` since v2.1 (after the #154 composition tracker cleared the #437 reproducibility harness at 11/11) but inert on the live hook path, which called the legacy `retrieve()`. The #1107 shim now passes `use_hrr_structural` resolver-driven (`None` → env→TOML→default-ON) instead of hard-off, so tooling callers that issue marker queries through the production path get structural routing. The lane is **marker-routed**: on any non-marker query (the shape of a free-text hook prompt) `parse_structural_marker` returns `None` and the call falls through byte-identically, so the graduation adds only one fast-failing regex to the non-marker hot path and its blast radius is confined to `<KIND>:<target_id>` callers. This adds a public on-HEAD signal — `benchmarks/hrr_structural_ablation.py`, a deterministic synthetic corpus of marker queries whose answers share no vocabulary with the marker string: recall@k **0.000 → 1.000** (textual BM25 cannot reach a structural answer; the lane routes it exactly), complementing the existing `tests/test_retrieve_v2_hrr_structural.py` IT1–IT6 wiring tests. Opt out with `AELFRICE_HRR_STRUCTURAL=0` or `[retrieval] use_hrr_structural = false`. The equivalence guard now pins four graduated lanes (spine + entity-persist + clustering + HRR-structural) live and a held lane (origin tie-break) off. Deterministic per #605.
- **Intentional-clustering lane goes live on the production `retrieve()` path ([#1107](https://github.com/robotrocketscience/aelfrice/issues/1107), Phase 4; [#436](https://github.com/robotrocketscience/aelfrice/issues/436)).** The multi-fact clustering pass — which biases the packed top-K toward distinct graph-connected clusters so a query needing two facts surfaces both, rather than K beliefs from one neighbourhood — was default-ON in `retrieve_v2` since v3.0 (after its A2 coverage / A3 non-regression / A4 latency gates) but inert on the live hook path. The #1107 shim now passes `use_intentional_clustering` resolver-driven (`None` → default-ON) instead of hard-off, so live hosts get the multi-fact coverage. Because the full A2/A3 gate corpus is lab-side and not shipped, this adds a public on-HEAD analogue — `benchmarks/intentional_clustering_ablation.py`, a deterministic synthetic multi-cluster corpus run through the same `run_clustering_uplift` driver the gate uses: cluster_coverage@k **0.500 → 1.000** with recall@k non-degrading (A2 ship condition PASS). A4 latency was cleared at v3.0 (60/60 PASS, p99 0.328 ms, ~15-30× under the 5 ms budget). Opt out with `AELFRICE_INTENTIONAL_CLUSTERING=0` or `[retrieval] use_intentional_clustering = false`. The equivalence guard now pins three graduated lanes (spine + entity-persist + clustering) live and a held lane (origin tie-break) off. Deterministic per #605.

- **Entity-persist demotion lane goes live on the production `retrieve()` path ([#1107](https://github.com/robotrocketscience/aelfrice/issues/1107), Phase 3; [#1096](https://github.com/robotrocketscience/aelfrice/issues/1096)).** The #1086 junk-percolation sink — the log-additive demotion that pushes beliefs grounded only in transient coordination tokens (bare PR/issue numbers, version tags) below those grounded in durable entities (file paths, symbols) — was default-ON in `retrieve_v2` since v4.0 but inert on the live hook path, which called the legacy `retrieve()`. The #1107 shim now passes `use_entity_persist_demote` resolver-driven (`None` → env→TOML→default-ON, the G2-cleared #1103 default) instead of hard-off, so the demotion reaches every host's `retrieve()`, `context_rebuilder`, and `mcp_server` — this is what makes the #1086 fix real for users rather than only bench/eval consumers. No-op on entity-free or well-grounded candidates; one batched `belief_entities` query, no candidate expansion. Opt out with `AELFRICE_ENTITY_PERSIST_DEMOTE=0` or `[retrieval] use_entity_persist_demote = false`. The `retrieve()`↔`retrieve_v2` equivalence guard now pins the graduated lanes resolver-driven with the remaining held lanes forced off. Deterministic per #605.
Expand Down
135 changes: 135 additions & 0 deletions benchmarks/hrr_structural_ablation.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
"""#152 HRR structural-query lane — offline marker-routing recall ablation.

Builds a SYNTHETIC edge-connected corpus and reports `recall@k` of the
graph-connected answer with the structural lane OFF vs ON, driving
`retrieve_v2` directly (the same entry point the production `retrieve()`
shim delegates to after the #1107 Phase-5 graduation).

Each row is a `<KIND>:<target_id>` marker query whose answer — the belief
that points at `target_id` via an edge of `KIND` — shares NO vocabulary with
the marker string. With the lane OFF, `retrieve_v2` BM25-searches the literal
marker text and cannot reach the answer (recall ~0). With the lane ON, the
query parses as a structural marker and the HRR probe returns the edge source
(recall 1.0). This is the public, on-HEAD analogue of the #437
reproducibility-harness gate (whose 11/11 result flipped the resolver default
to True at v2.1) and the `tests/test_retrieve_v2_hrr_structural.py` IT1-IT6
wiring tests — added for the #1107 Phase-5 production graduation so the flip
carries a reproducible recall signal rather than resting only on prior gates.

The lane is marker-routed: on any non-marker query it falls through
byte-identically, so its production blast radius is confined to callers that
issue `<KIND>:<target_id>` queries (structured tooling), not free-text hook
prompts. No live-store content — deterministic and CI-safe.

Ship condition: `recall_uplift > 0`.

Run: `python benchmarks/hrr_structural_ablation.py`
"""
from __future__ import annotations

from dataclasses import dataclass

from aelfrice.hrr_index import HRRStructIndexCache
from aelfrice.models import (
BELIEF_FACTUAL,
EDGE_CONTRADICTS,
EDGE_SUPPORTS,
EDGE_CITES,
LOCK_NONE,
Belief,
Edge,
)
from aelfrice.retrieval import retrieve_v2
from aelfrice.store import MemoryStore

N_ROWS = 20
_NOISE_PER_ROW = 3
_BUDGET = 10_000
_KINDS = [EDGE_CONTRADICTS, EDGE_SUPPORTS, EDGE_CITES]

# Disjoint NATO-ish vocab so marker strings ("CONTRADICTS:tgt7") share no
# tokens with any belief content — the lane-off arm cannot BM25 its way in.
_WORDS = [
"alpha", "bravo", "charlie", "delta", "echo", "foxtrot", "golf", "hotel",
"india", "juliet", "kilo", "lima", "mike", "november", "oscar", "papa",
]


def _content(seed: int) -> str:
return " ".join(_WORDS[(seed + j) % len(_WORDS)] for j in range(5))


@dataclass
class _Result:
n_rows: int
recall_off: float
recall_on: float

@property
def recall_uplift(self) -> float:
return self.recall_on - self.recall_off


def _build(store: MemoryStore) -> list[tuple[str, str]]:
"""Populate the store; return the (marker_query, answer_id) list."""
rows: list[tuple[str, str]] = []
for i in range(N_ROWS):
kind = _KINDS[i % len(_KINDS)]
src, tgt = f"src{i}", f"tgt{i}"
for bid, seed in ((src, i), (tgt, i + 100)):
store.insert_belief(Belief(
id=bid, content=_content(seed), content_hash=f"h_{bid}",
alpha=1.0, beta=1.0, type=BELIEF_FACTUAL,
lock_level=LOCK_NONE, locked_at=None,
created_at="2026-06-01T00:00:00Z", last_retrieved_at=None,
))
for j in range(_NOISE_PER_ROW):
nid = f"noise{i}_{j}"
store.insert_belief(Belief(
id=nid, content=_content(i + 200 + j), content_hash=f"h_{nid}",
alpha=1.0, beta=1.0, type=BELIEF_FACTUAL,
lock_level=LOCK_NONE, locked_at=None,
created_at="2026-06-01T00:00:00Z", last_retrieved_at=None,
))
store.insert_edge(Edge(src=src, dst=tgt, type=kind, weight=1.0))
rows.append((f"{kind}:{tgt}", src))
return rows


def _recall(store: MemoryStore, rows: list[tuple[str, str]], *,
use_lane: bool, k: int) -> float:
cache = HRRStructIndexCache(store=store, dim=512, seed=42) if use_lane else None
hits = 0
for query, answer in rows:
got = [
b.id for b in retrieve_v2(
store, query, use_hrr_structural=use_lane,
hrr_struct_index_cache=cache, budget=_BUDGET,
).beliefs[:k]
]
if answer in got:
hits += 1
return hits / len(rows)


def main() -> None:
store = MemoryStore(":memory:")
try:
rows = _build(store)
res = _Result(
n_rows=len(rows),
recall_off=_recall(store, rows, use_lane=False, k=3),
recall_on=_recall(store, rows, use_lane=True, k=3),
)
finally:
store.close()
print(f"synthetic corpus: {res.n_rows} marker queries "
f"({N_ROWS} edges, {_NOISE_PER_ROW} noise/row), budget={_BUDGET}, k=3")
print(f" recall@k OFF={res.recall_off:.3f} ON={res.recall_on:.3f} "
f"uplift={res.recall_uplift:+.3f}")
ship = res.recall_uplift > 0
print(f" ship condition (recall uplift > 0): {'PASS' if ship else 'FAIL'}")


if __name__ == "__main__":
main()
4 changes: 2 additions & 2 deletions docs/user/CONFIG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ This is the reference for power users whose project has a documentation idiom or
A single optional TOML file at the root of a project (or any ancestor). It exposes the following power-user surfaces:

- `[noise]` — onboard-time belief filter. Changes how `aelf onboard` ingests beliefs; nothing else.
- `[retrieval]` (v1.3+) — retrieval-time tier toggles + ranking. Knobs: `entity_index_enabled` (L2.5), `bfs_enabled` (L3), `posterior_weight` (partial Bayesian-weighted L1 ranking), `l1_limit` + `token_budget` (the #1045 wide-retrieval knobs — BM25 candidate cap + token budget, default 50/2400; raise both together for multi-hop recall), `use_bm25f_anchors` (BM25F-with-anchor-text since v1.7), `use_heat_kernel` (authority scoring lane, default-on since v2.1), `use_hrr_structural` (HRR structural-query lane, default-on since v2.1), `hrr_persist` (HRR structural-index on-disk persistence, default-on since v3.0), `use_type_aware_compression` (per-belief retention-class compression, default-on since #769), `use_intentional_clustering` (co-locating related beliefs, default-on since v3.0 — live on the production `retrieve()` path via the #1107 Phase-4 cutover), `expansion_gate_enabled`, `use_gamma_posterior_temperature` (default off), and `use_zeta_posterior_rerank` (default off; mutually exclusive with the γ flag — `retrieve()` raises `ValueError` when both are on), `use_temporal_spine` + `temporal_spine_budget` (the #1064 chronological-adjacency lane, default **on**/32 since v4.0 — live on the production `retrieve()` path via the #1107 cutover; pairs with `[ingest] write_temporal_spine`), `use_entity_persist_demote` (the #1096 entity-persistence demotion / organic-sink rerank modifier, default **on** since v4.0 — live on the production `retrieve()` path via the #1107 cutover), `use_origin_tiebreak` (the #1089 origin-priority within-tier tie-break, default off). Two placeholder flags (`use_signed_laplacian`, `use_posterior_ranking`) are recognised but emit a deprecation warning if set — their lanes have not yet shipped.
- `[retrieval]` (v1.3+) — retrieval-time tier toggles + ranking. Knobs: `entity_index_enabled` (L2.5), `bfs_enabled` (L3), `posterior_weight` (partial Bayesian-weighted L1 ranking), `l1_limit` + `token_budget` (the #1045 wide-retrieval knobs — BM25 candidate cap + token budget, default 50/2400; raise both together for multi-hop recall), `use_bm25f_anchors` (BM25F-with-anchor-text since v1.7), `use_heat_kernel` (authority scoring lane, default-on since v2.1), `use_hrr_structural` (HRR structural-query lane, default-on since v2.1 — live on the production `retrieve()` path via the #1107 Phase-5 cutover; marker-routed, a no-op fall-through on non-marker queries), `hrr_persist` (HRR structural-index on-disk persistence, default-on since v3.0), `use_type_aware_compression` (per-belief retention-class compression, default-on since #769), `use_intentional_clustering` (co-locating related beliefs, default-on since v3.0 — live on the production `retrieve()` path via the #1107 Phase-4 cutover), `expansion_gate_enabled`, `use_gamma_posterior_temperature` (default off), and `use_zeta_posterior_rerank` (default off; mutually exclusive with the γ flag — `retrieve()` raises `ValueError` when both are on), `use_temporal_spine` + `temporal_spine_budget` (the #1064 chronological-adjacency lane, default **on**/32 since v4.0 — live on the production `retrieve()` path via the #1107 cutover; pairs with `[ingest] write_temporal_spine`), `use_entity_persist_demote` (the #1096 entity-persistence demotion / organic-sink rerank modifier, default **on** since v4.0 — live on the production `retrieve()` path via the #1107 cutover), `use_origin_tiebreak` (the #1089 origin-priority within-tier tie-break, default off). Two placeholder flags (`use_signed_laplacian`, `use_posterior_ranking`) are recognised but emit a deprecation warning if set — their lanes have not yet shipped.
- `[rebuilder]` (v1.4+) — context-rebuilder knobs: `turn_window_n` (default 50), `token_budget` (default 4000), `trigger_mode` (`manual`|`threshold`|`dynamic`, default `threshold`), `threshold_fraction` (default 0.6), and `query_strategy` (v1.7+, default `stack-r1-r3` since v3.0). `[rebuild_floor]` (v1.7+) sets the token-budget floors for the session-scoped and L1 belief lanes (`[rebuild_floor] session` and `[rebuild_floor] l1`).
- `[onboard.llm]` (v1.3.0+) — direct-API onboard classifier gate; documented under [Keys § `[onboard.llm]`](#onboardllm-v130) below.
- `[cadence]`, `[implicit_feedback]`, and `[hook_audit]` — feedback-cadence scoring, deferred retrieval-exposure feedback, and the per-turn hook audit log. Recognised here but documented in their module docstrings (`src/aelfrice/cadence.py`, `src/aelfrice/deferred_feedback.py`, `src/aelfrice/hook.py`).
Expand Down Expand Up @@ -459,7 +459,7 @@ Precedence (first decisive wins): env var `AELFRICE_HEAT_KERNEL=0`/`1` > explici

### `use_hrr_structural`

Boolean, default `true` since the #154 composition tracker flipped the default after the #437 reproducibility-harness gate cleared at 11/11. Enables the HRR structural-query lane (#152). Wired into `retrieve_v2` as a parallel routing branch (per spec: not blended with the textual lane). When on, `retrieve_v2` parses the query for a structural marker before any other rewrite or lane fans out:
Boolean, default `true` since the #154 composition tracker flipped the default after the #437 reproducibility-harness gate cleared at 11/11. Enables the HRR structural-query lane (#152). Wired into `retrieve_v2` as a parallel routing branch (per spec: not blended with the textual lane), and **live on the production `retrieve()` path** since the #1107 Phase-5 cutover — until then the lane was resolver-default-ON on `retrieve_v2` but inert on the live hook path, which called the legacy `retrieve()`. Because the lane is marker-routed it is a byte-identical no-op fall-through on non-marker queries (the shape of a free-text hook prompt), so the graduation's blast radius is confined to callers that issue `<KIND>:<target_id>` queries. When on, `retrieve_v2` parses the query for a structural marker before any other rewrite or lane fans out:

```
query string -> parse_structural_marker
Expand Down
20 changes: 11 additions & 9 deletions src/aelfrice/retrieval.py
Original file line number Diff line number Diff line change
Expand Up @@ -3003,12 +3003,14 @@ def retrieve(
# so the production path honours its resolver (env -> TOML -> default)
# exactly like the eval surface. Graduated so far: **temporal spine**
# (#1064, Phase 2), **entity-persist demotion** (#1096, Phase 3 — the
# #1086 junk-percolation sink) and **intentional clustering** (#436,
# Phase 4 — multi-fact cluster-coverage, resolver default-ON since v3.0's
# A2/A3/A4 gate). The remaining three staged lanes (origin tie-break,
# HRR-expand, HRR-structural) stay forced OFF, because `retrieve()`'s
# historical pack loop never ran them; equivalence for those is pinned by
# tests/test_retrieve_v2_equivalence.py.
# #1086 junk-percolation sink), **intentional clustering** (#436, Phase 4 —
# multi-fact cluster-coverage, resolver default-ON since v3.0's A2/A3/A4
# gate) and the **HRR structural-query lane** (#152, Phase 5 — marker-routed
# `<KIND>:<target_id>` routing, resolver default-ON since v2.1's #154/#437
# gate; a no-op fall-through on non-marker queries). The remaining two
# staged lanes (origin tie-break, HRR-expand) stay forced OFF, because
# `retrieve()`'s historical pack loop never ran them; equivalence for those
# is pinned by tests/test_retrieve_v2_equivalence.py.
out = retrieve_v2(
store,
query,
Expand All @@ -3033,14 +3035,14 @@ def retrieve(
# Graduated lanes (#1107): resolver-driven (env -> TOML -> default)
# rather than hard-off, so a production host gets the lane the moment
# its resolver says on. temporal spine #1064 (Phase 2), entity-persist
# demotion #1096 (Phase 3), intentional clustering #436 (Phase 4) —
# all resolver default-ON.
# demotion #1096 (Phase 3), intentional clustering #436 (Phase 4),
# HRR structural-query lane #152 (Phase 5) — all resolver default-ON.
use_temporal_spine=None,
use_entity_persist_demote=None,
use_intentional_clustering=None,
use_hrr_structural=None,
use_origin_tiebreak=False,
use_hrr_expand=False,
use_hrr_structural=False,
).beliefs
# v1.6.0 #191: enqueue one retrieval_exposure row per surfaced belief
# for the deferred-feedback sweeper. Default-on; opt-out via
Expand Down
Loading
Loading