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
fix(search): lead hybrid results with concept pages for prose queries (#797)
Raghav Chamadiya93247cbf8a8f
diff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.pyindex 50f7a7cc1..9e9af7596 100644--- a/packages/server/src/repowise/server/mcp_server/tool_search.py+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py@@ -99,6 +99,40 @@ def _has_exact_symbol(candidates: list[str], symbols: list[dict]) -> bool:return False+def _prose_dominates(query: str, identifiers: list[str]) -> bool:+ """True when natural-language tokens outnumber the identifier tokens a query+ carries: the query reads as prose that merely *mentions* a symbol, not a+ symbol lookup dressed in a few words. Drives hybrid ordering below."""+ ident_count = len(identifiers)+ if ident_count == 0:+ return False+ total = len(re.findall(r"[A-Za-z0-9_]+", query))+ return (total - ident_count) > ident_count+++def _interleave_hybrid(query: str, symbols: list[dict], concepts: list[dict],+ limit: int, exact: bool) -> list[dict]:+ """Order one hybrid result window from the two incomparable score scales.++ Symbol SQL scores (~43, +100 on an exact-name hit) and concept relevance+ (0 to 1) can't be merge-sorted, so we interleave by block. Default: symbols+ lead, reserving up to half the window for concept pages so a flood of symbol+ matches can't truncate every page out.++ The exception is the score-scale trap. When NO returned symbol matches the+ query's identifier exactly AND the query is mostly prose, leading with fuzzy+ symbol hits buries the page the caller actually wants: the generic ``.get``+ methods that outscore the ``answer.py`` page for "how does retrieval feed+ synthesis in get_answer". There, concept pages lead and the fuzzy symbols+ fall to the tail (nothing is dropped, only reordered within the window).+ """+ if not exact and concepts and _prose_dominates(query, _embedded_identifiers(query)):+ reserved = min(len(symbols), limit // 2)+ return (concepts[: max(1, limit - reserved)] + symbols)[:limit]+ reserved = min(len(concepts), limit // 2)+ return (symbols[: max(1, limit - reserved)] + concepts)[:limit]++# Decision records are short, dense title-statements; they win cosine# similarity against long file-page embeddings on any query containing# design nouns ("store", "SQLite", "cap", "prune") and crowd file pages@@ -571,21 +605,24 @@ async def _structured_search(symbols.sort(key=lambda x: -(x.get("score") or 0.0))files.sort(key=lambda x: -(x.get("score") or 0.0))+ # Whether any returned symbol matches the query's identifier(s) exactly.+ # Computed once here so the hybrid interleave and the exact-match note below+ # agree on the same signal.+ candidates = _identifier_candidates(query, mode)+ exact = _has_exact_symbol(candidates, symbols) if candidates else False+if mode == "symbol":results = symbols[:limit]elif mode == "path":results = files[:limit]- else: # hybrid — symbol matches first, then concept pages for new files+ else: # hybrid: interleave symbol matches and concept pages for new filessym_files = {s.get("file") for s in symbols}concepts = [c for c in concepts if c.get("target_path") not in sym_files]# Federation appends per-repo concept lists in repo order — re-rank by# relevance so a strong page in repo B isn't buried under repo A's weak# ones. (Single-repo: already sorted upstream; this is a no-op.)concepts.sort(key=lambda x: -(x.get("relevance_score") or 0.0))- # Reserve up to half the window for concept pages so hybrid stays- # hybrid: a flood of symbol matches must not truncate every page out.- reserved = min(len(concepts), limit // 2)- results = (symbols[: max(1, limit - reserved)] + concepts)[:limit]+ results = _interleave_hybrid(query, symbols, concepts, limit, exact)repository = Noneif not multi:@@ -601,10 +638,9 @@ async def _structured_search(# indexed symbol still returns fuzzy neighbours. Say so, or the agent# anchors on a wrong hit that looks authoritative (their Alamofire# 44-overload read-spiral). Emit the boolean either way; a note only when- # there is no exact hit to distinguish from the fuzz.- candidates = _identifier_candidates(query, mode)+ # there is no exact hit to distinguish from the fuzz. ``candidates`` /+ # ``exact`` were computed above so ordering and this note stay consistent.if candidates:- exact = _has_exact_symbol(candidates, symbols)response["exact_match"] = exactif not exact:shown = ", ".join(repr(c) for c in candidates[:3])diff --git a/tests/unit/server/mcp/test_search.py b/tests/unit/server/mcp/test_search.pyindex 67dea6053..d84da2834 100644--- a/tests/unit/server/mcp/test_search.py+++ b/tests/unit/server/mcp/test_search.py@@ -464,6 +464,70 @@ class TestHybridSearch:assert "page" in types, "concept page must survive the merge"+class TestHybridInterleave:+ """The hybrid block-interleave: symbol and concept scores are incomparable,+ so ordering is by block. Default symbols-lead, EXCEPT the score-scale trap -+ a mostly-prose query whose embedded identifier matches no symbol exactly must+ lead with concept pages, or fuzzy symbol hits bury the relevant page."""++ def _sym(self, name, file, score):+ return {"type": "symbol", "name": name, "file": file, "score": score}++ def _page(self, path, rel):+ return {"type": "page", "target_path": path, "relevance_score": rel}++ def test_prose_dominates(self):+ from repowise.server.mcp_server.tool_search import _prose_dominates++ # 6 prose tokens vs 1 identifier -> prose.+ assert _prose_dominates("how does retrieval feed synthesis in get_answer", ["get_answer"])+ # Balanced / symbol-heavy -> not prose-dominant.+ assert not _prose_dominates("compare FooBar and BazQux", ["FooBar", "BazQux"])+ # No embedded identifier -> never prose-dominant (nothing to demote).+ assert not _prose_dominates("plain english question here", [])++ def test_no_exact_prose_query_leads_with_concepts(self):+ from repowise.server.mcp_server.tool_search import _interleave_hybrid++ symbols = [self._sym("get", "a/registry.py", 43.8),+ self._sym("get", "b/store.py", 43.7)]+ concepts = [self._page("mcp/answer.py", 0.47)]+ out = _interleave_hybrid(+ "how does retrieval feed synthesis in get_answer",+ symbols, concepts, limit=5, exact=False,+ )+ assert out[0]["type"] == "page", "the answer.py page must lead, not fuzzy .get"+ # Nothing dropped - the fuzzy symbols still ride along at the tail.+ assert {s["file"] for s in symbols} <= {r.get("file") for r in out}++ def test_exact_match_keeps_symbols_first(self):+ from repowise.server.mcp_server.tool_search import _interleave_hybrid++ symbols = [self._sym("get_answer", "mcp/answer.py", 143.0)]+ concepts = [self._page("mcp/other.py", 0.5)]+ out = _interleave_hybrid("where is get_answer defined", symbols, concepts,+ limit=5, exact=True)+ assert out[0]["type"] == "symbol"++ def test_symbol_heavy_query_keeps_symbols_first(self):+ from repowise.server.mcp_server.tool_search import _interleave_hybrid++ # Not prose-dominant, so default ordering even without an exact match.+ symbols = [self._sym("FooBar", "x.py", 40.0)]+ concepts = [self._page("y.py", 0.3)]+ out = _interleave_hybrid("compare FooBar BazQux", symbols, concepts,+ limit=5, exact=False)+ assert out[0]["type"] == "symbol"++ def test_no_concepts_returns_symbols(self):+ from repowise.server.mcp_server.tool_search import _interleave_hybrid++ symbols = [self._sym("get", "a.py", 43.0)]+ out = _interleave_hybrid("how does retrieval feed synthesis in get_answer",+ symbols, [], limit=5, exact=False)+ assert out == symbols++class TestConceptModeUnchanged:"""Forcing mode="concept" preserves the original semantic behavior."""