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.

feat(mcp): ground get_answer synthesis in the body it serves; slim low-confidence misses (#778)

Raghav Chamadiya2dc41d08bc4e
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 e4f8667a4..b82f672d5 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
@@ -104,7 +104,6 @@ from repowise.server.mcp_server.tool_answer.config import (
from repowise.server.mcp_server.tool_answer.retrieval import (
_apply_domain_penalty,
_candidate_justification,
- _enrich_gated_excerpts,
_intersection_boost,
_rerank_by_coverage,
)
@@ -246,6 +245,50 @@ def _drop_already_surfaced(rationale: list[dict], *surfaced: list[dict]) -> list
return kept
+def _gather_body_candidates(
+ hits: list[dict], answer_text: str
+) -> list[tuple[int, int, int, str, dict]]:
+ """Rank the definitions to inline in ``symbol_bodies``, most-relevant first.
+
+ Returns ``(tier, kind_rank, start_line, path, symbol)`` tuples, pre-sorted so
+ the leading entries are the bodies the agent is most likely to want:
+
+ * Tier 0 — the exact symbol the question named, resolved by symbol
+ anchoring (survives the fuzzy hydration cap a parent class name floods).
+ * Tier 1 — a question-matched hydrated symbol the answer names.
+
+ Within a tier a function/method outranks a class container (so "explain the
+ extract_all method of DecisionExtractor" serves extract_all, not the
+ 1,300-line class head), then document order. Only definitions the answer
+ text actually names qualify; constants stay in ``quotes``.
+ """
+ candidates: list[tuple[int, int, int, str, dict]] = []
+ for h in hits[:_ENRICH_TOP_N_HITS]:
+ path = h.get("target_path")
+ if not path:
+ continue
+ for s in h.get("_anchor_symbols") or []:
+ name = s.get("name")
+ if not name or name not in answer_text:
+ continue
+ kind = s.get("kind")
+ kind_rank = 0 if kind in ("function", "method") else 1
+ candidates.append((0, kind_rank, s.get("start_line") or 0, path, s))
+ for s in h.get("symbols") or []:
+ name = s.get("name")
+ if not name or len(name) < 3 or not s.get("_matched"):
+ continue
+ if name not in answer_text:
+ continue
+ kind = s.get("kind")
+ if kind not in ("function", "method", "class", "interface"):
+ continue
+ kind_rank = 0 if kind in ("function", "method") else 1
+ candidates.append((1, kind_rank, s.get("start_line") or 0, path, s))
+ candidates.sort(key=lambda t: (t[0], t[1], t[2]))
+ return candidates
+
+
@mcp.tool()
async def get_answer(
question: str,
@@ -587,9 +630,6 @@ async def get_answer(
dominant = (top_score / second_score) >= _DOMINANCE_RATIO
if not dominant:
- # Enrich top hits with substantive excerpts so the agent has
- # real material to ground in (not one-line summaries).
- await _enrich_gated_excerpts(hits, ctx)
# Structured candidate set: a decision-shaped list with a
# one-line justification per file. Beats the prior flat
# ``fallback_targets`` list because the agent can pick ONE file
@@ -607,6 +647,13 @@ async def get_answer(
# Mine source comments for rationale the wiki/decision corpus
# missed — turns "go Read these 5 files" into a cited why.
code_rationale = _gather_code_rationale(ctx, hits, fallback_targets, question)
+ # A miss should be cheap to READ, not just cheap to ignore. The old
+ # gated payload also carried a full per-hit key_symbols dump — the
+ # single largest block by volume — that duplicated best_guesses and
+ # went unused (2026-07-11 dogfood). best_guesses (file + one-line
+ # why + score) and code_rationale carry the choosing signal; the
+ # symbol dump does not. Drop it, and skip the excerpt-enrichment DB
+ # round-trip that only fed it (a small latency win on the miss path).
gated: dict = {
"answer": "",
"citations": [],
@@ -624,7 +671,7 @@ async def get_answer(
)
),
"fallback_targets": fallback_targets,
- "retrieval": _serialize_hits(hits, limit=_GATED_RETURN_HITS, lean_symbols=True),
+ "retrieval": [],
"note": (
"Multiple plausible candidates — synthesis skipped to "
"avoid anchoring on a wrong frame. Each best_guess entry "
@@ -810,37 +857,7 @@ async def get_answer(
# from get_symbol's `verified` contract. When the indexed body is longer
# than the hydrator's line cap, a `continuation` names the exact range
# read for the remainder (mirrors get_symbol).
- # Gather eligible definitions across the top hits, ranked so the most
- # relevant body leads. Tier 0 = the exact symbol the question named, as
- # resolved by symbol anchoring (survives the fuzzy hydration cap that a
- # parent class name otherwise floods). Tier 1 = question-matched hydrated
- # symbols. Within a tier, a function/method outranks a class container, so
- # "explain the extract_all method of DecisionExtractor" serves extract_all,
- # not the 1,300-line class head. Then document order.
- _body_candidates: list[tuple[int, int, int, str, dict]] = []
- for h in hits[:_ENRICH_TOP_N_HITS]:
- path = h.get("target_path")
- if not path:
- continue
- for s in h.get("_anchor_symbols") or []:
- name = s.get("name")
- if not name or name not in answer_text:
- continue
- kind = s.get("kind")
- kind_rank = 0 if kind in ("function", "method") else 1
- _body_candidates.append((0, kind_rank, s.get("start_line") or 0, path, s))
- for s in h.get("symbols") or []:
- name = s.get("name")
- if not name or len(name) < 3 or not s.get("_matched"):
- continue
- if name not in answer_text:
- continue
- kind = s.get("kind")
- if kind not in ("function", "method", "class", "interface"):
- continue
- kind_rank = 0 if kind in ("function", "method") else 1
- _body_candidates.append((1, kind_rank, s.get("start_line") or 0, path, s))
- _body_candidates.sort(key=lambda t: (t[0], t[1], t[2]))
+ _body_candidates = _gather_body_candidates(hits, answer_text)
symbol_bodies: list[dict] = []
_seen_bodies: set[tuple[str, str]] = set()
@@ -1016,8 +1033,11 @@ async def get_answer(
# 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 the full
- # block — that's when routing material earns its bytes.
+ # enrichment for graph-expansion neighbors. Low keeps a grounding
+ # block, but lean: the top hits with snippets, symbols pipeable but
+ # stripped of docstrings/excerpts — the full per-hit key_symbols dump
+ # was the largest block by volume and went mostly unused on a
+ # low-confidence answer (2026-07-11 dogfood).
if confidence == "high":
retrieval_view: list[dict] = []
elif confidence == "medium":
@@ -1025,7 +1045,9 @@ async def get_answer(
hits, limit=2, summary_chars=160, symbols_for_expanded=False
)
else:
- retrieval_view = _serialize_hits(hits)
+ retrieval_view = _serialize_hits(
+ hits, limit=_GATED_RETURN_HITS, lean_symbols=True
+ )
payload = {
"answer": answer_text,
"citations": citations,
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 3ac9e297f..81085a4aa 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
@@ -42,6 +42,19 @@ _INLINE_BODY_MAX_SYMBOLS = 2
# body of ~99% of symbols in one shot; the rest carry a continuation token.
_INLINE_BODY_MAX_LINES = 120
+# 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.
+_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
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
index 205ad7897..4021d9a61 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
@@ -23,6 +23,8 @@ from repowise.server.mcp_server.tool_answer.config import (
_MAX_SYMBOLS_PER_HIT,
_MAX_SYMBOLS_TOP_HIT,
_STOPWORDS,
+ _SYNTH_FULL_BODY_MAX_SYMBOLS,
+ _SYNTH_FULL_SOURCE_LINES,
)
@@ -602,6 +604,30 @@ async def _hydrate_symbols_for_hits(
if len(kept) >= cap:
break
kept.append(s)
+ # Upgrade the top question-relevant symbols to the inline-body depth
+ # BEFORE the reading-order sort, while `kept` is still in priority order
+ # (anchors, then matched, then unmatched). The default 40-line excerpt
+ # truncates a docstring-heavy definition before its answer-bearing logic,
+ # so synthesis hedges on the exact symbol whose full 120-line body the
+ # response inlines in symbol_bodies. Reading the leading few at the same
+ # depth keeps the LLM's view and the served body consistent. Bounded so a
+ # class-name flood can't balloon the prompt; the rest keep the excerpt.
+ upgraded = 0
+ for s in kept:
+ if upgraded >= _SYNTH_FULL_BODY_MAX_SYMBOLS:
+ break
+ if not s.get("_matched") or not s.get("source_excerpt"):
+ continue
+ fuller = _read_symbol_source(
+ repo_root,
+ path,
+ s["start_line"],
+ s.get("end_line") or 0,
+ max_lines=_SYNTH_FULL_SOURCE_LINES,
+ )
+ if fuller:
+ s["source_excerpt"] = fuller
+ upgraded += 1
# Sort final slice by start_line for natural reading order.
kept.sort(key=lambda s: s["start_line"])
h["symbols"] = kept
diff --git a/tests/unit/server/mcp/test_answer_payload.py b/tests/unit/server/mcp/test_answer_payload.py
index acac0dd62..35672299e 100644
--- a/tests/unit/server/mcp/test_answer_payload.py
+++ b/tests/unit/server/mcp/test_answer_payload.py
@@ -13,7 +13,10 @@ from types import SimpleNamespace
import pytest
-from repowise.server.mcp_server.tool_answer.answer import _is_readable_path
+from repowise.server.mcp_server.tool_answer.answer import (
+ _gather_body_candidates,
+ _is_readable_path,
+)
from repowise.server.mcp_server.tool_answer.retrieval import serialize_hits
# ---------------------------------------------------------------------------
@@ -65,6 +68,65 @@ RAW_HIT = {
}
+class TestGatherBodyCandidates:
+ """Ranking of the definitions get_answer inlines in ``symbol_bodies``:
+ anchor (question-named) first, then question-matched symbols the answer
+ names; a function/method outranks its class container within a tier."""
+
+ def _sym(self, name, kind="function", matched=False, start=1):
+ return {"name": name, "kind": kind, "_matched": matched, "start_line": start}
+
+ def test_anchor_outranks_matched(self) -> None:
+ hit = {
+ "target_path": "pkg/router.py",
+ "_anchor_symbols": [self._sym("dispatch", start=50)],
+ "symbols": [
+ self._sym("Router", kind="class", matched=True, start=1),
+ self._sym("dispatch", matched=True, start=50),
+ ],
+ }
+ answer = "Router.dispatch drives routing via dispatch."
+ cands = _gather_body_candidates([hit], answer)
+ # Anchor (tier 0) leads over the matched class container (tier 1).
+ assert cands[0][0] == 0 and cands[0][4]["name"] == "dispatch"
+
+ def test_matched_symbol_named_in_answer_included(self) -> None:
+ hit = {
+ "target_path": "pkg/router.py",
+ "symbols": [self._sym("find_route", matched=True, start=20)],
+ }
+ cands = _gather_body_candidates([hit], "The dispatcher calls find_route.")
+ assert [c[4]["name"] for c in cands] == ["find_route"]
+ assert cands[0][0] == 1
+
+ def test_non_matched_symbol_excluded(self) -> None:
+ # A symbol the answer names but the question never matched is NOT
+ # inlined (the answer-cited-mechanism lever regressed the agent A/B and
+ # was reverted): only question-named/matched definitions qualify.
+ hit = {
+ "target_path": "pkg/router.py",
+ "symbols": [self._sym("dispatch_request", matched=False, start=10)],
+ }
+ cands = _gather_body_candidates([hit], "Routing is driven by dispatch_request.")
+ assert cands == []
+
+ def test_symbol_absent_from_answer_excluded(self) -> None:
+ hit = {
+ "target_path": "pkg/router.py",
+ "symbols": [self._sym("unrelated_helper", matched=True, start=10)],
+ }
+ cands = _gather_body_candidates([hit], "The answer never names it.")
+ assert cands == []
+
+ def test_non_definition_kind_excluded(self) -> None:
+ hit = {
+ "target_path": "pkg/mod.py",
+ "symbols": [self._sym("MAX_SIZE", kind="constant", matched=True, start=3)],
+ }
+ cands = _gather_body_candidates([hit], "The cap MAX_SIZE bounds it.")
+ assert cands == []
+
+
class TestSerializeHits:
def test_internal_fields_stripped(self) -> None:
[entry] = serialize_hits([dict(RAW_HIT)])
diff --git a/tests/unit/server/mcp/test_answer_synthesis_body_depth.py b/tests/unit/server/mcp/test_answer_synthesis_body_depth.py
new file mode 100644
index 000000000..47146579e
--- /dev/null
+++ b/tests/unit/server/mcp/test_answer_synthesis_body_depth.py
@@ -0,0 +1,163 @@
+"""Calibration: synthesis must see the same body depth the response inlines.
+
+Dogfood 2026-07-11 item 4: get_answer returned confidence=low with "not
+determinable from the provided excerpts" while its own attached ``symbol_bodies``
+contained the answer. Root cause: the hydrator fed synthesis a 40-line
+``source_excerpt`` (``_MATCHED_SYMBOL_SOURCE_LINES``) but the response inlined a
+120-line body (``_INLINE_BODY_MAX_LINES``) — so a docstring-heavy definition was
+cut off before its answer-bearing logic ever reached the LLM, even though that
+logic was served to the agent.
+
+This locks the fix at the hydration layer (deterministic, no LLM): the top
+question-matched symbol's ``source_excerpt`` must reach the inline-body depth so
+the LLM reasons over what the agent gets.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from repowise.core.persistence.models import WikiSymbol
+from repowise.server.mcp_server.tool_answer.config import (
+ _MATCHED_SYMBOL_SOURCE_LINES,
+ _SYNTH_FULL_BODY_MAX_SYMBOLS,
+)
+from repowise.server.mcp_server.tool_answer.symbols import _hydrate_symbols_for_hits
+
+# A definition longer than the old 40-line synthesis cap, with a docstring
+# heavy enough to fill it and the answer-bearing return dict past line 40. The
+# unique marker sits at ~line 60 so its presence in source_excerpt proves the
+# fuller read happened.
+_MARKER = "RANGE_READ_RESPONSE_KEYS"
+_DOCSTRING_FILLER = "\n".join(f" docstring line {i} explaining behaviour." for i in range(45))
+_SOURCE = f'''\
+def _resolve_range_read(spec):
+ """Serve a live, bounded line-range read.
+
+{_DOCSTRING_FILLER}
+ """
+ start, end = spec
+ source = _slice(start, end)
+ return {{
+ # {_MARKER}: the keys a live range read returns
+ "source": source,
+ "start_line": start,
+ "end_line": end,
+ "verified": True,
+ }}
+'''
+
+
+def repo_with_body(tmp_path):
+ """A real file on disk plus the matching WikiSymbol row + hit + ctx."""
+ src_file = tmp_path / "tool_symbol.py"
+ src_file.write_text(_SOURCE, encoding="utf-8")
+ total_lines = _SOURCE.count("\n") + 1
+ assert total_lines > _MATCHED_SYMBOL_SOURCE_LINES, "fixture must exceed the old cap"
+ return SimpleNamespace(path=tmp_path, total_lines=total_lines)
+
+
+async def test_matched_symbol_source_reaches_inline_body_depth(
+ session, repo_id, repo_with_body
+) -> None:
+ row = WikiSymbol(
+ id="rr1",
+ repository_id=repo_id,
+ file_path="tool_symbol.py",
+ symbol_id="tool_symbol.py::_resolve_range_read",
+ name="_resolve_range_read",
+ qualified_name="tool_symbol._resolve_range_read",
+ kind="function",
+ signature="def _resolve_range_read(spec)",
+ start_line=1,
+ end_line=repo_with_body.total_lines,
+ docstring="Serve a live, bounded line-range read.",
+ visibility="private",
+ is_async=False,
+ complexity_estimate=3,
+ language="python",
+ parent_name=None,
+ )
+ session.add(row)
+ await session.commit()
+
+ hits = [{"target_path": "tool_symbol.py", "page_type": "file_page"}]
+ ctx = SimpleNamespace(path=repo_with_body.path)
+
+ await _hydrate_symbols_for_hits(
+ session, repo_id, hits, ctx, question_ids={"_resolve_range_read"}
+ )
+
+ syms = hits[0]["symbols"]
+ matched = next(s for s in syms if s["name"] == "_resolve_range_read")
+ assert matched["_matched"] is True
+ excerpt = matched["source_excerpt"]
+ # The answer-bearing return dict is past line 40; the old 40-line cap
+ # dropped it and synthesis hedged. The fuller read must now carry it.
+ assert _MARKER in excerpt
+ assert '"verified": True' in excerpt
+ assert excerpt.count("\n") + 1 >= 50
+
+
+async def test_class_flood_does_not_upgrade_every_sibling(
+ session, repo_id, tmp_path
+) -> None:
+ """A class-name flood must not read a fuller body for every sibling method.
+
+ When the question names a class, each method 'matches' through the parent's
+ qualified name. Upgrading all of them to the inline-body depth would balloon
+ the synthesis prompt; only the leading few earn the fuller read.
+ """
+ method_body = "\n".join(f" x{i} = {i}" for i in range(60))
+ lines: list[str] = ["class Coupling:"]
+ starts: list[int] = []
+ for j in range(5):
+ starts.append(len(lines) + 1) # 1-indexed line of the def
+ lines.append(f" def m{j}(self):")
+ lines.extend(method_body.splitlines())
+ lines.append(" return x0")
+ src = "\n".join(lines) + "\n"
+ (tmp_path / "coupling.py").write_text(src, encoding="utf-8")
+
+ rows = [
+ WikiSymbol(
+ id=f"coupling-m{j}",
+ repository_id=repo_id,
+ file_path="coupling.py",
+ symbol_id=f"coupling.py::Coupling.m{j}",
+ name=f"m{j}",
+ qualified_name=f"coupling.Coupling.m{j}",
+ kind="method",
+ signature=f"def m{j}(self)",
+ start_line=starts[j],
+ end_line=starts[j] + 61,
+ docstring="",
+ visibility="public",
+ is_async=False,
+ complexity_estimate=1,
+ language="python",
+ parent_name="Coupling",
+ )
+ for j in range(5)
+ ]
+ for r in rows:
+ session.add(r)
+ await session.commit()
+
+ hits = [{"target_path": "coupling.py", "page_type": "file_page"}]
+ ctx = SimpleNamespace(path=tmp_path)
+ # "coupling" (len>=5) substring-matches every method's qualified_name → the
+ # class-name flood: all 5 methods count as matched.
+ await _hydrate_symbols_for_hits(session, repo_id, hits, ctx, question_ids={"Coupling"})
+
+ syms = [s for s in hits[0]["symbols"] if s.get("source_excerpt")]
+ assert len(syms) == 5, "the flood should match every sibling method"
+ # Non-upgraded matched symbols keep the ~40-line excerpt (41 after the cap's
+ # inclusive slice); only the leading few get the deeper read.
+ fuller = [
+ s for s in syms if s["source_excerpt"].count("\n") + 1 > _MATCHED_SYMBOL_SOURCE_LINES + 1
+ ]
+ assert len(fuller) <= _SYNTH_FULL_BODY_MAX_SYMBOLS