fix(answer): spend the per-file symbol budget on the question, not the top of the file (#1597)

When a retrieved file held more symbols than its budget, hydration sorted them
by start_line and kept a prefix. The bigger the file, the smaller the fraction
served and the stronger the top-of-file bias, so on a large file the symbol the
question was about could not be reached at all and synthesis answered that the
excerpts did not contain the relevant code.

Score each symbol's already-loaded name, signature and docstring against the
question's content terms, and let that decide which symbols fill the same
budget. The count is unchanged, no new I/O is added, and with no signal every
score is zero and the sort falls back to start_line as before.

Two supporting changes it needs to work:

- The question-match test substring-compared the whole qualified name, so every
  symbol in a package whose path shared a word with the question counted as
  matched and the promotion collapsed to a no-op. Match the symbol's own name,
  its full qualified name, or its parent, which keeps a question about a class
  reaching its methods.

- That flood was also the only thing attaching source bodies. A question phrased
  in prose names no identifier, so nothing matched and the served symbols would
  carry signatures only. The leading few symbols the question scored against now
  get a body, bounded per file.

Selection order only: the kept slice is still sorted by start_line before it is
attached, so consumers continue to read it in document order.

Author: RaghavChamadiya

packages/server/src/repowise/server/mcp_server/tool_answer/answer.py

@@ -342,7 +342,7 @@ async def _run_retrieval_pipeline(
         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
+                    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.

packages/server/src/repowise/server/mcp_server/tool_answer/config.py

@@ -32,6 +32,26 @@
 _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.
+_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.
+_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

packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py

@@ -16,6 +16,7 @@
 
 from repowise.core.persistence.models import WikiSymbol
 from repowise.server.mcp_server._page_paths import hit_file_path
+from repowise.server.mcp_server._query_terms import content_terms, split_humps
 from repowise.server.mcp_server._verify import verify_and_heal
 from repowise.server.mcp_server.tool_answer.config import (
     _DEFINES_MAX_FILES,
@@ -29,12 +30,99 @@
     _MAX_RICH_SIG_LINES,
     _MAX_SYMBOLS_PER_HIT,
     _MAX_SYMBOLS_TOP_HIT,
+    _RELEVANCE_DOC_CHARS,
+    _RELEVANCE_DOC_WEIGHT,
+    _RELEVANCE_NAME_WEIGHT,
+    _RELEVANCE_SIG_WEIGHT,
+    _RELEVANT_EXCERPT_MAX_SYMBOLS,
     _STOPWORDS,
     _SYNTH_FULL_BODY_MAX_SYMBOLS,
     _SYNTH_FULL_SOURCE_LINES,
 )
 from repowise.server.mcp_server.tool_search import _prose_dominates
 
+# Suffixes stripped so a question's word reaches the identifier that answers it
+# ("routing" -> the `route` symbol). Longest first; never stems below 4 chars.
+_STEM_SUFFIXES = ("tion", "ing", "ion", "es", "ed", "er", "s")
+
+
+def _stem(token: str) -> str:
+    for suffix in _STEM_SUFFIXES:
+        if token.endswith(suffix) and len(token) - len(suffix) >= 4:
+            return token[: -len(suffix)]
+    return token
+
+
+def _text_stems(text: str) -> set[str]:
+    """Stemmed content tokens of *text*, hump- and separator-split."""
+    return {
+        _stem(tok.lower())
+        for tok in re.split(r"[^A-Za-z0-9]+", split_humps(text))
+        if len(tok) >= 3 and tok.lower() not in _STOPWORDS
+    }
+
+
+def _stem_hit(term: str, tokens: set[str]) -> bool:
+    """Whether *term* names one of *tokens*, allowing a shared 4-char root."""
+    if term in tokens:
+        return True
+    return any(
+        min(len(term), len(tok)) >= 4 and (term.startswith(tok) or tok.startswith(term))
+        for tok in tokens
+    )
+
+
+def _question_names_symbol(row, qids_lower: set[str]) -> bool:
+    """Whether an identifier from the question names this symbol.
+
+    Substring-matching the whole qualified name marked every symbol in a package
+    whose path shares a word with the question, which flattened the promotion to
+    a no-op. Matching is against the symbol's own name, its full qualified name,
+    or its parent: asking about a class should still reach its methods.
+    """
+    if not qids_lower:
+        return False
+    name_lower = (row.name or "").lower()
+    parent_lower = (row.parent_name or "").lower()
+    return (
+        name_lower in qids_lower
+        or (row.qualified_name or "").lower() in qids_lower
+        or (bool(parent_lower) and parent_lower in qids_lower)
+        or any(
+            q in name_lower
+            for q in qids_lower
+            if len(q) >= 5  # avoid spurious substring matches on short tokens
+        )
+    )
+
+
+def _symbol_relevance(entry: dict, terms: set[str]) -> int:
+    """How strongly a symbol's own text answers the question's content terms.
+
+    Reads only what hydration already loaded, so it adds no I/O to the call.
+    """
+    if not terms:
+        return 0
+    name_tokens = _text_stems(entry.get("name") or "")
+    sig_tokens = _text_stems(entry.get("signature") or "")
+    # Docstrings are the bulk of the text to tokenize and the weakest signal, so
+    # they are only read once a term has missed the name and the signature.
+    doc_tokens: set[str] | None = None
+    score = 0
+    for term in terms:
+        if _stem_hit(term, name_tokens):
+            score += _RELEVANCE_NAME_WEIGHT
+        elif _stem_hit(term, sig_tokens):
+            score += _RELEVANCE_SIG_WEIGHT
+        else:
+            if doc_tokens is None:
+                doc_tokens = _text_stems(
+                    (entry.get("docstring") or "")[:_RELEVANCE_DOC_CHARS]
+                )
+            if _stem_hit(term, doc_tokens):
+                score += _RELEVANCE_DOC_WEIGHT
+    return score
+
 
 def _extract_question_identifiers(question: str) -> set[str]:
     """Pull out Python-looking identifiers the question names explicitly.
@@ -774,6 +862,7 @@ async def _hydrate_symbols_for_hits(
     hits: list[dict],
     ctx: Any = None,
     question_ids: set[str] | None = None,
+    question: str = "",
 ) -> None:
     """Mutate `hits` in place: attach `symbols` list to top-N file_page hits.
 
@@ -788,10 +877,16 @@ async def _hydrate_symbols_for_hits(
     Top hit gets ``_MAX_SYMBOLS_TOP_HIT`` slots; secondaries get the smaller
     ``_MAX_SYMBOLS_PER_HIT``. Symbols not matching a question id carry the
     short 120-char docstring; matched symbols carry 400 chars + source body.
+
+    ``question`` decides which symbols fill those slots when the file holds more
+    than fit, and earns the leading few a source body: a question phrased in
+    prose names no identifier, so nothing matches and nothing would carry code.
     """
     question_ids = question_ids or set()
     # Case-folded copy for matching.
     qids_lower = {q.lower() for q in question_ids}
+    # Once per call: the question's terms, stemmed to match identifier roots.
+    term_stems = {_stem(t) for t in content_terms(question)}
 
     # Identify the top file_page hits in retrieval-rank order. `hits` is
     # already sorted by descending score upstream.
@@ -845,21 +940,7 @@ async def _hydrate_symbols_for_hits(
             rich_sig = _read_signature_from_source(
                 repo_root, row.file_path, start_line, text=text
             )
-        # Does the symbol name match any identifier from the question?
-        name_lower = (row.name or "").lower()
-        qname_lower = (row.qualified_name or "").lower()
-        matched = bool(
-            qids_lower
-            and (
-                name_lower in qids_lower
-                or qname_lower in qids_lower
-                or any(
-                    q in name_lower or q in qname_lower
-                    for q in qids_lower
-                    if len(q) >= 5  # avoid spurious substring matches on short tokens
-                )
-            )
-        )
+        matched = _question_names_symbol(row, qids_lower)
         entry: dict[str, Any] = {
             "name": row.name,
             "kind": row.kind,
@@ -868,7 +949,11 @@ async def _hydrate_symbols_for_hits(
             "start_line": start_line,
             "end_line": end_line,
             "_matched": matched,
+            "_verified": verified,
         }
+        # Scored once here, not in the sort key, so a dense file pays for it per
+        # symbol rather than per comparison.
+        entry["_relevance"] = _symbol_relevance(entry, term_stems)
         if matched and verified:
             src = _read_symbol_source(
                 repo_root, row.file_path, start_line, end_line, text=text
@@ -877,15 +962,16 @@ async def _hydrate_symbols_for_hits(
                 entry["source_excerpt"] = src
         by_file.setdefault(row.file_path, []).append(entry)
 
-    # Sort: matched symbols first (document order within the match group),
-    # then unmatched in start_line order. Cap per file — top hit gets more
-    # slots than secondary hits.
+    # Sort: matched symbols first, then by relevance to the question, then in
+    # start_line order. Cap per file — top hit gets more slots than secondary
+    # hits. This decides WHICH symbols are kept; the kept slice is put back into
+    # reading order below, so consumers still see document order.
     for i, h in enumerate(hits):
         path = h.get("target_path")
         if path not in by_file:
             continue
         syms = by_file[path]
-        syms.sort(key=lambda s: (not s["_matched"], s["start_line"]))
+        syms.sort(key=lambda s: (not s["_matched"], -s["_relevance"], s["start_line"]))
         cap = _MAX_SYMBOLS_TOP_HIT if i == 0 else _MAX_SYMBOLS_PER_HIT
         # Force-include the exact symbol the question named (via anchoring) so a
         # class-name flood — where every sibling method "matches" through the
@@ -903,6 +989,26 @@ async def _hydrate_symbols_for_hits(
             if len(kept) >= cap:
                 break
             kept.append(s)
+        # A prose question names no identifier, so nothing is `_matched` and the
+        # slate would carry signatures only. Give the leading few symbols the
+        # question scored against a body, so the excerpts hold the code the
+        # question is about. `kept` is still in priority order here.
+        bodied = 0
+        for s in kept:
+            if bodied >= _RELEVANT_EXCERPT_MAX_SYMBOLS:
+                break
+            if s.get("source_excerpt") or not s["_relevance"] or not s["_verified"]:
+                continue
+            src = _read_symbol_source(
+                repo_root,
+                path,
+                s["start_line"],
+                s.get("end_line") or 0,
+                text=text_cache.get(path),
+            )
+            if src:
+                s["source_excerpt"] = src
+                bodied += 1
         # 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

tests/unit/server/mcp/test_answer_symbol_relevance.py

@@ -0,0 +1,116 @@
+"""Calibration: the per-file symbol budget must go to the question, not the top.
+
+A file with more symbols than its budget used to serve a document-order prefix,
+so on a large file the symbol the question was actually about could not be
+reached at all — the more code the file held, the smaller the served fraction
+and the stronger the top-of-file bias. The budget is unchanged; what fills it
+is now scored against the question's content terms.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from repowise.core.persistence.models import WikiSymbol
+from repowise.server.mcp_server.tool_answer.config import _MAX_SYMBOLS_TOP_HIT
+from repowise.server.mcp_server.tool_answer.symbols import _hydrate_symbols_for_hits
+
+# Twice the budget, so half the file cannot be served whatever the ordering.
+_SYMBOL_COUNT = _MAX_SYMBOLS_TOP_HIT * 2
+_BODY_LINES = 4
+
+
+def _write_module(tmp_path, names: list[str]) -> list[int]:
+    """One trivial function per name; returns their 1-indexed def lines."""
+    lines: list[str] = []
+    starts: list[int] = []
+    for name in names:
+        starts.append(len(lines) + 1)
+        lines.append(f"def {name}(request):")
+        lines.extend(f"    step{i} = {i}" for i in range(_BODY_LINES))
+        lines.append("    return request")
+    (tmp_path / "app.py").write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return starts
+
+
+async def _hydrate(session, repo_id, tmp_path, names, question):
+    starts = _write_module(tmp_path, names)
+    for i, name in enumerate(names):
+        session.add(
+            WikiSymbol(
+                id=f"sym-{i}",
+                repository_id=repo_id,
+                file_path="app.py",
+                symbol_id=f"app.py::{name}",
+                name=name,
+                qualified_name=f"app.{name}",
+                kind="function",
+                signature=f"def {name}(request)",
+                start_line=starts[i],
+                end_line=starts[i] + _BODY_LINES + 1,
+                docstring="",
+                visibility="public",
+                is_async=False,
+                complexity_estimate=1,
+                language="python",
+                parent_name=None,
+            )
+        )
+    await session.commit()
+    hits = [{"target_path": "app.py", "page_type": "file_page"}]
+    await _hydrate_symbols_for_hits(
+        session, repo_id, hits, SimpleNamespace(path=tmp_path), question=question
+    )
+    return hits[0]["symbols"]
+
+
+_ROUTING_NAMES = [f"helper{i}" for i in range(_SYMBOL_COUNT - 1)] + ["find_route"]
+_ROUTING_QUESTION = "How does routing work in this app?"
+
+
+async def test_late_symbol_named_by_the_question_survives_the_cap(
+    session, repo_id, tmp_path
+) -> None:
+    """The routing code is at the end of the file; the question asks about it."""
+    served = await _hydrate(
+        session, repo_id, tmp_path, _ROUTING_NAMES, _ROUTING_QUESTION
+    )
+    names = [s["name"] for s in served]
+
+    assert "find_route" in names, "document order buried the symbol the question named"
+    assert len(names) <= _MAX_SYMBOLS_TOP_HIT, "the budget itself must not grow"
+
+
+async def test_no_content_term_falls_back_to_document_order(
+    session, repo_id, tmp_path
+) -> None:
+    """With nothing to score, the served slice is the old start_line prefix."""
+    names = [f"helper{i}" for i in range(_SYMBOL_COUNT)]
+    served = await _hydrate(session, repo_id, tmp_path, names, "How does it work?")
+
+    assert [s["name"] for s in served] == names[:_MAX_SYMBOLS_TOP_HIT]
+
+
+async def test_served_slice_stays_in_reading_order(session, repo_id, tmp_path) -> None:
+    """Relevance decides what is kept, never what order consumers read it in."""
+    served = await _hydrate(
+        session, repo_id, tmp_path, _ROUTING_NAMES, _ROUTING_QUESTION
+    )
+    names = [s["name"] for s in served]
+
+    assert names == sorted(names, key=_ROUTING_NAMES.index)
+
+
+async def test_prose_question_still_earns_a_source_body(
+    session, repo_id, tmp_path
+) -> None:
+    """A prose question matches no identifier, so nothing would carry code."""
+    served = await _hydrate(
+        session, repo_id, tmp_path, _ROUTING_NAMES, _ROUTING_QUESTION
+    )
+    scored = [s for s in served if s["name"] == "find_route"]
+
+    assert scored and scored[0].get("source_excerpt"), (
+        "the symbol the question scored against was served without its body"
+    )
+    assert not any(s["_matched"] for s in served), "prose names no identifier"