Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs(server): shorten comments in the get_answer tool package (#2576)

Raghav Chamadiyaec7bdb3b5210
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py
index 728503b4a..7b077c411 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py
@@ -190,10 +190,8 @@ from repowise.server.mcp_server.tool_answer.synthesis import (
_log = logging.getLogger("repowise.mcp.answer")
-# The excerpt fetch and the prompt formatter each cap page content, and they
-# live in different modules — which is how the formatter came to discard more
-# than half of every excerpt the fetch had paid a database round-trip for.
-# Checked here, at import, because this is the only module that sees both.
+# The excerpt fetch and the prompt formatter each cap page content in different
+# modules; checked at import here, the only module that sees both caps.
if _MAX_CHARS_PER_HIT_EXCERPT < _GATED_EXCERPT_CHARS:
raise RuntimeError(
"get_answer would truncate the page content it fetches: the prompt "
@@ -222,15 +220,9 @@ async def _run_retrieval_pipeline(
) -> _Retrieved:
"""Run every retrieval, ranking and enrichment stage, in order.
- Everything here is about FINDING the material; nothing here decides what
- the answer is. Each expansion stage is best-effort and suppressed on its
- own, so one slow or broken backend costs its contribution and never the
- call.
-
- Stages live in ``_answer_pipeline`` so each can evolve without rereading the
- orchestrator: hybrid retrieval (FTS + vector + RRF) → hydration → coverage
- rerank → domain penalty → intersection boost → PageRank bias → 1-hop graph
- expansion. This function only sequences them and decides when to stop.
+ Everything here is about FINDING the material; nothing decides the answer.
+ Each expansion stage is best-effort and suppressed on its own, so one slow
+ or broken backend costs its contribution and never the call.
"""
hits = await _hybrid_retrieve(question, ctx)
hits = await _hydrate_hits(hits, ctx, scope=scope)
@@ -239,39 +231,23 @@ async def _run_retrieval_pipeline(
# they never enter ranking, citations, or fallback_targets.
hits = filter_dicts_by_key(hits, "target_path", exclude_spec)
- # Identifiers the question names explicitly — drives symbol anchoring
- # (below) and question-aware symbol promotion (during hydration).
question_ids = _extract_question_identifiers(question)
- # Term-coverage re-rank before any graph-aware bias so conjunctive
- # matches survive the merge.
+ # Coverage re-rank before any graph-aware bias so conjunctive matches survive.
hits = _rerank_by_coverage(hits, question)
- # Domain heuristic: down-weight cross-domain hits (e.g. UI files for a
- # clearly backend question). Cheap tie-breaker, never a hard filter.
_apply_domain_penalty(hits, question)
- # Intersection-retrieval boost for relational questions (multi-entity).
- # Pages at the intersection of two split-FTS halves get a 2× bonus.
with contextlib.suppress(Exception):
await _intersection_boost(question, hits, ctx)
- # PageRank bias: nudge architecturally central files above peripheral
- # ones at the same retrieval score. Damped + normalised within the
- # candidate set so it's a tie-breaker, not a wholesale reordering.
+ # Damped and normalised within the candidate set: a tie-breaker only.
with contextlib.suppress(Exception):
await _apply_pagerank_bias(hits, ctx)
- # Graph expansion: 1-hop walk from the top hits to rescue near-misses
- # where retrieval landed in the right module but on the wrong file
- # (consumer instead of orchestrator). Adds up to 3 neighbors with a
- # damped score, then re-sorts.
+ # 1-hop walk rescues "right module, wrong file" near-misses.
with contextlib.suppress(Exception):
hits = await _expand_via_graph(hits, ctx, repo_id)
- # Re-filter: graph expansion can pull excluded neighbors back in (before the
- # cap, so an excluded neighbor can't occupy a top-5 slot).
+ # Graph expansion can pull excluded neighbors back in; re-filter before the cap.
hits = filter_dicts_by_key(hits, "target_path", exclude_spec)
- # Symbol anchoring: when the question names an indexed function / method /
- # class, force its defining file into the candidate set as a dominant hit.
- # Fuzzy retrieval misses deep-path definitions even when the symbol is
- # indexed; this makes "explain X" one-shot-complete instead of degrading
- # to best_guesses on plausible-but-wrong neighbors.
+ # Symbol anchoring: force a question-named symbol's defining file in as a
+ # dominant hit, since fuzzy retrieval misses deep-path definitions.
homonyms: dict = {"union": {}, "qualified_miss": []}
if question_ids:
with contextlib.suppress(Exception):
@@ -285,77 +261,47 @@ async def _run_retrieval_pipeline(
repo_root=_anchor_root,
session_factory=ctx.session_factory,
)
- # Concept anchoring: when a why/value question pins a literal number to a
- # described behaviour (no named symbol), grep source COMMENTS for the file
- # that justifies the number and anchor it as a dominant hit. Rescues the
- # retrieval-miss class where the rationale lives in a code comment fuzzy
- # retrieval did not rank.
+ # Concept anchoring: a why/value question pinning a number to a behaviour
+ # anchors the file whose source comment justifies that number.
if _is_why_question(question) or _is_value_question(question):
with contextlib.suppress(Exception):
hits = await _concept_anchor_hits(getattr(ctx, "path", None), question, hits)
- # Flow-path expansion: when the question anchors 2+ endpoints (a named
- # symbol's file, a module it names), lead with the dependency/call path
- # between them. Plain 1-hop expansion (above) rescues "right module wrong
- # file" ranking misses; it does NOT reach a far endpoint 2-4 hops away that
- # the question names but retrieval never ranked. This threads that path over
- # imports + projected calls edges and injects its files so both endpoints
- # surface in one call. Runs before the cap so an injected endpoint can take a
- # top-5 slot.
+ # Flow-path expansion: when the question anchors 2+ endpoints, inject the
+ # files on the path between them, reaching a far endpoint 1-hop expansion
+ # cannot. This and the stages below run before the cap so an injected file
+ # can take a top-5 slot.
flow_paths: list[list[str]] = []
with contextlib.suppress(Exception):
async with get_session(ctx.session_factory) as session:
hits, flow_paths = await _expand_via_flow_path(
session, repo_id, hits, question, question_ids
)
- # Neighborhood re-rank: the sibling to flow-path expansion for the flow
- # questions it can't reach — the ones whose gold file is never *named*. Seeds
- # from the top hits, walks 1-2 hops out over the same graph, and re-ranks the
- # reached neighborhood by fused embedding+lexical relevance so a far endpoint
- # that lost the corpus-wide retrieval but wins within its own subsystem gets
- # a top-5 slot. Additive and gated to flow-shaped questions; a no-op
- # otherwise. Runs before the cap so an injected file can land in the top-5.
+ # Neighborhood re-rank: for flow questions whose target file is never named,
+ # re-rank the 1-2 hop neighborhood of the top hits. No-op on other shapes.
with contextlib.suppress(Exception):
async with get_session(ctx.session_factory) as session:
hits = await _expand_via_neighbor_rerank(session, repo_id, hits, question, ctx)
- # Parent-concept surfacing: on a subsystem-shaped question ("overview of X",
- # "what subsystem does Y belong to", "where would I add a Z"), lead with the
- # concept/rollup page that documents the whole subsystem instead of the more
- # specific child pages retrieval ranks above it. Structural + query-shape
- # only; a no-op on every other question, so file/implementation queries keep
- # today's ranking. Runs before the cap so the parent can take a top-5 slot.
+ # Parent-concept surfacing: a subsystem-shaped question leads with the
+ # rollup page for the subsystem. No-op on other shapes.
with contextlib.suppress(Exception):
hits = await _expand_via_parent_page(hits, question, ctx)
- # Demote retrieval noise (decision records on non-why questions, test file
- # pages on non-test questions) below real pages before the cap, so it can't
- # occupy a top-5 slot and feed synthesis. Stable and non-dropping; runs after
- # all anchoring/expansion (which inject file/symbol pages, never noise) so it
- # only reorders what those stages left in place.
+ # Demote noise (decisions on non-why, test pages on non-test questions)
+ # below real pages. Non-dropping; after anchoring, which never injects noise.
hits = _demote_noise_hits(hits, question, is_why=_is_why_question(question))
- # Everything retrieval resolved, in rank order, before the cap. Synthesis
- # keeps its 5-hit budget, which is a context-window decision and the
- # right one, but the files below the cut are still the best answer to
- # "where do I look next", and they used to be discarded. ``candidates``
- # (built after synthesis) hands them over at one line each.
+ # The pre-cap ranking feeds ``candidates``: files below the synthesis cut
+ # are still the best answer to "where do I look next".
resolved_pool = list(hits)
- # Always cap retrieval hits at 5 for the response payload.
hits = hits[:5]
- # Enrich each file_page hit with its top-N WikiSymbol rows. Question-
- # aware: identifiers extracted from the question promote matching
- # symbols and attach a source-body excerpt — the difference between a
- # hedged answer on a specific-method question and a grounded one.
+ # Question-aware symbol hydration: matching symbols get a body excerpt.
if hits:
with contextlib.suppress(Exception):
async with get_session(ctx.session_factory) as session:
await _hydrate_symbols_for_hits(
session, repo_id, hits, ctx, question_ids=question_ids, question=question
)
- # And the shortlist BELOW the synthesis cap: `candidates` names
- # those files and, until now, said nothing about any of them.
- # Runs here, sharing the open session, and against
- # `resolved_pool` rather than `hits` because the whole point is
- # the files the cap discarded. Suppressed with the block above:
- # a missing `_defines` costs a `defines` key, never an answer.
+ # Against `resolved_pool`: the point is the files below the cap.
+ # A missing `_defines` costs a `defines` key, never an answer.
await _hydrate_candidate_defines(
session, repo_id, resolved_pool, question_ids=question_ids
)
@@ -420,15 +366,8 @@ async def get_answer(
repo_id = repository.id
# --- Data-shape fast path ----------------------------------------------
- # "what fields does each entry in <blob> contain" is answered by mining the
- # field set straight from source (a documented {...} shape, else consistent
- # key accesses) instead of gating to a best_guesses pointer list — the exact
- # payload that triggers the agent's Read/get_symbol drill. Runs before the
- # cache and retrieval: it's deterministic from live source, cheap, and reads
- # the field set directly (retrieval scatters across every file that touches
- # the blob and misses the one file that documents it). Returns None (falls
- # through) unless the fields are genuinely grounded, so it can never invent a
- # shape.
+ # Before cache and retrieval: deterministic from live source, and retrieval
+ # scatters across every consumer of the blob. Falls through unless grounded.
ds_ids = _extract_question_identifiers(question)
if _is_data_shape_question(question, ds_ids):
grounded = await asyncio.to_thread(mine_data_shape, getattr(ctx, "path", None), ds_ids)
@@ -462,16 +401,8 @@ async def get_answer(
homonyms = retrieved.homonyms
flow_paths = retrieved.flow_paths
- # Agreement dominance recovers the "both retrievers rank this #1" signal that
- # RRF fusion compresses out of the numeric score. Computed once and OR'd into
- # every place dominance is decided, so it can only LIFT a retrieval.
- # Read the vector leg's own recorded status rather than inferring it from
- # `hits`, which is capped to 5 by here: "no _vec_rank in the top 5" is also
- # what a timed-out, errored, scope-filtered or simply outranked vector leg
- # looks like, and those must NOT fall back to the symbol leg.
- #
- # Above the early returns because they rate their retrieval too. Pure over
- # `hits` and the recorded leg status, both settled by the pipeline call above.
+ # Computed once, above the early returns (they rate retrieval too). The leg
+ # status is read, not inferred from the capped `hits`; see _agreement_dominant.
agreement_dominant = (
_agreement_dominant(
hits,
@@ -484,10 +415,8 @@ async def get_answer(
)
# --- Qualified-miss guard ----------------------------------------------
- # The question qualified a symbol (``Parent.leaf``) but the exact-name scan
- # found the leaf only under OTHER parents. Return not-found rather than
- # synthesizing from a same-named symbol elsewhere: a precise query must
- # never degrade to a confidently-wrong answer.
+ # ``Parent.leaf`` found only under OTHER parents: not-found, never a
+ # confidently-wrong answer from a same-named symbol elsewhere.
if homonyms.get("qualified_miss"):
missed = homonyms["qualified_miss"]
return _with_candidates(
@@ -524,11 +453,8 @@ async def get_answer(
]
if not hits:
- # Wrapped like every other post-retrieval return even though the pool is
- # necessarily empty here (``resolved_pool`` is ``hits`` before the cap, so
- # no hits means no pool). Keeping the invariant "every return after
- # retrieval goes through ``_with_candidates``" is what stops the next
- # reordering of this function quietly re-opening the hole.
+ # The pool is empty here, but every post-retrieval return goes through
+ # ``_with_candidates`` so a later reordering cannot skip it.
return _with_candidates(
_no_answer_payload(
"No wiki hits for this question. Rephrase around the code "
@@ -539,16 +465,9 @@ async def get_answer(
resolved_pool,
)
- # Attach real page content to the top hits, once, for every retrieval —
- # before anything downstream branches on how good the retrieval looks.
- #
- # This used to run only when retrieval was NOT dominant, and dominance is
- # what earns high confidence: the more certain retrieval was, the less
- # prose the model was given, so confident answers were the ones built from
- # symbol names alone. Whatever replaces the code below, keep this
- # unconditional. Two call sites under different conditions is what made
- # that inversion possible, and the cost of enriching a hit that a later
- # fast path never reads is one indexed SELECT over at most five rows.
+ # Page content for the top hits, unconditionally, before anything branches
+ # on retrieval quality: gating it on dominance starves the confident
+ # answers of prose. The cost is one indexed SELECT over at most five rows.
hits_without_page_content = await _attach_page_excerpts(hits, ctx)
if hits_without_page_content:
_log.warning(
@@ -559,17 +478,9 @@ async def get_answer(
)
# --- Retrieval dominance -----------------------------------------------
- # ``dominant`` = retrieval clearly pointed at ONE page (the top hit
- # outscores the rest). It no longer decides WHETHER to synthesize — under
- # the always-synthesize default, synthesis runs for every retrieval so
- # coverage matches a research assistant that answers every question. It now
- # feeds the confidence grade (as the starting grade AND the ceiling), rates
- # the retrieval, and gates the ambiguous-retrieval evidence folded into the
- # reply. All of those read `dominance_reason`, where the two-tier test now
- # lives: a second copy of it inside the grade is what let one payload claim
- # the top result dominated and append the no-dominant-page caveat to the same
- # note. The grade takes the TIER rather than the bool, because the note it
- # writes may only quote the measurement that was actually made.
+ # Under always-synthesize, dominance feeds the grade, the retrieval rating
+ # and the ambiguity evidence rather than deciding whether to synthesize.
+ # The grade takes the TIER so its note quotes only the measurement made.
always_synthesize = _always_synthesize()
dominance = dominance_reason(hits, agreement_dominant=agreement_dominant)
dominant = dominance is not None
@@ -587,14 +498,9 @@ async def get_answer(
resolved_pool,
)
- # Confidence is the only axis we gate on. We deliberately do NOT add a
- # second gate keyed on question shape (e.g. relational questions
- # containing connectives like "between", "and", "from"). Relational vs
- # non-relational is the wrong axis to gate on: the hard relational
- # failures already surface as low-dominance retrievals and are caught
- # by the gate above, while a shape-based gate over-fires on confidently
- # dominant relational questions and pushes cost back onto the agent's
- # own reasoning loop.
+ # No second gate on question shape (e.g. relational connectives): hard
+ # relational failures already show as low dominance, and a shape gate
+ # over-fires on dominant relational questions.
# --- Value-extraction fast path ----------------------------------------
# Value-shaped question + a question-matched constant in the top hits →
@@ -614,9 +520,8 @@ async def get_answer(
)
# --- Synthesis (LLM) ---------------------------------------------------
- # Both ways synthesis can go missing return the same payload from the same
- # evidence, so they name only what differs between them: why, and what to
- # tell the caller.
+ # Both ways synthesis can go missing share one payload; they differ only in
+ # the reason and the note.
async def _degrade(reason: str, note: str) -> dict:
payload = await _degraded_payload(
reason=reason,
@@ -639,10 +544,8 @@ async def get_answer(
provider = _resolve_provider_for_answer(getattr(ctx, "path", None))
if provider is None:
- # Retrieval-only mode (no provider). Return the hits so the agent can
- # at least skip the search_codebase step — but mark the degradation
- # loudly: an arm/user should never need to diff payload shapes to
- # notice synthesis is unplugged.
+ # Retrieval-only mode, logged loudly so nobody has to diff payload
+ # shapes to notice synthesis is unplugged.
_log.warning(
"get_answer running WITHOUT synthesis: no LLM provider resolvable "
"(set REPOWISE_PROVIDER + its API key, or any supported API key)."
@@ -652,10 +555,8 @@ async def get_answer(
"Synthesis is unavailable; local retrieval and source evidence remain usable.",
)
- # Decision fusion (why-shaped questions only) + structured prelude. Both
- # layers are gated on signal: no ADRs for the top hits → no decisions
- # block, no symbols / commits / decisions → no prelude. Empty layers are
- # dropped before formatting, so the prompt never carries hollow scaffolding.
+ # Decision fusion (why questions only) and the structured prelude are both
+ # dropped when empty, so the prompt never carries hollow scaffolding.
top_paths = [h["target_path"] for h in hits if h.get("target_path")]
decisions: list[dict] = []
if _is_why_question(question) and top_paths:
@@ -671,10 +572,8 @@ async def get_answer(
context=_build_context_block_v2(hits, prelude=prelude, decisions=decisions),
)
- # The call budgets itself against what this provider actually needs. A
- # remote API answers in single-digit seconds; an agent-CLI subprocess or a
- # local model needs minutes, and a flat 30s cancelled every one of those
- # before it could return.
+ # Budgets its own timeout per provider: a remote API needs seconds, a CLI
+ # subprocess or local model needs minutes.
answer_text, failure_note = await synthesize(
provider,
_SYSTEM_PROMPT,
@@ -695,11 +594,8 @@ async def get_answer(
quotes = build_quotes(hits, answer_text)
- # ``served_named_body`` is True once a tier-0 body (the exact symbol the
- # question named, resolved by symbol anchoring) is inlined. Its full live
- # body IS the ground truth, so a response carrying it is content-grounded
- # even when synthesis hedges. The confidence gates read this to avoid the
- # "low, go Read" label that contradicts a payload already holding the answer.
+ # ``served_named_body``: the question-named symbol's live body is inlined, so
+ # the response is content-grounded even when synthesis hedges.
repo_root = _repo_root(ctx)
symbol_bodies, served_named_body = _build_symbol_bodies(
_gather_body_candidates(hits, answer_text), repo_root
@@ -735,17 +631,11 @@ async def get_answer(
exclude_spec=exclude_spec,
)
- # Flow-path lead: when the question anchored 2+ endpoints, surface the
- # dependency/call chain the answer traverses so the agent sees the path in
- # the same call instead of reconstructing it hop by hop.
if flow_paths:
payload["flow_path"] = [" -> ".join(p) for p in flow_paths[:2]]
- # Where to look next, always. ``retrieval`` shrinks as confidence rises
- # (correctly: it is re-read evidence, and a trustworthy answer needs less
- # of it), but that left the highest-confidence answers naming no file at
- # all, which is the one thing an agent always has a use for. This block is
- # navigation rather than evidence: the ranked shortlist, one path per line.
+ # Where to look next, always: navigation, not evidence, so it survives the
+ # shrinking of ``retrieval`` on high-confidence answers.
candidates = _serialize_candidates(resolved_pool)
if candidates:
payload["candidates"] = candidates
@@ -777,19 +667,12 @@ async def get_answer(
repository=repository,
targets=[*citations, *fallback_targets],
)
- # Each retrieval leg is best-effort so one slow backend cannot block an
- # answer, which is right, but it made a lexical-only answer indistinguishable
- # from a whole one: nothing failed, nothing was logged where a caller could
- # see it, and ``embedder_live`` stayed true because a configured embedder is
- # live whether or not this call beat its budget. Named only when a leg
- # actually fell over, so a healthy response pays nothing for it.
+ # Legs are best-effort, so a lexical-only answer would otherwise look whole.
+ # Named only when a leg fell over.
if degraded:
payload["_meta"]["retrieval_degraded"] = degraded
- # After the cache write above, deliberately. That write copies the payload
- # as it stood then, so the episode reaches the caller and never the cache
- # row, which is why adding it needs no _ANSWER_SCHEMA_VERSION bump: a row
- # written before this change and one written after are the same bytes, and
- # bumping would invalidate every user's cache for a field that is not in it.
+ # After the cache write on purpose: the episode never reaches the cache row,
+ # so it needs no _ANSWER_SCHEMA_VERSION bump.
await _attach_episode(
payload,
question=question,
@@ -799,11 +682,8 @@ async def get_answer(
return payload
-# Keep the orchestrator as a literal ``get_answer`` definition for the source-
-# shape invariants that audit its early returns. The exported function below is
-# also literal (rather than a decorator-generated coroutine), because CLI tool
-# adapters inspect ``cr_code.co_qualname`` to confirm they invoked the requested
-# tool. Both paths still share the one projector here.
+# Both definitions are literal ``get_answer``: source-shape tests audit the
+# orchestrator's early returns, and CLI adapters check ``cr_code.co_qualname``.
_get_answer_raw = get_answer
_projected_get_answer = projected_answer(_get_answer_raw)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/bodies.py b/packages/server/src/repowise/server/mcp_server/tool_answer/bodies.py
index 1325d641d..32bd79fb5 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/bodies.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/bodies.py
@@ -40,10 +40,8 @@ def _gather_body_candidates(
order. Only definitions the answer text actually names qualify; constants
stay in ``quotes``.
- ``anchor_names`` switches tier 0 off the prose and onto the identifiers the
- QUESTION named: the degraded path, where there is no synthesised text to
- match against. Tier 1 is skipped in that mode by construction, since it
- exists to catch a symbol only the prose names.
+ ``anchor_names`` switches tier 0 onto the identifiers the QUESTION named,
+ for the degraded path that has no prose; tier 1 is skipped there.
"""
candidates: list[tuple[int, int, int, str, dict]] = []
for h in hits[:_ENRICH_TOP_N_HITS]:
@@ -53,8 +51,7 @@ def _gather_body_candidates(
for s in h.get("_anchor_symbols") or []:
if _selection_names(s.get("name"), answer_text, anchor_names):
candidates.append((0, _kind_rank(s), s.get("start_line") or 0, path, s))
- # Tier 1 exists to catch a symbol only the PROSE names, so it has
- # nothing to do in the degraded mode that has no prose.
+ # Tier 1 catches symbols only the prose names; the degraded mode has none.
if anchor_names is not None:
continue
for s in h.get("symbols") or []:
@@ -67,11 +64,8 @@ def _gather_body_candidates(
def _selection_names(name: str | None, answer_text: str, anchor_names: set[str] | None) -> bool:
"""Whether the text that selects bodies names this symbol.
- Two selection texts, one predicate: normally the synthesised answer decides
- which definitions are worth inlining, but the degraded path has no prose, so
- ``anchor_names`` puts the question's own identifiers in its place. Note the
- difference in kind: ``anchor_names`` is an exact set membership, the answer
- text a substring match.
+ ``anchor_names`` (exact membership) stands in for the answer text
+ (substring match) on the degraded path, which has no prose.
"""
if not name:
return False
@@ -109,21 +103,13 @@ def _build_symbol_bodies(
) -> tuple[list[dict], bool]:
"""Inline the ranked definitions as live source, with the truncation contract.
- Returns ``(symbol_bodies, served_named_body)``. ``served_named_body`` is True
- once a tier-0 body (the exact symbol the question named) is inlined; the
- confidence gates read it to avoid the "low, go Read" label on a payload that
- already holds the answer.
-
- Every step here is prose-independent: the body is re-read live from disk at
- the indexed bounds, and when the indexed body outruns the line cap a
- ``continuation`` names the exact range read for the remainder plus the
- ``withheld_symbols`` it covers. That is why the degraded path can call this
- too.
-
- ``source`` is the live body sliced at the indexed bounds. ``verified: True``
- is set only when the cheap bounds gate holds on the live file (the name is
- still on its definition line and the stored end still closes the body), the
- same gate get_symbol uses; an entry that fails it carries no such key.
+ Returns ``(symbol_bodies, served_named_body)``; the latter is True once a
+ tier-0 body (the exact symbol the question named) is inlined.
+
+ Prose-independent, so the degraded path calls it too: bodies are re-read
+ live at the indexed bounds, and a body past the line cap gets a
+ ``continuation`` and its ``withheld_symbols``. ``verified: True`` is set
+ only when get_symbol's bounds gate holds on the live file.
"""
symbol_bodies: list[dict] = []
seen: set[tuple[str, str]] = set()
@@ -136,10 +122,8 @@ def _build_symbol_bodies(
if (path, name) in seen:
continue
sym_end = s.get("end_line") or 0
- # Re-read a fuller body than the synthesis excerpt: this block is for
- # the agent, so a docstring-heavy def shouldn't spend its whole window
- # on docstring and truncate the logic the question asked about. Falls
- # back to the hydrator's excerpt if the re-read fails.
+ # A fuller body than the synthesis excerpt, so a docstring-heavy def
+ # still reaches its logic. Falls back to the hydrator's excerpt.
if path not in texts:
texts[path] = _read_repo_text(repo_root, path)
text = texts[path]
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/cache.py b/packages/server/src/repowise/server/mcp_server/tool_answer/cache.py
index 971606abf..f15334ac9 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/cache.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/cache.py
@@ -32,9 +32,8 @@ _log = logging.getLogger("repowise.mcp.answer")
def _json_default(obj):
"""Serialize the non-JSON types retrieval hits carry (``_sources`` sets).
- Before this fallback existed, EVERY cache write failed on the sets the
- hybrid retriever attaches to hits — silently, under the old blanket
- suppress. The cache never stored a single post-hybrid-pipeline answer.
+ Without it every cache write fails on the sets the hybrid retriever
+ attaches to hits.
"""
if isinstance(obj, (set, frozenset)):
# str-key the sort: a serializer whose whole job is "never fail the
@@ -77,22 +76,13 @@ def _cache_bypass_reason(
Each reason is logged where it is decided, with its own values, so the log
says why a caller got a fresh synthesis rather than merely that it did.
- * schema: payloads from a pre-rework code path do not carry the fields the
- current consumer expects. Serving them masks every later improvement until
- the row happens to expire, so bypass silently and let the next write
- upgrade the row.
- * hedged: the retrieval and symbol pipeline has been upgraded since, so give
- synthesis another shot with the new context rather than pinning a bad
- answer.
- * empty: older versions cached gated empty-answer payloads, which pinned a
- retrieval miss until TTL. The write side no longer does this; the check
- retires the rows that predate the fix.
- * excluded: a row cached before ``exclude_patterns`` changed may reference a
- now-excluded file in its fields or in its prose. Re-synthesize rather than
- scrub the fields and leave the prose dangling.
- * commit / TTL: a row synthesised against a previous index may cite moved
- code or stale values. The TTL covers pre-stamping rows and gitless repos,
- where there is no commit to compare.
+ * schema: an older shape would mask every later improvement until expiry.
+ * hedged: give synthesis another shot rather than pin a bad answer.
+ * empty: retires gated empty-answer rows the write side no longer makes.
+ * excluded: the row references a now-excluded file, possibly in its prose,
+ so re-synthesize rather than scrub fields and leave the prose dangling.
+ * commit / TTL: the row may cite moved code; the TTL covers unstamped rows
+ and gitless repos.
"""
cached_version = payload.get("_schema_version", 1)
if cached_version < _ANSWER_SCHEMA_VERSION:
@@ -164,9 +154,7 @@ async def _serve_cached_answer(
targets=[p for p in cached_paths if isinstance(p, str) and p],
extra=({"retrieval_degraded": retrieval_degraded} if retrieval_degraded else None),
)
- # Serve-time, on this path as well as the fresh one: the episode is read
- # on every call and never cached into an answer, so a disagreement
- # cannot be frozen into a row and served after it has been superseded.
+ # Serve-time on this path too, so an episode is never frozen into a row.
await _attach_episode(
payload,
question=question,
@@ -190,14 +178,10 @@ async def _write_answer_cache(
) -> None:
"""Persist this answer as the cache row for the question (upsert).
- Best-effort: a cache failure must never block the response, but it must be
- LOGGED rather than suppressed. A plain INSERT under a blanket suppress
- violated ``uq_answer_cache_q`` on every bypass-and-resynthesize round and
- failed silently, so hedged and stale rows were never upgraded.
- Delete-then-insert in one transaction is the dialect-agnostic upsert. It
- also removes the legacy question-only identity on the first successful
- synthesis, while the versioned lookup guarantees that row is never served.
- The stamped ``_indexed_commit`` is what the read-side freshness check reads.
+ Best-effort, but LOGGED rather than suppressed, so a failing write cannot
+ silently leave stale rows in place. Delete-then-insert in one transaction
+ is the dialect-agnostic upsert (``uq_answer_cache_q``), and also removes the
+ legacy question-only identity.
The row is a shallow copy taken here, so anything the caller attaches to the
payload after this point reaches the caller and never the cache.
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.py b/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.py
index 32635f13b..f6be5aacf 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.py
@@ -44,15 +44,9 @@ from repowise.server.mcp_server.tool_answer.symbols import is_symbol_lookup_ques
def _answer_is_hedged(answer_text: str) -> bool:
"""True when the synthesized answer confesses it can't answer.
- Retrieval dominance alone doesn't tell you whether the LLM produced a
- usable answer — the underlying model happily admits insufficiency even
- on a top-scoring hit. Treat an admitted non-answer as low confidence,
- regardless of how dominant retrieval was.
-
- Typographic apostrophes are normalized to ASCII first: the markers use
- plain "can't" / "i can't", but the LLM routinely emits the curly U+2019,
- which would slip every apostrophe-bearing marker and let a hedged answer
- ride through as high confidence.
+ The model admits insufficiency even on a top-scoring hit, so an admitted
+ non-answer is low confidence however dominant retrieval was. Curly
+ apostrophes are normalized first, or they would slip every "can't" marker.
"""
low = (answer_text or "").lower().replace("\u2019", "'").replace("\u02bc", "'")
return any(marker in low for marker in _HEDGE_MARKERS)
@@ -76,11 +70,8 @@ _FILE_LINE_REF_RE = re.compile(r"[\w./-]+:\d+(?:-\d+)?")
# matching sentence-final numbers ("the default is 3.").
_NUMBER_RE = re.compile(r"(?<![\w.])-?\d+(?:\.\d+)?(?!\w)(?!\.\d)")
-# Digit-grouping separators: ``100_000`` (source) and ``100,000`` (prose) are
-# the same value as ``100000``. Strip them on both sides before comparing, or
-# a correct constant like ``MAX = 100_000`` reads as ungrounded against an
-# answer that says "100000" — a false downgrade on the exact value-shaped
-# constants this gate exists to protect.
+# Digit-grouping separators: ``100_000`` and ``100,000`` equal ``100000``.
+# Stripped on both sides, or a correct constant reads as ungrounded.
_THOUSANDS_SEP_RE = re.compile(r"(?<=\d)[,_](?=\d)")
@@ -126,11 +117,9 @@ def _retrieval_corpus(hits: list[dict], *, include_paths: bool = False) -> str:
v = s.get(key)
if v:
parts.append(str(v))
- # A concept-anchored hit carries a rationale comment mined live from the
- # source. It grounds the question's number (the comment was selected
- # because it contains it) and is surfaced to the agent as code_rationale.
- # Without it the value/frame gates would flag the (correct) number the
- # answer echoes from the question as if synthesis invented it.
+ # A concept-anchored hit's rationale comment was selected for containing
+ # the question's number; without it the value/frame gates would flag the
+ # correct number the answer echoes as invented.
cr = h.get("_concept_rationale")
if isinstance(cr, dict) and cr.get("comment"):
parts.append(str(cr["comment"]))
@@ -145,11 +134,8 @@ def _retrieval_corpus(hits: list[dict], *, include_paths: bool = False) -> str:
def _ungrounded_numbers(answer_text: str, hits: list[dict]) -> list[str]:
"""Numbers the answer asserts that appear nowhere in the retrieval material.
- The exact failure this guards: synthesis confidently inventing a default
- ("the minimum count is 3") when no retrieved excerpt ever contained a 3.
- Compares the answer's standalone numbers against the numbers present in
- everything the LLM was shown for the hits — titles, summaries, snippets,
- and hydrated symbols (signatures, docstrings, source excerpts).
+ Guards against synthesis inventing a default ("the minimum count is 3")
+ when no retrieved excerpt contained a 3.
"""
asserted = _asserted_numbers(answer_text)
if not asserted:
@@ -159,28 +145,19 @@ def _ungrounded_numbers(answer_text: str, hits: list[dict]) -> list[str]:
return sorted(asserted - grounded)
-# Identifier-shaped tokens an answer uses to NAME a mechanism: CamelCase
-# (``PageRank``), snake_case (``apply_pagerank_bias``), dotted paths
-# (``Foo.bar``), or anything bearing a digit. Pure-lowercase English
-# (``centrality``, ``fallback``, ``cache``) is intentionally excluded —
-# only distinctive, code-like terms are strong enough signal that a wrong
-# "why" frame imported a foreign name. Mirrors the question-identifier
-# shape rule in ``symbols._extract_question_identifiers``.
+# Identifier-shaped tokens an answer uses to NAME a mechanism (CamelCase,
+# snake_case, dotted, digit-bearing). Plain lowercase English is excluded: only
+# code-like terms signal that a wrong frame imported a foreign name.
_FRAME_TOKEN_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*")
def _distinctive_terms(text: str) -> set[str]:
"""Identifier-shaped terms in *text*: internal-caps, snake_case, or digit.
- A LEADING capital alone is NOT enough. Sentence-initial words and markdown
- headers (``Because``, ``Determine``, ``Mechanism``, ``Short``, ``Since``,
- ``What``) are prose, not mechanisms — they never appear verbatim in source,
- so an "any uppercase" rule flags them as ungrounded frame terms and the gate
- over-fires on the answer's own formatting. Requiring an *internal* uppercase
- letter keeps real code names (``PageRank``, ``WikiSymbol``, ``AnswerCache``,
- ``API``) while dropping capitalized English. A single leading-cap class name
- (``Repository``) is conservatively skipped too: missing a frame term only
- weakens the gate, whereas over-firing on prose breaks it.
+ A leading capital alone is not enough: sentence-initial words and headers
+ (``Because``, ``What``) would read as ungrounded frame terms. A single
+ leading-cap class name is skipped too, since missing a frame term only
+ weakens the gate while over-firing on prose breaks it.
"""
terms: set[str] = set()
for tok in _FRAME_TOKEN_RE.findall(text or ""):
@@ -198,13 +175,10 @@ def _frame_term_grounding(
) -> tuple[list[str], int]:
"""Split the answer's mechanism-naming terms by whether retrieval grounds them.
- Returns ``(ungrounded, grounded_count)``. A wrong "why" frame betrays
- itself by importing a distinctive code-like term — a class, a function,
- a module — that the cited material never contained, while the surface
- facts (the number, the file) can be right. This surfaces the absent
- terms so the gate can downgrade when they are not outweighed by grounded
- ones. Terms the question itself named are excluded: echoing the user's
- own framing is not a synthesised frame.
+ Returns ``(ungrounded, grounded_count)``. A wrong "why" frame betrays itself
+ by importing a code-like term the cited material never contained, even when
+ the surface facts are right. Terms the question named are excluded: echoing
+ the user's framing is not a synthesised frame.
"""
answer_terms = _distinctive_terms(answer_text)
if not answer_terms:
@@ -224,12 +198,9 @@ def _frame_term_grounding(
return sorted(ungrounded), grounded
-# Unattributed exclusivity tokens. Words like "entirely" / "the sole" assert
-# a global property ("I have seen every relevant site") that get_answer cannot
-# observe from a top-k slice. They are only valid when the retrieved material
-# itself makes the claim (a type constraint, an assertion, an explicit comment).
-# "always" / "never" are intentionally excluded — those are temporal, not
-# spatial exhaustiveness claims, and are legitimate when quoting a constraint.
+# Unattributed exclusivity tokens: they assert a global property a top-k slice
+# cannot observe. "always" / "never" are excluded: temporal, not spatial,
+# and legitimate when quoting a constraint.
_EXCLUSIVITY_TOKENS = (
"entirely",
"solely",
@@ -248,14 +219,8 @@ def _has_unqualified_exclusivity_over_truncated(
) -> bool:
"""True when the prose makes an exclusivity claim over a truncated body.
- The co-occurrence of (1) an unattributed exclusivity token in the prose
- and (2) truncated: true on any symbol_bodies entry is the structural bug
- from issue #1444: exhaustiveness is asserted from a sample the pipeline
- knows is incomplete.
-
- Does not fire when no symbol body was truncated — the check gates on the
- structured flag already present in the response, so it is a no-op on the
- common case where all bodies were served whole.
+ Exhaustiveness asserted from a sample the pipeline knows is incomplete.
+ A no-op when every body was served whole.
"""
if not any(b.get("truncated") for b in (symbol_bodies or [])):
return False
@@ -278,14 +243,9 @@ _PATHISH_SPAN_RE = re.compile(
def _code_reference(text: str, name: str) -> bool:
"""Does *text* refer to *name* as CODE rather than as an English word?
- A bare word-boundary match is not usable here. Withheld symbols include
- ``on``, ``line``, ``input``, ``width`` and ``join``, all ordinary English,
- so ``\bon\b`` matches "based on the excerpts" and scores a harmless
- truncation as harmful. Measured across the transcripts on disk, the naive
- matcher put the harm rate 4+ points high and its hits were visibly prose.
-
- The call shape allows no space before the paren: ``the width (in pixels)``
- is a prose parenthetical, not a call, and admitting the space made it one.
+ A bare word match is unusable: withheld names like ``on`` or ``width`` are
+ ordinary English. The call shape allows no space before the paren, since
+ ``the width (in pixels)`` is a prose parenthetical.
"""
n = re.escape(name)
patterns = [
@@ -312,10 +272,8 @@ def _code_reference(text: str, name: str) -> bool:
def _is_distinctive_name(name: str) -> bool:
"""Is *name* code-shaped enough that a bare word match cannot be prose?
- Internal capital, underscore or digit — the same shape rule
- ``_distinctive_terms`` uses. ``_validate`` and ``TodoStore`` qualify;
- ``write``, ``main``, ``line`` and ``on`` do not, and those are exactly the
- names that collapse confidence on an ordinary English question.
+ Internal capital, underscore or digit, the shape rule ``_distinctive_terms``
+ uses. ``_validate`` qualifies; ``main`` and ``on`` do not.
"""
return (
any(ch.isupper() for ch in name[1:])
@@ -343,15 +301,11 @@ def _question_names(question: str, name: str) -> bool:
Three tiers, loosest first:
- * distinctive names (``_validate``, ``TodoStore``) match case-insensitively
- on a word boundary — no English word has that shape;
- * a leading-capital name (``Store``) matches only with its own case, so
- "the store where results land" does not implicate ``Store``, and not at
- the start of a sentence, where the capital is grammar rather than a name
- ("Run the indexer, then what?" must not implicate a symbol ``Run``);
- * an all-lowercase name (``on``, ``line``, ``write``, ``main``) needs an
- actual code context, because a bare word match on those demotes ordinary
- questions like "what is the main entry point?".
+ * distinctive names match case-insensitively on a word boundary;
+ * a leading-capital name (``Store``) matches only with its own case, and
+ not as a sentence-initial imperative ("Run the indexer" is not ``Run``);
+ * an all-lowercase name (``main``) needs a code context, or "what is the
+ main entry point?" would be demoted.
"""
if not question:
return False
@@ -375,34 +329,19 @@ def implicated_withheld_symbols(
) -> list[str]:
"""Withheld symbols the response actually leans on, worst case first.
- Truncation on its own is not a defect: measured on the transcripts on disk,
- 31% of responses truncate something and in 22% of those the withheld range
- holds nothing the response relies on. Capping confidence on the bare flag
- would spend `high` on those for no gain.
-
- What matters is whether a symbol the response DEPENDS ON is in the withheld
- range. Two independent routes, and the split is deliberate:
-
- * the **question** names it. Always present, so it fires on any answer,
- including one whose prose never mentions the symbol at all.
- * the **answer** names it in a code context. Only when synthesis ran.
-
- The question route is what stops this becoming the mistake the previous gate
- made: a check conditioned solely on prose stays silent on every answer whose
- prose happens not to name the symbol, which was 3 responses in 4 measured.
-
- It is NOT what protects the no-LLM modes, and an earlier version of this
- docstring wrongly claimed it was. Both of those paths now serve bodies:
- ``_degraded_payload`` builds them from the question's anchors, and the
- homonym-union early return inlines every definition, and neither calls this
- gate. The union path caps on truncation alone. The degraded path does not gate
- at all, because it has no synthesised claim to demote: its ``confidence`` is
- already "low" for want of prose, and what a cut body costs it is said in the
- payload instead, by the ``continuation`` on the entry and by the next action.
-
- ``body_continues`` entries sort first: a symbol whose body was cut by the
- truncation boundary is the sharper failure, because the response has already
- shown its signature and may reason about behaviour it never saw.
+ Truncation alone is not a defect: often the withheld range holds nothing
+ the response relies on. What matters is whether a symbol the response
+ DEPENDS ON was withheld, found by two independent routes:
+
+ * the **question** names it, which fires even when the prose never
+ mentions the symbol;
+ * the **answer** names it in a code context (only when synthesis ran).
+
+ Neither no-LLM path calls this: the union path caps on truncation alone,
+ and the degraded path has no synthesised claim to demote.
+
+ ``body_continues`` entries sort first: the response has shown that
+ symbol's signature and may reason about behaviour it never saw.
"""
hits: list[tuple[int, str]] = []
for body in symbol_bodies or []:
@@ -451,47 +390,23 @@ def _top_two_score_ratio(hits: list[dict]) -> float:
def _agreement_dominant(hits: list[dict], *, vector_leg_keyless: bool = False) -> bool:
"""True when the top hit is the confident pick by retriever AGREEMENT.
- RRF fusion compresses scores: a page both retrievers rank #1 barely
- outscores one they rank #2, so the numeric dominance ratio calls the *most*
- confident retrieval "non-dominant" and demotes it. This reads the per-source
- ranks instead: when two retrievers put the SAME page at (or within a rank of)
- the top, that consensus is a stronger ground-truth signal than any RRF score
- margin.
-
- Conservative. Requires the top hit to be found by BOTH retrievers near the
- top of each, to rank no lower than the runner-up in either source, and the
- runner-up to be meaningfully weaker. Otherwise returns False and the caller
- falls back to the pure ratio/gap gate. Agreement can only LIFT — the demotion
- gates still apply.
-
- ``vector_leg_keyless`` swaps the vector leg for the symbol leg. On an index
- with no semantic vectors the vector leg is skipped outright, so ``_vec_rank``
- is never written for any question and a fixed FTS+vector pair makes this
- signal permanently unreachable — every keyless answer is then graded by the
- pure ratio gate, which is exactly the gate this function exists because it
- mis-reads. The symbol leg runs on every index and records ``_sym_rank``.
-
- **The caller must pass the retrieval leg's own status, not infer it from
- the hits.** By the time this runs, ``hits`` is capped to the top 5 out of a
- much larger fused pool, so "no hit carries a ``_vec_rank``" is *not*
- evidence the leg was skipped: a keyed index whose vector leg timed out,
- errored, was scope-filtered, or was simply outranked by five FTS-and-symbol
- hits presents identically. Substituting on that inference would fire exactly
- when evidence is weakest and manufacture "high" confidence from it.
-
- The symbol pair is held to a stricter rank than the vector pair. FTS and the
- symbol leg are not independent — the wiki page FTS indexes contains the
- public symbol table the symbol leg matches on — so their agreeing is closer
- to one lexical match observed twice than to two retrievers concurring, and
- the fusion beside this already prices that leg well below the others.
- Requiring an exact rank-0 tie keeps the weaker signal from carrying the
- stronger claim.
-
- Note the consequence: at ``top_rank_max = 0`` the runner-up comparison below
- can no longer reject anything, because two hits cannot share rank 0 within
- one leg. The symbol pair therefore reduces exactly to "the top hit is #1 in
- FTS and #1 in the symbol leg", which is the intended rule; the shared gap
- check is retained for the vector pair, where it does constrain.
+ RRF compresses scores, so the ratio calls the most confident retrieval
+ (both retrievers rank the same page top) "non-dominant". This reads the
+ per-source ranks instead. Conservative: the top hit must be found by BOTH
+ retrievers near the top, rank no lower than the runner-up in either, and
+ the runner-up must be weaker. Agreement only lifts; demotion gates apply.
+
+ ``vector_leg_keyless`` swaps the vector leg for the symbol leg, since a
+ keyless index never writes ``_vec_rank``. **The caller must pass the leg's
+ own status, not infer it from the hits:** ``hits`` is capped to the top 5,
+ so a missing ``_vec_rank`` is not evidence the leg was skipped (it may have
+ timed out or been outranked), and substituting then would manufacture
+ "high" exactly when evidence is weakest.
+
+ The symbol pair needs an exact rank-0 tie because FTS and the symbol leg
+ read overlapping text. At rank 0 the runner-up check cannot reject anything
+ (two hits cannot share rank 0 in one leg), so the rule reduces to "#1 in
+ both"; the gap check constrains the vector pair only.
"""
if len(hits) < 2:
return False
@@ -504,9 +419,7 @@ def _agreement_dominant(hits: list[dict], *, vector_leg_keyless: bool = False) -
top = hits[0]
top_a = top.get("_fts_rank")
top_b = top.get(second_field)
- # Top must be a consensus pick: found by both retrievers, near the top of
- # each. A one-retriever top hit is exactly the ambiguous case we must NOT
- # lift.
+ # A one-retriever top hit is exactly the ambiguous case not to lift.
if top_a is None or top_b is None:
return False
if top_a > top_rank_max or top_b > top_rank_max:
@@ -529,29 +442,19 @@ def _agreement_dominant(hits: list[dict], *, vector_leg_keyless: bool = False) -
def dominance_reason(hits: list[dict], *, agreement_dominant: bool = False) -> str | None:
"""WHICH test found the top hit dominant, or None if none did.
- The single owner of "did retrieval clearly point at ONE page". Callers that
- only need the verdict take :func:`is_dominant`; the note builder needs the
- reason, because the three tiers measure different things and a note that
- quotes the wrong one refutes itself.
-
- * ``"ratio"`` — the top hit outscores the runner-up by a clear multiple.
- * ``"gap"`` — where both scores are excellent a close ratio is expected
- (6.0 vs 5.4 is a clear win reading as 1.11x), so dominance is an absolute
- gap and the RATIO IS NOT THE MEASUREMENT. Quoting it as one prints a near
- tie as the reason for confidence.
- * ``"agreement"`` — both retrievers independently rank this page top. RRF
- compresses fused scores, so this fires around 1.02x; the ratio is not the
- measurement here either.
- * ``"sole_hit"`` — one hit, nothing to be ambiguous against.
-
- Coverage (fraction of query terms in the top hit) biases ranking but is
- deliberately NOT a gate: natural-language questions rarely put every content
- term in one page, so a coverage threshold over-fires.
-
- No hits at all is not dominance: there is no page for the claim to be about,
- and rating that dominant would grade an empty retrieval as merely
- under-scoring. Unreachable from the synthesised path, which returns early on
- empty hits, but the degraded path rates its retrieval through here too.
+ The single owner of "did retrieval clearly point at ONE page". The note
+ builder needs the reason, not just the verdict, because a note quoting the
+ wrong tier refutes itself.
+
+ * ``"ratio"``: the top hit outscores the runner-up by a clear multiple.
+ * ``"gap"``: both scores are excellent, so dominance is an absolute gap
+ and the ratio is NOT the measurement (6.0 vs 5.4 reads as 1.11x).
+ * ``"agreement"``: both retrievers rank this page top; fires near 1.02x,
+ so the ratio is not the measurement here either.
+ * ``"sole_hit"``: one hit, nothing to be ambiguous against.
+
+ Coverage is deliberately not a gate: natural-language questions rarely put
+ every content term in one page. No hits at all is not dominance.
"""
if not hits:
return None
@@ -570,14 +473,9 @@ def dominance_reason(hits: list[dict], *, agreement_dominant: bool = False) -> s
def is_dominant(hits: list[dict], *, agreement_dominant: bool = False) -> bool:
"""Did retrieval clearly point at ONE page? See :func:`dominance_reason`.
- Three callers ask it and they must not disagree: the confidence grade uses it
- as both the starting grade and the ceiling, :func:`_retrieval_quality` rates
- the retrieval from it, and the payload folds in the ambiguous-retrieval
- evidence on it. It used to be computed twice — a two-tier version in the
- answer module and a ratio-only re-derivation inside the grade — and the two
- disagree in a real window (a 6.0/5.4 pair is dominant by gap and not by
- ratio), which is how one payload came to assert that the top result "clearly
- dominates" while appending the caveat that retrieval found no dominant page.
+ The confidence grade, :func:`_retrieval_quality` and the payload's
+ ambiguity caveat all read this one test, so they cannot disagree about the
+ same retrieval.
"""
return dominance_reason(hits, agreement_dominant=agreement_dominant) is not None
@@ -585,17 +483,9 @@ def is_dominant(hits: list[dict], *, agreement_dominant: bool = False) -> bool:
def _retrieval_quality(hits: list[dict], agreement_dominant: bool) -> str:
"""Rate the retrieval, independently of the text it fed.
- Kept as one function because the degraded path needs the same rating and must
- not invent a second one. That path has no synthesised text to rate, but it ran
- exactly the same retrieval, and "high" has to mean the same thing to a keyless
- caller as to a keyed one or the field is worth less than nothing. It is also
- what :func:`_degraded_confidence` grades from, so the two fields on a
- synthesis-less payload can never disagree about the same retrieval.
-
- Reads :func:`is_dominant` rather than re-deriving the ratio, so "weak" means
- exactly "not dominant" — the same fact the confidence ceiling and the
- ambiguity caveat are keyed on. Without that the payload could rate retrieval
- weak and treat it as dominant in the same breath.
+ Shared with the degraded path so "high" means the same to keyless and keyed
+ callers, and :func:`_degraded_confidence` grades from it. "weak" means
+ exactly "not dominant" per :func:`is_dominant`.
"""
top_score = _confidence_score(hits[0]) if hits else 0.0
dominant_grade = is_dominant(hits, agreement_dominant=agreement_dominant)
@@ -607,27 +497,16 @@ def _retrieval_quality(hits: list[dict], agreement_dominant: bool) -> str:
def _degraded_confidence(reason: str, retrieval_quality: str) -> str:
"""Grade a synthesis-less payload on what a caller can act on, not on prose.
- ``confidence`` used to be pinned to "low" here on the grounds that it rates
- the synthesised text and there is none. That referent is the problem, not the
- answer to it: the field is what an agent reads to decide whether it still has
- work to do, and pinning it told 69 percent of field calls to distrust evidence
- that was often excellent — 84 percent of those "low" verdicts were unearned,
- and the keyless install that never configures a provider got one on every call
- forever. So the field is graded from the retrieval it actually served.
-
+ The field tells an agent whether it still has work to do, so it is graded
+ from the retrieval served rather than pinned "low" for want of prose.
Two ceilings, both load bearing:
- "high" is unreachable. ``answer`` on this path is assembled boilerplate, and
- our own agent instructions license citing a high-confidence answer directly,
- so a "high" here would be an invitation to cite the boilerplate. That was the
- real objection behind the old pin and it is preserved as a cap rather than
- discarded.
-
- ``synthesis-failed`` stays "low" whatever retrieval did. The evidence is
- identical to the no-provider case, but the *situation* is not: a provider is
- configured, so a retry can still produce a real answer and this payload is not
- the end of the line. "no-llm-provider" is the end of the line — no better reply
- is coming for that install — so there the evidence is all there is to grade.
+ "high" is unreachable: ``answer`` here is assembled boilerplate, and a
+ high-confidence answer is licensed to be cited directly.
+
+ ``synthesis-failed`` stays "low": a provider is configured, so a retry can
+ still produce a real answer. "no-llm-provider" is the end of the line, so
+ there the evidence is all there is to grade.
"""
if reason != "no-llm-provider":
return "low"
@@ -637,13 +516,9 @@ def _degraded_confidence(reason: str, retrieval_quality: str) -> str:
def _is_question_named_body_cut_by_us(entry: dict, question_ids: set[str]) -> bool:
"""Whether this body is the question's own symbol, cut because WE ran out of lines.
- ``truncated`` alone is not trustworthy enough to demote on. The stale-bound
- case this was written for is now fixed at its source — ``check_symbol_bounds``
- clamps every bound to the live file — but the guard still earns its keep on
- the ``source_excerpt`` fallback, where the served bytes come from the index
- rather than from disk and the live length says nothing. Requiring the served
- span to have reached the line cap says the cut was ours, which is the only
- case where something was really withheld.
+ ``truncated`` alone is not enough to demote on: on the ``source_excerpt``
+ fallback the bytes come from the index, not disk. A served span at the line
+ cap says the cut was ours, the only case where something was withheld.
"""
if not (entry.get("truncated") and entry.get("continuation")):
return False
@@ -656,10 +531,8 @@ def _is_enclosing_continuation(entry: dict, implicated: set[str]) -> bool:
"""Whether this body simply continues past the cut, rather than losing a symbol.
A withheld entry carrying the served body's OWN name is the enclosing symbol
- continuing past the cut, not something that never arrived. Calling that "not
- served" is wrong about the payload directly above the note, and sends the
- caller to get_symbol for a body they already hold most of. The accurate
- pointer is the ``continuation`` the entry already carries.
+ continuing past the cut; the accurate pointer is its ``continuation``, not
+ a get_symbol call for a body the caller mostly holds.
"""
name = entry.get("name")
if not (entry.get("continuation") and name in implicated):
@@ -670,10 +543,8 @@ def _is_enclosing_continuation(entry: dict, implicated: set[str]) -> bool:
class _Grade(NamedTuple):
"""The confidence verdict, and every finding the notes are written from.
- The gates do not just produce a label: each one that fires records WHAT
- it objected to, and the payload builder turns that into the note and the
- next action. Carrying the findings out beside the verdict is what keeps
- the two in step.
+ Each gate that fires records WHAT it objected to, and the payload builder
+ writes the note and next action from that, keeping the two in step.
"""
confidence: str
@@ -681,13 +552,10 @@ class _Grade(NamedTuple):
ratio: float
top_score: float
second_score: float
- #: Why the grade is "high", or None when it is not: a
- #: :func:`dominance_reason` tier, or "symbol_body" / "grounding". The note is
- #: written from this rather than from the bare label, because the reasons
- #: license different sentences — only "ratio" may quote the ratio as the
- #: measurement, and only a dominance tier or "symbol_body" may tell the agent
- #: not to re-read. Writing one reason for every high is how a payload came to
- #: quote a 1.00x dominance ratio, a tie, as the reason it was confident.
+ #: Why the grade is "high", or None: a :func:`dominance_reason` tier, or
+ #: "symbol_body" / "grounding". The reasons license different sentences:
+ #: only "ratio" may quote the ratio, and only a dominance tier or
+ #: "symbol_body" may tell the agent not to re-read.
high_reason: str | None
ungrounded_values: list[str]
frame_unsupported: list[str]
@@ -710,44 +578,25 @@ def _grade_answer(
) -> _Grade:
"""Grade the synthesised answer through the gate cascade, in order.
- One starting grade from retrieval dominance, then a run of gates that can
- only demote it. Several are guarded on the answer still being at high, so
- that one response cannot be pushed two levels for one problem. Read them
- as a list of reasons not to trust the prose: the order is the order they
- were added, and each comment says which failure it was built to catch.
+ One starting grade from retrieval dominance, then gates that can only
+ demote it. Several fire only while the answer is still high, so one
+ response is not pushed two levels for one problem.
``dominance`` is :func:`dominance_reason`'s verdict, computed once by the
- caller and used here for the starting grade, the ceiling, and the reason the
- note is written from. A bare bool used to be accepted for the ceiling alone
- while the starting grade re-derived a ratio-only version of the same
- question, so a retrieval the rest of the pipeline treated as dominant could
- start the cascade as if it were not.
+ caller and used for the starting grade, the ceiling, and the note's reason.
"""
dominant = dominance is not None
_ratio = _top_two_score_ratio(hits)
_top_score = _confidence_score(hits[0]) if hits else 0.0
_second_score = _confidence_score(hits[1]) if len(hits) >= 2 else 0.0
- # A response can EARN "high" on a NON-dominant retrieval, by two routes that
- # are NOT equally good and so are tracked apart. Both need the score floor,
- # and a retrieval that clears the floor and dominates is already high — so
- # earning fires exactly when `retrieval_quality` reads "weak".
- #
- # * `earned_body` — the question named a symbol and its live body is inlined
- # in this payload. Resolved by exact name, not by ranking, so how ambiguous
- # the ranking was does not bear on it, and "do not re-read the source" is
- # literally true: the source is in the response. (An oversized body can
- # still arrive cut, which is why the note it writes says "the live body"
- # rather than "the full body" and lets the truncation tail speak.)
- # * `earned_grounding` — every distinctive mechanism term the answer names
- # appears in the material it was shown, and a cited hit carries real symbol
- # bodies. That is evidence the model did not FABRICATE a mechanism. It is
- # not evidence retrieval found the right page, which is the only thing in
- # doubt on a weak retrieval — an answer can be perfectly consistent with
- # the wrong file. Off by default; see the env flag's comment.
- #
- # The demotion gates below (hedge, value, claim-support) still pull an earned
- # high back down.
+ # Two routes EARN "high" on a non-dominant (weak) retrieval, tracked apart:
+ # * `earned_body`: the question-named symbol's live body is inlined, resolved
+ # by exact name rather than ranking, so the source is in the response.
+ # * `earned_grounding`: every mechanism term the answer names was in the
+ # material shown. Shows no fabrication, not that retrieval found the right
+ # page, so it is off by default (see the env flag's comment).
+ # The demotion gates below still pull an earned high back down.
earned_body = False
earned_grounding = False
if _flag_on(_EARN_HIGH_GROUNDING_ENV) and _top_score >= _HIGH_CONFIDENCE_SCORE_FLOOR:
@@ -762,89 +611,55 @@ def _grade_answer(
if (dominant or earn_high) and _top_score >= _HIGH_CONFIDENCE_SCORE_FLOOR:
confidence = "high"
elif dominant:
- # Dominant but weak — the right file relative to its siblings, but
- # the signal isn't strong enough to trust the synthesised answer
- # without verification. Downgrade so the consumer Reads the source.
+ # Dominant but weak: right file relative to its siblings, but not
+ # strong enough to trust the synthesis without verification.
confidence = "medium"
else:
confidence = "medium"
- # Second gate: downgrade when the LLM's own answer admits insufficiency.
- # Retrieval dominance only tells us we indexed the right file; it does
- # not mean the synthesized text is usable. Shipping a hedged answer with
- # confidence="high" misleads the consumer AND drags the full retrieval
- # payload through the conversation cache for no benefit.
+ # Hedge gate: dominance says we indexed the right file, not that the
+ # synthesised text is usable.
hedged = _answer_is_hedged(answer_text)
if hedged:
- # A hedge means the synthesised PROSE is weak — but when the exact
- # symbol the question named is inlined in symbol_bodies (tier-0 anchor,
- # full live body), the answer's ground truth is already in-hand. Labeling
- # that "low" contradicts the payload and fires the "go Read" hint the
- # body makes unnecessary, so the agent bails to Read when it never needed
- # to. Hold such a response at medium; the note redirects the agent from
- # the hedged prose to the served body.
+ # When the question-named symbol's body is served, the ground truth is
+ # in hand; "low" would send the agent to Read for nothing.
confidence = "medium" if served_named_body else "low"
- # Third gate — identifier-citation gate: when the question explicitly
- # names identifiers (classes / methods / snake_case / CamelCase) and
- # NONE of the top retrieval hits contain any of those identifiers as a
- # hydrated symbol, retrieval may be pointing at plausible-but-wrong
- # files (same module family, similar vocabulary). Downgrade high->medium
- # so the consumer Reads the `fallback_targets`. Only applies when the
- # question actually names identifiers — mechanism-descriptive questions
- # (no symbol names) are unaffected.
+ # Identifier-citation gate: the question names identifiers but no top hit
+ # hydrates any of them, so retrieval may be on plausible-but-wrong files.
if confidence == "high" and question_ids:
top_n = [h for h in hits[:_ENRICH_TOP_N_HITS] if h.get("symbols")]
has_match = any(s.get("_matched") for h in top_n for s in (h.get("symbols") or []))
if not has_match:
confidence = "medium"
- # Fourth gate — value grounding: on value-shaped questions (default /
- # threshold / limit / how many), every number the answer asserts must
- # appear somewhere in the material retrieval actually contained. A
- # number synthesis produced from thin air is a factual error delivered
- # with authority — the single worst calibration failure, because the
- # consumer was told not to verify. Cap and say why.
+ # Value gate: on value-shaped questions every asserted number must appear in
+ # the retrieved material. An invented number delivered as "high" is the
+ # worst calibration failure, because the consumer was told not to verify.
ungrounded_values: list[str] = []
if not hedged and _is_value_question(question):
ungrounded_values = _ungrounded_numbers(answer_text, hits)
if ungrounded_values:
- # A value derived from grounded operands is not a fabrication, so
- # soften one notch instead of capping — but only on a clean high over
- # dominant retrieval (earn_high on weak retrieval stays capped), and
- # only when some OTHER asserted number is grounded. Without that
- # second clause a lone invented value would soften too, which is the
- # case this gate exists to catch. The note and next_action_hint fire
- # on ungrounded_values regardless of tier.
+ # A value derived from grounded operands softens one notch, but only
+ # on a dominant high and only when another asserted number is
+ # grounded; a lone invented value is what this gate exists to catch.
grounded_sibling = len(_asserted_numbers(answer_text)) > len(ungrounded_values)
if grounded_sibling and confidence == "high" and dominant:
confidence = "medium"
else:
confidence = "low"
- # Fifth gate — citation-source gate: a high-confidence answer must cite
- # at least one page that contributed actual source material (hydrated
- # symbols with signatures/bodies), not just file summaries. Summary-only
- # grounding is how plausible-but-wrong syntheses get through.
+ # Citation-source gate: a high answer must cite a page that contributed
+ # hydrated symbols; summary-only grounding lets plausible-wrong prose through.
if confidence == "high":
cited = set(citations)
if not any(h.get("symbols") for h in hits if h.get("target_path") in cited):
confidence = "medium"
- # Sixth gate — claim-support / frame grounding: a high-confidence answer
- # must name its mechanism in terms the cited material actually contains. The
- # dominance gate is generous on repo-internal questions (an anchored symbol +
- # a dominant hit clear it), so a synthesis that conflates two mechanisms —
- # right file, wrong reason/function — rides through at high confidence. The
- # tell is a distinctive code-like term (a class / function / module the
- # answer names AS the mechanism) that appears nowhere in everything retrieval
- # showed. When such terms are not outweighed by grounded ones, downgrade
- # high->medium so the consumer verifies instead of trusting.
- #
- # The original gate fired only on "why" questions, but the same failure
- # occurs on "how" questions that name the mechanism in the ANSWER, not the
- # question. Value questions have their own numeric gate above; naming/lookup
- # questions legitimately just echo the named symbol, so they are excluded.
+ # Claim-support gate: a synthesis can conflate mechanisms (right file, wrong
+ # function) and still clear dominance. The tell is a code-like term the
+ # answer names as the mechanism that retrieval never showed. Covers why and
+ # how questions; lookups legitimately echo the named symbol.
frame_unsupported: list[str] = []
_claim_scope = _is_why_question(question) or (
_flag_on(_CLAIM_SUPPORT_GATE_ENV) and _is_mechanism_question(question)
@@ -856,12 +671,7 @@ def _grade_answer(
else:
frame_unsupported = []
- # Seventh gate — completeness scope over truncated bodies: prose asserts an
- # unqualified exclusivity claim ("entirely", "the sole", "the only") while a
- # cited symbol body arrived truncated, so the answer asserts a global
- # property from a sample it knows is incomplete.
- # Guard: only fires at high (like gates 3 / 5 / 6) so it cannot stack with
- # other downgrades and push a single response two levels for one problem.
+ # Exclusivity gate: "the only" / "entirely" asserted over a truncated body.
exclusivity_over_truncated = False
if confidence == "high" and not hedged:
exclusivity_over_truncated = _has_unqualified_exclusivity_over_truncated(
@@ -870,41 +680,18 @@ def _grade_answer(
if exclusivity_over_truncated:
confidence = "medium"
- # Eighth gate — a WITHHELD symbol the response depends on. The seventh gate
- # needs an exclusivity token in the prose as well as truncation, and across
- # repeated runs of the reference defect the token usually does not appear:
- # the rest are equally incomplete, equally "high", and it stays silent. It is
- # also inert by construction in no-LLM mode, where there is no prose to hold
- # a token.
- #
- # This gate keys on the dependency instead. It fires when a symbol in the
- # withheld range is named by the QUESTION (every mode) or referenced as code
- # by the ANSWER (LLM mode). Truncation alone is deliberately NOT enough: a
- # large minority of truncations withhold nothing the response leans on, and
- # `high` is worth keeping when it is earned.
+ # Withheld-dependency gate: a withheld symbol is named by the question or
+ # referenced as code by the answer. Unlike the exclusivity gate it needs no
+ # prose token; truncation alone is deliberately not enough.
withheld_implicated = implicated_withheld_symbols(question, answer_text, symbol_bodies)
if confidence == "high" and withheld_implicated:
confidence = "medium"
- # Ninth gate — the LOOKUP half of the eighth, and a routing hole rather
- # than a threshold problem. Gate 8 asks whether the question names a
- # WITHHELD symbol; on a bare-name lookup it provably never can, because the
- # question names the symbol that was SERVED and the withheld names are that
- # symbol's own inner members. The union path caps on truncation alone for
- # exactly this shape, on the grounds that where the caller asked for a symbol
- # the bodies ARE the answer. But a name with a single definition never
- # reaches the union path — `_anchor_symbol_hits` short-circuits at
- # `len(cands) == 1` before `homonyms["union"]` is built — so it lands here
- # with the same shape and, until now, no cap. The dominance ratio is not the
- # cause and is not touched.
- #
- # Deliberately narrow. It needs the question to read as a symbol lookup
- # rather than prose, AND the truncated body to be the very symbol the
- # question named. On a prose question the body is evidence for a claim rather
- # than the answer itself, and truncation alone is a poor signal there, which
- # is why gate 8 keeps the dependency test for that population. Kept as the
- # entry rather than a flag so the note can quote the real served range and
- # continuation instead of describing the cut in the abstract.
+ # Lookup gate: on a bare-name lookup the question names the SERVED symbol,
+ # so the withheld-dependency gate can never fire. A multi-def name caps on
+ # truncation in the union path; a single-def name never reaches it, so it
+ # is capped here. Narrow on purpose: a symbol-lookup question whose own
+ # symbol was cut. Kept as the entry so the note can quote the real range.
named_body_cut = next(
(b for b in symbol_bodies if _is_question_named_body_cut_by_us(b, question_ids)),
None,
@@ -917,28 +704,15 @@ def _grade_answer(
if lookup_body_truncated:
confidence = "medium"
- # Non-dominant ceiling: ambiguous retrieval is the calibration cost of
- # always synthesizing — the answer may be right, but with no single dominant
- # page it must never read "high" (cite without verifying). Cap at medium even
- # if every gate passed. (A non-dominant retrieval already scores <high via
- # the ratio, so this is usually a no-op; it is explicit so the
- # always-synthesize contract — "answered, but verify" — is self-documenting.)
- # Exception: an answer that EARNED high is not "cite without verifying". By
- # default that means only the served-body route — the source IS in the
- # payload — since grounded PROSE is merely consistent with material this same
- # retrieval says may be the wrong material, and an agent reads "high" as
- # permission to skip the verification that would catch precisely that. The
- # exemption is written against `earn_high` rather than `earned_body` so the
- # opt-in genuinely restores the old behaviour instead of being overruled two
- # lines later.
+ # Non-dominant ceiling: with no single dominant page the answer must not
+ # read "high" (cite without verifying) unless it EARNED high. Keyed on
+ # `earn_high`, not `earned_body`, so the grounding opt-in really restores
+ # the old behaviour. Usually a no-op; explicit so the contract is visible.
if not dominant and not earn_high and confidence == "high":
confidence = "medium"
- # Name the reason while the evidence for it is still in scope. The dominance
- # tier first, and the specific tier rather than "dominant": the gap and
- # agreement tiers fire at ratios near 1.0, so a note quoting the ratio as the
- # measurement would print a near tie as its own justification — the reported
- # defect, one layer down.
+ # The specific dominance tier, not "dominant": gap and agreement fire near a
+ # 1.0 ratio, so quoting the ratio would print a near tie as justification.
high_reason = None
if confidence == "high":
high_reason = dominance or ("symbol_body" if earned_body else "grounding")
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/config.py b/packages/server/src/repowise/server/mcp_server/tool_answer/config.py
index 75d9df1d6..b16cec5bf 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/config.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/config.py
@@ -1,9 +1,8 @@
"""Tuning constants and prompt templates for get_answer.
All of get_answer's knobs live here so the retrieval / synthesis / confidence
-modules read like policy applied to data, and the data is tunable in one place.
-None of these are repo-specific — they are properties of BM25-style retrieval
-with a coverage re-ranker, not of any particular codebase.
+modules read like policy applied to data. None are repo-specific: they are
+properties of BM25-style retrieval with a coverage re-ranker.
"""
from __future__ import annotations
@@ -15,139 +14,77 @@ from repowise.server.mcp_server._query_terms import STOPWORDS
_log = logging.getLogger("repowise.mcp.answer")
-# How many top retrieval hits to enrich with WikiSymbol context. Enriching
-# every hit produces large responses that bloat the cached prompt prefix on
-# multi-turn agent sessions without changing the answer — the agent typically
-# cites the top-1 file. Top-2 captures the primary navigation need with a
-# bounded payload.
+# Top hits enriched with WikiSymbol context. Enriching every hit bloats the
+# cached prompt prefix on multi-turn sessions; the agent usually cites top-1.
_ENRICH_TOP_N_HITS = 2
-# How many symbols per enriched file. Bounded to keep the context block from
-# growing unboundedly on dense files. We allocate more slots to the top hit
-# (where the answer usually lives) and fewer to secondary hits.
+# Symbols per enriched file: more for the top hit, where the answer usually lives.
_MAX_SYMBOLS_TOP_HIT = 10
_MAX_SYMBOLS_PER_HIT = 4
-# When a retrieved file contains symbols whose name matches an identifier
-# from the question, we promote those to the top of the symbol list for that
-# file, pass a longer docstring, and attach a source excerpt so the LLM
-# actually sees the method body — not just a stub docstring. Without this,
-# specific-method questions get hedged answers even on dominant retrievals.
+# Symbols whose name matches a question identifier are promoted, get a longer
+# docstring and a source excerpt, so the LLM sees the body and not just a stub.
_MATCHED_SYMBOL_DOC_CHARS = 400
_MATCHED_SYMBOL_SOURCE_LINES = 40
-# Which symbols survive the per-file cap. A `start_line` tiebreak served a
-# document-order prefix, so on a file larger than its symbol budget the symbol
-# the question was about could not be reached at all. Scoring the already-loaded
-# name / signature / docstring against the question's content terms changes which
-# symbols fill the same budget, not how many: no extra I/O, no prompt growth.
-# A name hit outranks a signature hit outranks a mention in the docstring. With
-# no signal every score is 0 and the sort falls back to `start_line` as before.
+# Which symbols survive the per-file cap: scored against the question's content
+# terms (name > signature > docstring) so a large file's relevant symbol is
+# reachable. Changes which symbols fill the budget, not how many. With no signal
+# every score is 0 and the sort falls back to `start_line`.
_RELEVANCE_NAME_WEIGHT = 3
_RELEVANCE_SIG_WEIGHT = 2
_RELEVANCE_DOC_WEIGHT = 1
# Score the docstring's opening prose only, so a long one can't out-score a
# precise name on word count alone.
_RELEVANCE_DOC_CHARS = 400
-# A source excerpt used to require a question IDENTIFIER match, so a question
-# phrased in prose reached the right symbols and then showed only their
-# signatures — the "excerpts don't include the actual code" answer. The leading
-# few symbols the question scored against get a body too. Bounded hard: this is
-# the one part of the change that adds prompt text.
+# The top few relevance-scored symbols get a body excerpt even without an
+# identifier match, so prose questions see code. Bounded: this adds prompt text.
_RELEVANT_EXCERPT_MAX_SYMBOLS = 2
-# How many question-named symbol bodies get_answer inlines in `symbol_bodies`.
-# The hydrator already reads these bodies live for synthesis; surfacing them
-# in the response collapses the get_answer -> get_symbol drill-down on
-# "how does X work" / "explain method Y" questions (the agent gets X's body in
-# the same call). Bounded so the body block can't dominate the cached prefix.
+# Question-named symbol bodies inlined in `symbol_bodies`, which saves the
+# get_symbol follow-up. Bounded so the body block can't dominate the cached prefix.
_INLINE_BODY_MAX_SYMBOLS = 2
-# Line cap for an inlined symbol_bodies block. Larger than the synthesis
-# excerpt (_MATCHED_SYMBOL_SOURCE_LINES) because this body is for the agent,
-# not the LLM prompt: a docstring-heavy definition (e.g. get_symbol) burns the
-# 40-line synthesis cap on docstring and truncates the actual logic, forcing
-# the get_symbol follow-up the field exists to remove. 120 serves the whole
-# body of ~99% of symbols in one shot; the rest carry a continuation token.
+# Line cap for an inlined body. Larger than the synthesis excerpt because a
+# docstring-heavy definition would otherwise truncate before its logic; bodies
+# past the cap carry a continuation token.
_INLINE_BODY_MAX_LINES = 120
-# `candidates[].defines` — what each ranked file actually contains.
-#
-# `candidates` names up to 20 files and, until now, carried nothing about any of
-# them beyond an optional line span. Measured on the 25 flow questions, 434 of
-# the 499 paths a get_answer response served carried no content at all, and the
-# Layer B taxonomy judged 89% of the agent's post-answer searches as EXPAND: it
-# took a name we served and went to fetch the substance we did not attach. A
-# file named without its definitions is a Grep the agent has to run.
-#
-# This is bounded hard rather than generously, because the same measurements say
-# our payload is ALREADY the larger context (13,958 chars against a bare agent's
-# 12,735) and scores lower. The goal is substance per served path, not more
-# chars: names and line numbers, no signatures, no docstrings, no bodies.
-#
-# `_DEFINES_CHAR_BUDGET` is the ceiling for the whole block in one response and
-# is spent in retrieval-rank order, so the best-ranked file is the one that
-# always gets described. `_DEFINES_PER_CANDIDATE` stops a 200-symbol module from
-# consuming the budget before the second candidate is reached.
+# `candidates[].defines`: the definitions each ranked file contains, so a named
+# file is not a Grep the agent has to run. Names and line numbers only; the goal
+# is substance per served path, not more chars. The budget is spent in rank
+# order so the best file is always described, and the per-candidate cap stops a
+# large module from consuming it before the second candidate.
_DEFINES_PER_CANDIDATE = 6
_DEFINES_CHAR_BUDGET = 1500
-# Files whose symbols get looked up at all. Matches _CANDIDATE_LIMIT: querying
-# beyond what `candidates` can emit is wasted work.
+# Matches _CANDIDATE_LIMIT: querying beyond what `candidates` can emit is wasted.
_DEFINES_MAX_FILES = 20
-# Synthesis-body depth for the top question-relevant symbols. The default
-# _MATCHED_SYMBOL_SOURCE_LINES (40) excerpt cuts a docstring-heavy definition
-# off before its answer-bearing logic reaches the LLM, so synthesis hedges
-# ("not in the excerpts") on the very symbol whose full 120-line body the
-# response then inlines in symbol_bodies — the excerpt the LLM saw and the body
-# the agent gets were different depths. Read the top few matched symbols at the
-# inline-body depth so what synthesis reasons over matches what the response
-# serves. Bounded so a class-name flood (every sibling method "matches" through
-# the parent's qualified name) can't balloon the synthesis prompt; the rest keep
-# the cheap 40-line excerpt.
+# The top few matched symbols are read at the inline-body depth so synthesis
+# reasons over the same body the response serves, instead of hedging on a
+# 40-line cut. Bounded so a class-name flood can't balloon the prompt.
_SYNTH_FULL_SOURCE_LINES = _INLINE_BODY_MAX_LINES
_SYNTH_FULL_BODY_MAX_SYMBOLS = 2
-# Answer-by-union (homonym exact-name lookup). When a question names a symbol
-# with N>=2 defs that no qualifier disambiguates (`_severity_for` x 4), get_answer
-# inlines the UNION of their bodies instead of a best_guesses pointer list — the
-# pointer list is exactly what triggers the agent's get_symbol/get_context drill.
-# Bodies render greedily under this char budget (mirrors the get_context budget
-# philosophy); defs that don't fit are listed file:line with a "call get_symbol,
-# do NOT Read" redirect. First def always renders even if it alone exceeds budget.
+# Answer-by-union: when a question names a symbol with N>=2 undisambiguated defs,
+# inline the union of their bodies rather than a pointer list that triggers a
+# drill-down. Bodies render greedily under this budget; the rest are listed
+# file:line. The first def always renders even if it alone exceeds the budget.
_HOMONYM_UNION_CHAR_BUDGET = 12000
-# Line cap per union body — same rationale as _INLINE_BODY_MAX_LINES.
_HOMONYM_UNION_BODY_MAX_LINES = 120
-# Ceiling on how many same-named defs a *prose* question may answer-by-union.
-# The union is for a small set of genuine parallel implementations of one concept
-# (``_severity_for`` has 4 across the biomarkers); past a handful, the name is a
-# generic method implemented on many unrelated classes (``to_dict`` x33,
-# ``from_dict`` x26, ``provider_name`` x12), and inlining every body as a
-# confidence=high answer buries the actual question. So a prose question that
-# merely *mentions* such a name (measured: "how does a wiki page get its
-# provider_name during indexing?" dumped 12 unrelated provider stubs) falls
-# through to synthesis, which grounds in the file the question is really about.
-# An explicit symbol lookup (a bare name, where prose does not dominate) still
-# unions at any count — that caller asked for every definition. The gap between a
-# genuine union (<=4 seen) and a generic method (>=12 seen) is wide, so this is
-# not tuned to an exact count.
+# Ceiling on defs a *prose* question may union. A few defs are parallel
+# implementations of one concept; many are a generic method on unrelated classes
+# (`to_dict`), and unioning them buries the question, so prose falls through to
+# synthesis. A bare-name lookup still unions at any count. The gap between the two
+# cases is wide, so this is not tuned to an exact count.
_HOMONYM_UNION_PROSE_DEF_CEILING = 6
-# Data-shape grounding. "what fields does each entry in <blob> contain" is
-# answered directly by mining the field set from source instead of gating to a
-# best_guesses pointer list (the pointer list is exactly what triggers the
-# agent's Read/get_symbol drill). Two grounding sources, precision-ordered:
-# * a documented {...} shape in a docstring/comment near the identifier
-# (authoritative -> confidence high);
-# * consistent key accesses (VAR.get("f") / VAR["f"]) on the value bound from
-# the identifier (access-mined -> confidence medium).
-# Every reported field is a quoted token lifted verbatim from source, so the
-# path cannot synthesise a field with no source backing (no confidently-wrong
-# shapes). Returns nothing (falls through to normal retrieval) unless a shape
-# is genuinely grounded.
-# Cap on files scanned for the shape. A specific blob name can be referenced
-# across dozens of files (every consumer), and the one file that *documents* the
-# shape need not sort first, so the cap is generous - source files are small and
-# the doc scan must not miss the documenting file. Non-test files are scanned
-# first (fixtures document nothing), so the cap mostly trims trailing tests.
+# Data-shape grounding: "what fields does each entry in <blob> contain" is
+# answered by mining the field set from source, precision-ordered:
+# * a documented {...} shape near the identifier (confidence high);
+# * consistent VAR.get("f") / VAR["f"] accesses on the bound value (medium).
+# Every field is a token lifted verbatim from source, so no shape is invented;
+# nothing is returned unless a shape is genuinely grounded.
+# The file cap is generous because the documenting file need not sort first;
+# non-test files are scanned first, so the cap mostly trims trailing tests.
_DATA_SHAPE_MAX_FILES = 30 # cap the identifier grep fan-out
_DATA_SHAPE_DOC_WINDOW = 6 # lines below an identifier mention to scan for a {...}
_DATA_SHAPE_ACCESS_WINDOW = 40 # lines below a binding to mine VAR key accesses
@@ -155,71 +92,42 @@ _DATA_SHAPE_MIN_FIELDS = 2 # never answer from a single-field shape (too weak t
_DATA_SHAPE_MIN_IDENT_LEN = 6 # identifier must be specific, not a bare generic name
_DATA_SHAPE_GREP_TIMEOUT_S = 6.0
-# Sort priority by symbol kind. Classes first because "what does X do" /
-# "which class inherits from Y" questions resolve at the class level. Then
-# top-level functions, then methods (which usually only matter once the
-# class context is established).
+# Classes first: "what does X do" / "which class inherits Y" resolve at class level.
_KIND_PRIORITY = {"class": 0, "interface": 0, "function": 1, "method": 2}
-# Per-symbol docstring truncation. Keeps the context block bounded — the
-# first sentence is typically sufficient and trailing prose mostly contributes
-# cache-write cost on follow-up turns.
+# The first sentence is usually enough; trailing prose is cache-write cost.
_MAX_SYMBOL_DOC_CHARS = 120
-# The lower tier of the dominance test: how far the top hit must outscore the
-# runner-up, as a multiple, when neither score is strong enough for the absolute
-# gap below. Generic, repo-agnostic, no question parsing. The failure modes it
-# addresses are (a) wrong-target retrieval where top-1 and top-2 are both
-# plausible and (b) synthesis hallucination on tangential top hits.
-#
-# It no longer decides WHETHER to synthesise — under the always-synthesize
-# default that gate is gone, and dominance feeds the confidence grade, the
-# retrieval rating and the ambiguity caveat instead.
+# Dominance, lower tier: how far the top hit must outscore the runner-up, as a
+# multiple, when neither score is strong enough for the absolute gap below.
+# Dominance feeds the confidence grade, retrieval rating and ambiguity caveat;
+# it no longer decides whether to synthesise.
_DOMINANCE_RATIO = 1.2
_COVERAGE_THRESHOLD = 0.66
-# The second tier of the dominance test. Where both scores are excellent a close
-# ratio is expected — 6.0 vs 5.4 is a clear win that reads as 1.11x — so above
-# the score floor below, dominance is measured as an absolute gap instead. Held
-# here beside the ratio because ``is_dominant`` is the sole reader of all three;
-# they were inline in the answer module while a second, ratio-only copy of the
-# test lived in the grade, and the two disagreed in exactly this window.
+# Dominance, upper tier: between two excellent scores a close ratio is expected
+# (6.0 vs 5.4 is a clear win), so above the floor dominance is an absolute gap.
+# ``is_dominant`` is the sole reader of all three knobs.
_DOMINANCE_ABS_SCORE_FLOOR = 3.0
_DOMINANCE_ABS_GAP = 0.5
-# Agreement-aware dominance. The dominance ratio above is computed on
-# RRF-fused scores, and RRF *compresses*: a page both retrievers rank #1
-# (2/60) barely outscores one they rank #2 (2/61) — ratio ~1.017, far below
-# _DOMINANCE_RATIO — so the numeric gate calls the *most* confident retrieval
-# (both retrievers agree on the top page) "non-dominant". These knobs let the
-# grade read the per-source ranks directly: when FTS and vector independently
-# put the SAME page at (or within one rank of) the top and the runner-up is
-# meaningfully weaker, that consensus is treated as dominance the ratio can't
-# see. Conservative by design — agreement only LIFTS a retrieval to high; the
-# six demotion gates still pull it back if the synthesised text is ungrounded.
-# The top hit must rank no lower than this in EACH retriever (0-indexed, so
-# 1 == "#1 or #2 in both").
+# Agreement-aware dominance. RRF compresses scores, so a page both retrievers
+# rank #1 barely outscores one they rank #2 and the ratio calls the most
+# confident retrieval "non-dominant". When the retrievers independently put the
+# same page at (or near) the top and the runner-up is weaker, that consensus
+# counts as dominance. Agreement only lifts; the demotion gates still apply.
+# Max 0-indexed rank of the top hit in EACH retriever (1 == "#1 or #2 in both").
_AGREEMENT_TOP_RANK_MAX = 1
-# The same ceiling for the FTS+symbol pair a keyless index has to use instead:
-# no vector leg runs there, so it can never produce a rank, and a fixed
-# FTS+vector pair would make agreement permanently unreachable for those users.
-# Stricter than the vector pair on purpose — an exact rank-0 tie in both, not
-# "#1 or #2". FTS and the symbol leg read overlapping text (the indexed wiki
-# page carries the public symbol table the symbol leg matches on), so the two
-# agreeing is nearer to one lexical match counted twice than to two independent
-# retrievers concurring. `_SYMBOL_LEG_RRF_K` (180 vs `_RRF_K` 60) already prices
-# that leg at a third of the others' in ranking, after a same-named React
-# component displaced the right file on the 99-question eval; this stops the
-# confidence gate from handing the same signal a full vote.
+# The same ceiling for the FTS+symbol pair a keyless index uses (it has no
+# vector leg). Stricter on purpose: FTS and the symbol leg read overlapping text,
+# so their agreement is nearer one lexical match counted twice than two
+# independent retrievers, and the symbol leg is already priced at a third weight.
_SYMBOL_AGREEMENT_TOP_RANK_MAX = 0
-# The runner-up must trail the top by at least this many ranks in at least one
-# source (when it was found by both). 1 == "top is strictly ahead somewhere".
+# The runner-up must trail by at least this many ranks in at least one source.
_AGREEMENT_RANK_GAP = 1
-# Hedge-phrase markers that indicate the LLM refused to synthesize even though
-# retrieval was dominant. When the answer contains any of these, we downgrade
-# confidence to "low" and drop the retrieval payload — the hits aren't useful
-# to a consumer that has already been told to go read the source, and letting
-# them ride through the conversation cache inflates multi-turn cost.
+# Phrases that mean the LLM declined to answer despite dominant retrieval.
+# A match downgrades confidence to "low" and drops the retrieval payload, since
+# a consumer told to read the source gains nothing from it in the cache.
_HEDGE_MARKERS = (
"do not contain",
"does not contain",
@@ -260,35 +168,22 @@ _HEDGE_MARKERS = (
"was not found in",
)
-# The dominance ratio threshold (top_score / second_score >= 1.2x) separates
-# reliable retrievals from ambiguous ones. This is a property of BM25-style
-# retrieval with a coverage re-ranker on top, not of any particular repository;
-# tune if a deployment shows systematic over- or under-gating.
-
-# How many chars of real page content to attach per top hit, for the synthesis
-# prompt and for the pointer payload alike. 1500 chars is enough for a page's
-# opening section plus a code reference; at 600 the excerpt stopped mid-context
-# and agents fell back to native exploration anyway (context-tool bench
-# transcripts, 2026-07-17).
+# Page content chars attached per top hit, for synthesis and the pointer payload.
+# Enough for a page's opening section plus a code reference; much less stops
+# mid-context and agents fall back to native exploration.
_GATED_EXCERPT_CHARS = 1500
# How many hits the low-confidence payload hands back to the agent.
_GATED_RETURN_HITS = 3
-# How many top hits get their page content attached. Retrieval is capped at 5
-# and all 5 reach the synthesis prompt, so this is 5: a hit the model is asked
-# to read with no prose behind it is one it can only answer from symbol names.
-# This is the cost knob for the feature — 5 hits × 1500 chars is roughly 2k
-# prompt tokens on top of the symbol block, measured at +24% of the tool's own
-# synthesis spend. Lower it to spend less; hits below the cut fall back to
-# their one-line summaries.
+# Top hits that get page content attached. All 5 retrieved hits reach synthesis,
+# and a hit with no prose can only be answered from symbol names. This is the
+# feature's cost knob; hits below the cut fall back to one-line summaries.
_PAGE_EXCERPT_HITS = 5
-# Path-prefix domain heuristics — down-weight cross-domain retrievals so a
-# clearly backend question doesn't anchor on a same-vocabulary UI file (and
-# vice versa). The penalty is multiplicative, not absolute, so a strongly
-# matching cross-domain file can still survive on raw signal; the goal is
-# to break ties when retrieval is otherwise ambiguous, not to censor results.
+# Path-prefix domain heuristics: down-weight cross-domain hits so a backend
+# question doesn't anchor on a same-vocabulary UI file (and vice versa). The
+# penalty is multiplicative, to break ties rather than censor strong matches.
_UI_PATH_PREFIXES = (
"packages/ui/",
"packages/web/",
@@ -302,9 +197,8 @@ _BACKEND_PATH_PREFIXES = (
"backend/",
"modal_app/",
)
-# Tokens that flag a question as being about a specific domain. Kept small
-# and conservative — ambiguous questions (both lists hit, or neither) fall
-# through to no penalty rather than misclassify.
+# Question tokens that flag a domain. Kept small; an ambiguous question (both
+# lists hit, or neither) gets no penalty rather than a misclassification.
_UI_QUESTION_TOKENS = frozenset(
{
"ui",
@@ -351,127 +245,31 @@ _BACKEND_QUESTION_TOKENS = frozenset(
"sql",
}
)
-# Penalty factor applied to cross-domain hits. 0.5 is strong enough to
-# overtake a same-domain near-tie but small enough that a dominant cross-
-# domain hit (real top score outlier) still survives.
+# Strong enough to overtake a same-domain near-tie, weak enough that a dominant
+# cross-domain hit survives.
_DOMAIN_PENALTY = 0.5
-# Floor on raw top-hit score for "high" confidence. Below this the answer
-# may be technically dominant but built on weak retrieval — downgrade to
-# "medium" so the agent verifies. Tuned against observed BM25 ranges on
-# the wiki corpus where useful hits routinely score >1.5.
+# Floor on the top-hit score for "high": below it a dominant answer rests on
+# weak retrieval, so it grades "medium". Useful wiki hits routinely score >1.5.
_HIGH_CONFIDENCE_SCORE_FLOOR = 1.5
-# Schema version stamped on every cached payload. Bump whenever the response
-# shape changes in a way that would mislead a consumer reading an old cached
-# entry (new top-level fields, semantics of existing fields). On cache reads
-# we treat any payload at a lower version as a miss and re-synthesise — the
-# alternative (returning stale-shape payloads) silently bypasses every
-# improvement to the tool and was the failure mode that hid the entire
-# get_answer rework behind a cache hit during testing.
-# v3: retrieval pipeline overhaul (hybrid FTS+vector, PageRank bias, graph
-# expansion, structured prelude, decision fusion). Cached v2 payloads were
-# synthesised over weaker retrieval — bumping forces re-synthesis so the
-# upgrade actually reaches callers without waiting for cache expiry.
-# v4: confidence calibration gates (value-grounding, citation-source,
-# expanded hedge markers). Cached v3 confidence values predate the gates
-# and can carry confidently-asserted ungrounded values.
-# v5: `symbol_bodies` field — inline full bodies of question-named symbols so
-# the consumer skips the get_symbol follow-up. Cached v4 payloads lack it.
-# v6: frame-grounding gate — why-answers naming a mechanism term absent from
-# the retrieval corpus downgrade high→medium. Cached v5 payloads predate the
-# gate and can carry a confidently-asserted, conflated "because X" frame.
-# v7: concept anchoring - number-bearing why/value questions anchor the file
-# whose comment justifies the number and surface that comment as code_rationale
-# even on the high path. Cached v6 payloads predate the anchor + surfacing.
-# v8: always-synthesize — retrievals that used to abstain (no dominant page) now
-# carry synthesized prose + best_guesses/code_rationale evidence at medium/low
-# instead of an empty pointer list. Cached v8 gated (empty-answer) rows must
-# bypass so the new answered-with-evidence contract reaches callers.
-# v9: agreement-aware confidence — the top hit is graded "dominant/high" when
-# both retrievers independently rank it at/near the top, not only when its
-# RRF-fused score numerically dominates. RRF compresses scores, so retriever
-# agreement (the most confident case) previously graded medium/low. Cached
-# pre-v9 rows carry the compressed-ratio grade and must bypass.
-# v10: (reserved for the agreement rollout above.)
-# v11: answer-grounding calibration — (1) a mechanism/"how" question that merely
-# names an indexed symbol no longer short-circuits to an exact_symbol body dump;
-# (2) the claim-support gate now covers how-questions, not only why; (3) strong
-# answer-grounding earns high on a non-dominant retrieval. Cached pre-v11 rows
-# carry the old body-dump / dominance-only grade and must bypass so the
-# recalibrated confidence reaches callers.
-# v12: `candidates[].defines` — each ranked file now names the definitions it
-# contains. Cached pre-v12 rows carry the bare {path, lines} shape, which is the
-# named-but-not-carried payload this version exists to replace, so they must
-# bypass rather than serve the old block back.
-# v13: withheld-body calibration — a truncated symbol_bodies entry now carries
-# `withheld_symbols`, confidence is capped when the response depends on one of
-# them (and on the homonym-union path whenever any cited body was truncated),
-# and the high/union notes no longer tell the caller to skip re-reading a
-# payload that admits it withheld part of a cited body. Cached pre-v13 rows
-# carry both the old `high` and the old "do not re-read the source" note, which
-# is precisely what this version exists to stop serving, so they must bypass.
-# v14: the LOOKUP half of v13. v13 capped the homonym-union path on truncation
-# alone, but a name with exactly ONE definition never reaches that path, so a
-# bare-symbol-name question about a uniquely-defined symbol still graded `high`
-# with most of the cited body withheld (measured: 93% and 78% withheld, on two
-# trees and two languages). It is now capped the same way. Separately, a
-# withheld entry naming the very symbol the payload already served is described
-# by its `continuation` range instead of being reported as "not served" with a
-# get_symbol pointer to a body the caller already holds most of. Cached pre-v14
-# rows carry both the old `high` and the old note, so they must bypass.
-# v15: the scanner behind `withheld_symbols` stops reading backtick strings as
-# code. Go raw strings and TS template literals were never masked, so the
-# GraphQL and interpolated text inside them was emitted as symbols — 282 of
-# 22,898 sweep entries on cli/cli, 19 of them the HEADLINE entry the note tells
-# the agent to fetch. Those ids are not dead (`get_symbol` answers them with a
-# live grep, since the name really is on that line) but they are misleading:
-# the "symbol" is a GraphQL field. A cached pre-v15 row still lists them, so it
-# must bypass. Secondarily, the note no longer advertises a symbol_id that
-# resolves to nothing at all — a guard rather than an observed fix, since 0 of
-# the 130 ids on the corpus were dead ends.
-# NOT bumped for the degraded-payload rework (`symbol_bodies` / `citations` /
-# `grounding` / `next_action_hint` / `retrieval_quality` on the no-provider and
-# synthesis-failed paths). Every one of those is a response-shape change, which
-# is normally exactly what this counter is for, but no cached row can carry the
-# old shape: the cache write is gated on `answer_text` and sits below both
-# degraded returns, so a degraded payload has never been written to it. The
-# synthesised shape is untouched. A bump here would invalidate every keyed
-# install's cache, and re-synthesis is real provider spend, for nothing.
-# v16: the same scanner again, in three places, and unlike the degraded rework
-# above every one of them changes the SYNTHESISED payload, which is the shape
-# that gets cached. (1) A run left open at end of file no longer masks to EOF,
-# so definitions below a phantom `"""` or `/*` are listed again — 26 real Rust
-# definitions across two corpus files, one of which had 3,002 lines masked.
-# (2) A cut inside a multi-line string keeps the symbol enclosing it, which
-# changes which entry is the HEADLINE `body_continues`, and therefore the note
-# and the get_symbol pointer. (3) An unverified symbol bound is clamped to the
-# live file, so a body served whole is no longer flagged `truncated` — and
-# v13/v14 cap confidence on that flag, so a cached row can carry a `medium`
-# this version would not produce. Cached pre-v16 rows carry all three, so they
-# must bypass.
-# v17: `confidence` itself moves. Dominance now has one owner, so a retrieval
-# with a strong absolute gap but a compressed ratio grades high where a cached
-# v16 row holds medium; and answer-grounding no longer earns high over a weak
-# retrieval, so the reverse case is cached too. The note is rewritten from the
-# reason the grade was reached rather than from the bare fact that it is high,
-# so v16 rows carry a note this version would not produce.
+# Schema version stamped on every cached payload. Bump whenever the synthesised
+# response shape or the meaning of a field (including `confidence` and `note`)
+# changes: a cached row at a lower version is a miss and re-synthesises, since
+# serving an old-shape row silently hides the change behind a cache hit.
+# Degraded (no-provider / synthesis-failed) payloads are never cached, so changes
+# confined to them need no bump; a needless bump costs every keyed install a
+# round of provider spend.
_ANSWER_SCHEMA_VERSION = 17
-# Hard TTL on answer-cache rows. Commit-based invalidation (the payload's
-# stamped ``_indexed_commit`` vs the repo's current head) is the primary
-# freshness gate, but rows written before commit stamping existed — or for
-# repos without git metadata — need a backstop so they can't serve forever.
+# Backstop TTL for cache rows. Commit stamping is the primary freshness gate;
+# this covers rows without a stamp (older rows, repos without git metadata).
_ANSWER_CACHE_TTL_DAYS = 14
-# Intersection-retrieval connectives. If a question contains any of these
-# (case-insensitive whole-word), it's likely a relational/multi-entity
-# question. We split the question on the connective, run two FTS passes,
-# and boost any page that appears in BOTH result sets — the page at the
-# intersection is much more likely to be the actual answer than a page
-# at the top of either single-side query.
-# This is grammar, not domain — the same list applies to any English-language
-# code question, independent of the repository or codebase.
+# Intersection-retrieval connectives (case-insensitive whole-word). A question
+# containing one is split on it, both sides are searched, and pages in BOTH
+# result sets are boosted: the intersection is likelier the answer than either
+# side's top. Grammar, not domain: it applies to any English code question.
_RELATIONAL_CONNECTIVES = (
" between ",
" from ",
@@ -483,32 +281,20 @@ _RELATIONAL_CONNECTIVES = (
" vs ",
)
-# Term-coverage re-ranker tuning. Multiplies BM25 by (FLOOR + (1-FLOOR)*coverage)
-# where coverage = (# distinct query terms present in hit) / (# query terms).
-# FLOOR=0.5 → single-concept questions (coverage≈1.0) are unaffected;
-# multi-constraint questions where a hit covers 1/3 of terms get scored at 0.67
-# of their raw BM25 (vs 1.0 for a hit covering 3/3). Conjunctive coverage
-# becomes a tie-breaker rather than a hard filter.
+# Term-coverage re-ranker: BM25 * (FLOOR + (1-FLOOR)*coverage), where coverage is
+# the share of distinct query terms present in the hit. Single-concept questions
+# are unaffected; on multi-constraint ones coverage is a tie-breaker, not a filter.
_COVERAGE_FLOOR = 0.5
-# English stopwords. Defined in ``_query_terms`` (stdlib-only, imported by
-# nothing in this package) so the coverage re-ranker here and the prose-keyed
-# symbol leg in ``_prose_symbols`` share one list instead of drifting apart.
+# Shared with the prose-keyed symbol leg so the two lists cannot drift apart.
_STOPWORDS = STOPWORDS
-# Cap on bytes read from source per symbol when we recover a real signature
-# from disk (multi-line def with type annotations). Anything longer than this
-# gets truncated; the agent can call get_symbol for the full body.
+# Line cap on a real signature recovered from disk; get_symbol has the rest.
_MAX_RICH_SIG_LINES = 4
-# Synthesis sampling. Answers target 150-400 words (~550 tokens), so the cap is
-# headroom rather than the binding constraint; generation speed is. Temperature
-# is low because the answer must track the retrieved excerpts, not embellish.
-#
-# That headroom reasoning holds only for a non-reasoning model. A reasoning
-# model spends the same budget on hidden thinking *before* emitting any answer
-# token, so 1024 is not headroom for it — it is the entire allowance, and the
-# call comes back empty with a ``length`` finish_reason (see
-# ``synthesis._empty_completion_note``). REPOWISE_SYNTHESIS_MAX_TOKENS exists
-# so such a model can be given room, instead of being swapped for a weaker one.
+# Synthesis sampling. Answers target 150-400 words, so for a non-reasoning model
+# the token cap is headroom. A reasoning model spends the budget on hidden
+# thinking first and can come back empty with a ``length`` finish_reason, so the
+# env override lets such a model be given room. Low temperature: the answer
+# must track the excerpts, not embellish.
_SYNTHESIS_MAX_TOKENS_ENV = "REPOWISE_SYNTHESIS_MAX_TOKENS"
_SYNTHESIS_MAX_TOKENS_DEFAULT = 1024
@@ -517,8 +303,7 @@ def _synthesis_max_tokens() -> int:
"""The synthesis token budget, from env or the hosted-model default.
An unparseable or non-positive value warns and keeps the default instead
- of silently capping synthesis at 0 — matching how REPOWISE_EMBEDDING_TIMEOUT
- and REPOWISE_VECTOR_SEARCH_TIMEOUT_S are resolved.
+ of silently capping synthesis at 0.
"""
raw = os.environ.get(_SYNTHESIS_MAX_TOKENS_ENV, "").strip()
if not raw:
@@ -577,63 +362,41 @@ of sites; qualify causal claims when a symbol's body was truncated.
# --- Feature flags -----------------------------------------------------------
-# Every REPOWISE_ANSWER_* switch, read at call time so a test or an eval arm can
-# flip one between calls. Each is independently reversible on purpose: they were
-# added one at a time and an A/B must be able to switch one without the others.
-
-# Always-synthesize. Default ON: synthesis runs for every retrieval and the
-# post-synthesis grading cascade demotes confidence instead of the tool
-# abstaining, so coverage matches a research assistant that answers every
-# question. Falsey restores the legacy abstain-on-ambiguous behaviour.
+# Every REPOWISE_ANSWER_* switch, read at call time so a test or eval arm can
+# flip one between calls. Each is independently reversible so an A/B can switch
+# one without the others.
+
+# Default ON: synthesis runs for every retrieval and grading demotes confidence
+# instead of abstaining. Falsey restores abstain-on-ambiguous.
_ALWAYS_SYNTHESIZE_ENV = "REPOWISE_ANSWER_ALWAYS_SYNTHESIZE"
-# Retriever-agreement confidence lift (the measured FTS + vector pair).
+# Retriever-agreement confidence lift (the FTS + vector pair).
_AGREEMENT_CONFIDENCE_ENV = "REPOWISE_ANSWER_AGREEMENT_CONFIDENCE"
-# The keyless-only half of that signal (FTS + symbol in place of FTS + vector,
-# which a keyless index can never produce). Its own flag on purpose: it
-# substitutes a leg the fusion already prices at a third weight, so it must be
-# reversible WITHOUT also switching off the measured half.
+# The keyless FTS + symbol pair. Its own flag so it can be reversed without
+# switching off the FTS + vector half.
_SYMBOL_AGREEMENT_ENV = "REPOWISE_ANSWER_SYMBOL_AGREEMENT"
# Keep the exact_symbol union fast path from hijacking a "how does X work"
-# mechanism question, whose real answer often lives in a different file than the
-# named symbol's body.
+# question, whose answer often lives outside the named symbol's body.
_UNION_MECHANISM_DEFER_ENV = "REPOWISE_ANSWER_UNION_MECHANISM_DEFER"
-# Require the answer's central named mechanism symbol to be grounded in served
-# source before a mechanism/how answer may be stamped high.
+# Require the answer's central mechanism symbol to be grounded in served source
+# before a mechanism/how answer may be stamped high.
_CLAIM_SUPPORT_GATE_ENV = "REPOWISE_ANSWER_CLAIM_SUPPORT_GATE"
-# Let a response earn "high" on a non-dominant retrieval — the served body of
-# the symbol the question named — rather than only a clear dominance margin.
+# Let the served body of the question-named symbol earn "high" on a
+# non-dominant retrieval.
_EARN_HIGH_GROUNDING_ENV = "REPOWISE_ANSWER_EARN_HIGH_GROUNDING"
-# The other half of that lift, and OFF by default: earning high from the prose
-# being consistent with the material it was shown.
-#
-# It is only ever reachable over a weak retrieval. Earning high requires the top
-# score to clear the confidence floor, and a retrieval that clears the floor and
-# dominates is already high without earning anything — so the lift fires exactly
-# when ``retrieval_quality`` reads "weak", which is the pipeline reporting that
-# it may have surfaced the wrong material. Frame-term grounding cannot answer
-# that: it checks that the answer named nothing retrieval did not show it, which
-# is evidence against fabrication and says nothing about whether the material
-# was the right material. The served-body lift above CAN answer it — that body
-# is exact-name resolution rather than ranking, and the source is in the payload
-# — which is why the two are split rather than capped together.
-#
-# On for the previous behaviour, where grounded prose over a tied top pair
-# returned high with "do not re-read the source unless a specific detail is
-# missing".
+# Off by default: earning high from prose consistent with the material shown.
+# This lift only fires over a weak retrieval (a strong dominant one is already
+# high), and frame-term grounding shows the answer invented nothing, not that
+# the material was the right material. The served-body lift above can show
+# that (exact-name resolution, not ranking), which is why the two are split.
_EARN_HIGH_ON_WEAK_RETRIEVAL_ENV = "REPOWISE_ANSWER_EARN_HIGH_ON_WEAK_RETRIEVAL"
-# Test/eval hook: skip the answer cache entirely (both read and write). The
-# cache keys on (repo, question) only — not on feature-flag state — so an A/B
-# eval that flips the flags above between arms would otherwise read the first
-# arm's cached answers. Off by default.
+# Skip the answer cache (read and write). The cache keys on (repo, question), not
+# flag state, so an A/B flipping the flags above would read the first arm's rows.
_DISABLE_CACHE_ENV = "REPOWISE_ANSWER_DISABLE_CACHE"
-# Opt-in: strip re-read evidence from high-confidence answers. A high answer's
-# contract is "cite this, do not re-read the source", so the bodies, quotes,
-# flow_path and candidate evidence are payload the consumer was told it does not
-# need. Off by default; only safe once high-confidence answers are reliable
-# enough that the prose + citation suffices, else the agent calls get_symbol and
-# adds a round-trip.
+# Opt-in: strip re-read evidence from high-confidence answers, whose contract is
+# "cite this, do not re-read". Only safe once high answers are reliable enough;
+# otherwise the agent calls get_symbol and adds a round-trip.
_LEAN_HIGH_ENV = "REPOWISE_ANSWER_LEAN_HIGH"
# Re-read evidence stripped from a lean high answer. NOT stripped: answer,
@@ -657,20 +420,14 @@ def _always_synthesize() -> bool:
def _agreement_confidence_enabled() -> bool:
- """Whether retriever-agreement lifts confidence (default) or pure ratio rules.
-
- Falsey restores the exact prior RRF-compressed ratio/gap behaviour, for A/B
- measurement and instant reversibility.
- """
+ """Whether retriever-agreement lifts confidence (default) or pure ratio rules."""
return _flag_on(_AGREEMENT_CONFIDENCE_ENV)
def _symbol_agreement_enabled() -> bool:
"""Whether a keyless index may read agreement from FTS + the symbol leg.
- Independently reversible from :func:`_agreement_confidence_enabled`, which
- governs the measured FTS + vector pair. Off restores the state where a
- keyless index simply cannot earn the agreement lift.
+ Independently reversible from :func:`_agreement_confidence_enabled`.
"""
return _flag_on(_SYMBOL_AGREEMENT_ENV)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/data_shape.py b/packages/server/src/repowise/server/mcp_server/tool_answer/data_shape.py
index 172cd640c..c39627192 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/data_shape.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/data_shape.py
@@ -1,19 +1,9 @@
"""Ground data-shape questions ("what fields does each entry in X contain?").
-A data-shape question names a data blob / row / record and asks for its field
-set. Fuzzy retrieval scatters across every file that *touches* the blob and
-gates low, so the tool hands back a best_guesses pointer list and the agent
-drills with Read/get_symbol to find the fields itself. But the answer usually
-lives verbatim in source: a documented ``{...}`` shape in a docstring near the
-identifier, and/or the concrete keys consumers pull off the parsed value
-(``partner.get("co_change_count")``). This module mines that field set directly
-so the tool answers in one call.
-
-Precision-first: every reported field is a quoted token lifted from source, so a
-field with no source backing can never be synthesised. Two grounding sources,
-precision-ordered: a documented brace shape (authoritative -> high) beats mined
-key accesses (usage-inferred -> medium). Returns ``None`` (the caller falls
-through to normal retrieval) unless a shape is genuinely grounded.
+Fuzzy retrieval scatters across every file that touches a blob, but the field
+set usually lives verbatim in source: a documented ``{...}`` shape (high) or the
+keys consumers read off the value (medium). Every field is a quoted token lifted
+from source; ``None`` means nothing was grounded and retrieval runs as normal.
"""
from __future__ import annotations
@@ -66,29 +56,21 @@ _CONTAINMENT_VERBS = ("contain", "consist", "comprise", "hold", "look like", "ma
_WORD = re.compile(r"[a-z_]+")
-# A body this long is not a question, it is a report that may contain one. The
-# bound is deliberately generous: the longest genuine one-line data-shape
-# question anyone writes is well under it, and the bug reports this exists to
-# exclude run to a median of about 1200 characters.
+# Longer than this with no `?` is a pasted report, not a question. Generous:
+# genuine one-line shape questions are well under it.
_BARE_QUESTION_MAX_CHARS = 400
-# Sentence-ish split. Only `?` actually matters below; `.`/`!`/newline are here
-# so a question sentence is bounded by the prose around it rather than swallowing
-# it. Fenced code and tracebacks are full of `.` and newlines, which is fine:
-# splitting them finer only makes it harder for a stray cue to land in a clause
-# that also ends in `?`.
+# Only `?` matters below; the other splits bound a question sentence so it
+# cannot swallow the prose around it.
_SENTENCE_SPLIT = re.compile(r"(?<=[.?!])\s+|\n+")
def _interrogative_clauses(question: str) -> list[str]:
"""The parts of ``question`` that are actually asking something.
- A sentence ending in `?` is a question. If the whole input is short and asks
- nothing explicitly, the input *is* the question — "what keys are in the
- blame_record blob" and "describe the schema of GitCommitMeta" are how people
- type, and demanding punctuation of them would break the short-question case
- this fast path exists for. Anything longer with no `?` in it is a report, and
- reports get no clauses.
+ A sentence ending in `?` is a question. A short input with no `?` is itself
+ the question (people rarely punctuate); a longer one is a report and gets
+ no clauses.
"""
clauses = [s.strip() for s in _SENTENCE_SPLIT.split(question) if s.strip().endswith("?")]
if clauses:
@@ -107,16 +89,9 @@ def _is_data_shape_question(question: str, question_ids: set[str]) -> bool:
(entry/record/element/...) paired with a containment verb. Mechanism
questions ("how does X work") carry neither and fall through.
- The cue itself is still cheap, and the miner is still the real precision
- gate. What the clause restriction adds is a precondition on *where* the cue
- may sit. "A false-positive cue is safe" holds for a question someone typed
- and fails for a body someone pasted: across a bug-report corpus a shape noun
- like `field` or `key` appears incidentally in nearly every ticket, the
- identifier extractor always finds something to ground on, and the miner then
- answers a question nobody asked — returning a field list to a caller who
- pasted a stack trace, before retrieval has run at all. Requiring the cue to
- sit in the question's own interrogative clause keeps the short-question case
- intact and stops an arbitrarily long body from being mined by accident.
+ The clause restriction matters for pasted bodies: shape nouns like `field`
+ appear incidentally in most bug reports, and without it the miner would
+ answer a question nobody asked before retrieval runs.
"""
if not question or not question_ids:
return False
@@ -231,17 +206,10 @@ def _run_grep(
def _grep_identifier_files(repo_root: Path, identifier: str, spec: object = None) -> list[str]:
"""Source files naming ``identifier`` (whole word), repo-relative.
- Tracked ``git grep`` first (fast, skips ignored/vendored). If the tree isn't
- a git checkout (returncode 128), retry with ``--no-index`` so the tool still
- grounds its answer on a non-git tree - both are fast C greps, never the
- per-file Python read that wedges on a large tree. Returns the full match set;
- the caller orders (doc files first) then caps, so the documenting file is
- never dropped by an unlucky order.
-
- ``--no-index`` scans the raw filesystem and ignores ``.gitignore``, so a
- gitignored stale wheel / vendored copy can surface as a match. The compiled
- ``spec`` (gitignore + ``exclude_patterns``) filters those out authoritatively,
- matching every other MCP read path.
+ Tracked ``git grep`` first; on a non-git tree (returncode 128) retry with
+ ``--no-index``, which ignores ``.gitignore``, so ``spec`` filters the hits
+ like every other MCP read path. Returns the full match set; the caller
+ orders then caps, so the documenting file is never dropped.
"""
proc = _run_grep(repo_root, [], identifier)
if proc is not None and proc.returncode == 128:
@@ -344,14 +312,10 @@ def _alias_keys_on_documented_lines(
) -> list[tuple[str, int]]:
"""Alias keys a documented field is read as a fallback for.
- Targets one idiom precisely: ``<recv>.get("<A>") or <recv>.get("<B>")`` - the
- same receiver reads two keys joined by ``or``, so when one is a documented
- field the other is an alias for it (``partner.get("co_change_count") or
- partner.get("count")`` -> ``count``; ``... or partner.get("path")`` ->
- ``path``). Requiring the ``or`` fallback and a shared receiver keeps this tight:
- an assignment that merely co-mentions a documented key on a different record
- (``meta["prior_defect_count"] = ...meta["file_path"]``) or a test assertion
- does not match. Returns ``(alias, line)`` for keys not in ``doc_fields``.
+ Targets one idiom: ``<recv>.get("<A>") or <recv>.get("<B>")`` where one key
+ is documented, so the other is its alias. The ``or`` and the shared receiver
+ keep incidental co-mentions out. Returns ``(alias, line)`` for keys not in
+ ``doc_fields``.
"""
out: list[tuple[str, int]] = []
for idx, line in enumerate(lines, 1):
@@ -445,9 +409,7 @@ def mine_data_shape(repo_root: Path | None, question_ids: set[str]) -> dict | No
except Exception:
return None
- # Compile the repo's exclusion rules once per query. The grep fallbacks
- # (esp. ``git grep --no-index`` on a non-git tree) don't honour .gitignore,
- # so filter their hits the same way every other MCP read path does.
+ # ``--no-index`` ignores .gitignore, so grep hits are filtered through this.
exclude_spec = build_exclude_spec(root)
for identifier in _specific_identifiers(question_ids):
@@ -507,12 +469,8 @@ def mine_data_shape(repo_root: Path | None, question_ids: set[str]) -> dict | No
if any(src["file"] == s["file"] for s in sources):
continue
sources.append(src)
- # Divergence: keys consumers read right beside a documented field but
- # the doc never lists (a legacy alias like ``count`` for
- # ``co_change_count``, an optional key). The documented shape is
- # authoritative for what it declares, but if we said "cite it, no Read
- # needed" while hiding a key four consumers defensively handle, an
- # agent could ship a change that ignores it. Surface it instead.
+ # Keys consumers read beside a documented field that the doc omits
+ # (an alias): "no Read needed" must not hide a key the code handles.
doc_field_set = set(fields)
also_accessed: list[dict] = []
also_seen: set[str] = set()
@@ -582,9 +540,6 @@ def _data_shape_prose(grounded: dict, citations: list[str]) -> tuple[str, str]:
"data_shape.sources lists every field's origin line.",
)
- # The doc lists the declared shape, but consumers read alias key(s) it omits
- # (a legacy fallback). Surface them: telling the agent "no Read needed" while
- # hiding a key it must handle would be a confidently-incomplete answer.
alias_list = ", ".join(f"`{a['field']}`" for a in also_accessed)
first_alias = also_accessed[0]
return (
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py b/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py
index f9d153c23..1d3ba68d5 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py
@@ -1,12 +1,8 @@
"""The synthesis-less get_answer reply.
-Both ways synthesis can be missing — no provider resolvable, or the call failed —
-return the same payload from the same evidence. Only synthesis is missing here:
-retrieval ran, ranked the corpus and succeeded, and everything below the provider
-check (bodies, citations, best guesses, mined rationale, the next action) is read
-live off disk from index anchors and needs no LLM. The only thing that coupled
-that evidence to synthesis was that body selection matched against the answer
-text, so here the question's own identifiers stand in.
+No provider and a failed call share one payload. Retrieval succeeded and all
+evidence (bodies, citations, best guesses, rationale) is read live from disk
+with no LLM; body selection matches the question's identifiers, not prose.
"""
from __future__ import annotations
@@ -41,19 +37,13 @@ from repowise.server.mcp_server.tool_answer.retrieval import (
def _degraded_summary(reason: str, symbol_bodies: list[dict], served: int) -> str:
"""The ``answer`` sentence a synthesis-less payload states about itself.
- An empty ``answer`` beside a working retrieval reads as a failed call rather
- than a partial one, and a reader who takes it at face value discards a usable
- result and starts over. So the sentence is assembled from what the payload
- actually carries — it can never claim more than it has, and it invents no
- prose about the question itself, that being precisely the part that needs a
- provider. Three cases, best evidence first: bodies in hand, a ranked
- retrieval, or nothing.
+ An empty ``answer`` reads as a failed call and gets a usable result
+ discarded. Assembled only from what the payload carries, inventing no prose
+ about the question. Best evidence first: bodies, a ranked retrieval, nothing.
"""
if symbol_bodies:
names = ", ".join(f"`{b['name']}`" for b in symbol_bodies)
- # Never say "full" over a body the payload itself flags as cut. The
- # entry carries `truncated` and a `continuation` two keys away, so the
- # claim is refutable from inside the same response.
+ # Never say "full" over a body the payload itself flags as cut.
cut = any(b.get("truncated") for b in symbol_bodies)
return (
f"No synthesized prose ({reason}), but the evidence is here: "
@@ -95,16 +85,9 @@ async def _degraded_payload(
) -> dict:
"""Shape a synthesis-less get_answer response.
- ``degraded`` is mirrored into ``_meta`` because consumers read freshness and
- health signals from there; the failure path used to set only the top-level
- key, so a caller watching ``_meta`` saw a normal empty answer.
-
- ``confidence`` is graded by :func:`_degraded_confidence` from the retrieval
- this payload actually served, not pinned. It rates what the caller can act on
- without further work, which is the same thing it rates on the keyed path; the
- boilerplate ``answer`` is why "high" is unreachable here rather than why the
- field says nothing. ``retrieval_quality`` rates the retrieval on its own and
- is what the grade is derived from, so the two can never disagree.
+ ``degraded`` is mirrored into ``_meta``, where consumers read health
+ signals. ``confidence`` is graded by :func:`_degraded_confidence` from
+ ``retrieval_quality``, so the two can never disagree.
"""
retrieval_quality = _retrieval_quality(hits, agreement_dominant)
confidence = _degraded_confidence(reason, retrieval_quality)
@@ -113,10 +96,7 @@ async def _degraded_payload(
_gather_body_candidates(hits, "", anchor_names=question_ids or set()),
repo_root,
)
- # Cite what is actually in hand. `[]` was right when the payload carried no
- # source; with bodies inlined the paths they were read from are citations in
- # the ordinary sense, and a caller filtering on non-empty `citations` stops
- # discarding this reply.
+ # Inlined bodies are citations in the ordinary sense.
citations = list(dict.fromkeys(b["path"] for b in symbol_bodies))
summary = _degraded_summary(reason, symbol_bodies, len(hits))
@@ -161,11 +141,8 @@ async def _degraded_payload(
"answer from that rather than re-reading the file."
)
elif best_guesses and retrieval_quality != "weak":
- # No body, so the next step is a choice between files. Not on a weak
- # retrieval: `_meta.hint` there says "refine the query rather than
- # reading these files in order", and two hints that disagree are worse
- # than one. Names `best_guesses`, not its excerpt — that copy is dropped
- # on the way out, since this path always has a populated `retrieval`.
+ # Not on a weak retrieval, where `_meta.hint` says to refine the query
+ # and two disagreeing hints are worse than one.
payload["next_action_hint"] = (
f"Start from {best_guesses[0]['file']} — it ranked highest, and "
"best_guesses says why each candidate is in the running."
@@ -190,18 +167,10 @@ async def _degraded_payload(
async def _degraded_next_action(symbol_bodies: list[dict], ctx, repository, exclude_spec) -> str:
"""The one next step a degraded payload with bodies in hand should name.
- A whole body is a terminal answer, so say so rather than sending the caller
- to Read a file it already holds. A cut body is not: name the continuation, or
- a withheld symbol when one resolves.
-
- Two filters on the withheld ids, both already established on the synthesised
- path. A withheld entry carrying the served body's OWN name is the enclosing
- symbol continuing past the cut, not something that never arrived, so it is
- dropped and the ``continuation``, which fetches exactly the missing part, is
- the pointer. And the ids come from a regex scanner over source lines, so it
- can name something that is not a symbol at all: ``_first_resolvable_id``
- keeps a fabricated id from becoming the next action here exactly as it does
- there.
+ A whole body is a terminal answer. A cut body names a withheld symbol that
+ resolves, else its ``continuation``. As on the synthesised path, the
+ enclosing symbol's own name is not a withheld symbol, and
+ ``_first_resolvable_id`` keeps a scanner-invented id out of the hint.
"""
cut = next((b for b in symbol_bodies if b.get("continuation")), None)
if cut is None:
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.py b/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.py
index d94489555..3029172c2 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.py
@@ -1,18 +1,9 @@
"""Attach a dated episode that disagrees with a synthesised answer.
-``get_answer`` reasons from the code as it is now, and it is confidently wrong
-about what was *decided*. The reproduction this module exists for: asked
-whether to run the declared formatter before committing, the tool reads a
-``format`` target out of the build files and answers yes — while the checkout's
-own episode store holds a ``formatter_drift`` record saying the tree is not
-formatter-clean and a repo-wide run would produce a large unrelated diff.
-
-**Add, never replace.** The synthesis stays exactly as it was; a matching
-episode is appended beside it as a dated, attributed quotation. Replacing the
-answer would introduce the failure this exists to prevent, because the episode
-is sometimes the stale one and the synthesis the correct one. A reader who sees
-"recorded at ``acd24602``" next to "run the formatter" does not run it, and
-nothing is lost when the episode has expired.
+``get_answer`` reasons from the code as it is now and can be confidently wrong
+about what was *decided*. **Add, never replace:** a matching episode is appended
+beside the synthesis as a dated quotation, because sometimes the episode is the
+stale one.
Three preconditions, checked in this order:
@@ -20,10 +11,8 @@ Three preconditions, checked in this order:
2. the episode is still true,
3. the synthesis is below ``confidence: high``.
-Any one missing means silence, and silence is byte-identical to today's
-payload. This runs at **serve time on both the fresh and the cached path**, so
-the episode is read fresh on every call and a disagreement is never frozen into
-a cache row — which is also why adding it needs no answer-schema bump.
+Any one missing means silence. Runs at serve time on the fresh and cached paths,
+so an episode is never frozen into a cache row.
"""
from __future__ import annotations
@@ -52,20 +41,13 @@ _MAX_EPISODES = 1
#: stays recoverable via ``repowise expand`` rather than vanishing.
_MAX_BODY_CHARS = 600
-#: How many node-scoped candidates are tested for staleness before giving up.
-#: Each test may cost one git query, so this is what keeps the sanctioned
-#: read-time exception bounded no matter how large the store grows. One
-#: repo-wide candidate may follow them (see :func:`_candidate_window`), so the
-#: ceiling on git queries per call is this plus one.
+#: Node-scoped candidates tested for staleness. Each may cost one git query, so
+#: this bounds the read-time git cost; with one possible repo-wide candidate
+#: (see :func:`_candidate_window`) the ceiling is this plus one.
_MAX_SCOPED_CANDIDATES = 4
-#: The tiers this guard is willing to put in front of a reader. Shared with
-#: every other episode reader (:mod:`repowise.server.mcp_server._episodes`),
-#: because "which tiers are shareable" is a property of the store rather than
-#: of one tool, and the first version of this constant reached the wrong answer
-#: by being local: an unnamed default let the store's second tier arrive
-#: uninvited, and with 56 of this repository's 426 sessions recorded the guard
-#: went **silent on its own reproduction** and served a session instead.
+#: Shared with every episode reader: which tiers are shareable is a property
+#: of the store, not of one tool.
_SERVED_TIERS = SERVED_TIERS
#: Room the block needs before it is worth attaching at all.
@@ -187,25 +169,11 @@ def _attach(
def _candidate_window(scoped: list[tuple[dict, list[str]]]) -> list[tuple[dict, list[str]]]:
"""The candidates staleness is tested on: bounded, and never one-sided.
- Ranking puts path matches above subject matches, which is right. But a
- node-scoped episode is *suppressed outright* when anything has touched its
- files since, while a repo-wide one is served with its age labelled. A store
- holding hundreds of the former and a handful of the latter would therefore
- fill the whole window with candidates that can only fall through, and the
- surface would go silent on a repository that had more history rather than
- less.
-
- So the best repo-wide candidate is **appended** when the window would
- otherwise hold none. Appended rather than substituted, and the difference
- is the whole point: a repo-wide verdict never suppresses, so putting one
- in the last slot would not fall back to it, it would pre-empt the
- node-scoped candidate standing there — trading a git-verified "nothing in
- its scope has changed" for an unchecked claim about the whole tree, which
- is backwards on a surface whose bar is precision at the acting stage.
-
- It costs one more possible git query in the worst case, and that is the
- honest price of a fifth candidate rather than something to hide by
- dropping the fourth.
+ A stale node-scoped episode is suppressed, while a repo-wide one is served
+ with its age labelled, so a window of node-scoped candidates alone could
+ all fall through. The best repo-wide candidate is therefore **appended**
+ when the window holds none. Not substituted: a repo-wide verdict never
+ suppresses, so in the last slot it would pre-empt a git-verified candidate.
"""
window = scoped[:_MAX_SCOPED_CANDIDATES]
if any(not matched for _row, matched in window):
@@ -228,28 +196,20 @@ def _scope(
) -> list[str] | None:
"""The part of the answer this episode is about, or None if it is not.
- Two rules, one per shape of episode. An episode that names files is scoped
- by those files. An episode with an **empty node set is a claim about the
- checkout as a whole** — it is not "unknown scope", and it does not
- therefore intersect everything: read that way, the repo-wide facts would
- ride along on every sub-high-confidence answer in the repository, which is
- the noise this gate exists to prevent. Repo-wide episodes are scoped by
- their subject instead, which the store already defines as the field that
- discriminates episodes within a kind.
+ An episode that names files is scoped by them. An empty node set is a claim
+ about the whole checkout, not "unknown scope" that intersects everything,
+ so repo-wide episodes are scoped by their subject instead.
"""
nodes = [n for n in (row.get("nodes") or []) if isinstance(n, str) and n]
if nodes:
return sorted({p for p in answer_paths if _covers(nodes, p)}) or None
subject = (row.get("subject") or "").strip()
- # A subject with no word character (``nested_repos`` uses ``.`` for the
- # repo root) is not a topic — and ``\b`` around pure punctuation matches in
- # places no reader would call a mention.
+ # A punctuation-only subject (``.`` for the repo root) is not a topic, and
+ # ``\b`` around punctuation matches nonsense.
if not re.search(r"\w", subject):
return None
- # A subject equal to the repository's own name has no topic scope: every
- # answer in a repo names the repo, so matching on it is matching on
- # nothing.
+ # Every answer names its own repo, so that subject scopes nothing.
if repo_name and subject.casefold() == repo_name.strip().casefold():
return None
if not re.search(rf"\b{re.escape(subject.casefold())}\b", haystack):
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/evidence.py b/packages/server/src/repowise/server/mcp_server/tool_answer/evidence.py
index 88413374e..d9199883e 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/evidence.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/evidence.py
@@ -54,20 +54,10 @@ def _is_readable_path(target: str) -> bool:
async def _first_resolvable_id(ids: list[str], ctx, repository, exclude_spec) -> str | None:
"""The first id ``get_symbol`` would actually answer, or None if none would.
- Notes and ``next_action_hint``s interpolate a ``symbol_id`` straight out of
- the scanner. The scanner is a regex over source lines, so it can name
- something that is not a symbol, and an answer must never advertise a next
- action that dead-ends.
-
- ``get_symbol`` has THREE outcomes and only one of them is a failure: an
- indexed row, a live-grep fallback when the name is in the file but not the
- index, and nothing at all. Treating the live-grep case as unresolvable is a
- mistake already made once while measuring this, so it counts as resolved.
-
- Deliberately conservative in the other direction: an id whose file cannot be
- read is KEPT, because an unreadable file is absence of evidence, not
- evidence the id is fabricated. Only a positive read that does not contain
- the name, with no index row either, disqualifies one.
+ The regex scanner can name a non-symbol, and a next action must never
+ dead-end. ``get_symbol`` answers from an indexed row or a live grep of the
+ file, so either counts as resolved. An unreadable file is KEPT (absence of
+ evidence); only a read lacking the name, with no index row, disqualifies.
"""
repo_root = _repo_root(ctx)
for sid in ids:
@@ -92,12 +82,9 @@ async def _first_resolvable_id(ids: list[str], ctx, repository, exclude_spec) ->
def _rationale_anchors(h: dict) -> list[tuple[str, int | None]]:
"""One ``(path, near-line)`` pair per reason this hit is worth scanning.
- A concept-anchored file leads: it was selected precisely because its comment
- explains the question, and the grep match line is the best near-line boost
- available. Each anchored or question-matched symbol then contributes the
- same path again at its own definition line, so a file with several matches
- is repeated as many times as it has reasons, which is the weighting the
- scan orders on.
+ A concept-anchored file leads, at its grep match line. Each anchored or
+ matched symbol repeats the path at its definition line, so a file appears
+ once per reason: the weighting the scan orders on.
"""
path = h.get("target_path")
if not path:
@@ -115,16 +102,10 @@ def _rationale_anchors(h: dict) -> list[tuple[str, int | None]]:
async def _gather_code_rationale(ctx, hits: list[dict], fallback_targets: list[str], question: str):
"""Mine in-code rationale comments for a low-confidence answer.
- The wiki/decision corpus failed to ground the question; the "why" may be a
- plain code comment instead. Scan the already-relevant files — anchored /
- matched-symbol files lead, with a near-line boost on their definition, then
- fallback_targets fill the rest — for comment blocks carrying a rationale
- marker overlapping the question. Best-effort: returns [] on any failure,
- never raises into the tool path.
-
- Off the loop, like the sibling live-source miner on the value fast path:
- it is small per call, and every concurrent request pays it if it runs where
- the loop can feel it.
+ The "why" may be a plain code comment the wiki missed. Scans anchored and
+ matched files first, then fallback_targets, for rationale comments
+ overlapping the question. Best-effort ([] on failure) and off the event
+ loop, so concurrent requests do not pay for it.
"""
repo_root = getattr(ctx, "path", None)
if not repo_root:
@@ -149,11 +130,8 @@ async def _gather_code_rationale(ctx, hits: list[dict], fallback_targets: list[s
def _drop_already_surfaced(rationale: list[dict], *surfaced: list[dict]) -> list[dict]:
"""Drop mined rationale comments already shown elsewhere in the response.
- The same comment can reach the payload twice — once as material already in
- the response (a ``symbol_bodies`` block whose body contains it, a quote, a
- line-ranged citation, or a legacy ``code_comment`` decision) and once as a
- live-mined ``code_rationale`` entry. Drop any mined comment whose
- ``(path, line-range)`` overlaps an entry already surfaced. Entries without a
+ Drops any mined comment whose ``(path, line-range)`` overlaps a surfaced
+ entry (a body, quote or line-ranged citation). Entries without a
``(path, lines)`` pair are ignored.
"""
occupied = [span for entries in surfaced for span in map(_line_span, entries or []) if span]
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/payload.py b/packages/server/src/repowise/server/mcp_server/tool_answer/payload.py
index e31d80373..abbf73101 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/payload.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/payload.py
@@ -62,15 +62,9 @@ from repowise.server.mcp_server.tool_answer.symbols import (
def _trim_served_payload(payload: dict) -> dict:
"""Every size cut that runs on the way OUT, on both the fresh and cache paths.
- Serve-time rather than build-time, and that is the whole point. A cut applied
- where the payload is assembled reaches only fresh answers: a cache row
- written by an older build keeps the old shape until ``_ANSWER_SCHEMA_VERSION``
- moves, and bumping that invalidates every user's answer cache — re-synthesis,
- i.e. real provider spend — to change the size of a block. Trimming on the way
- out fixes old and new rows alike and costs nobody a re-synthesis.
-
- Anything that only REMOVES redundancy belongs here. Anything that changes
- what an answer says does not, and still owes a schema bump.
+ Serve-time so cached rows from older builds are trimmed too, without a
+ ``_ANSWER_SCHEMA_VERSION`` bump and its re-synthesis spend. Only cuts that
+ REMOVE redundancy belong here; changing what an answer says owes a bump.
"""
_cap_candidates(payload)
_drop_duplicated_guess_excerpts(payload)
@@ -88,16 +82,9 @@ def _cap_candidates(payload: dict) -> dict:
def _drop_duplicated_guess_excerpts(payload: dict) -> dict:
"""Drop ``best_guesses[].excerpt`` where ``retrieval[]`` already carries it.
- Both blocks slice the same page excerpt for the same file, so when both are
- present the guess copy is byte-for-byte redundant.
-
- **Conditional, and the condition matters.** ``retrieval`` is
- confidence-gated and shrinks to nothing as the prose gets more trustworthy;
- the legacy abstain path ships ``retrieval: []`` outright. On those responses
- the guess excerpt is the only content in the payload, not a duplicate of
- anything. So the drop is keyed on the duplicate actually being present, which
- makes it lossless rather than merely cheap — and keeps every ``excerpt``
- mentioned by ``note`` / ``next_action_hint`` on the paths that mention it.
+ Keyed on the duplicate actually being present: ``retrieval`` is often empty
+ (high confidence, legacy abstain), and there the guess excerpt is the only
+ content, so the drop stays lossless.
"""
guesses = payload.get("best_guesses")
if not guesses:
@@ -117,12 +104,9 @@ def _drop_duplicated_guess_excerpts(payload: dict) -> dict:
def _apply_lean_high(payload: dict, question: str) -> dict:
"""Strip re-read evidence from a mainline high-confidence answer, in place.
- No-op unless the flag is on and confidence is high. Two carve-outs keep the
- evidence where it IS the answer: grounded fast paths (extracted /
- exact_symbol / symbol_body / data_shape, which carry a ``grounding`` key,
- and whose inlined body is the whole answer) and why-questions — a "because X"
- is justified by exactly the code_rationale / quotes this strips, so a lean
- why-answer loses the grounding its rationale stands on.
+ No-op unless the flag is on and confidence is high. Evidence is kept where
+ it IS the answer: grounded fast paths (a ``grounding`` key) and why-questions,
+ whose "because X" rests on the code_rationale / quotes this strips.
"""
if not _lean_high() or payload.get("confidence") != "high" or payload.get("grounding"):
return payload
@@ -139,23 +123,16 @@ def _apply_lean_high(payload: dict, question: str) -> dict:
def _build_best_guesses(hits: list[dict]) -> list[dict]:
"""Decision-shaped candidate list: per-file justification, score, excerpt.
- The evidence an ambiguous-retrieval reply carries so the agent can pick ONE
- file to verify instead of skimming five. Shared by the legacy abstain path,
- the always-synthesize low/medium fold-in, and the degraded paths.
-
- ``file`` is resolved through ``hit_file_path``, and a hit resolving to no
- file is skipped — both for the reason ``serialize_candidates`` does it: a
- ``symbol_spotlight`` page's ``target_path`` is ``file.py::Symbol`` and a
- module page's is a group key, neither of which a consumer can open. This
- field is named "file" and gets Read.
+ Lets the agent pick ONE file to verify on an ambiguous retrieval. ``file``
+ goes through ``hit_file_path`` and unresolvable hits are skipped, since a
+ spotlight or module page's ``target_path`` is not an openable file.
"""
return [
{
"file": hit_file_path(h),
"why_relevant": _candidate_justification(h),
"score": round(h.get("score", 0.0), 3),
- # Absent rather than null: a penalty applies to a minority of hits,
- # so the common row would pay characters to say nothing happened.
+ # Absent rather than null: most rows carry no penalty.
**({"domain_penalty": h["_domain_penalty"]} if h.get("_domain_penalty") else {}),
**({"excerpt": h["excerpt"]} if h.get("excerpt") else {}),
}
@@ -167,23 +144,10 @@ def _build_best_guesses(hits: list[dict]) -> list[dict]:
def _with_candidates(payload: dict, resolved_pool: list[dict]) -> dict:
"""Attach the ranked shortlist to a payload that is about to be returned.
- ``get_answer`` has several early returns that fire *after* retrieval has run:
- the qualified-miss guard, answer-by-union, the value-extraction fast path,
- the legacy abstain, and both degraded paths. Each was written as a complete
- reply in its own terms and each set ``retrieval`` to ``[]`` and returned.
-
- That is right about ``retrieval``, which is re-read evidence for a synthesised
- answer, and wrong about what the caller is left holding. ``resolved_pool``
- already exists at every one of these sites: the full ranked file list, built
- before the 5-hit synthesis cap, at no further cost. Discarding it means a
- caller whose question tripped one of these gates gets a narrower reply than
- one whose question did not, and gets it *because* we recognised their question
- more precisely.
-
- So the shortlist travels with every reply. This adds to a payload and takes
- nothing away: no gate stops firing, no predicate moves, and the special reply
- each gate exists to give is returned unchanged. It is deliberately NOT the
- fix of loosening a gate, which measured worse on recall@5.
+ Every post-retrieval early return empties ``retrieval``, but the pre-cap
+ ranked pool is still free and useful, so a caller whose question tripped a
+ special path is not left with less than one whose question did not. Adds to
+ the payload only; no gate changes.
"""
candidates = _serialize_candidates(resolved_pool)
if candidates:
@@ -194,14 +158,8 @@ def _with_candidates(payload: dict, resolved_pool: list[dict]) -> dict:
def _no_answer_payload(note: str, *, repository, t0: float) -> dict:
"""The reply for a post-retrieval gate that has nothing to answer with.
- Two gates end this way and both mean the same thing: retrieval ran, and the
- honest reply is "not this" plus what to do instead. The qualified-miss guard
- refuses to substitute a same-named symbol from another file; the no-hits
- guard has no candidates at all. ``note`` is the only part that differs, and
- it carries the redirect.
-
- Both callers still wrap this in :func:`_with_candidates`, which is what keeps
- the ranked shortlist travelling with every post-retrieval return.
+ Used by the qualified-miss and no-hits guards; ``note`` carries the
+ redirect. Callers still wrap it in :func:`_with_candidates`.
"""
return {
"answer": "",
@@ -233,21 +191,13 @@ def _union_answer_payload(
) -> dict | None:
"""The answer-by-union reply, or None to let synthesis handle the question.
- The question named a symbol with N>=2 defs no qualifier disambiguates
- (``_severity_for`` x 4). Instead of bailing to a best_guesses pointer list
- (the exact thing that triggers the agent's get_symbol/get_context drill),
- inline the UNION of the candidate bodies (char-budgeted, Read-parity) so the
- agent picks the one it wants from material already in-hand. This is the fix
- for the retrieval-MISS class: those defs are never in the fuzzy candidate
- set, so the exact-name scan is the only thing that surfaces them.
-
- Returns None in three cases, all of which mean the union is not the answer:
- the union is incidental (a prose question that merely mentions a many-def
- generic method like ``to_dict`` would otherwise dump every unrelated body as
- a confidence=high answer, burying what was actually asked), the question is a
- mechanism/"how" question whose real answer often lives in another file the
- union path never retrieves, or the bodies could not be read — in which case
- falling through to the normal gate path beats returning an empty union.
+ The question named a symbol with N>=2 undisambiguated defs, so the UNION of
+ their bodies is inlined (char-budgeted) rather than a pointer list. The
+ exact-name scan is the only thing that surfaces defs fuzzy retrieval missed.
+
+ Returns None when the union is not the answer: a prose question merely
+ mentioning a generic many-def method, a mechanism question whose answer
+ often lives elsewhere, or unreadable bodies.
"""
union_groups = homonyms.get("union") or {}
if union_groups and union_defers_to_synthesis(question, question_ids, union_groups):
@@ -259,25 +209,13 @@ def _union_answer_payload(
repo_root = _repo_root(ctx)
union_bodies, more_defs = build_homonym_union_bodies(repo_root, union_groups)
if not union_bodies:
- # Bodies unreadable (no repo root / files gone) — fall through to the
- # normal retrieval/gate path rather than returning an empty union.
return None
names = sorted(union_groups)
total = sum(len(v) for v in union_groups.values())
cited = sorted({b["path"] for b in union_bodies})
- # This payload returns BEFORE synthesis, so none of the confidence gates ever
- # see it: it is served in no-LLM mode and it used to hardcode
- # confidence="high" with "no verification Read" even when a body arrived
- # truncated. "this is the complete set" is also an exclusivity claim,
- # generated by us rather than by a model, and it is true of the DEFINITION
- # SET while saying nothing about whether each body was served whole.
- #
- # The dependency test the synthesis gate uses CANNOT work here, and keying on
- # it made this gate dead code. This path is reached only for naming/lookup
- # questions about the homonym, so the question names the SERVED symbol by
- # construction while the withheld symbols are its inner members, and there is
- # no answer prose to inspect either. Here the bodies simply ARE the answer,
- # so truncation alone is the right condition.
+ # Returns before synthesis, so no confidence gate sees it. The withheld
+ # dependency test cannot fire here (the question names the SERVED symbol),
+ # and the bodies ARE the answer, so truncation alone caps the grade.
union_truncated = any(b.get("truncated") for b in union_bodies)
_union_confidence = "medium" if union_truncated else "high"
note = (
@@ -311,9 +249,7 @@ def _union_answer_payload(
),
"citations": cited,
"confidence": _union_confidence,
- # Rates the `candidates` shortlist, not the bodies: the union answers by
- # exact name and the note offers that shortlist for "if you meant
- # something else". It is the one body-serving return that had no rating.
+ # Rates the `candidates` shortlist, not the exact-name bodies.
"retrieval_quality": retrieval_quality,
"grounding": "exact_symbol",
"symbol_bodies": union_bodies,
@@ -340,17 +276,12 @@ async def build_abstain_payload(
) -> dict:
"""The legacy abstain reply (REPOWISE_ANSWER_ALWAYS_SYNTHESIZE=off).
- Retrieval is ambiguous, so skip synthesis and hand back ranked excerpts +
- best_guesses for the agent to ground in. The excerpts those best_guesses
- carry were attached by the caller: a pointers-only gated payload sends the
- agent into a long Grep/Read spree that costs more than a bare agent, since it
- paid for the tool call and still had to acquire all content natively.
- Excerpts turn the miss path into "pick one candidate, verify with at most one
- Read".
+ Retrieval is ambiguous, so synthesis is skipped and best_guesses carry
+ excerpts: pointers alone send the agent on a Grep/Read spree, excerpts turn
+ the miss into "pick one candidate, verify with at most one Read".
"""
best_guesses = _build_best_guesses(hits)
- # Mine source comments for rationale the wiki/decision corpus missed —
- # turns "go Read these 5 files" into a cited why.
+ # Source-comment rationale the wiki/decision corpus missed.
code_rationale = await _gather_code_rationale(ctx, hits, fallback_targets, question)
has_excerpts = any("excerpt" in g for g in best_guesses)
gated: dict = {
@@ -402,8 +333,7 @@ def build_value_payload(
"""The value-extraction fast path reply.
The verbatim assignment line (read live by the hydrator) IS the answer.
- One call, zero LLM cost, and it cannot hallucinate. Not cached: extraction is
- cheap and must always reflect the current source.
+ Not cached: extraction is cheap and must reflect the current source.
"""
top_score_fp = hits[0].get("score", 0.0) if hits else 0.0
answer_text = extraction["answer"]
@@ -491,13 +421,8 @@ async def build_synthesized_payload(
exclude_spec=exclude_spec,
)
- # Ambiguous-retrieval evidence (always-synthesize). The questions that used
- # to abstain (no dominant page) now carry synthesized PROSE — but the
- # retrieval was genuinely ambiguous, so ship the same evidence the old
- # abstain path did: best_guesses (per-file justification + excerpts) and
- # mined code_rationale, plus an honest caveat. This is the "answered, but
- # verify against these candidates" reply that replaced the empty pointer
- # list. Guarded so it never touches the dominant / high-confidence paths.
+ # Non-dominant retrieval: the prose ships with the abstain path's evidence
+ # (best_guesses, code_rationale) and a caveat, "answered, but verify".
if not dominant:
payload.setdefault("best_guesses", _build_best_guesses(hits))
if "code_rationale" not in payload:
@@ -506,11 +431,8 @@ async def build_synthesized_payload(
if _cr:
payload["code_rationale"] = _cr
if grade.high_reason == "symbol_body":
- # Held at high over an ambiguous ranking because the body of the
- # symbol the question named is inlined below. Telling the agent to
- # verify against best_guesses would send it to the ranked pages the
- # confidence deliberately does not rest on, so the caveat scopes the
- # doubt to the page choice and leaves the served body alone.
+ # High rests on the served body, not the ranking, so the caveat
+ # scopes doubt to the page choice rather than pointing at best_guesses.
_caveat = (
"Retrieval was ambiguous (no single dominant page), so the "
"candidates listed are a ranking, not a finding — the confidence "
@@ -549,13 +471,9 @@ async def _hedged_payload(
) -> dict:
"""The reply for an answer whose own prose admits it could not answer.
- Keep the retrieval payload lean but non-empty. The consumer has been told to
- read the source, but the ranked hits are exactly what tells it WHICH source —
- and a flow endpoint or a surfaced subsystem page that only lives in this block
- would otherwise vanish from the response entirely, since it is not in
- citations, which are drawn from the prose. The lean form (no per-hit
- key_symbols dump) keeps the prompt-cache cost the empty payload was
- protecting.
+ The retrieval block stays lean but non-empty: the ranked hits say WHICH
+ source to read, and a hit absent from the prose-drawn citations would
+ otherwise vanish entirely.
"""
payload = {
"answer": answer_text,
@@ -563,11 +481,8 @@ async def _hedged_payload(
"confidence": confidence,
"retrieval_quality": retrieval_quality,
"fallback_targets": fallback_targets[:5],
- # The hedge is the priciest reply we send and the least likely to be
- # right, so it gets the graded low branch's excerpt budget rather than
- # one of its own. Safe to cut at build time, unlike most payload cuts:
- # `_cache_bypass_reason` refuses every hedged row, so a hedged reply is
- # always freshly built and no stored row can keep the wider shape.
+ # The low branch's excerpt budget. Safe to cut at build time: hedged rows
+ # are never served from cache, so no stored row keeps a wider shape.
"retrieval": _serialize_hits(
hits, limit=5, lean_symbols=True, excerpt_rows=_GATED_RETURN_HITS
),
@@ -576,16 +491,10 @@ async def _hedged_payload(
"the indexed wiki. Read one of fallback_targets to answer."
),
}
- # Even on a hedge, hand over any question-named symbol bodies we resolved —
- # the agent can read the body directly instead of the fallback_targets file,
- # which is the whole point of anchoring.
if symbol_bodies:
payload["symbol_bodies"] = symbol_bodies
if served_named_body:
- # The exact symbol the question named is inlined below as live
- # source. That is the answer; the hedge is about the surrounding
- # prose, not the body. Say so, and mark the response grounded so the
- # agent cites the body instead of re-reading the file.
+ # The hedge is about the prose; the named body is the answer.
payload["grounding"] = "symbol_body"
payload["note"] = (
"Synthesis hedged on the prose, but symbol_bodies carries "
@@ -597,9 +506,8 @@ async def _hedged_payload(
"Synthesis hedged, but symbol_bodies carries the live body "
"of the symbol(s) you named — read that to answer."
)
- # The hedge often means the rationale isn't in the wiki at all — it's a code
- # comment. Mine the candidate source for it before sending the agent off to
- # Read. A comment already visible in symbol_bodies must not surface twice.
+ # A hedge often means the rationale is a code comment, not wiki prose. A
+ # comment already visible in symbol_bodies must not surface twice.
code_rationale = await _gather_code_rationale(ctx, hits, fallback_targets, question)
code_rationale = _drop_already_surfaced(code_rationale, symbol_bodies)
if code_rationale:
@@ -614,16 +522,10 @@ async def _hedged_payload(
def _high_confidence_note(grade: _Grade, tail: str) -> str:
"""The high-confidence note, written from the reason the grade was reached.
- Each branch quotes the measurement its own tier made and no other. The ratio
- is a valid justification only under ``"ratio"``: the gap tier exists BECAUSE
- the ratio is uninformative where both scores are strong (6.0 vs 5.4 reads as
- 1.11x), and fusion compresses agreement pairs to about 1.02x, so quoting it
- under either would print a near tie as the reason for confidence.
-
- Only the dominance tiers and ``"symbol_body"`` reach *tail*, which is what
- tells the agent it need not re-read the source. ``"grounding"`` never does:
- it establishes the prose is not fabricated, which is not a claim about
- whether the page it describes is the right one.
+ Each branch quotes only the measurement its own tier made (see
+ :func:`dominance_reason`). Only the dominance tiers and ``"symbol_body"``
+ reach *tail*, the "need not re-read" line; ``"grounding"`` shows the prose
+ is not fabricated, not that the page is the right one.
"""
if grade.high_reason == "symbol_body":
return (
@@ -683,15 +585,9 @@ async def _graded_payload(
) -> dict:
"""The non-hedged reply, with the note the first applicable gate finding writes.
- Confidence-conditional retrieval block: the block exists so the agent can
- ground when the answer alone isn't trustworthy. At high confidence the
- citations + answer suffice — carrying five enriched hits through the
- conversation cache buys nothing. At medium the agent verifies the top
- candidates: two truncated hits, no symbol enrichment for graph-expansion
- neighbors. Low keeps a grounding block, but lean: the top hits with snippets,
- symbols pipeable but stripped of docstrings/excerpts, since the full per-hit
- key_symbols dump was the largest block by volume and went mostly unused on a
- low-confidence answer.
+ The retrieval block is confidence-conditional: empty at high (citations
+ suffice), two truncated hits at medium, and a lean block at low (symbols
+ without docstrings/excerpts, the largest and least-used part).
"""
confidence = grade.confidence
if confidence == "high":
@@ -715,12 +611,7 @@ async def _graded_payload(
if symbol_bodies:
payload["symbol_bodies"] = symbol_bodies
if grade.high_reason == "symbol_body":
- # Same value the hedged path already emits for the same situation: what
- # this answer rests on is the served body, not the ranking. It also has
- # to be set for `_apply_lean_high` to see it — that strips `symbol_bodies`
- # from a high-confidence payload unless `grounding` marks it as the
- # evidence, and the note below points the agent straight at the block it
- # would otherwise have removed.
+ # Also what stops `_apply_lean_high` stripping the body the note cites.
payload["grounding"] = "symbol_body"
if grade.ungrounded_values:
payload["note"] = (
@@ -736,11 +627,8 @@ async def _graded_payload(
f"{grade.ungrounded_values} against the live source."
)
elif grade.frame_unsupported:
- # The synthesised answer leaned on a mechanism term retrieval never
- # showed, so the real mechanism likely lives in code the wiki / decision
- # corpus never captured. Mine the candidate source for it — the same
- # lever the gated/hedged paths use — so the downgrade ships a lead, not
- # just a warning.
+ # The real mechanism likely lives in uncaptured code; mine source
+ # comments so the downgrade ships a lead, not just a warning.
code_rationale = await _gather_code_rationale(ctx, hits, fallback_targets, question)
code_rationale = _drop_already_surfaced(code_rationale, symbol_bodies, quotes)
if code_rationale:
@@ -758,9 +646,7 @@ async def _graded_payload(
f"{grade.frame_unsupported} are not in the retrieved material."
)
elif grade.exclusivity_over_truncated:
- # Note names the axis of doubt (what to be uncertain about), not the
- # check that triggered it — so a reader can tell which kind of doubt
- # this is without consulting the source code.
+ # Names the axis of doubt, not the check that triggered it.
payload["note"] = (
"Answer may not cover every relevant site: a cited symbol's body "
"was truncated and the answer makes an unqualified causal claim. "
@@ -783,9 +669,7 @@ async def _graded_payload(
exclude_spec=exclude_spec,
)
elif grade.lookup_body_truncated:
- # The ninth gate fired: the caller asked for a symbol by name and its
- # body did not fit. Without this the demotion would ship with no note at
- # all, since the high-confidence branch below is unreachable for it.
+ # The lookup gate fired; without this the demotion would ship no note.
cut = grade.named_body_cut
payload["note"] = (
f"You asked for {cut['name']} and its body did not fit: "
@@ -798,34 +682,21 @@ async def _graded_payload(
f"call get_symbol id='{cut['continuation']}' for the rest of {cut['name']}"
)
elif confidence == "high":
- # The rationale deliberately no longer cites "the answer is direct (no
- # hedging)". _SYSTEM_PROMPT instructs the model not to hedge, so scoring
- # the absence of hedging as evidence FOR confidence is circular: the
- # pipeline mandates directness and then reads its own mandate back as a
- # signal. Dominance is an independent measurement; directness is not.
+ # "No hedging" is not cited as evidence: the prompt forbids hedging, so
+ # reading its absence back as a signal would be circular.
_tail = (
"Cite this answer; do not re-read the source unless a specific "
"detail is missing."
if not any(b.get("truncated") for b in symbol_bodies)
- # Never tell the consumer to skip re-reading when the payload itself
- # admits it withheld part of a cited body. The withheld names are in
- # `symbol_bodies[].withheld_symbols`.
+ # Never say "skip re-reading" when the payload admits it withheld
+ # part of a cited body.
else "Some cited bodies were truncated; see "
"symbol_bodies[].withheld_symbols for what was not served."
)
- # Say which test earned the grade, and quote only the measurement that
- # test actually made. Writing one sentence for every high is how a
- # response came to quote "clearly dominates (dominance ratio 1.00x)" — a
- # tie — as its own justification, beside the caveat that no page
- # dominated. The gap and agreement tiers fire at ratios near 1.0 too, so
- # naming them without their own numbers would reproduce it exactly.
payload["note"] = _high_confidence_note(grade, _tail)
- # Concept anchoring put a comment-justified file at the top, so synthesis may
- # now run high — but the agent asked a "why is X = <number>" question and the
- # literal rationale is the comment we already mined. Surface it so the win is
- # the answer AND the cited comment in one call (no re-read), unless a gate
- # above already attached code_rationale.
+ # A concept-anchored hit's comment is the literal rationale for a "why is
+ # X = <number>" question; surface it unless a gate already did.
if "code_rationale" not in payload and any(h.get("_concept_anchored") for h in hits):
concept_rationale = await _gather_code_rationale(ctx, hits, fallback_targets, question)
concept_rationale = _drop_already_surfaced(concept_rationale, symbol_bodies, quotes)
@@ -845,23 +716,16 @@ async def _attach_withheld_note(
) -> None:
"""Write the note and next action for a withheld symbol the answer depends on.
- A withheld entry whose name matches the body it was found in is the ENCLOSING
- symbol — served up to the cut and continuing past it — not a symbol that
- never arrived. Calling that "not served" is wrong about the payload directly
- above the note, and sends the caller to get_symbol for a body they already
- hold most of. The accurate pointer is the ``continuation`` the entry already
- carries, which fetches just the missing part and is a valid get_symbol id in
- its own right ("path.py:174-221").
+ An enclosing-symbol continuation (see :func:`_is_enclosing_continuation`)
+ is pointed at by its ``continuation``, itself a valid get_symbol id
+ ("path.py:174-221"), rather than reported as not served.
"""
_implicated = set(withheld_implicated)
_continuing = [b for b in symbol_bodies if _is_enclosing_continuation(b, _implicated)]
_continuing_names = {b["name"] for b in _continuing}
_absent = [n for n in withheld_implicated if n not in _continuing_names]
- # Only advertise an id get_symbol can actually answer. The scanner that
- # produced these is a regex over source lines, so it can name something that
- # is not a symbol, and the id does not stay in a list of eight — it becomes
- # the next action the payload tells the agent to take. When none resolves the
- # names are still reported; only the dead pointer is withheld.
+ # Only advertise an id get_symbol can answer: the regex scanner can name a
+ # non-symbol, and this id becomes the next action. Names are still reported.
_hint_id = await _first_resolvable_id(
[
s["symbol_id"]
@@ -885,9 +749,7 @@ async def _attach_withheld_note(
else ""
)
)
- # Qualify by path only when the same name was cut in more than one file, so
- # the common case stays readable and the ambiguous case does not ship two
- # sentences that look identical.
+ # Qualify by path only when the same name was cut in more than one file.
_dupe = len({_b["name"] for _b in _continuing}) < len(_continuing)
for _b in _continuing:
_who = f"{_b['name']} ({_b['path']})" if _dupe else _b["name"]
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py b/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py
index 456c01375..a97e8a526 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py
@@ -273,12 +273,8 @@ def _keep(payload: dict[str, Any], key: str, limit: int | None) -> None:
def _default_shape(payload: dict[str, Any], question: str) -> None:
- # A degraded payload keeps the fullest evidence shape whatever it graded.
- # The trimming above is keyed on prose REPLACING evidence: a high-confidence
- # answer makes the ranked list redundant, so it goes. There is no answer on
- # this path - the evidence IS the product - and its ``confidence`` now rates
- # that evidence rather than prose, so reading the two on one scale would cut
- # a body and a hit from exactly the caller who has nothing else to read.
+ # A degraded payload keeps the fullest shape whatever it graded: trimming is
+ # keyed on prose replacing evidence, and there the evidence IS the product.
confidence = "low" if payload.get("degraded") else payload.get("confidence", "low")
why = question.lstrip().lower().startswith("why")
if confidence == "high":
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py b/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py
index 5fd921b39..1ead81f11 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py
@@ -36,63 +36,29 @@ from repowise.server.mcp_server.tool_answer.config import (
_log = logging.getLogger("repowise.mcp.answer")
-# How many files ``candidates`` names.
-#
-# Was 20, on the estimate that "twenty path lines cost roughly 800 characters
-# against the ~10k a get_answer response already spends". Measured on the wire
-# 2026-08-11 the block is **3,107-3,279 characters, up to 39.9% of a
-# get_answer payload** — four times the estimate, because ``defines`` and the
-# paths themselves are both longer than a bare path line. That estimate was
-# also made before ``defines`` existed.
-#
-# Five, not zero. Rows 6-20 appear in no other block, but nor are rows 1-5
-# redundant: on the repowise samples ``candidates`` is the only block naming
-# files outside the top-two ``citations``, and dropping it whole (which the
-# CLI projection does) pushes the agent into a Grep that costs more than the
-# rows saved. The head keeps the ``defines`` budget, so the navigational value
-# per character goes up.
+# How many files ``candidates`` names. Rows with ``defines`` are long, so a large
+# cap made this block a big share of the payload. Five, not zero: it is often the
+# only block naming files beyond the top ``citations``, and without it the agent
+# runs a Grep that costs more than the rows.
_CANDIDATE_LIMIT = 5
def serialize_candidates(hits: list[dict], *, limit: int = _CANDIDATE_LIMIT) -> list[dict]:
"""The files retrieval ranked, one line each, ordered best first.
- Separate from ``retrieval`` on purpose, and deliberately not
- confidence-gated. ``retrieval`` is *evidence*: enriched hits an agent reads
- to check the prose, so it is right for it to shrink as the prose gets more
- trustworthy. This block is *navigation*: the shortlist of files worth
- opening next. Under the old shape a confident answer named zero files and a
- medium one named two, which is backwards. The more sure we are of a
- subsystem, the better placed we are to say which files it lives in.
-
- One entry per distinct path, ``{path, lines?}``. Line bounds are attached
- only where a hit already carries hydrated symbols; nothing is fetched to
- build this.
-
- ``path`` is always a **file** path, resolved through ``hit_file_path``. A
- ``symbol_spotlight`` hit's ``target_path`` is ``file.py::Symbol``, which is
- a page identifier, not something a consumer can open; two distinct symbols
- in one file are also one file to read, so they collapse to one entry here.
-
- Pages naming no file at all are skipped rather than emitted (finding A15).
- A module page's target_path is a structural group key that reads like a
- directory and an onboarding page's is a slot name, so every "does this look
- like a path" heuristic says yes and the agent that opens it gets an error.
- Scoring impact is about zero, measured; it is wrong on the same argument
- A14 was, which is that this field has one meaning and it is not "page id".
-
- ``defines`` carries what the file declares, as ``name:line`` pairs, when
- ``_hydrate_candidate_defines`` resolved any. That is the difference between
- a path the agent has to Grep and a line it can read: 434 of the 499 paths a
- get_answer response served on the 25 flow questions carried no content
- whatsoever, and the Layer B taxonomy judged 89% of the agent's post-answer
- searches to be exactly that expansion. **Line numbers here are as indexed
- and are not verified against the live file** (unlike ``get_symbol``); they
- are navigation, not a citation.
-
- **Which paths are emitted, and in what order, is not affected by any of
- this.** ``defines`` is attached to entries the existing loop already built,
- so an added or exhausted budget can never add, drop or reorder a path.
+ Deliberately not confidence-gated: ``retrieval`` is *evidence* and shrinks
+ as the prose gets trustworthy, while this block is *navigation*, the files
+ worth opening next, and a confident answer is best placed to name them.
+
+ One entry per distinct **file** path (via ``hit_file_path``), ``{path,
+ lines?}``; line bounds come only from already-hydrated symbols. Pages that
+ name no file (module group keys, onboarding slots) are skipped, since they
+ look like paths but cannot be opened.
+
+ ``defines`` lists what the file declares as ``name:line`` pairs, turning a
+ path to Grep into a line to read. **Line numbers are as indexed, not
+ verified** against the live file: navigation, not a citation. The
+ ``defines`` budget never adds, drops or reorders a path.
"""
out: list[dict] = []
seen: set[str] = set()
@@ -131,37 +97,24 @@ def serialize_hits(
) -> list[dict]:
"""Agent-facing view of retrieval hits — content only, no plumbing.
- Internal scoring fields (``_coverage``, ``_coverage_multiplier``,
- ``_confidence_score_factor``, ``_raw_score``, ``_sources``,
- ``_pagerank``, …) and ``page_id`` are ranking debug an agent can do
- nothing with; they were ~70% of a get_answer response by volume. Zero
- information loss for the consumer: path, title, summary, snippet,
- excerpt, score, and hydrated symbols all survive.
-
- ``summary_chars`` truncates summaries (medium-confidence diet);
- ``symbols_for_expanded=False`` drops symbol enrichment from hits that
- only entered via 1-hop graph expansion (they are routing material, not
- answer material). ``lean_symbols=True`` keeps each symbol pipeable
- (name/kind/signature/lines) but drops docstrings and excerpts — for the
- gated low-confidence path, where the hits are candidates to pick between,
- not answer material, and ``best_guesses`` + ``code_rationale`` already
- carry the choosing signal.
-
- ``excerpt_rows`` serves the page excerpt on the first N rows only. An
- excerpt is ~1,500 characters against ~300 for the whole rest of a row, so it
- is essentially the entire cost of this block; rows past the cut keep path,
- title, summary, snippet and score, which is a described candidate rather
- than a bare pointer. Deliberately a *field* cut and not a row cut: dropping
- rows takes paths out of the response, and a named path costs almost nothing.
+ Internal scoring fields (``_coverage``, ``_raw_score``, ...) and
+ ``page_id`` are ranking debug an agent cannot use, so they are dropped.
+
+ ``summary_chars`` truncates summaries; ``symbols_for_expanded=False`` drops
+ symbols from hits that only entered via graph expansion (routing material);
+ ``lean_symbols=True`` keeps symbols pipeable but drops docstrings and
+ excerpts, for the low-confidence path where hits are candidates to pick.
+
+ ``excerpt_rows`` serves the page excerpt on the first N rows only: the
+ excerpt is most of a row's cost. A *field* cut, not a row cut, because
+ dropping rows takes paths out and a named path costs almost nothing.
"""
out: list[dict] = []
for idx, h in enumerate(hits[: limit if limit is not None else len(hits)]):
target = h.get("target_path")
entry: dict[str, Any] = {"path": target}
- # A symbol_spotlight page's target_path is ``file.py::Symbol``: a page
- # id, not a path a consumer can open. Keep it (callers pipe it into
- # get_symbol) and name the file too, so ``path`` never has to be
- # guessed at by anything downstream.
+ # ``file.py::Symbol`` is a page id callers pipe into get_symbol; name
+ # the openable file beside it.
if target and "::" in target:
entry["file"] = target.split("::", 1)[0]
if h.get("title"):
@@ -254,15 +207,11 @@ async def _intersection_boost(question: str, hits: list[dict], ctx: Any = None)
async def _attach_page_excerpts(hits: list[dict], ctx: Any = None) -> int:
"""Attach each top hit's real page content as ``excerpt``. Mutates `hits`.
- Every consumer of a hit — the synthesis prompt and the pointer payload
- alike — otherwise sees only the page's one-line LLM summary or a 200-char
- opener, next to a symbol block carrying docstrings and source bodies. A
- consumer given names but no prose reconstructs rationale from the names,
- which is a confident wrong answer rather than a thin one.
+ Without it a consumer sees only a one-line summary beside symbol names, and
+ reconstructs rationale from the names: a confident wrong answer.
- Returns the number of top hits left without page content. That count is
- the point: a hit reaching synthesis with no body used to be invisible,
- which is how this went unnoticed for as long as it did.
+ Returns the number of top hits left without page content, so a hit
+ reaching synthesis with no body is visible rather than silent.
"""
if not hits:
return 0
@@ -280,9 +229,7 @@ async def _attach_page_excerpts(hits: list[dict], ctx: Any = None) -> int:
res = await session.execute(select(Page.id, Page.content).where(Page.id.in_(page_ids)))
content_by_id = {row[0]: (row[1] or "") for row in res.all()}
except Exception:
- # Never fail the answer over an excerpt fetch — but never lose the
- # fact either. Without this line the whole prompt silently degrades
- # to summaries and the answer still looks confident.
+ # Never fail the answer over an excerpt fetch, but never hide it either.
_log.warning(
"get_answer: page-content fetch failed for %d hits; synthesis "
"will read one-line summaries instead of page prose",
@@ -303,12 +250,9 @@ async def _attach_page_excerpts(hits: list[dict], ctx: Any = None) -> int:
def _detect_question_domain(question: str) -> str | None:
"""Return ``"ui"``, ``"backend"``, or ``None`` when the question is ambiguous.
- Used to break ties on retrievals where vocabulary overlaps across domains
- (e.g. "how does indexing work" could plausibly retrieve a UI status-pill
- component or the actual ingestion pipeline). The classifier is intentionally
- conservative: if both domain token sets fire, or neither does, we return
- ``None`` and apply no penalty — better to leave ranking alone than to
- miscategorise a cross-cutting question.
+ Breaks ties where vocabulary overlaps across domains. Conservative: if both
+ token sets fire, or neither, no penalty applies rather than miscategorise a
+ cross-cutting question.
"""
qlow = question.lower()
has_ui = any(tok in qlow for tok in _UI_QUESTION_TOKENS)
@@ -346,11 +290,8 @@ def _apply_domain_penalty(hits: list[dict], question: str) -> None:
def _candidate_justification(h: dict) -> str:
"""One-line reason this hit might answer the question.
- Used on the low-confidence return path so the agent sees something
- decision-shaped ("Read file X because it implements Y") instead of a
- flat list of paths it has to scan into. Prefers the matched-symbol name
- over the file summary because the matched symbol is what tied this hit
- to the question in the first place.
+ Decision-shaped ("implements Y") rather than a bare path. Prefers the
+ matched symbol, which is what tied this hit to the question.
"""
syms = h.get("symbols") or []
matched = next((s for s in syms if s.get("_matched")), None)
@@ -360,8 +301,7 @@ def _candidate_justification(h: dict) -> str:
return f"Implements {kind} {name}."
summary = (h.get("summary") or h.get("snippet") or "").strip()
if summary:
- # First sentence only; trailing prose is mostly cache-write cost on
- # the consumer side.
+ # First sentence only; the rest is mostly cache-write cost.
first = summary.split(". ")[0]
return (first[:160].rstrip() + ".") if first else ""
title = h.get("title") or ""
@@ -376,12 +316,8 @@ def _rerank_by_coverage(hits: list[dict], question: str) -> list[dict]:
so a generic lexical overlap such as ``coverage`` cannot beat a page that
also agrees on ``PR``, ``test impact``, and ``changed files``. Raw fused
retrieval remains the base signal; this is a bounded multiplier, not a
- replacement score.
-
- This addresses a common BM25 failure mode where a hit that matches one
- constraint very strongly can outrank a hit that matches all constraints
- moderately — the latter is usually the better answer for multi-constraint
- questions.
+ replacement score. Counters BM25 ranking one strongly-matched constraint
+ above a hit that matches every constraint moderately.
"""
return rerank_by_context_coverage(
hits,