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.

perf(mcp): halve get_why search payloads and stop embedding the query twice (#1555)

Raghav Chamadiya62a871ddf801
diff --git a/packages/server/src/repowise/server/mcp_server/tool_why.py b/packages/server/src/repowise/server/mcp_server/tool_why.py
index 51c95e66e..5f111f6dc 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_why.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_why.py
@@ -198,6 +198,37 @@ _COLLECTOR_HEADROOM_CHARS = 600
_PATH_STATUS_ORDER = {"active": 0, "proposed": 1, "deprecated": 2, "superseded": 3}
+# --- Search-mode caps -------------------------------------------------------
+#
+# Search mode had no caps at all: it served eight whole records with their file
+# arrays inlined, measuring 27 640 - 34 917 chars over five probe questions
+# against a 32 000 budget, so two of the five went over the ceiling outright.
+# The cost was not only transport. On a question the store does answer ("why
+# ruff check and not ruff format", held by two active records) it returned eight
+# records, none of them those, three restating one unrelated decision. A long
+# low-relevance answer teaches an agent that the tool is not worth calling,
+# which is more expensive than a miss.
+#
+# So this mode gets few records served whole rather than many served thin: a
+# padded answer is the failure mode, and thinning every record to keep eight of
+# them is padding with extra steps.
+
+#: Records kept by search mode. Three whole beats eight thinned: past the third
+#: hit the ranking is not trustworthy enough to spend an agent's context on.
+_MAX_SEARCH_DECISIONS = 3
+
+#: Nearest pages pulled for the *one* semantic lookup search mode makes. Both
+#: lanes (decisions, documentation) are partitioned out of this single window,
+#: so the depth is the old decision lane's rather than the sum of the two.
+_SEMANTIC_WINDOW = 50
+
+#: Keyword candidates scored before restatements are collapsed. Wider than the
+#: serving cap on purpose: the worst cluster here is fourteen phrasings of one
+#: decision, so a pool cut to three first would serve one decision three times.
+#: Bounded because the lineage walk after the collapse costs a query per record.
+_KEYWORD_POOL = 24
+
+
def _path_decision_sort_key(d: Any) -> tuple[int, float, float]:
return (
_PATH_STATUS_ORDER.get(d.status, 4),
@@ -500,53 +531,82 @@ async def _load_target_git(
def _rank_keyword_matches(all_decisions: list, query: str, target_set: set[str]) -> list:
- """Score decisions by weighted keyword overlap and return the top 8."""
+ """Score decisions by weighted keyword overlap, best-first.
+
+ Score first, then status: a record someone confirmed wins a tie against one
+ an extractor proposed, but never outranks a better-matching record. Ordering
+ by status *first* was tried and measured worse, and the reason generalises —
+ only 69 of this repo's 614 records are active, so a hard status gate serves
+ three weakly-matching confirmed records ahead of the only relevant ones. The
+ four records that answer "why is entry-point candidacy decided at ingestion"
+ are all proposed, and status-first ordering made them unreachable.
+
+ Returns a pool wider than the serving cap because restatements are collapsed
+ downstream, and a pool cut to the cap first would let three phrasings of one
+ decision fill every slot.
+ """
query_words = set(query.lower().split()) - _QUERY_STOP_WORDS
- scored_decisions: list[tuple[float, Any]] = []
+ scored_decisions: list[tuple[float, int, Any]] = []
for d in all_decisions:
score = _score_decision(d, query_words, target_set)
if score > 0:
- scored_decisions.append((score, d))
- scored_decisions.sort(key=lambda t: t[0], reverse=True)
- return [d for _, d in scored_decisions[:8]]
+ scored_decisions.append((-score, _PATH_STATUS_ORDER.get(d.status, 4), d))
+ scored_decisions.sort(key=lambda t: (t[0], t[1]))
+ return [d for _, _, d in scored_decisions[:_KEYWORD_POOL]]
-async def _semantic_decision_results(ctx: Any, query: str) -> list:
- """Semantic search of the page store, filtered to the decision: namespace.
+async def _fts_doc_results(ctx: Any, query: str) -> list:
+ """Documentation hits from the lexical index.
- Empty on a keyless index: there is no lexical fallback here, and a window of
- arbitrary decisions is worse than none for a tool whose whole job is
- explaining why a specific thing is the way it is.
+ The keyless path, and the fallback whenever the vector store is present but
+ unusable: a store that cannot rank gives the same answer as no store.
"""
- decision_results: list = []
+ doc_results: list = []
with contextlib.suppress(Exception):
- if ctx.vector_store is not None and store_has_semantic_vectors(ctx.vector_store):
- _raw = await ctx.vector_store.search(query, limit=50)
- decision_results = [
- r for r in _raw if getattr(r, "page_id", "").startswith(DECISION_VECTOR_PREFIX)
- ][:5]
- return decision_results
+ doc_results = await ctx.fts.search(query, limit=3)
+ return doc_results
-async def _semantic_doc_results(ctx: Any, query: str) -> list:
- """Semantic search over documentation, falling back to FTS.
+async def _semantic_lanes(ctx: Any, query: str) -> tuple[list, list]:
+ """``(decision_hits, doc_hits)`` from **one** embedding of *query*.
- A keyless index takes the FTS path directly rather than going through a
- vector store that cannot rank, which is the same answer the ``except``
- branch already produces for an unusable store.
+ These were two awaits embedding the same string back to back, so every
+ search-mode call paid two network round trips to ask one question. One
+ ``embed_texts`` plus ``search_by_vector`` is the documented way to spend one
+ (see ``vector_store._base``), and ``search`` remains the fallback for a
+ backend that cannot search by raw vector.
+
+ Partitioning one window also fixes a quieter bug: the doc lane took the
+ nearest three pages *of any kind*, so decision records were being served
+ back as "related documentation" beside the decisions list they came from.
+ Splitting by namespace gives each lane only what belongs to it.
+
+ The decision lane stays empty on a keyless index, deliberately: there is no
+ lexical fallback for it, because a window of arbitrary decisions is worse
+ than none for a tool whose whole job is explaining one specific thing.
"""
if not store_has_semantic_vectors(getattr(ctx, "vector_store", None)):
- doc_results: list = []
- with contextlib.suppress(Exception):
- doc_results = await ctx.fts.search(query, limit=3)
- return doc_results
- try:
- return await ctx.vector_store.search(query, limit=3)
- except Exception:
- doc_results = []
- with contextlib.suppress(Exception):
- doc_results = await ctx.fts.search(query, limit=3)
- return doc_results
+ return [], await _fts_doc_results(ctx, query)
+
+ raw: list | None = None
+ with contextlib.suppress(Exception):
+ vectors = await ctx.vector_store.embed_texts([query])
+ if vectors:
+ raw = await ctx.vector_store.search_by_vector(vectors[0], limit=_SEMANTIC_WINDOW)
+ if raw is None:
+ # Backend holds no embedder, or cannot search by raw vector.
+ raw = await ctx.vector_store.search(query, limit=_SEMANTIC_WINDOW)
+ if raw is None:
+ return [], await _fts_doc_results(ctx, query)
+
+ decision_hits, doc_hits = [], []
+ for r in raw:
+ page_id = getattr(r, "page_id", "")
+ if page_id.startswith(DECISION_VECTOR_PREFIX):
+ decision_hits.append(r)
+ else:
+ doc_hits.append(r)
+ return decision_hits[:_MAX_SEARCH_DECISIONS], doc_hits[:3]
async def _lineage_for_matches(ctx: Any, keyword_matches: list) -> dict[str, list[dict]]:
@@ -563,33 +623,91 @@ async def _lineage_for_matches(ctx: Any, keyword_matches: list) -> dict[str, lis
return lineage_by_id
+def _evidence_key(d: Any) -> tuple[str, str] | None:
+ """The evidence a record cites, as a merge key, or ``None`` when it cites none.
+
+ Re-extraction paraphrases a record's prose but not its provenance. The
+ fourteen records on this repo that all restate one LIKE-escaping decision
+ carry fourteen titles and fourteen ids and the same single
+ ``evidence_commits`` entry; comment-sourced restatements repeat an
+ ``evidence_file`` instead. Store-wide, 478 of 614 records sit in a cluster
+ like that, which is why one query could return five phrasings of one
+ decision.
+
+ So the key is the cited evidence plus the extractor that read it, never the
+ text. Normalising titles would need a tuned similarity threshold, and a
+ wrong merge there hides a human-confirmed record. Keeping ``source`` in the
+ key also means two extractors that independently found the same commit stay
+ separate, which is the provenance-accretion case ``decision_evidence``
+ already models.
+ """
+ commits = json.loads(getattr(d, "evidence_commits_json", None) or "[]")
+ if commits:
+ return (d.source or "", f"commit:{commits[0]}")
+ if d.evidence_file:
+ return (d.source or "", f"file:{d.evidence_file}")
+ return None
+
+
+def _collapse_restatements(records: list) -> list[tuple[Any, list[str]]]:
+ """``(kept, folded_ids)`` per distinct decision, input order preserved.
+
+ Runs on records rather than on the projected dicts so the collapse happens
+ *before* the lineage walk, which costs a query per surviving record. Records
+ citing no evidence at all cannot be compared this way and are always kept.
+ """
+ by_evidence: dict[tuple[str, str], int] = {}
+ out: list[tuple[Any, list[str]]] = []
+ for d in records:
+ key = _evidence_key(d)
+ if key is not None and key in by_evidence:
+ out[by_evidence[key]][1].append(d.id)
+ continue
+ if key is not None:
+ by_evidence[key] = len(out)
+ out.append((d, []))
+ return out
+
+
def _merge_decisions(
- keyword_matches: list,
+ keyword_matches: list[tuple[Any, list[str]]],
decision_results: list,
lineage_by_id: dict[str, list[dict]],
) -> list[dict]:
- """Merge keyword and semantic decision hits, deduplicated by id."""
+ """Project collapsed keyword hits, then append semantic hits not already in.
+
+ *keyword_matches* arrives from :func:`_collapse_restatements`, so the folded
+ ids ride along on ``restates``: nothing becomes unaddressable and the store
+ is untouched.
+ """
seen_ids: set[str] = set()
merged_decisions: list[dict] = []
- for d in keyword_matches:
+ for d, folded in keyword_matches:
if d.id in seen_ids:
continue
- seen_ids.add(d.id)
- merged_decisions.append(
- {
- "id": d.id,
- "title": d.title,
- "status": d.status,
- "decision": _decision_body(d),
- "rationale": d.rationale,
- "context": d.context,
- "consequences": json.loads(d.consequences_json),
- "affected_files": json.loads(d.affected_files_json),
- "source": d.source,
- "confidence": d.confidence,
- "lineage": lineage_by_id.get(d.id, []),
- }
- )
+ seen_ids.update([d.id, *folded])
+ affected_files = json.loads(d.affected_files_json)
+ entry = {
+ "id": d.id,
+ "title": d.title,
+ "status": d.status,
+ "decision": _decision_body(d),
+ "rationale": d.rationale,
+ "context": d.context,
+ "consequences": json.loads(d.consequences_json),
+ # Whole arrays reached 83 paths and 4 812 chars, 36% of the payload
+ # across the eight records served. A head plus a total answers "how
+ # wide is this decision" as well, and path mode already says so.
+ "affected_files": affected_files[:_MAX_AFFECTED_FILES],
+ "source": d.source,
+ "confidence": d.confidence,
+ "lineage": lineage_by_id.get(d.id, []),
+ }
+ if len(affected_files) > _MAX_AFFECTED_FILES:
+ entry["affected_files_total"] = len(affected_files)
+ if folded:
+ entry["restates"] = folded
+ merged_decisions.append(entry)
for r in decision_results:
# Strip the "decision:" prefix so the returned id matches the SQL primary key.
@@ -673,16 +791,22 @@ async def _why_search(query: str, targets: list[str] | None, repo: str | None) -
target_git = await _load_target_git(session, repository.id, targets)
target_set = set(targets) if targets else set()
- keyword_matches = _rank_keyword_matches(all_decisions, query, target_set)
- decision_results = await _semantic_decision_results(ctx, query)
- doc_results = await _semantic_doc_results(ctx, query)
- lineage_by_id = await _lineage_for_matches(ctx, keyword_matches)
- merged_decisions = _merge_decisions(keyword_matches, decision_results, lineage_by_id)
-
+ # Rank wide, collapse restatements, then cap — so the cap spends its slots on
+ # distinct decisions — and only walk lineage for what survives.
+ ranked = _rank_keyword_matches(all_decisions, query, target_set)
+ collapsed = _collapse_restatements(ranked)[:_MAX_SEARCH_DECISIONS]
+ decision_results, doc_results = await _semantic_lanes(ctx, query)
+ lineage_by_id = await _lineage_for_matches(ctx, [d for d, _ in collapsed])
+ merged_decisions = _merge_decisions(collapsed, decision_results, lineage_by_id)
+
+ # No further slice: the cap is on *bodies*, applied to ``collapsed`` above.
+ # Semantic hits append as id-plus-snippet at roughly 200 chars each, so
+ # dropping them to fit a record count would cost the lane that carries a
+ # calibrated relevance score for the sake of no measurable payload.
result_data: dict[str, Any] = {
"mode": "search",
"query": query,
- "decisions": merged_decisions[:8],
+ "decisions": merged_decisions,
"related_documentation": [
{
"page_id": r.page_id,
@@ -745,7 +869,16 @@ def _score_decision(
if not query_words:
return 1.0 if target_files else 0.0
- # Build weighted text fields
+ # Build weighted text fields.
+ #
+ # ``affected_files`` is deliberately absent. Joining a record's whole path
+ # list into one haystack and substring-matching a question against it scores
+ # by *breadth*: the record here governing 83 files matched almost every
+ # question asked, because ordinary query words ("index", "page", "format")
+ # occur somewhere in 83 paths, and it became the top hit for three of five
+ # probe questions including one about ruff. A scope is not question text.
+ # The legitimate use of that field — does this record govern the file the
+ # caller named — is the exact set membership in the target boost below.
fields = [
(3.0, d.title.lower()),
(2.0, d.decision.lower()),
@@ -753,7 +886,6 @@ def _score_decision(
(1.5, d.context.lower()),
(1.0, " ".join(json.loads(d.consequences_json)).lower()),
(1.0, " ".join(json.loads(d.tags_json)).lower()),
- (1.5, " ".join(json.loads(d.affected_files_json)).lower()),
(1.0, (d.evidence_file or "").lower()),
]
diff --git a/tests/unit/server/mcp/test_why_search_payload.py b/tests/unit/server/mcp/test_why_search_payload.py
new file mode 100644
index 000000000..8a63ec332
--- /dev/null
+++ b/tests/unit/server/mcp/test_why_search_payload.py
@@ -0,0 +1,287 @@
+"""Search-mode payload shape: caps, restatement collapse, one embedding.
+
+Search mode had no caps at all. It served eight whole records with their file
+arrays inlined, measuring 27 640 - 34 917 chars against a 32 000 budget, and
+paid two embeddings of the same query to build them. These pin the three things
+that fixed: the projection is clamped, restatements of one decision collapse
+instead of filling every slot, and the two semantic lanes come out of one
+embedding rather than two round trips.
+
+Six of these eight fail against the code they were written for. The two that do
+not — ``test_search_keeps_records_citing_different_commits_apart`` and
+``test_status_breaks_ties_without_gating`` — are deliberate guards on behaviour
+the fix must *not* change: one bounds the restatement collapse so two real
+decisions never merge, the other pins the ordering back after status-first
+ranking was tried and measured worse. They are here to fail on a future change,
+not this one.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+
+async def _seed(
+ session,
+ rid: str,
+ *,
+ id_: str,
+ title: str,
+ status: str = "proposed",
+ source: str = "pr",
+ commits: list[str] | None = None,
+ files: list[str] | None = None,
+ confidence: float = 0.8,
+ decision: str = "dec",
+ rationale: str = "why",
+ context: str = "ctx",
+ evidence_file: str | None = None,
+) -> None:
+ from repowise.core.persistence.models import DecisionRecord
+
+ session.add(
+ DecisionRecord(
+ id=id_,
+ repository_id=rid,
+ title=title,
+ status=status,
+ context=context,
+ decision=decision,
+ rationale=rationale,
+ affected_files_json=json.dumps(files or []),
+ affected_modules_json=json.dumps([]),
+ evidence_commits_json=json.dumps(commits or []),
+ evidence_file=evidence_file,
+ source=source,
+ confidence=confidence,
+ staleness_score=0.0,
+ )
+ )
+ await session.flush()
+
+
+async def test_search_clamps_affected_files_and_reports_the_total(session, setup_mcp):
+ """Whole arrays were 36% of the payload; path mode already clamps to a head."""
+ from repowise.server.mcp_server import get_why
+ from repowise.server.mcp_server.tool_why import _MAX_AFFECTED_FILES
+
+ await _seed(
+ session,
+ setup_mcp,
+ id_="wide1",
+ title="Zebrafish caching strategy",
+ files=[f"src/mod{n}/file.py" for n in range(83)],
+ )
+
+ result = await get_why("why the zebrafish caching strategy")
+ wide = next(d for d in result["decisions"] if d["id"] == "wide1")
+
+ assert len(wide["affected_files"]) == _MAX_AFFECTED_FILES
+ assert wide["affected_files_total"] == 83
+
+
+async def test_search_collapses_restatements_of_one_decision(session, setup_mcp):
+ """Dedup was by id, which is unique per extraction, so it collapsed nothing.
+
+ Fourteen records on the dogfooded repo restate one decision and share a
+ single ``evidence_commits`` entry. Serving five phrasings of one decision is
+ how a three-slot cap gets spent on one answer.
+ """
+ from repowise.server.mcp_server import get_why
+
+ for n in range(5):
+ await _seed(
+ session,
+ setup_mcp,
+ id_=f"restate{n}",
+ title=f"Zebrafish caching, phrasing {n}",
+ commits=["deadbeef"],
+ confidence=0.9 - n / 100,
+ )
+
+ result = await get_why("why the zebrafish caching phrasing")
+ served = [d for d in result["decisions"] if d["id"].startswith("restate")]
+
+ assert len(served) == 1, f"expected one record, got {[d['id'] for d in served]}"
+ # The folded ids stay addressable rather than vanishing.
+ assert sorted(served[0]["restates"]) == [f"restate{n}" for n in range(1, 5)]
+
+
+async def test_search_keeps_records_citing_different_commits_apart(session, setup_mcp):
+ """The key is the cited evidence, so two real decisions must not merge."""
+ from repowise.server.mcp_server import get_why
+
+ await _seed(session, setup_mcp, id_="ev1", title="Zebrafish caching one", commits=["aaa"])
+ await _seed(session, setup_mcp, id_="ev2", title="Zebrafish caching two", commits=["bbb"])
+
+ result = await get_why("why zebrafish caching")
+ served = {d["id"] for d in result["decisions"]}
+
+ assert {"ev1", "ev2"} <= served
+
+
+async def test_search_caps_full_bodies(session, setup_mcp):
+ """Three whole records, not eight thinned ones."""
+ from repowise.server.mcp_server import get_why
+ from repowise.server.mcp_server.tool_why import _MAX_SEARCH_DECISIONS
+
+ for n in range(12):
+ await _seed(
+ session,
+ setup_mcp,
+ id_=f"many{n}",
+ title=f"Zebrafish caching decision {n}",
+ commits=[f"sha{n}"],
+ )
+
+ result = await get_why("why zebrafish caching decision")
+ bodies = [d for d in result["decisions"] if "decision" in d]
+
+ assert len(bodies) == _MAX_SEARCH_DECISIONS
+
+
+async def test_search_embeds_the_query_once(setup_mcp, monkeypatch):
+ """Two awaits embedded the same string back to back, one question, two trips."""
+ import repowise.server.mcp_server as mcp_mod
+ from repowise.server.mcp_server import get_why
+
+ vs = mcp_mod._vector_store
+ calls: list[str] = []
+
+ original = vs.embed_texts
+
+ async def _counting(texts):
+ calls.append("embed_texts")
+ return await original(texts)
+
+ async def _forbidden(query, limit=10):
+ calls.append(f"search:{query}")
+ return []
+
+ monkeypatch.setattr(vs, "embed_texts", _counting)
+ monkeypatch.setattr(vs, "search", _forbidden)
+
+ await get_why("why is JWT used for authentication")
+
+ # One embedding, and no fall-through to the text-embedding search path.
+ assert calls.count("embed_texts") == 1, calls
+ assert not [c for c in calls if c.startswith("search:")], calls
+
+
+async def test_related_documentation_excludes_decision_pages(setup_mcp):
+ """The doc lane took the nearest pages of any kind, decisions included.
+
+ So a decision record came back as "related documentation" beside the
+ decisions list it belonged in. One window, partitioned by namespace, gives
+ each lane only what is its own.
+ """
+ import repowise.server.mcp_server as mcp_mod
+ from repowise.core.analysis.decision_semantic_match import DECISION_VECTOR_PREFIX
+ from repowise.server.mcp_server import get_why
+
+ vs = mcp_mod._vector_store
+ await vs.embed_and_upsert(
+ f"{DECISION_VECTOR_PREFIX}dec-doc-lane",
+ "Zebrafish caching keeps latency down",
+ {
+ "title": "Zebrafish caching",
+ "page_type": "decision_record",
+ "target_path": "",
+ "content": "Zebrafish caching keeps latency down",
+ },
+ )
+
+ result = await get_why("why zebrafish caching keeps latency down")
+
+ assert all(
+ not r["page_id"].startswith(DECISION_VECTOR_PREFIX)
+ for r in result["related_documentation"]
+ ), result["related_documentation"]
+
+
+async def test_breadth_does_not_outscore_relevance(session, setup_mcp):
+ """A record's file list is a scope, not question text.
+
+ Joining 83 paths into one haystack and substring-matching a question against
+ it scored by breadth: ordinary query words occur somewhere in 83 paths, so
+ the widest record on the dogfooded repo led three of five probe questions,
+ including one about ruff that it has nothing to do with.
+ """
+ from repowise.server.mcp_server import get_why
+
+ await _seed(
+ session,
+ setup_mcp,
+ id_="broad",
+ title="Unrelated infrastructure change",
+ decision="unrelated",
+ rationale="unrelated",
+ context="unrelated",
+ files=[f"src/zebrafish/caching/mod{n}.py" for n in range(83)],
+ )
+ await _seed(
+ session,
+ setup_mcp,
+ id_="narrow",
+ title="Zebrafish caching strategy",
+ decision="Use zebrafish caching",
+ rationale="zebrafish caching is faster",
+ files=["src/one.py"],
+ )
+
+ result = await get_why("why zebrafish caching")
+ ids = [d["id"] for d in result["decisions"]]
+
+ # The wide record matches the question on nothing but its file paths, so it
+ # now scores zero and is not a candidate at all.
+ assert "narrow" in ids, ids
+ assert "broad" not in ids, ids
+
+
+async def test_status_breaks_ties_without_gating(session, setup_mcp):
+ """Confirmed wins a tie; it does not outrank a better match.
+
+ Ordering by status first was tried and measured worse: only 69 of the
+ dogfooded repo's 614 records are active, so a hard gate served three weakly
+ matching confirmed records ahead of the only relevant ones. The four records
+ answering one probe question are all proposed.
+ """
+ from repowise.server.mcp_server import get_why
+
+ await _seed(
+ session,
+ setup_mcp,
+ id_="weak-active",
+ status="active",
+ title="Zebrafish unrelated",
+ decision="unrelated",
+ rationale="unrelated",
+ context="unrelated",
+ commits=["aaa"],
+ )
+ await _seed(
+ session,
+ setup_mcp,
+ id_="strong-proposed",
+ status="proposed",
+ title="Zebrafish caching strategy chosen",
+ decision="Zebrafish caching strategy chosen",
+ rationale="zebrafish caching strategy",
+ context="zebrafish caching",
+ commits=["bbb"],
+ )
+
+ result = await get_why("why zebrafish caching strategy")
+ ids = [d["id"] for d in result["decisions"]]
+
+ assert ids.index("strong-proposed") < ids.index("weak-active"), ids