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(answer): serve a ranked file list when keyless retrieval is weak (#3137)

Raghav Chamadiya8dc2f4dc1bc4
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.md
index e5b196428..1552c874e 100644
--- a/docs/agent/MCP_TOOLS.md
+++ b/docs/agent/MCP_TOOLS.md
@@ -149,7 +149,7 @@ Answers a how, where or why question in one call: it runs hybrid retrieval over
**Key return fields:** `answer`, `confidence` (`high` / `medium` / `low`, rates the prose), `retrieval_quality` (`high` / `partial` / `weak`, rates the evidence), `citations`, `symbol_bodies` (live bodies of symbols the answer names), `retrieval`, `best_guesses` and `fallback_targets` (on low confidence; a low `best_guesses` row carries `functions`, `lines` and `size_bytes` instead of a page excerpt), `candidate_files` (ranked file paths the citations do not already name: up to 3 at `high`, 5 otherwise), `episodes` (dated facts bearing on the question), `degraded` (synthesis could not run), `_meta.scope_hint` (areas the answer did not touch).
-A `high` answer can be cited directly. On `low`, read the rows the reply names, then `candidate_files`, before searching again. Without an LLM provider the tool still answers from retrieval, marked `degraded`.
+A `high` answer can be cited directly. On `low`, read the rows the reply names, then `candidate_files`, before searching again. Without an LLM provider the tool still answers from retrieval, marked `degraded`. When retrieval is also `weak`, the reply serves `best_guesses` and `candidate_files` with one guidance line in `answer`, and no `citations`.
```
get_answer(question="How does the authentication flow work?")
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 e8190614d..39784dba8 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
@@ -414,11 +414,76 @@ def _default_shape(payload: dict[str, Any], question: str) -> None:
)
+_RANKED_RATIONALE_CHARS = 200
+
+
+def _ranked_list_only(payload: dict[str, Any]) -> bool:
+ """Keyless, weak retrieval and no body: the ranked files are the whole product."""
+ return (
+ payload.get("degraded") == "no-llm-provider"
+ and payload.get("retrieval_quality") == "weak"
+ and payload.get("confidence") == "low"
+ and not payload.get("symbol_bodies")
+ and _first_guess(payload) is not None
+ )
+
+
+def _serve_ranked_list(payload: dict[str, Any]) -> None:
+ """Cut a keyless weak reply to best_guesses, candidate_files and one guidance line.
+
+ A rationale row from the top guess, or one opening with its file's
+ ``why_relevant``, adds nothing; one other row survives, shortened.
+ ``include=["evidence"]`` restores everything.
+ """
+ top = _nav_path(_first_guess(payload))
+ why = {
+ _nav_path(guess): " ".join(_text(guess, "why_relevant", "why").rstrip(".").split())
+ for guess in payload["best_guesses"]
+ if isinstance(guess, dict)
+ }
+
+ def _restates(row: dict[str, Any]) -> bool:
+ path = _nav_path(row)
+ if path == top:
+ return True
+ opening = why.get(path)
+ comment = " ".join(_text(row, "rationale", "comment", "quote", "source", "text").split())
+ return bool(opening) and comment.startswith(opening)
+
+ row = next(
+ (
+ row for row in payload.get("code_rationale") or []
+ if isinstance(row, dict) and not _restates(row)
+ ),
+ None,
+ )
+ payload.pop("code_rationale", None)
+ if row is not None:
+ comment = _text(row, "rationale", "comment", "quote", "source", "text")
+ if len(comment) > _RANKED_RATIONALE_CHARS:
+ comment = comment[:_RANKED_RATIONALE_CHARS].rstrip() + "…"
+ payload["code_rationale"] = [
+ {"path": _path(row), "lines": row.get("lines"), "comment": comment}
+ ]
+ # Every cited path is a guess or a rationale row, so citations would repeat them.
+ for key in ("citations", "note", "next_action_hint"):
+ payload.pop(key, None)
+ if isinstance(payload.get("_meta"), dict):
+ payload["_meta"].pop("hint", None)
+ payload["answer"] = (
+ f"No synthesis ({payload['degraded']}), weak retrieval: best_guesses ranks the "
+ f"likeliest files, {top} first. If none fits, refine with search_codebase."
+ )
+
+
def _record_reductions(
payload: dict[str, Any], totals: dict[str, int], *, scope: str | None, repo: str | None,
- expanded: bool
+ expanded: bool, ranked: bool = False
) -> None:
reduced = False
+ reason = "deduplicated" if expanded else "confidence_projection_and_deduplication"
+ # Ranked shape only: rows summed across every reduced collection.
+ shown = hidden = 0
for key in _COLLECTIONS:
# By default ``candidate_files`` carries these paths, so counting the
# hidden rows would only advertise what the reply already serves.
@@ -428,11 +493,19 @@ def _record_reductions(
emitted = len(payload.get(key) or []) if isinstance(payload.get(key), list) else 0
if total <= emitted:
continue
- reason = "deduplicated" if expanded else "confidence_projection_and_deduplication"
+ reduced = True
+ if ranked:
+ shown, hidden = shown + emitted, hidden + total
+ continue
payload[f"{key}_total"] = total
payload[f"{key}_emitted"] = emitted
payload[f"{key}_reduced_reason"] = reason
- reduced = True
+ if ranked and reduced:
+ # One row instead of three sibling counts per collection: the ranked
+ # list is the product, and ``_meta.completeness`` still rolls this up.
+ payload.setdefault("_meta", {}).setdefault("reductions", []).append(
+ {"field": "evidence", "total": hidden, "emitted": shown, "reason": reason}
+ )
if reduced and not expanded:
projection = payload.setdefault("_meta", {}).setdefault("projection", {})
# The caller already holds the question; restating a long one costs
@@ -461,8 +534,8 @@ def project_answer_payload(
def _project(
raw: dict[str, Any], *, question: str, scope: str | None,
repo: str | None, include: list[str] | None
-) -> tuple[dict[str, Any], bool]:
- """The projection, and whether it slimmed ``best_guesses`` (decided once, here)."""
+) -> tuple[dict[str, Any], bool, bool]:
+ """The projection, whether it slimmed ``best_guesses``, and whether it is the ranked list."""
payload = copy.deepcopy(raw)
totals = {
key: len(payload.get(key) or []) if isinstance(payload.get(key), list) else 0
@@ -478,14 +551,19 @@ def _project(
slimmed = _slim_best_guesses(payload, facts if isinstance(facts, dict) else {})
_shape_candidate_files(payload, expanded=expanded)
_rewrite_degraded_answer(payload)
+ ranked = not expanded and _ranked_list_only(payload)
+ if ranked:
+ _serve_ranked_list(payload)
for key in _COLLECTIONS:
if not payload.get(key):
payload.pop(key, None)
- _record_reductions(payload, totals, scope=scope, repo=repo, expanded=expanded)
+ _record_reductions(
+ payload, totals, scope=scope, repo=repo, expanded=expanded, ranked=ranked
+ )
unknown = sorted(set(include or []) - {"evidence"})
if unknown:
payload.setdefault("_meta", {})["ignored_arguments"] = {"include": unknown}
- return payload, slimmed
+ return payload, slimmed, ranked
def _served_paths(payload: dict[str, Any]) -> list[str]:
@@ -594,7 +672,7 @@ def _file_size(root: Path, path: str) -> tuple[int | None, int] | None:
return lines + (1 if last and last != b"\n" else 0), size
-def _add_file_sizes(payload: dict[str, Any], root: Path | None) -> None:
+def _add_file_sizes(payload: dict[str, Any], root: Path | None, *, ranked: bool = False) -> None:
"""Stamp live ``lines`` / ``size_bytes`` on slimmed guesses and cue a ranged read.
Serve-time, not cached, so a dirty tree reports the bytes an agent would Read.
@@ -617,11 +695,15 @@ def _add_file_sizes(payload: dict[str, Any], root: Path | None) -> None:
f"get_context(targets=[\"{path}\"], include=[\"skeleton\"]), "
"rather than the whole file."
)
- hint = payload.get("next_action_hint")
- payload["next_action_hint"] = f"{hint.rstrip()} {cue}" if isinstance(hint, str) else cue
+ # The keyless ranked list carries its one guidance line in ``answer``.
+ key = "answer" if ranked else "next_action_hint"
+ hint = payload.get(key)
+ payload[key] = f"{hint.rstrip()} {cue}" if isinstance(hint, str) else cue
-async def _refresh_file_sizes(payload: dict[str, Any], repo: str | None) -> None:
+async def _refresh_file_sizes(
+ payload: dict[str, Any], repo: str | None, *, ranked: bool = False
+) -> None:
"""Size the slimmed guesses. Best-effort: a sync stat and bounded read of <= 3 files."""
if repo == "all":
return
@@ -632,7 +714,7 @@ async def _refresh_file_sizes(payload: dict[str, Any], repo: str | None) -> None
root = _repo_root(await _resolve_repo_context(repo))
except Exception:
return
- _add_file_sizes(payload, root)
+ _add_file_sizes(payload, root, ranked=ranked)
def _whole_bodies(payload: dict[str, Any]) -> int:
@@ -678,12 +760,12 @@ def projected_answer(fn: Callable[..., Any]) -> Callable[..., Any]:
include: list[str] | None = None,
) -> dict[str, Any]:
raw = await fn(question=question, scope=scope, repo=repo, include=include)
- payload, slimmed = _project(
+ payload, slimmed, ranked = _project(
raw, question=question, scope=scope, repo=repo, include=include
)
await _refresh_freshness(payload, repo)
if slimmed:
- await _refresh_file_sizes(payload, repo)
+ await _refresh_file_sizes(payload, repo, ranked=ranked)
_stamp_completeness(payload)
return payload
diff --git a/tests/unit/server/mcp/test_answer_shortlist.py b/tests/unit/server/mcp/test_answer_shortlist.py
index 5a4337a20..bd32dde07 100644
--- a/tests/unit/server/mcp/test_answer_shortlist.py
+++ b/tests/unit/server/mcp/test_answer_shortlist.py
@@ -247,3 +247,89 @@ async def test_candidate_file_facts_never_leak_through_the_tool_on_a_cache_hit(
assert provider.calls == 1
for reply in (fresh, cached):
assert "_candidate_file_facts" not in json.dumps(reply, default=str)
+
+
+_COMMENT = "Why this module exists, at length. " * 20 # a long mined docstring
+
+
+def _keyless_weak(**extra) -> dict:
+ """A keyless reply on a weak retrieval, shaped like a live OpenWhisper one."""
+ raw = _raw("low", **{"degraded": "no-llm-provider", **extra})
+ raw["citations"] = _POOL[:3]
+ raw["note"] = "Synthesis is unavailable; local retrieval remains usable."
+ raw["fallback_targets"] = _POOL[:5]
+ raw["code_rationale"] = [
+ {"path": _POOL[0], "lines": [1, 12], "comment": f"guess {_POOL[0]}. {_COMMENT}"},
+ {"path": _POOL[1], "lines": [40, 46], "comment": f"High edge. {_COMMENT}"},
+ {"path": _POOL[1], "lines": [1, 9], "comment": f"guess {_POOL[1]}.. {_COMMENT}"},
+ {"path": _POOL[2], "lines": [5, 8], "comment": f"Low edge. {_COMMENT}"},
+ ]
+ raw["_meta"] = {"contract_version": 1, "hint": "No synthesis, and retrieval was weak."}
+ return raw
+
+
+def test_keyless_weak_reply_serves_the_ranked_list_and_one_guidance_line():
+ raw = _keyless_weak()
+ out = project_answer_payload(raw, question="which file registers the hotkey")
+ before = project_answer_payload(
+ _keyless_weak(degraded="synthesis-failed"), question="which file registers the hotkey"
+ )
+
+ assert set(out) == {
+ "answer", "confidence", "retrieval_quality", "degraded", "best_guesses",
+ "candidate_files", "code_rationale", "_meta",
+ }
+ assert "src/pkg/f0.py first" in out["answer"] and "search_codebase" in out["answer"]
+ assert "hint" not in out["_meta"]
+ # Ranking and the files served are untouched.
+ assert out["best_guesses"] == before["best_guesses"]
+ assert out["candidate_files"] == before["candidate_files"]
+ # Rows from the top guess, or opening with a guess's reason, restate best_guesses.
+ (row,) = out["code_rationale"]
+ assert (row["path"], row["lines"]) == (_POOL[1], [40, 46])
+ assert row["comment"].startswith("High edge.") and len(row["comment"]) <= 201
+ assert not any(key.endswith(("_total", "_emitted", "_reduced_reason")) for key in out)
+ (reduction,) = out["_meta"]["reductions"]
+ assert reduction["field"] == "evidence" and reduction["emitted"] < reduction["total"]
+ assert out["_meta"]["projection"]["recovery"]["arguments"] == {"include": ["evidence"]}
+
+
+def test_keyless_weak_reply_fits_its_size_ceiling():
+ # Served live, the envelope (_meta scope, freshness, completeness) adds about
+ # 750 chars; 1,300 here keeps the whole reply near 2 KB, down from about 4.6 KB.
+ out = project_answer_payload(_keyless_weak(), question="which file registers the hotkey")
+ assert len(json.dumps(out, separators=(",", ":"), ensure_ascii=False)) < 1_300
+
+
+def test_keyless_weak_drops_rationale_when_every_row_restates_the_list():
+ raw = _keyless_weak()
+ del raw["code_rationale"][1]
+ out = project_answer_payload(raw, question="q")
+ assert "code_rationale" not in out
+
+
+ ("extra", "include"),
+ [
+ ({"degraded": "synthesis-failed"}, None),
+ ({"retrieval_quality": "partial", "confidence": "medium"}, None),
+ ({"symbol_bodies": [{"path": "src/pkg/f0.py", "name": "run_0", "lines": [10, 12],
+ "source": "def run_0(): ...", "verified": True}]}, None),
+ ({}, ["evidence"]),
+ ],
+)
+def test_other_replies_keep_their_shape(extra, include):
+ raw = _keyless_weak()
+ raw.update(extra)
+ out = project_answer_payload(raw, question="q", include=include)
+ assert "note" in out
+ assert out.get("citations")
+ assert "reductions" not in out["_meta"]
+
+
+def test_the_ranked_list_puts_the_size_cue_in_its_answer_line(tmp_path):
+ (tmp_path / "big.py").write_bytes(b"x\n" * 30000)
+ payload = {"answer": "Ranked.", "best_guesses": [{"file": "big.py"}]}
+ _add_file_sizes(payload, tmp_path, ranked=True)
+ assert payload["answer"].startswith("Ranked. big.py is 58 KB")
+ assert "next_action_hint" not in payload