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(search): stop ranking on a keyless index's own vectors (#1378)

Raghav Chamadiyabb4ccbc06827
diff --git a/packages/cli/src/repowise/cli/providers/embedders.py b/packages/cli/src/repowise/cli/providers/embedders.py
index f61d59a34..179e040f9 100644
--- a/packages/cli/src/repowise/cli/providers/embedders.py
+++ b/packages/cli/src/repowise/cli/providers/embedders.py
@@ -133,12 +133,12 @@ def build_embedder(embedder_name_resolved: str) -> Any:
the same backend selection logic isn't duplicated. Real providers fall
back to the deterministic mock when their SDK/credentials are unavailable.
"""
- from repowise.core.providers.embedding.base import MockEmbedder
+ from repowise.core.providers.embedding.base import KeylessEmbedder
from repowise.core.providers.embedding.registry import get_embedder
if embedder_name_resolved == "mock":
- return MockEmbedder()
+ return KeylessEmbedder()
try:
return get_embedder(embedder_name_resolved, **_embedder_kwargs(embedder_name_resolved))
except Exception:
- return MockEmbedder()
+ return KeylessEmbedder()
diff --git a/packages/core/src/repowise/core/analysis/decisions/semantic_match.py b/packages/core/src/repowise/core/analysis/decisions/semantic_match.py
index 87b97789b..f75a2cd34 100644
--- a/packages/core/src/repowise/core/analysis/decisions/semantic_match.py
+++ b/packages/core/src/repowise/core/analysis/decisions/semantic_match.py
@@ -27,6 +27,8 @@ from __future__ import annotations
import contextlib
from typing import Any
+from repowise.core.providers.embedding.base import store_has_semantic_vectors
+
__all__ = [
"DECISION_PAGE_TYPE",
"DECISION_VECTOR_PREFIX",
@@ -238,7 +240,14 @@ async def find_duplicate_decision_by_vector(
than the store's stale row. Same policy as the text twin: the overall
nearest decision decides, thresholded at *tau*; store errors degrade to
the pending-only comparison.
+
+ Returns None on a keyless store, without consulting *pending* either: the
+ pending index holds vectors from that same embedder, so it cannot separate
+ a duplicate from an unrelated record any better than the store can. See
+ :func:`store_has_semantic_vectors`.
"""
+ if not store_has_semantic_vectors(store):
+ return None
best: tuple[str, float] | None = None
try:
results = await store.search_by_vector(vector, limit=SEARCH_FETCH)
@@ -339,9 +348,11 @@ async def find_duplicate_decision(
Queries the shared store, filters hits to the ``decision:`` namespace
(dropping any in *exclude_ids*), and returns the nearest one whose cosine
- similarity is ≥ *tau* — or None when nothing clears the bar. Store errors
- degrade to None (title dedup still applied upstream).
+ similarity is ≥ *tau* — or None when nothing clears the bar. Store errors,
+ and a keyless store, degrade to None (title dedup still applied upstream).
"""
+ if not store_has_semantic_vectors(store):
+ return None
query = decision_match_text(title, decision)
if not query:
return None
@@ -377,9 +388,11 @@ async def find_related_decisions(
whose cosine similarity sits in the band ``[lo, hi)`` — high enough to be
the same topic, but (by default) *below* the dedup threshold so they were
not collapsed into one record. Those are exactly the candidates that might
- contradict / supersede each other. Ordered best-first; store errors degrade
- to an empty list.
+ contradict / supersede each other. Ordered best-first; store errors, and a
+ keyless store, degrade to an empty list.
"""
+ if not store_has_semantic_vectors(store):
+ return []
query = decision_match_text(title, decision)
if not query:
return []
@@ -428,11 +441,13 @@ async def find_related_decisions_many(
*items* is ``(title, decision, exclude_ids)`` per query; the result list
is aligned by index. Uses the store's ``search_many`` so every query is
embedded in a single embedder call — the per-query network round-trip is
- what made the supersession pass scale with decision count. Store errors
- degrade to empty lists, matching the per-item helper.
+ what made the supersession pass scale with decision count. Store errors,
+ and a keyless store, degrade to empty lists, matching the per-item helper.
"""
if not items:
return []
+ if not store_has_semantic_vectors(store):
+ return [[] for _ in items]
queries = [decision_match_text(title, decision) for title, decision, _ in items]
try:
# Empty query texts still occupy their slot (keeps results aligned)
diff --git a/packages/core/src/repowise/core/persistence/crud/decisions.py b/packages/core/src/repowise/core/persistence/crud/decisions.py
index 5c30e977d..9c3d4666b 100644
--- a/packages/core/src/repowise/core/persistence/crud/decisions.py
+++ b/packages/core/src/repowise/core/persistence/crud/decisions.py
@@ -775,6 +775,7 @@ async def bulk_upsert_decisions(
upsert_decision_vectors,
)
from repowise.core.persistence.vector_store import VectorStore
+ from repowise.core.providers.embedding import store_has_semantic_vectors
# Static capability check: the base-class search_by_vector is the
# "unsupported" sentinel. A runtime probe would conflate a transient
@@ -782,7 +783,12 @@ async def bulk_upsert_decisions(
# O(N)-round-trip path this branch exists to avoid.
store_cls_search = getattr(type(vector_store), "search_by_vector", None)
supports_vector_search = (
- callable(store_cls_search) and store_cls_search is not VectorStore.search_by_vector
+ callable(store_cls_search)
+ and store_cls_search is not VectorStore.search_by_vector
+ # A keyless store supports the call and cannot answer it: every
+ # matcher below refuses on it. Without this the batch pays for a
+ # full embed round whose vectors are then never read.
+ and store_has_semantic_vectors(vector_store)
)
ordered = [
diff --git a/packages/core/src/repowise/core/pipeline/phases/generation.py b/packages/core/src/repowise/core/pipeline/phases/generation.py
index c073c1588..0d6cc9e5e 100644
--- a/packages/core/src/repowise/core/pipeline/phases/generation.py
+++ b/packages/core/src/repowise/core/pipeline/phases/generation.py
@@ -68,7 +68,7 @@ async def run_generation(
PageGenerator,
)
from repowise.core.persistence.vector_store import InMemoryVectorStore
- from repowise.core.providers.embedding.base import MockEmbedder
+ from repowise.core.providers.embedding.base import KeylessEmbedder
# Attach cost tracker to LLM client if available
if cost_tracker is not None and llm_client is not None and hasattr(llm_client, "_cost_tracker"):
@@ -84,7 +84,7 @@ async def run_generation(
assembler = ContextAssembler(config)
# Resolve embedder and vector store
- embedder_impl = embedder if embedder is not None else MockEmbedder()
+ embedder_impl = embedder if embedder is not None else KeylessEmbedder()
if vector_store is None:
vector_store = InMemoryVectorStore(embedder_impl)
diff --git a/packages/core/src/repowise/core/providers/embedding/__init__.py b/packages/core/src/repowise/core/providers/embedding/__init__.py
index d1d77770a..db0cf6d67 100644
--- a/packages/core/src/repowise/core/providers/embedding/__init__.py
+++ b/packages/core/src/repowise/core/providers/embedding/__init__.py
@@ -11,10 +11,16 @@ registry to instantiate an embedder by name.
Built-in embedders:
openai — text-embedding-3-small (1536d), text-embedding-3-large (3072d)
gemini — gemini-embedding-001 (768d, up to 3072d)
- mock — deterministic 8d vectors (zero deps, testing only)
+ mock — KeylessEmbedder: what a no-key index embeds with (zero deps)
"""
-from repowise.core.providers.embedding.base import Embedder, MockEmbedder
+from repowise.core.providers.embedding.base import (
+ Embedder,
+ KeylessEmbedder,
+ MockEmbedder,
+ is_semantic_embedder,
+ store_has_semantic_vectors,
+)
from repowise.core.providers.embedding.registry import (
get_embedder,
list_embedders,
@@ -23,8 +29,11 @@ from repowise.core.providers.embedding.registry import (
__all__ = [
"Embedder",
+ "KeylessEmbedder",
"MockEmbedder",
"get_embedder",
+ "is_semantic_embedder",
"list_embedders",
"register_embedder",
+ "store_has_semantic_vectors",
]
diff --git a/packages/core/src/repowise/core/providers/embedding/base.py b/packages/core/src/repowise/core/providers/embedding/base.py
index fcfddc294..eea245f4d 100644
--- a/packages/core/src/repowise/core/providers/embedding/base.py
+++ b/packages/core/src/repowise/core/providers/embedding/base.py
@@ -71,3 +71,67 @@ class MockEmbedder:
norm = 1.0
results.append([x / norm for x in raw])
return results
+
+
+class KeylessEmbedder(MockEmbedder):
+ """What an index built without an API key embeds with.
+
+ Identical arithmetic to :class:`MockEmbedder`, and a separate type on
+ purpose. The two produce the same vectors and mean opposite things:
+
+ - In a **test**, ``MockEmbedder`` stands in for a real embedder. The suite
+ wants the vector leg to run, and controls what comes back by seeding the
+ store or scripting ``search``, so the vectors themselves are incidental.
+ - In **production**, this class is what you get when nobody supplied a key.
+ Its vectors are the only ones there are, they carry no signal, and the
+ vector leg must therefore not run at all.
+
+ One class cannot be told apart at the point that decision is made, which is
+ the whole reason this one exists. Nothing else differs, and subclassing
+ keeps ``isinstance(x, MockEmbedder)`` true for the width and dimension
+ checks that already depend on it.
+
+ Why the vectors carry no signal: every component is non-negative, so they
+ all lie in the positive orthant of an 8-dimensional space and no two can
+ point meaningfully different ways. Measured over 2,000 texts, two
+ *unrelated* strings score 0.750 cosine on average, never below 0.207, and
+ the nearest neighbours of any query sit at 0.926-0.962. They are distinct,
+ which is what the base class promises; they are not discriminative, which
+ is what a retriever needs.
+ """
+
+
+def is_semantic_embedder(embedder: object) -> bool:
+ """Whether *embedder* produces vectors worth ranking on.
+
+ False for :class:`KeylessEmbedder` and for nothing else. **Deliberately
+ fails open**: anything unrecognised, including ``None``, counts as semantic.
+
+ The asymmetry is the point. This predicate exists to switch off a leg that
+ is actively harmful in one identifiable configuration, so it should refuse
+ only what it can positively identify. Failing closed would mean any store
+ this cannot introspect loses semantic search with no error and no log line,
+ which is a far worse failure than the one being fixed: it would hit custom
+ and out-of-tree stores that hold a perfectly good embedder somewhere other
+ than the attribute below.
+ """
+ return not isinstance(embedder, KeylessEmbedder)
+
+
+def store_has_semantic_vectors(store: object) -> bool:
+ """Whether *store*'s vectors carry signal, i.e. whether to run its vector leg.
+
+ Reads the embedder off the store rather than off any module-level server
+ state, because workspace mode builds one context per repo through its own
+ registry and factory (``core/workspace/registry.py``), so there is no single
+ global that describes them all.
+
+ Every concrete store takes an embedder as a required constructor argument
+ and keeps it on ``_embedder``, so in this repo the attribute is always
+ there. A store without one still returns True, per the fail-open rule in
+ :func:`is_semantic_embedder`; only ``None`` is False, and that means "no
+ store", not "a store that cannot rank".
+ """
+ if store is None:
+ return False
+ return is_semantic_embedder(getattr(store, "_embedder", None))
diff --git a/packages/core/src/repowise/core/providers/embedding/registry.py b/packages/core/src/repowise/core/providers/embedding/registry.py
index e74b1ddde..3e154b162 100644
--- a/packages/core/src/repowise/core/providers/embedding/registry.py
+++ b/packages/core/src/repowise/core/providers/embedding/registry.py
@@ -28,7 +28,7 @@ _BUILTIN_EMBEDDERS: dict[str, tuple[str, str]] = {
"gemini": ("repowise.core.providers.embedding.gemini", "GeminiEmbedder"),
"ollama": ("repowise.core.providers.embedding.ollama", "OllamaEmbedder"),
"openrouter": ("repowise.core.providers.embedding.openrouter", "OpenRouterEmbedder"),
- "mock": ("repowise.core.providers.embedding.base", "MockEmbedder"),
+ "mock": ("repowise.core.providers.embedding.base", "KeylessEmbedder"),
}
_custom_embedders: dict[str, Callable[..., Embedder]] = {}
diff --git a/packages/core/src/repowise/core/workspace/registry.py b/packages/core/src/repowise/core/workspace/registry.py
index 481539ea2..a613beea9 100644
--- a/packages/core/src/repowise/core/workspace/registry.py
+++ b/packages/core/src/repowise/core/workspace/registry.py
@@ -169,7 +169,7 @@ class RepoRegistry:
)
from repowise.core.persistence.search import FullTextSearch
from repowise.core.persistence.vector_store import InMemoryVectorStore
- from repowise.core.providers.embedding.base import MockEmbedder
+ from repowise.core.providers.embedding.base import KeylessEmbedder
db_url = get_db_url(f"sqlite:///{db_path.as_posix()}")
@@ -188,7 +188,7 @@ class RepoRegistry:
# Seed placeholder vector stores.
# decision_store is repointed to the shared page store — decisions are
# embedded under the "decision:" namespace, no separate LanceDB table.
- embedder = self._embedder_factory() if self._embedder_factory else MockEmbedder()
+ embedder = self._embedder_factory() if self._embedder_factory else KeylessEmbedder()
vector_store: Any = InMemoryVectorStore(embedder=embedder)
vs_ready = asyncio.Event()
diff --git a/packages/server/src/repowise/server/app.py b/packages/server/src/repowise/server/app.py
index 891d2c316..037ac7f4a 100644
--- a/packages/server/src/repowise/server/app.py
+++ b/packages/server/src/repowise/server/app.py
@@ -27,7 +27,7 @@ from repowise.core.persistence.database import (
)
from repowise.core.persistence.models import GenerationJob
from repowise.core.persistence.search import FullTextSearch
-from repowise.core.providers.embedding.base import MockEmbedder
+from repowise.core.providers.embedding.base import KeylessEmbedder
from repowise.server import __version__
from repowise.server.routers import (
blast_radius,
@@ -124,7 +124,7 @@ def _build_embedder():
logger.warning(
"embedder.mock_active: set REPOWISE_EMBEDDER=gemini, openai, openrouter, or ollama for real RAG"
)
- return MockEmbedder()
+ return KeylessEmbedder()
@asynccontextmanager
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 917a89f9d..a6863b1e6 100644
--- a/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py
+++ b/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py
@@ -53,6 +53,7 @@ from sqlalchemy import func, 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.providers.embedding import store_has_semantic_vectors
from repowise.core.test_paths import is_test_path
from repowise.server.mcp_server._prose_symbols import symbol_backed_pages
@@ -173,8 +174,15 @@ def retrieval_legs() -> dict[str, str]:
def degraded_legs(legs: dict[str, str]) -> list[str]:
- """The legs that did not run, named. Empty when retrieval was whole."""
- return sorted(leg for leg, outcome in legs.items() if outcome != "ok")
+ """The legs that *broke*, named. Empty when retrieval was whole.
+
+ ``keyless`` is not degradation and is deliberately excluded. A keyless index
+ has no semantic vectors by construction, so its vector leg is permanently
+ absent rather than transiently broken, and naming it here would put a
+ failure marker on every answer the mode ever produces. The configuration
+ itself is reported once per response by ``_meta`` instead.
+ """
+ return sorted(leg for leg, outcome in legs.items() if outcome not in ("ok", "keyless"))
# Third retrieval leg: the structural symbol index. FTS and the vector store
# both read the generated wiki page, which by construction carries an overview
@@ -232,6 +240,9 @@ async def question_vector(ctx: Any, question: str) -> list[float] | None:
store = getattr(ctx, "vector_store", None)
if store is None or not question:
return None
+ if not store_has_semantic_vectors(store):
+ # Nothing will consume it, so do not pay to compute it.
+ return None
key = (id(store), question)
cached = _QUESTION_VECTORS.get(key)
@@ -282,7 +293,14 @@ async def vector_search(
Every backend that can search by raw vector is spared a second embedding of
text it has already embedded; one that cannot returns None from
``search_by_vector`` and is asked to search the text as before.
+
+ Returns nothing on a keyless store. Guarded here rather than only at the
+ callers because this is the shared floor under every vector read in the
+ answer pipeline, and the text fallback on the last line would otherwise
+ route a keyless store straight back into the embedder this is avoiding.
"""
+ if not store_has_semantic_vectors(store):
+ return []
if vector is not None:
by_vector = await store.search_by_vector(vector, limit=limit)
if by_vector is not None:
@@ -413,10 +431,19 @@ async def _safe_vector_search(ctx: Any, question: str) -> list[Any]:
Also waits for vector-store readiness when the lifespan event is set —
skipping the wait would race a background-loading store on cold start.
+
+ Returns nothing on a keyless index, before the readiness wait and before the
+ question is embedded: there is no vector worth computing when there is
+ nothing discriminative to compare it against. See
+ ``store_has_semantic_vectors``. This leg is the only entry to vector
+ retrieval here, so guarding it covers every caller.
"""
if ctx.vector_store is None:
_record_leg("vector", "absent")
return []
+ if not store_has_semantic_vectors(ctx.vector_store):
+ _record_leg("vector", "keyless")
+ return []
ready = getattr(ctx, "vector_store_ready", None)
if ready is not None:
with contextlib.suppress(TimeoutError):
diff --git a/packages/server/src/repowise/server/mcp_server/_meta.py b/packages/server/src/repowise/server/mcp_server/_meta.py
index 72224fe5b..13d6f0623 100644
--- a/packages/server/src/repowise/server/mcp_server/_meta.py
+++ b/packages/server/src/repowise/server/mcp_server/_meta.py
@@ -337,17 +337,28 @@ def _embedder_meta() -> dict[str, Any]:
agent can detect — programmatically — that semantic search is broken instead
of trusting empty/garbage retrieval. Emits nothing when the embedder is
healthy or unresolved, so healthy responses stay clean.
+
+ A *keyless* index is a different state and gets a different field. Nothing
+ is broken and nothing was misconfigured, so it is not flagged as degraded;
+ but retrieval really is full-text-only, and a caller that assumes semantic
+ matching is running will misread a lexical miss as "not in the codebase".
+ ``semantic_search: false`` says so once per response without crying wolf.
"""
# Lazy import: `_state` is a sibling module; importing it at call-time keeps
# `_meta` free of any package import-ordering coupling.
from repowise.server.mcp_server import _state
status = getattr(_state, "_embedder_status", None)
- if not status or not status.get("degraded"):
+ if not status:
+ return {}
+ if not status.get("degraded"):
+ if status.get("active") == "mock":
+ return {"embedder": "mock", "semantic_search": False}
return {}
out: dict[str, Any] = {
"embedder": status.get("active", "mock"),
"embedder_degraded": True,
+ "semantic_search": False,
}
reason = status.get("reason")
if reason:
diff --git a/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py b/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py
index f7b712962..f8ebab0e5 100644
--- a/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py
+++ b/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py
@@ -36,6 +36,7 @@ from typing import Any
from sqlalchemy import select
from repowise.core.persistence.models import Page
+from repowise.core.providers.embedding import store_has_semantic_vectors
from repowise.server.mcp_server._answer_pipeline import question_vector, vector_search
from repowise.server.mcp_server._flow_path import _is_plumbing, _load_file_adjacency
@@ -165,6 +166,12 @@ async def _relevance_order(
"""
if searcher is None or not pool:
return []
+ # Checked here and not only inside ``vector_search``: on a keyless index
+ # ``question_vector`` returns None, which routes to the ``else`` arm below
+ # and would reach the store directly, re-embedding the question on the way
+ # to vectors that cannot rank. The guard has to sit above the branch.
+ if not store_has_semantic_vectors(searcher):
+ return []
try:
if vector is not None:
results = await vector_search(searcher, question, _RANK_SCAN, vector=vector)
diff --git a/packages/server/src/repowise/server/mcp_server/_server.py b/packages/server/src/repowise/server/mcp_server/_server.py
index cb381a170..dc638bda7 100644
--- a/packages/server/src/repowise/server/mcp_server/_server.py
+++ b/packages/server/src/repowise/server/mcp_server/_server.py
@@ -20,7 +20,7 @@ from repowise.core.persistence.database import (
)
from repowise.core.persistence.search import FullTextSearch
from repowise.core.persistence.vector_store import InMemoryVectorStore
-from repowise.core.providers.embedding.base import MockEmbedder
+from repowise.core.providers.embedding.base import KeylessEmbedder
from repowise.server.mcp_server import _state
_log = __import__("logging").getLogger("repowise.mcp")
@@ -195,7 +195,7 @@ def _resolve_embedder():
"requested": name or None,
"degraded": False,
}
- return MockEmbedder()
+ return KeylessEmbedder()
try:
embedder = get_embedder(name, **_embedder_kwargs(name))
@@ -219,7 +219,7 @@ def _resolve_embedder():
"degraded": True,
"reason": reason,
}
- return MockEmbedder()
+ return KeylessEmbedder()
async def _cancel_task(task: asyncio.Task) -> None:
@@ -304,7 +304,7 @@ async def _load_vector_stores(repo_path: str | None) -> None:
_state._decision_store = vector_store
except Exception:
_log.exception("Failed to load vector stores — falling back to MockEmbedder")
- _fallback = InMemoryVectorStore(embedder=MockEmbedder())
+ _fallback = InMemoryVectorStore(embedder=KeylessEmbedder())
_state._vector_store = _fallback
_state._decision_store = _fallback
finally:
@@ -491,7 +491,7 @@ async def _lifespan(server: FastMCP):
# Seed InMemory placeholder so tools that don't need vector search
# can start immediately, before the background load completes.
# decision_store is repointed to the same store — no separate table.
- _placeholder = InMemoryVectorStore(embedder=MockEmbedder())
+ _placeholder = InMemoryVectorStore(embedder=KeylessEmbedder())
_state._vector_store = _placeholder
_state._decision_store = _placeholder
diff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.py
index f5a8d59b7..9b5b9b6e3 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_search.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py
@@ -13,6 +13,7 @@ from repowise.core.persistence.models import (
GitMetadata,
Page,
)
+from repowise.core.providers.embedding import store_has_semantic_vectors
from repowise.core.registry import mcp_tool_registry as mcp
from repowise.core.test_paths import is_test_path, is_test_related_path
from repowise.server.mcp_server._answer_pipeline import _RRF_K, _RRF_SCORE_SCALE
@@ -273,11 +274,13 @@ async def _non_decision_fallback(ctx, query: str, fetch_limit: int) -> list[dict
"""
results = []
src = "vector"
- with contextlib.suppress(TimeoutError, Exception):
- results = await asyncio.wait_for(
- ctx.vector_store.search(query, limit=fetch_limit * 4),
- timeout=8.0,
- )
+ # Skipped on a keyless index, which then falls through to the FTS branch.
+ if store_has_semantic_vectors(ctx.vector_store):
+ with contextlib.suppress(TimeoutError, Exception):
+ results = await asyncio.wait_for(
+ ctx.vector_store.search(query, limit=fetch_limit * 4),
+ timeout=8.0,
+ )
if not results:
src = "fts"
with contextlib.suppress(Exception):
@@ -565,8 +568,13 @@ async def _safe_vector(ctx, query: str, limit: int) -> list:
Readiness is awaited by the caller (``_wait_for_vector_store``) before the
fused retrieve runs, so this path does not re-wait.
+
+ Returns nothing on a keyless index. ``store_has_semantic_vectors`` explains
+ why the mock's vectors cannot be ranked on; the reason this is enforced here
+ rather than in ``_fused_retrieve`` is that this function is the only place
+ the vector leg is entered, so a later caller inherits the guard.
"""
- if ctx.vector_store is None:
+ if ctx.vector_store is None or not store_has_semantic_vectors(ctx.vector_store):
return []
with contextlib.suppress(Exception):
return await asyncio.wait_for(ctx.vector_store.search(query, limit=limit), timeout=8.0)
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 a52372317..4e5235cb4 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_why.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_why.py
@@ -18,6 +18,7 @@ from repowise.core.persistence.models import (
GitMetadata,
)
from repowise.core.precedent.currency import describe_decision_currency
+from repowise.core.providers.embedding import store_has_semantic_vectors
from repowise.core.registry import mcp_tool_registry as mcp
from repowise.server.mcp_server._budget import OmissionCollector, effective_char_budget
from repowise.server.mcp_server._code_rationale import mine_rationale as _mine_rationale
@@ -511,10 +512,15 @@ def _rank_keyword_matches(all_decisions: list, query: str, target_set: set[str])
async def _semantic_decision_results(ctx: Any, query: str) -> list:
- """Semantic search of the page store, filtered to the decision: namespace."""
+ """Semantic search of the page store, filtered to the decision: namespace.
+
+ 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.
+ """
decision_results: list = []
with contextlib.suppress(Exception):
- if ctx.vector_store is not None:
+ 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)
@@ -523,11 +529,21 @@ async def _semantic_decision_results(ctx: Any, query: str) -> list:
async def _semantic_doc_results(ctx: Any, query: str) -> list:
- """Semantic search over documentation, falling back to FTS."""
+ """Semantic search over documentation, falling back to FTS.
+
+ 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.
+ """
+ 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: list = []
+ doc_results = []
with contextlib.suppress(Exception):
doc_results = await ctx.fts.search(query, limit=3)
return doc_results
diff --git a/packages/server/src/repowise/server/routers/search.py b/packages/server/src/repowise/server/routers/search.py
index ca07a7f15..d227a07f6 100644
--- a/packages/server/src/repowise/server/routers/search.py
+++ b/packages/server/src/repowise/server/routers/search.py
@@ -11,6 +11,7 @@ from pathlib import Path
from fastapi import APIRouter, Depends, Query, Request
+from repowise.core.providers.embedding import store_has_semantic_vectors
from repowise.server.deps import (
get_fts,
get_vector_store,
@@ -64,10 +65,19 @@ async def search(
- Workspace mode without ``repo_id``: fans out across every loaded
repo's index and merges results by score.
"""
- if search_type == "fulltext":
+ # A keyless index has no semantic vectors, so a semantic request is served
+ # lexically rather than refused. Returning nothing would read as "not in the
+ # codebase"; returning that store's nearest neighbours would be worse still,
+ # because on it they are noise. Full-text is what the mode actually offers,
+ # and what the docs already promise it offers.
+ if search_type == "fulltext" or not store_has_semantic_vectors(vector_store):
results = await _fulltext(request, query, limit, repo_id=repo_id, primary_fts=fts)
else:
results = await _semantic(request, query, limit, repo_id=repo_id, primary_vs=vector_store)
+ if results is None:
+ # The scoped repo turned out to be keyless even though the primary
+ # store is not. Serve it lexically, same as the whole-index case.
+ results = await _fulltext(request, query, limit, repo_id=repo_id, primary_fts=fts)
return [_to_response(r) for r in results]
@@ -127,9 +137,12 @@ async def _semantic(request: Request, query: str, limit: int, *, repo_id, primar
if repo_id.startswith("ws:"):
return []
vs = await resolve_repo_vector_store(request.app.state, repo_id)
- if vs is None:
- return await primary_vs.search(query, limit=limit)
- return await vs.search(query, limit=limit)
+ target = primary_vs if vs is None else vs
+ # None, not [], so the caller can serve this repo lexically. An empty
+ # list here would be indistinguishable from "nothing matched".
+ if not store_has_semantic_vectors(target):
+ return None
+ return await target.search(query, limit=limit)
if ws_config is None:
# Single-repo mode. Startup resolves the primary store from the same
@@ -170,7 +183,11 @@ async def _semantic(request: Request, query: str, limit: int, *, repo_id, primar
vs = await resolve_repo_vector_store(request.app.state, rid)
except Exception:
vs = None
- if vs is not None:
+ # A keyless repo is skipped here rather than searched, so it reaches the
+ # FTS fallback below. Its vector leg never returns empty (mock scores
+ # sit near 0.75 for anything), so without this the noise window would
+ # permanently suppress the fallback for that repo.
+ if vs is not None and store_has_semantic_vectors(vs):
try:
per_repo = await vs.search(query, limit=limit)
except Exception:
diff --git a/packages/server/src/repowise/server/search_helpers.py b/packages/server/src/repowise/server/search_helpers.py
index c97137b93..24dbdb153 100644
--- a/packages/server/src/repowise/server/search_helpers.py
+++ b/packages/server/src/repowise/server/search_helpers.py
@@ -166,9 +166,9 @@ def _resolve_embedder_from_state(app_state):
primary_vs = getattr(app_state, "vector_store", None)
embedder = getattr(primary_vs, "_embedder", None) if primary_vs else None
if embedder is None:
- from repowise.core.providers.embedding.base import MockEmbedder
+ from repowise.core.providers.embedding.base import KeylessEmbedder
- embedder = MockEmbedder()
+ embedder = KeylessEmbedder()
return embedder
diff --git a/tests/unit/server/mcp/test_keyless_vector_leg.py b/tests/unit/server/mcp/test_keyless_vector_leg.py
new file mode 100644
index 000000000..ea1711350
--- /dev/null
+++ b/tests/unit/server/mcp/test_keyless_vector_leg.py
@@ -0,0 +1,238 @@
+"""A keyless index must not rank on its own vectors.
+
+``MockEmbedder``'s components are every one non-negative, so all of its vectors
+live in the positive orthant of an 8-dimensional space and no two of them can
+point meaningfully different ways: two *unrelated* strings score ~0.75 cosine on
+average and never below ~0.21. They are distinct, which is what its test callers
+need, and not discriminative, which is what a retriever needs.
+
+Every documented description of the keyless mode says it is full-text-only
+(``docs/reference/CONFIG.md``, ``ui/mode_selection.py``, ``init_cmd/command.py``,
+``README.md``). These tests pin that.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import statistics
+from typing import ClassVar
+
+import pytest
+
+from repowise.core.analysis.decisions import semantic_match
+from repowise.core.persistence.vector_store.in_memory import InMemoryVectorStore
+from repowise.core.providers.embedding.base import (
+ KeylessEmbedder,
+ MockEmbedder,
+ is_semantic_embedder,
+ store_has_semantic_vectors,
+)
+from repowise.server.mcp_server import _answer_pipeline as pipeline
+from repowise.server.mcp_server import tool_search
+
+
+class _RealisticEmbedder:
+ """Stand-in for a real embedder: distinct texts get distinct directions."""
+
+ dimensions = 4
+
+ async def embed(self, texts: list[str]) -> list[list[float]]:
+ out = []
+ for text in texts:
+ raw = [float(text.count(c)) for c in "abcd"]
+ norm = math.sqrt(sum(x * x for x in raw)) or 1.0
+ out.append([x / norm for x in raw])
+ return out
+
+
+class _Ctx:
+ def __init__(self, store, fts=None):
+ self.vector_store = store
+ self.fts = fts
+ self.vector_store_ready = None
+
+
+# --------------------------------------------------------------------------
+# The property that motivates the whole change
+# --------------------------------------------------------------------------
+
+
+def test_mock_vectors_are_not_discriminative():
+ """Unrelated texts are near-identical under the mock, so ranking is noise."""
+ embedder = KeylessEmbedder()
+ vectors = asyncio.run(embedder.embed([f"unrelated-document-{i}" for i in range(200)]))
+ pairs = [
+ sum(x * y for x, y in zip(vectors[i], vectors[j], strict=True))
+ for i in range(len(vectors))
+ for j in range(i + 1, len(vectors))
+ ]
+ # Two texts with nothing in common should not look alike. Under the mock
+ # they do, which is why the vector leg has to be skipped rather than
+ # thresholded: there is no cutoff that separates signal from noise.
+ assert statistics.mean(pairs) > 0.6
+ assert min(pairs) > 0.15
+
+
+# --------------------------------------------------------------------------
+# The predicate
+# --------------------------------------------------------------------------
+
+
+def test_predicate_rejects_keyless_and_accepts_real():
+ assert is_semantic_embedder(_RealisticEmbedder()) is True
+ assert is_semantic_embedder(KeylessEmbedder()) is False
+
+
+def test_predicate_accepts_the_bare_test_double():
+ """MockEmbedder stands in for a real embedder in the suite and must rank.
+
+ The two classes share their arithmetic, so only the type separates them.
+ If this ever flips, ~25 existing tests lose their vector leg silently.
+ """
+ assert is_semantic_embedder(MockEmbedder()) is True
+ assert isinstance(KeylessEmbedder(), MockEmbedder), "width checks rely on this"
+
+
+def test_predicate_reads_the_embedder_off_the_store():
+ assert store_has_semantic_vectors(InMemoryVectorStore(embedder=_RealisticEmbedder())) is True
+ assert store_has_semantic_vectors(InMemoryVectorStore(embedder=KeylessEmbedder())) is False
+
+
+def test_predicate_fails_open_on_a_store_it_cannot_inspect():
+ """Only positively-identified keyless stores are refused.
+
+ Failing closed would silently disable semantic search for any store holding
+ its embedder somewhere else, including out-of-tree ones. It also breaks the
+ several test doubles in this suite that carry no ``_embedder`` at all.
+ """
+ assert store_has_semantic_vectors(object()) is True
+ assert is_semantic_embedder(None) is True
+ # None means "no store", which is a different thing from "cannot rank".
+ assert store_has_semantic_vectors(None) is False
+
+
+# --------------------------------------------------------------------------
+# search_codebase
+# --------------------------------------------------------------------------
+
+
+def _seed(store, n=20):
+ async def go():
+ for i in range(n):
+ await store.embed_and_upsert(
+ f"page-{i}",
+ f"page {i} about an entirely unrelated subject",
+ {"title": f"Page {i}", "page_type": "file_page"},
+ )
+
+ asyncio.run(go())
+ return store
+
+
+def test_search_vector_leg_is_silent_on_a_keyless_store():
+ """The regression test. Fails on unfixed code, which returns a full window."""
+ store = _seed(InMemoryVectorStore(embedder=KeylessEmbedder()))
+ hits = asyncio.run(tool_search._safe_vector(_Ctx(store), "a totally unrelated query", 5))
+ assert hits == []
+
+
+def test_search_vector_leg_still_runs_on_a_real_store():
+ store = _seed(InMemoryVectorStore(embedder=_RealisticEmbedder()))
+ hits = asyncio.run(tool_search._safe_vector(_Ctx(store), "aaa bbb", 5))
+ assert hits, "a real embedder must still retrieve"
+
+
+def test_fused_retrieve_returns_nothing_when_keyless_and_fts_misses():
+ """Keyless + no lexical match must mean no results, not nearest neighbours."""
+
+ class _EmptyFts:
+ async def search(self, query, limit=10):
+ return []
+
+ store = _seed(InMemoryVectorStore(embedder=KeylessEmbedder()))
+ out = asyncio.run(
+ tool_search._fused_retrieve(_Ctx(store, _EmptyFts()), "unrelated query", 15, None)
+ )
+ assert out == []
+
+
+# --------------------------------------------------------------------------
+# get_answer
+# --------------------------------------------------------------------------
+
+
+def test_answer_vector_leg_is_silent_and_says_why():
+ store = _seed(InMemoryVectorStore(embedder=KeylessEmbedder()))
+ pipeline.begin_leg_record()
+ hits = asyncio.run(pipeline._safe_vector_search(_Ctx(store), "an unrelated question"))
+ assert hits == []
+ assert pipeline.retrieval_legs()["vector"] == "keyless"
+
+
+def test_keyless_is_reported_but_not_as_a_failure():
+ """A permanent configuration is not a leg that fell over."""
+ assert pipeline.degraded_legs({"fts": "ok", "vector": "keyless"}) == []
+ assert pipeline.degraded_legs({"fts": "ok", "vector": "timeout"}) == ["vector"]
+
+
+# --------------------------------------------------------------------------
+# Decision dedup
+# --------------------------------------------------------------------------
+
+
[email protected]("n_existing", [10, 60])
+def test_dedup_refuses_rather_than_guessing_on_a_keyless_store(n_existing):
+ """Unfixed, this merges an unrelated decision ~100% of the time at n=60."""
+ store = InMemoryVectorStore(embedder=KeylessEmbedder())
+
+ async def go():
+ for i in range(n_existing):
+ await store.embed_and_upsert(
+ f"{semantic_match.DECISION_VECTOR_PREFIX}d{i}",
+ f"decision {i} on an entirely separate topic",
+ {"title": f"Decision {i}"},
+ )
+ return await semantic_match.find_duplicate_decision(
+ store, title="A brand new and unrelated decision"
+ )
+
+ assert asyncio.run(go()) is None
+
+
+def test_related_decisions_are_empty_on_a_keyless_store():
+ store = InMemoryVectorStore(embedder=KeylessEmbedder())
+
+ async def go():
+ for i in range(30):
+ await store.embed_and_upsert(
+ f"{semantic_match.DECISION_VECTOR_PREFIX}d{i}",
+ f"decision {i}",
+ {"title": f"Decision {i}"},
+ )
+ single = await semantic_match.find_related_decisions(store, title="Unrelated", lo=0.5)
+ many = await semantic_match.find_related_decisions_many(
+ store, [("Unrelated", "", set()), ("Also unrelated", "", set())], lo=0.5
+ )
+ return single, many
+
+ single, many = asyncio.run(go())
+ assert single == []
+ assert many == [[], []]
+
+
+def test_dedup_by_vector_ignores_the_pending_index_too():
+ """Pending vectors come from the same embedder, so they are equally blind."""
+ store = InMemoryVectorStore(embedder=KeylessEmbedder())
+ vector = asyncio.run(KeylessEmbedder().embed(["a new decision"]))[0]
+
+ class _Pending:
+ ids: ClassVar[set[str]] = {"decision:other"}
+
+ def best(self, _v):
+ return ("decision:other", 0.99)
+
+ got = asyncio.run(
+ semantic_match.find_duplicate_decision_by_vector(store, vector, pending=_Pending())
+ )
+ assert got is None