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(mcp): surface embedder init failure instead of silent mock fallback (#324)

Raghav Chamadiya910d374805d2
diff --git a/packages/server/src/repowise/server/mcp_server/__init__.py b/packages/server/src/repowise/server/mcp_server/__init__.py
index 847684581..2a1966016 100644
--- a/packages/server/src/repowise/server/mcp_server/__init__.py
+++ b/packages/server/src/repowise/server/mcp_server/__init__.py
@@ -70,6 +70,7 @@ _STATE_NAMES = frozenset(
"_registry",
"_workspace_root",
"_cross_repo_enricher",
+ "_embedder_status",
}
)
diff --git a/packages/server/src/repowise/server/mcp_server/_meta.py b/packages/server/src/repowise/server/mcp_server/_meta.py
index a16e4cfc4..ab97f54e9 100644
--- a/packages/server/src/repowise/server/mcp_server/_meta.py
+++ b/packages/server/src/repowise/server/mcp_server/_meta.py
@@ -204,11 +204,39 @@ def build_meta(
out["cached"] = True
if repository is not None:
out.update(freshness_from_repo(repository))
+ out.update(_embedder_meta())
if extra:
out.update(extra)
return out
+def _embedder_meta() -> dict[str, Any]:
+ """Surface embedder degradation (issue #306) in the `_meta` envelope.
+
+ When the configured embedder failed to initialise and the server silently
+ fell back to mock vectors, every tool response carries ``embedder: "mock"``,
+ ``embedder_degraded: True``, and a human-readable ``embedder_warning`` so an
+ 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.
+ """
+ # 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"):
+ return {}
+ out: dict[str, Any] = {
+ "embedder": status.get("active", "mock"),
+ "embedder_degraded": True,
+ }
+ reason = status.get("reason")
+ if reason:
+ out["embedder_warning"] = reason
+ return out
+
+
def context_hint(targets: list[str], compact: bool, include: set[str] | None = None) -> str | None:
"""Hint for `get_context` callers.
diff --git a/packages/server/src/repowise/server/mcp_server/_server.py b/packages/server/src/repowise/server/mcp_server/_server.py
index 257fb151a..15d85cca8 100644
--- a/packages/server/src/repowise/server/mcp_server/_server.py
+++ b/packages/server/src/repowise/server/mcp_server/_server.py
@@ -25,10 +25,30 @@ from repowise.server.mcp_server import _state
_log = __import__("logging").getLogger("repowise.mcp")
-def _resolve_embedder():
- """Resolve embedder from REPOWISE_EMBEDDER env var or .repowise/config.yaml."""
- name = os.environ.get("REPOWISE_EMBEDDER", "").lower()
- if not name and _state._repo_path:
+# Per-embedder remediation hints, appended to the ERROR log and the `_meta`
+# warning so a misconfiguration is actionable without grepping SDK tracebacks.
+# Keyed by built-in embedder name; unknown/custom embedders fall back to the
+# generic exception message alone.
+_EMBEDDER_REMEDIATION: dict[str, str] = {
+ "openai": "set OPENAI_API_KEY in the MCP server's environment (and `pip install openai`)",
+ "gemini": (
+ "set GEMINI_API_KEY (or GOOGLE_API_KEY) in the MCP server's environment "
+ "(and `pip install google-genai`)"
+ ),
+ "openrouter": "set OPENROUTER_API_KEY in the MCP server's environment (and `pip install openai`)",
+}
+
+
+def _configured_embedder_name() -> str:
+ """Read the configured embedder name from env or ``.repowise/config.yaml``.
+
+ Returns a lowercased name, or ``""`` when nothing is explicitly configured
+ (in which case MockEmbedder is the intended default, not a degradation).
+ """
+ name = os.environ.get("REPOWISE_EMBEDDER", "").strip().lower()
+ if name:
+ return name
+ if _state._repo_path:
try:
from pathlib import Path
@@ -37,30 +57,84 @@ def _resolve_embedder():
import yaml # type: ignore[import-untyped]
cfg = yaml.safe_load(cfg_path.read_text(encoding="utf-8")) or {}
- name = (cfg.get("embedder") or "").lower()
+ return (cfg.get("embedder") or "").strip().lower()
except Exception:
_log.debug("Failed to read embedder from config.yaml", exc_info=True)
+ return ""
+
+
+def _embedder_kwargs(name: str) -> dict[str, Any]:
+ """Map repowise embedding env vars onto an embedder's constructor kwargs.
+
+ Kept backend-agnostic: ``REPOWISE_EMBEDDING_MODEL`` applies to any embedder
+ that accepts a ``model`` arg; ``REPOWISE_EMBEDDING_DIMS`` is gemini-specific
+ (its constructor exposes ``output_dimensionality``). Anything not set here
+ falls through to the embedder's own defaults.
+ """
+ kwargs: dict[str, Any] = {}
+ model = os.environ.get("REPOWISE_EMBEDDING_MODEL")
+ if model:
+ kwargs["model"] = model
if name == "gemini":
- try:
- from repowise.core.providers.embedding.gemini import GeminiEmbedder
+ dims = os.environ.get("REPOWISE_EMBEDDING_DIMS")
+ kwargs["output_dimensionality"] = int(dims) if dims else 768
+ return kwargs
- dims = int(os.environ.get("REPOWISE_EMBEDDING_DIMS", "768"))
- return GeminiEmbedder(output_dimensionality=dims)
- except Exception:
- _log.warning(
- "Failed to initialise Gemini embedder — falling back to mock", exc_info=True
- )
- if name == "openai":
- try:
- from repowise.core.providers.embedding.openai import OpenAIEmbedder
- model = os.environ.get("REPOWISE_EMBEDDING_MODEL", "text-embedding-3-small")
- return OpenAIEmbedder(model=model)
- except Exception:
- _log.warning(
- "Failed to initialise OpenAI embedder — falling back to mock", exc_info=True
- )
- return MockEmbedder()
+def _resolve_embedder():
+ """Resolve the embedder from ``REPOWISE_EMBEDDER`` / ``.repowise/config.yaml``.
+
+ Goes through the shared embedder registry (``get_embedder``) so *every*
+ backend is honoured — openai, gemini, openrouter, and any custom embedder
+ registered via ``register_embedder`` — not just a hardcoded subset.
+
+ When an embedder is **explicitly configured** but fails to initialise (most
+ often a missing API key, but also a missing SDK or an unknown name), we
+ still fall back to ``MockEmbedder`` so the server keeps serving non-RAG
+ tools — but we record the degradation in ``_state._embedder_status`` and log
+ at ``ERROR`` with the missing key and remediation. ``build_meta`` then
+ surfaces ``embedder_degraded`` in every tool's ``_meta`` envelope so callers
+ can detect that semantic search is running on mock vectors instead of the
+ real index, rather than the broken server masquerading as healthy (#306).
+
+ When nothing is configured (or ``mock`` is requested explicitly),
+ MockEmbedder is the intended default and is **not** flagged as degraded.
+ """
+ from repowise.core.providers.embedding import get_embedder
+
+ name = _configured_embedder_name()
+
+ if not name or name == "mock":
+ _state._embedder_status = {
+ "active": "mock",
+ "requested": name or None,
+ "degraded": False,
+ }
+ return MockEmbedder()
+
+ try:
+ embedder = get_embedder(name, **_embedder_kwargs(name))
+ _state._embedder_status = {"active": name, "requested": name, "degraded": False}
+ return embedder
+ except Exception as exc:
+ detail = str(exc).strip() or type(exc).__name__
+ reason = (
+ f"Configured embedder '{name}' failed to initialise ({detail}). "
+ "Semantic search (search_codebase, get_answer) is running on mock "
+ "vectors and CANNOT match the real index — results will be empty or "
+ "irrelevant."
+ )
+ remediation = _EMBEDDER_REMEDIATION.get(name)
+ if remediation:
+ reason += f" To fix: {remediation}, then restart the MCP server."
+ _log.error(reason, exc_info=True)
+ _state._embedder_status = {
+ "active": "mock",
+ "requested": name,
+ "degraded": True,
+ "reason": reason,
+ }
+ return MockEmbedder()
async def _load_vector_stores(repo_path: str | None) -> None:
diff --git a/packages/server/src/repowise/server/mcp_server/_state.py b/packages/server/src/repowise/server/mcp_server/_state.py
index 9012d7648..bf42a8f94 100644
--- a/packages/server/src/repowise/server/mcp_server/_state.py
+++ b/packages/server/src/repowise/server/mcp_server/_state.py
@@ -20,3 +20,12 @@ _vector_store_ready: asyncio.Event | None = None
_registry: Any = None # RepoRegistry | None
_workspace_root: str | None = None
_cross_repo_enricher: Any = None # CrossRepoEnricher | None
+
+# Embedder health — set by _resolve_embedder() in _server.py. ``None`` until an
+# embedder is resolved. When an explicitly-configured embedder fails to
+# initialise we still fall back to MockEmbedder (so non-RAG tools stay up) but
+# record the degradation here so build_meta() can surface it in every tool's
+# `_meta` envelope — otherwise broken semantic search looks perfectly healthy
+# (issue #306). Shape: {"active": str, "requested": str | None,
+# "degraded": bool, "reason": str (only when degraded)}.
+_embedder_status: dict[str, Any] | None = None
diff --git a/tests/unit/server/mcp/conftest.py b/tests/unit/server/mcp/conftest.py
index 825a9409c..45a109f4c 100644
--- a/tests/unit/server/mcp/conftest.py
+++ b/tests/unit/server/mcp/conftest.py
@@ -562,6 +562,7 @@ async def setup_mcp(factory, fts, vector_store, populated_db):
mcp_mod._repo_path = None
mcp_mod._registry = None
mcp_mod._workspace_root = None
+ mcp_mod._embedder_status = None
@pytest.fixture
diff --git a/tests/unit/server/mcp/test_embedder_resolution.py b/tests/unit/server/mcp/test_embedder_resolution.py
new file mode 100644
index 000000000..8739f43fe
--- /dev/null
+++ b/tests/unit/server/mcp/test_embedder_resolution.py
@@ -0,0 +1,170 @@
+"""Tests for MCP embedder resolution + degradation surfacing (issue #306).
+
+When an explicitly-configured embedder fails to initialise (missing key,
+missing SDK, unknown name) the MCP server must NOT silently masquerade as
+healthy. It still falls back to MockEmbedder so non-RAG tools keep working, but
+records the degradation so `build_meta` surfaces it in every tool's `_meta`.
+
+These tests also pin the "all embedders work" contract: resolution goes through
+the shared registry, so openrouter and custom-registered embedders are honoured
+— not just the hardcoded openai/gemini branches that the old code special-cased.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.providers.embedding.base import MockEmbedder
+from repowise.server.mcp_server import _server, _state
+from repowise.server.mcp_server._meta import build_meta
+
+# Embedder env vars that, if present in the real environment, would let an
+# explicitly-configured embedder succeed and break the "missing key" tests.
+_EMBEDDER_ENV_VARS = (
+ "REPOWISE_EMBEDDER",
+ "REPOWISE_EMBEDDING_MODEL",
+ "REPOWISE_EMBEDDING_DIMS",
+ "OPENAI_API_KEY",
+ "OPENAI_BASE_URL",
+ "GEMINI_API_KEY",
+ "GOOGLE_API_KEY",
+ "OPENROUTER_API_KEY",
+)
+
+
[email protected](autouse=True)
+def _clean_env_and_state(monkeypatch):
+ """Strip embedder env vars + reset status so each test starts from scratch."""
+ for var in _EMBEDDER_ENV_VARS:
+ monkeypatch.delenv(var, raising=False)
+ monkeypatch.setattr(_state, "_repo_path", None, raising=False)
+ monkeypatch.setattr(_state, "_embedder_status", None, raising=False)
+ yield
+ _state._embedder_status = None
+
+
+def test_no_config_uses_mock_not_degraded(monkeypatch):
+ """Nothing configured → MockEmbedder is the intended default, not degraded."""
+ embedder = _server._resolve_embedder()
+ assert isinstance(embedder, MockEmbedder)
+ assert _state._embedder_status == {
+ "active": "mock",
+ "requested": None,
+ "degraded": False,
+ }
+
+
+def test_explicit_mock_not_degraded(monkeypatch):
+ """Explicitly requesting mock is a deliberate choice, never a degradation."""
+ monkeypatch.setenv("REPOWISE_EMBEDDER", "mock")
+ embedder = _server._resolve_embedder()
+ assert isinstance(embedder, MockEmbedder)
+ assert _state._embedder_status["degraded"] is False
+
+
+def test_openai_without_key_degrades_and_names_remediation(monkeypatch):
+ """Explicit openai + no key → fall back to mock, flag degraded, name the key."""
+ monkeypatch.setenv("REPOWISE_EMBEDDER", "openai")
+ embedder = _server._resolve_embedder()
+
+ assert isinstance(embedder, MockEmbedder)
+ status = _state._embedder_status
+ assert status["degraded"] is True
+ assert status["active"] == "mock"
+ assert status["requested"] == "openai"
+ assert "OPENAI_API_KEY" in status["reason"]
+
+
+def test_openrouter_without_key_degrades(monkeypatch):
+ """openrouter is NOT one of the old hardcoded branches — it must still degrade
+ (and not be silently treated as mock). Proves all registry embedders work."""
+ monkeypatch.setenv("REPOWISE_EMBEDDER", "openrouter")
+ embedder = _server._resolve_embedder()
+
+ assert isinstance(embedder, MockEmbedder)
+ status = _state._embedder_status
+ assert status["degraded"] is True
+ assert status["requested"] == "openrouter"
+ assert "OPENROUTER_API_KEY" in status["reason"]
+
+
+def test_unknown_embedder_name_degrades(monkeypatch):
+ """A typo'd / unknown embedder name surfaces as degraded, not silent mock."""
+ monkeypatch.setenv("REPOWISE_EMBEDDER", "definitely-not-an-embedder")
+ embedder = _server._resolve_embedder()
+
+ assert isinstance(embedder, MockEmbedder)
+ status = _state._embedder_status
+ assert status["degraded"] is True
+ assert status["requested"] == "definitely-not-an-embedder"
+
+
+def test_custom_registered_embedder_is_honoured(monkeypatch):
+ """A custom embedder registered via register_embedder must resolve cleanly —
+ the server resolves through the shared registry, not a hardcoded subset."""
+ from repowise.core.providers.embedding import register_embedder
+ from repowise.core.providers.embedding.registry import _custom_embedders
+
+ class _FakeEmbedder:
+ dimensions = 4
+
+ async def embed(self, texts):
+ return [[0.0, 0.0, 0.0, 1.0] for _ in texts]
+
+ register_embedder("fake-test-embedder", lambda **kw: _FakeEmbedder())
+ try:
+ monkeypatch.setenv("REPOWISE_EMBEDDER", "fake-test-embedder")
+ embedder = _server._resolve_embedder()
+ assert isinstance(embedder, _FakeEmbedder)
+ assert _state._embedder_status == {
+ "active": "fake-test-embedder",
+ "requested": "fake-test-embedder",
+ "degraded": False,
+ }
+ finally:
+ _custom_embedders.pop("fake-test-embedder", None)
+
+
+def test_config_yaml_embedder_is_read(monkeypatch, tmp_path):
+ """The embedder name is read from .repowise/config.yaml when no env var set."""
+ repo_dir = tmp_path / "repo"
+ (repo_dir / ".repowise").mkdir(parents=True)
+ (repo_dir / ".repowise" / "config.yaml").write_text(
+ "provider: deepseek\nembedder: openai\n", encoding="utf-8"
+ )
+ monkeypatch.setattr(_state, "_repo_path", str(repo_dir))
+
+ embedder = _server._resolve_embedder()
+ assert isinstance(embedder, MockEmbedder) # no key → fell back
+ assert _state._embedder_status["requested"] == "openai"
+ assert _state._embedder_status["degraded"] is True
+
+
+def test_build_meta_surfaces_degraded_embedder(monkeypatch):
+ """A degraded embedder shows up in the _meta envelope so callers can detect it."""
+ monkeypatch.setattr(
+ _state,
+ "_embedder_status",
+ {"active": "mock", "requested": "openai", "degraded": True, "reason": "boom"},
+ )
+ meta = build_meta(timing_ms=1.0)
+ assert meta["embedder"] == "mock"
+ assert meta["embedder_degraded"] is True
+ assert meta["embedder_warning"] == "boom"
+
+
+def test_build_meta_clean_when_healthy(monkeypatch):
+ """A healthy (or unresolved) embedder leaves _meta clean — no noise fields."""
+ monkeypatch.setattr(
+ _state,
+ "_embedder_status",
+ {"active": "openai", "requested": "openai", "degraded": False},
+ )
+ meta = build_meta(timing_ms=1.0)
+ assert "embedder_degraded" not in meta
+ assert "embedder" not in meta
+ assert "embedder_warning" not in meta
+
+ # And when nothing has been resolved at all.
+ monkeypatch.setattr(_state, "_embedder_status", None)
+ assert "embedder_degraded" not in build_meta(timing_ms=1.0)