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.

fix(answer): keep decision vectors and pageless ids out of the answer (#1183)

Swati Ahujafc9588144d1b
diff --git a/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py b/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py
index 5e464ab4a..fa80bf057 100644
--- a/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py
+++ b/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py
@@ -44,6 +44,7 @@ from typing import Any
from sqlalchemy import select
+from repowise.core.analysis.decisions.semantic_match import DECISION_VECTOR_PREFIX
from repowise.core.persistence.database import get_session
from repowise.core.persistence.models import GraphEdge, GraphNode, Page
from repowise.core.test_paths import is_test_path
@@ -55,6 +56,19 @@ _log = logging.getLogger("repowise.mcp.answer")
# resolve ties without dragging weak tail hits into the merge.
_RETRIEVAL_FETCH_LIMIT = 15
+# Page-id namespace decision vectors live under in the shared page store. Read
+# from the module that writes them so the two cannot drift apart.
+_DECISION_PREFIX = DECISION_VECTOR_PREFIX
+
+# Decision records share the page vector store under this page-id namespace, so
+# a page fetch has to ask for more rows than it needs and drop them. Over-fetch
+# rather than post-filter a fixed window: a query whose nearest neighbours are
+# all decisions would otherwise return a candidate set short by however many
+# happened to rank high, which reads downstream as thin retrieval rather than as
+# a filtered one. The margin is generous because decision rows cluster on the
+# question-shaped text that also retrieves well.
+_DECISION_OVERFETCH = 15
+
# RRF constant. The standard k=60 from the original RRF paper — large enough
# that rank-1 (1/61) and rank-2 (1/62) are close, small enough that rank-10
# (1/70) still contributes meaningfully when a hit only shows up in one mode.
@@ -236,6 +250,43 @@ async def _safe_fts_search(ctx: Any, question: str) -> list[Any]:
return []
+def _pages_only(results: list[Any], limit: int) -> list[Any]:
+ """Best-first *results* with decision vectors removed, capped at *limit*.
+
+ Decision records live in the page store under their own page-id namespace so
+ dedup can match a paraphrase and ``search_codebase`` can surface a decision
+ directly. Neither is true of answering: a decision row has no ``wiki_pages``
+ row, so hydration leaves it pathless — and a pathless hit skips the tombstone
+ check and the scope filter, can only be reordered by noise demotion rather
+ than dropped, and cannot be cited by the answer it helped write.
+
+ A why-shaped question still gets its decisions. They are injected from a
+ path-overlap query over ``decision_records``, which does not involve this
+ store at all.
+ """
+ kept = [r for r in results if not str(getattr(r, "page_id", "")).startswith(_DECISION_PREFIX)]
+ dropped = len(results) - len(kept)
+ if dropped:
+ _log.debug(
+ "get_answer page retrieval dropped %d decision vector(s) from a window of %d",
+ dropped,
+ len(results),
+ )
+ if len(kept) < limit and dropped:
+ # The over-fetch margin was not enough. Reported because the visible
+ # symptom is a short candidate set, which otherwise reads as a corpus
+ # too small or a query too narrow.
+ _log.warning(
+ "get_answer page retrieval kept only %d of a requested %d candidates: %d "
+ "decision vector(s) filled the window. Decisions may be over-represented "
+ "in the vector store.",
+ len(kept),
+ limit,
+ dropped,
+ )
+ return kept[:limit]
+
+
async def _safe_vector_search(ctx: Any, question: str) -> list[Any]:
"""Vector search wrapped in timeout + suppression. Returns [] on any failure.
@@ -252,12 +303,18 @@ async def _safe_vector_search(ctx: Any, question: str) -> list[Any]:
# to need the vector, and every later stage reads the same one back.
vector = await question_vector(ctx, question)
try:
- return await asyncio.wait_for(
- vector_search(ctx.vector_store, question, _RETRIEVAL_FETCH_LIMIT, vector=vector),
+ results = await asyncio.wait_for(
+ vector_search(
+ ctx.vector_store,
+ question,
+ _RETRIEVAL_FETCH_LIMIT + _DECISION_OVERFETCH,
+ vector=vector,
+ ),
timeout=8.0,
)
except Exception:
return []
+ return _pages_only(results, _RETRIEVAL_FETCH_LIMIT)
def _hit_dict_from_result(result: Any) -> dict:
@@ -352,8 +409,18 @@ async def hydrate_hits(hits: list[dict], ctx: Any, *, scope: str | None = None)
}
out: list[dict] = []
+ pageless = 0
for h in hits:
- meta = meta_by_id.get(h["page_id"], {})
+ meta = meta_by_id.get(h["page_id"])
+ if meta is None:
+ # A retrieved id with no page behind it: a decision vector, or a
+ # vector left over from a page the stores have since disagreed
+ # about. Either way there is nothing to cite and nothing to read,
+ # and keeping it costs a served slot — while every later gate that
+ # would have caught it (tombstone, scope) is keyed on a path it
+ # does not have.
+ pageless += 1
+ continue
# Tombstoned pages document deleted/renamed files — serving them as
# answer material would cite code that no longer exists.
if meta.get("freshness") == "tombstone":
@@ -367,6 +434,14 @@ async def hydrate_hits(hits: list[dict], ctx: Any, *, scope: str | None = None)
# of truth; retrievers sometimes carry stale or empty types.
h["page_type"] = meta.get("page_type") or h.get("page_type", "")
out.append(h)
+ if pageless:
+ _log.warning(
+ "get_answer dropped %d of %d retrieved hit(s) with no page row behind them; "
+ "an id in a retriever that the page table does not know is either a "
+ "non-page vector or a three-store disagreement (repowise doctor --repair)",
+ pageless,
+ len(hits),
+ )
return out
diff --git a/tests/unit/server/mcp/test_answer_decision_rows.py b/tests/unit/server/mcp/test_answer_decision_rows.py
new file mode 100644
index 000000000..8516fd33b
--- /dev/null
+++ b/tests/unit/server/mcp/test_answer_decision_rows.py
@@ -0,0 +1,195 @@
+"""Decision vectors are not page-search candidates, and a hit with no page is not a hit.
+
+Decision records are embedded into the same vector store as wiki pages, under a
+``decision:`` page-id namespace. That is deliberate — it is how dedup finds a
+paraphrase and how a "why Redis?" search surfaces the decision itself. What was
+not deliberate is that ``get_answer``'s page retrieval had no way to say "pages
+only", so decision rows competed for its fixed fetch window.
+
+Those rows are worse than irrelevant. They have no ``wiki_pages`` row, so
+hydration gives them no ``target_path`` — and with no path the tombstone check
+cannot fire, the ``scope`` filter is skipped, and noise demotion can only
+reorder them, never drop them. A decision row could hold a top-5 slot, reach
+the synthesis prompt, and produce no citation for the answer built on it.
+
+Decisions still reach a why-shaped answer: they come from a path-overlap SQL
+query over ``decision_records``, not from vector search, which the last test
+here pins.
+"""
+
+from __future__ import annotations
+
+import logging
+from types import SimpleNamespace
+
+import pytest
+
+from repowise.core.analysis.decisions.semantic_match import (
+ DECISION_PAGE_TYPE,
+ DECISION_VECTOR_PREFIX,
+)
+from repowise.core.persistence.search import SearchResult
+from repowise.core.persistence.vector_store import InMemoryVectorStore
+from repowise.core.providers.embedding.base import MockEmbedder
+from repowise.server.mcp_server import _answer_pipeline as pipeline
+
+_QUESTION = "how does the answer cache decide to invalidate an entry"
+
+
+def _decision_row(i: int) -> SearchResult:
+ return SearchResult(
+ page_id=f"{DECISION_VECTOR_PREFIX}dec{i}",
+ title=f"Decision {i}",
+ page_type=DECISION_PAGE_TYPE,
+ target_path="", # decision vectors have no page row, hence no path
+ score=0.9,
+ snippet="",
+ search_type="vector",
+ )
+
+
+def _page_row(i: int) -> SearchResult:
+ return SearchResult(
+ page_id=f"file_page:pkg/alpha/{i}.py",
+ title=f"File: pkg/alpha/{i}.py",
+ page_type="file_page",
+ target_path=f"pkg/alpha/{i}.py",
+ score=0.5,
+ snippet="",
+ search_type="vector",
+ )
+
+
+class _ScriptedStore:
+ """Vector store that returns *n_decisions* decision rows ahead of pages.
+
+ Scripted rather than embedded because the point is the ordering: decision
+ rows outranking real pages is the case that emptied the window, and no
+ fixture embedder reproduces it on demand.
+ """
+
+ def __init__(self, n_decisions: int, n_pages: int = 40) -> None:
+ self._rows = [_decision_row(i) for i in range(n_decisions)] + [
+ _page_row(i) for i in range(n_pages)
+ ]
+ self.limits: list[int] = []
+
+ async def embed_texts(self, texts: list[str]) -> list[list[float]]:
+ return [[0.1, 0.2, 0.3] for _ in texts]
+
+ async def search_by_vector(self, vector, limit: int = 10) -> list[SearchResult]:
+ self.limits.append(limit)
+ return self._rows[:limit]
+
+ async def search(self, query: str, limit: int = 10) -> list[SearchResult]:
+ self.limits.append(limit)
+ return self._rows[:limit]
+
+
[email protected](autouse=True)
+def _clear_vector_cache():
+ cache = getattr(pipeline, "_QUESTION_VECTORS", None)
+ if cache is not None:
+ cache.clear()
+ yield
+ if cache is not None:
+ cache.clear()
+
+
+async def test_page_retrieval_returns_no_decision_rows():
+ store = _ScriptedStore(n_decisions=5)
+ ctx = SimpleNamespace(fts=None, vector_store=store)
+
+ hits = await pipeline.hybrid_retrieve(_QUESTION, ctx)
+
+ assert hits, "the fetch must still return pages"
+ assert not [h for h in hits if h["page_id"].startswith(DECISION_VECTOR_PREFIX)]
+
+
+async def test_dropped_decision_rows_are_counted(caplog):
+ """Silently dropping them would hide both a regression here and a store
+ filling up with decisions."""
+ store = _ScriptedStore(n_decisions=5)
+ ctx = SimpleNamespace(fts=None, vector_store=store)
+
+ with caplog.at_level(logging.DEBUG, logger="repowise.mcp.answer"):
+ await pipeline.hybrid_retrieve(_QUESTION, ctx)
+
+ assert any(
+ "5" in r.getMessage() and "decision" in r.getMessage().lower() for r in caplog.records
+ ), caplog.text
+
+
+async def test_the_window_still_fills_with_real_pages_when_decisions_crowd_it():
+ """The regression this must not become: filtering after a fixed-size fetch
+ would return 15 minus however many decisions happened to rank high."""
+ store = _ScriptedStore(n_decisions=pipeline._RETRIEVAL_FETCH_LIMIT)
+ ctx = SimpleNamespace(fts=None, vector_store=store)
+
+ hits = await pipeline.hybrid_retrieve(_QUESTION, ctx)
+
+ assert len(hits) == pipeline._RETRIEVAL_FETCH_LIMIT
+ assert store.limits[0] > pipeline._RETRIEVAL_FETCH_LIMIT, (
+ "the fetch must ask for more than it needs, or crowding empties the window"
+ )
+
+
+async def test_a_window_that_stays_short_is_reported(caplog):
+ """More decisions than the over-fetch covers is a store shape worth seeing,
+ not a quietly thin candidate set."""
+ store = _ScriptedStore(n_decisions=500, n_pages=0)
+ ctx = SimpleNamespace(fts=None, vector_store=store)
+
+ with caplog.at_level(logging.DEBUG, logger="repowise.mcp.answer"):
+ hits = await pipeline.hybrid_retrieve(_QUESTION, ctx)
+
+ assert hits == []
+ assert any("decision" in r.getMessage().lower() for r in caplog.records)
+
+
+async def test_hydration_drops_a_hit_with_no_page_row_and_counts_it(factory, populated_db, caplog):
+ """Any pathless hit, whatever its source: with no page row behind it the
+ answer cannot cite it and the tombstone check never runs."""
+ ctx = SimpleNamespace(session_factory=factory)
+ hits = [
+ {"page_id": "repo_overview:test-repo", "score": 1.0, "_sources": {"fts"}},
+ {"page_id": "file_page:this/page/does/not/exist.py", "score": 0.9, "_sources": {"fts"}},
+ ]
+
+ with caplog.at_level(logging.DEBUG, logger="repowise.mcp.answer"):
+ out = await pipeline.hydrate_hits(hits, ctx)
+
+ assert [h["page_id"] for h in out] == ["repo_overview:test-repo"]
+ assert any("no page row" in r.getMessage().lower() for r in caplog.records), caplog.text
+
+
+async def test_decision_dedup_still_finds_decision_vectors():
+ """The filter belongs to page retrieval alone — dedup queries the same store
+ for exactly these rows and must keep getting them."""
+ from repowise.core.analysis.decisions.semantic_match import (
+ SEARCH_FETCH,
+ nearest_decision_hit,
+ upsert_decision_vector,
+ )
+
+ store = InMemoryVectorStore(embedder=MockEmbedder())
+ await upsert_decision_vector(store, "dec1", title="Cache answers by question hash")
+
+ results = await store.search("Cache answers by question hash", limit=SEARCH_FETCH)
+ hit = nearest_decision_hit(results)
+
+ assert hit is not None and hit[0] == "dec1"
+
+
+async def test_why_answers_read_decisions_from_the_database_not_the_vector_store(
+ factory, populated_db
+):
+ """What makes dropping decision vectors safe: the decisions a why-shaped
+ answer injects come from a path-overlap query, with no vector store in play."""
+ from repowise.server.mcp_server._answer_context import fetch_relevant_decisions
+
+ ctx = SimpleNamespace(session_factory=factory, vector_store=None)
+
+ decisions = await fetch_relevant_decisions(ctx, populated_db, ["src/auth/service.py"])
+
+ assert decisions, "a why answer must still be able to reach its decisions"