Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.mdindex 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.pyindex 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 = 0for 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 0if total <= emitted:continue- reason = "deduplicated" if expanded else "confidence_projection_and_deduplication"+ reduced = True+ if ranked:+ shown, hidden = shown + emitted, hidden + total+ continuepayload[f"{key}_total"] = totalpayload[f"{key}_emitted"] = emittedpayload[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, rankeddef _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) -> Noneroot = _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 payloaddiff --git a/tests/unit/server/mcp/test_answer_shortlist.py b/tests/unit/server/mcp/test_answer_shortlist.pyindex 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 == 1for 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