Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(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__.pyindex 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.pyindex 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"] = Trueif 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.pyindex 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"] = modelif 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.pyindex 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 = Nonediff --git a/tests/unit/server/mcp/conftest.py b/tests/unit/server/mcp/conftest.pyindex 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 = Nonemcp_mod._registry = Nonemcp_mod._workspace_root = None+ mcp_mod._embedder_status = None@pytest.fixturediff --git a/tests/unit/server/mcp/test_embedder_resolution.py b/tests/unit/server/mcp/test_embedder_resolution.pynew file mode 100644index 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)