fix: isolate best-effort locale failures

Author: kingpanther13

custom_components/ha_mcp_tools/llm_api.py

@@ -49,9 +49,10 @@
 import asyncio
 import importlib
 import logging
-from collections.abc import AsyncIterator, Iterable
+from collections.abc import AsyncIterator, Callable, Iterable
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
+from functools import cache
 from typing import TYPE_CHECKING, Any, cast
 
 import voluptuous as vol
@@ -128,18 +129,22 @@
 _SEARCH_RESULT_LIMIT = 8
 
 
-def convert_to_voluptuous(schema: Any) -> vol.Schema:
-    """Convert an OpenAPI schema on stable and Probatio-based HA Core."""
+@cache
+def _schema_converter() -> Callable[[Any], Any]:
+    """Resolve the Core-provided schema converter once, off the event loop."""
     try:
-        probatio = importlib.import_module("probatio")
+        legacy = importlib.import_module("voluptuous_openapi")
     except ModuleNotFoundError as err:
-        if err.name != "probatio":
+        if err.name != "voluptuous_openapi":
             raise
-        legacy = importlib.import_module("voluptuous_openapi")
-        converter = legacy.convert_to_voluptuous
-    else:
-        converter = probatio.from_openapi
-    return cast(vol.Schema, converter(schema))
+        probatio = importlib.import_module("probatio")
+        return probatio.from_openapi
+    return legacy.convert_to_voluptuous
+
+
+def convert_to_voluptuous(schema: Any) -> vol.Schema:
+    """Convert an OpenAPI schema on stable and Probatio-based HA Core."""
+    return cast(vol.Schema, _schema_converter()(schema))
 
 
 # Used when the server's initialize result carries no instructions (it always
@@ -213,14 +218,15 @@ def _is_transport_failure(err: BaseException) -> bool:
 
 
 def _import_mcp_sdk() -> None:
-    """Import the mcp client SDK modules (blocking; run on the executor).
+    """Import lazy LLM dependencies (blocking; run on the executor).
 
-    Raises ImportError when the SDK is not importable — the caller decides
-    whether that skips registration (SDK missing entirely) or surfaces as a
-    conversation error.
+    Raises ImportError when the MCP SDK or Core's schema converter is not
+    importable — the caller decides whether that skips registration or
+    surfaces as a conversation error.
     """
     importlib.import_module("mcp.client.session")
     importlib.import_module("mcp.client.streamable_http")
+    _schema_converter()
 
 
 async def async_probe_mcp_sdk(hass: HomeAssistant) -> bool:
@@ -229,8 +235,8 @@ async def async_probe_mcp_sdk(hass: HomeAssistant) -> bool:
         await hass.async_add_executor_job(_import_mcp_sdk)
     except ImportError as err:
         _LOGGER.warning(
-            "The installed server package provides no importable 'mcp' client "
-            "SDK (%s); the conversation-agent LLM API will not be available",
+            "A required LLM dependency is not importable (%s); the "
+            "conversation-agent LLM API will not be available",
             err,
         )
         return False

src/ha_mcp/settings_ui/_i18n.py

@@ -134,6 +134,89 @@ def _warn_best_effort_catalog(locale: str, path: Path, exc: Exception) -> None:
     _LOGGER.warning("Skipping best-effort locale %s from %s: %s", locale, path, exc)
 
 
+def _warn_best_effort_entry(locale: str, entry: str, exc: Exception) -> None:
+    _LOGGER.warning(
+        "Ignoring invalid best-effort locale %s %s; using English fallback: %s",
+        locale,
+        entry,
+        exc,
+    )
+
+
+def _catalog_fragment(
+    catalog: dict[str, Any],
+    *,
+    messages: dict[str, str] | None = None,
+    tools: dict[str, dict[str, str]] | None = None,
+) -> dict[str, Any]:
+    """Return a minimal catalog used to validate one translated entry."""
+    return {
+        "meta": catalog["meta"],
+        "messages": messages or {},
+        "tool_groups": {},
+        "tools": tools or {},
+    }
+
+
+def _sanitize_best_effort_catalog(
+    locale: str,
+    catalog: dict[str, Any],
+    english: dict[str, Any],
+    settings_html: Path,
+) -> dict[str, Any]:
+    """Drop only invalid translated entries so the rest of a locale survives."""
+    sanitized = {
+        "meta": dict(catalog["meta"]),
+        "messages": dict(catalog["messages"]),
+        "tool_groups": dict(catalog["tool_groups"]),
+        "tools": {
+            tool_name: dict(fields) for tool_name, fields in catalog["tools"].items()
+        },
+    }
+    known_panels = _known_panels(settings_html)
+
+    for key, translated in tuple(sanitized["messages"].items()):
+        english_messages = (
+            {key: english["messages"][key]} if key in english["messages"] else {}
+        )
+        candidate = {
+            DEFAULT_LOCALE: _catalog_fragment(english, messages=english_messages),
+            locale: _catalog_fragment(sanitized, messages={key: translated}),
+        }
+        try:
+            _validate_placeholder_parity(candidate)
+            _validate_inline_markup(candidate)
+            _validate_panel_links(candidate, settings_html, known_panels=known_panels)
+        except ValueError as exc:
+            del sanitized["messages"][key]
+            _warn_best_effort_entry(locale, f"message {key!r}", exc)
+
+    for tool_name, translated_tool in tuple(sanitized["tools"].items()):
+        for field, translated in tuple(translated_tool.items()):
+            english_field = english["tools"].get(tool_name, {}).get(field)
+            english_tools = (
+                {tool_name: {field: english_field}} if english_field is not None else {}
+            )
+            candidate = {
+                DEFAULT_LOCALE: _catalog_fragment(english, tools=english_tools),
+                locale: _catalog_fragment(
+                    sanitized,
+                    tools={tool_name: {field: translated}},
+                ),
+            }
+            try:
+                _validate_placeholder_parity(candidate)
+            except ValueError as exc:
+                del translated_tool[field]
+                _warn_best_effort_entry(
+                    locale, f"tool {tool_name!r} field {field!r}", exc
+                )
+        if not translated_tool:
+            del sanitized["tools"][tool_name]
+
+    return sanitized
+
+
 def load_catalogs(
     directory: Path = LOCALES_DIR, settings_html: Path = _SETTINGS_HTML
 ) -> dict[str, dict[str, Any]]:
@@ -174,17 +257,9 @@ def load_catalogs(
     _validate_panel_links(strict_catalogs, settings_html)
 
     for locale in sorted(set(catalogs) - set(strict_catalogs)):
-        candidate = {
-            DEFAULT_LOCALE: catalogs[DEFAULT_LOCALE],
-            locale: catalogs[locale],
-        }
-        try:
-            _validate_placeholder_parity(candidate)
-            _validate_inline_markup(candidate)
-            _validate_panel_links(candidate, settings_html)
-        except ValueError as exc:
-            _warn_best_effort_catalog(locale, directory / f"{locale}.json", exc)
-            del catalogs[locale]
+        catalogs[locale] = _sanitize_best_effort_catalog(
+            locale, catalogs[locale], catalogs[DEFAULT_LOCALE], settings_html
+        )
     return catalogs
 
 
@@ -272,7 +347,10 @@ def _known_panels(settings_html: Path = _SETTINGS_HTML) -> set[str]:
 
 
 def _validate_panel_links(
-    catalogs: dict[str, dict[str, Any]], settings_html: Path = _SETTINGS_HTML
+    catalogs: dict[str, dict[str, Any]],
+    settings_html: Path = _SETTINGS_HTML,
+    *,
+    known_panels: set[str] | None = None,
 ) -> None:
     """Reject cross-panel links that point at a tab which does not exist.
 
@@ -285,7 +363,7 @@ def _validate_panel_links(
     and group labels go through ``escapeHtml``, so a link written there shows
     as visible garbled markup rather than a dead link — wrong, but not silent.
     """
-    panels = _known_panels(settings_html)
+    panels = known_panels if known_panels is not None else _known_panels(settings_html)
     english_messages = catalogs[DEFAULT_LOCALE]["messages"]
     for locale, catalog in catalogs.items():
         for key, value in catalog["messages"].items():

tests/src/unit/test_llm_api.py

@@ -14,6 +14,7 @@
 
 import asyncio
 import logging
+import threading
 from contextlib import asynccontextmanager
 from types import SimpleNamespace
 from typing import Any
@@ -260,38 +261,83 @@ def _boom() -> None:
 
         assert fake_llm_apis(hass) == {}
         assert DATA_LLM_API_UNSUB not in hass.data.get(DOMAIN, {})
-        assert "no importable 'mcp' client SDK" in caplog.text
+        assert "required LLM dependency is not importable" in caplog.text
 
 
 class TestSchemaConversionCompatibility:
-    def test_prefers_probatio_when_home_assistant_provides_it(self, monkeypatch):
+    @pytest.fixture(autouse=True)
+    def _clear_schema_converter_cache(self):
+        llm_api._schema_converter.cache_clear()
+        yield
+        llm_api._schema_converter.cache_clear()
+
+    def test_prefers_stable_core_converter_when_available(self, monkeypatch):
+        schema = {"type": "object"}
+        legacy = SimpleNamespace(
+            convert_to_voluptuous=lambda value: {"voluptuous_openapi": value}
+        )
+
+        def _import_module(name):
+            assert name == "voluptuous_openapi"
+            return legacy
+
+        monkeypatch.setattr(llm_api.importlib, "import_module", _import_module)
+
+        assert llm_api.convert_to_voluptuous(schema) == {"voluptuous_openapi": schema}
+
+    def test_falls_back_to_probatio_on_newer_core(self, monkeypatch):
         schema = {"type": "object"}
         probatio = SimpleNamespace(from_openapi=lambda value: {"probatio": value})
 
         def _import_module(name):
+            if name == "voluptuous_openapi":
+                raise ModuleNotFoundError(
+                    "No module named 'voluptuous_openapi'",
+                    name="voluptuous_openapi",
+                )
             assert name == "probatio"
             return probatio
 
         monkeypatch.setattr(llm_api.importlib, "import_module", _import_module)
 
         assert llm_api.convert_to_voluptuous(schema) == {"probatio": schema}
 
-    def test_falls_back_to_voluptuous_openapi_on_stable_core(self, monkeypatch):
-        schema = {"type": "object"}
+    async def test_converter_import_is_warmed_once_off_event_loop(self, monkeypatch):
+        main_thread = threading.get_ident()
+        imports: list[tuple[str, int]] = []
         legacy = SimpleNamespace(
             convert_to_voluptuous=lambda value: {"voluptuous_openapi": value}
         )
 
         def _import_module(name):
+            imports.append((name, threading.get_ident()))
+            if name.startswith("mcp."):
+                return SimpleNamespace()
+            if name == "voluptuous_openapi":
+                return legacy
             if name == "probatio":
                 raise ModuleNotFoundError("No module named 'probatio'", name="probatio")
-            assert name == "voluptuous_openapi"
-            return legacy
+            raise AssertionError(name)
+
+        async def _executor(func, *args):
+            return await asyncio.to_thread(func, *args)
 
+        hass = _make_hass()
+        hass.async_add_executor_job = AsyncMock(side_effect=_executor)
         monkeypatch.setattr(llm_api.importlib, "import_module", _import_module)
 
+        assert await llm_api.async_probe_mcp_sdk(hass)
+        schema = {"type": "object"}
+        assert llm_api.convert_to_voluptuous(schema) == {"voluptuous_openapi": schema}
         assert llm_api.convert_to_voluptuous(schema) == {"voluptuous_openapi": schema}
 
+        assert [name for name, _ in imports] == [
+            "mcp.client.session",
+            "mcp.client.streamable_http",
+            "voluptuous_openapi",
+        ]
+        assert all(thread_id != main_thread for _, thread_id in imports)
+
 
 class TestFullModeInstance:
     async def test_lists_exposed_tools_with_converted_schemas_and_prompt(

tests/src/unit/test_locale_parity.py

@@ -41,6 +41,7 @@
 import subprocess
 import sys
 import tempfile
+import warnings
 from collections import Counter
 from functools import cache
 from pathlib import Path, PurePosixPath
@@ -394,6 +395,7 @@ def test_every_locale_ships_on_every_surface() -> None:
     )
 
 
+@pytest.mark.filterwarnings("always:best-effort locale")
 def test_best_effort_locale_surface_problems_are_warning_only() -> None:
     issues: list[str] = []
     locale_lines = [
@@ -431,9 +433,10 @@ def test_best_effort_locale_surface_problems_are_warning_only() -> None:
                 issues.append(f"invalid {path.relative_to(_REPO_ROOT)}: {exc}")
 
     if issues:
-        print(
-            "::warning::best-effort locale audit: " + "; ".join(issues),
-            file=sys.stderr,
+        warnings.warn(
+            "best-effort locale audit: " + "; ".join(issues),
+            pytest.PytestWarning,
+            stacklevel=1,
         )
 
 
@@ -857,11 +860,6 @@ def _non_english_settings_locales() -> list[str]:
     )
 
 
-def test_best_effort_locales_are_outside_hard_content_gates() -> None:
-    assert BEST_EFFORT_LOCALES.isdisjoint(_translated_component_locales())
-    assert BEST_EFFORT_LOCALES.isdisjoint(_non_english_settings_locales())
-
-
 @cache
 def _renderable_groups_and_tools() -> tuple[frozenset[str], frozenset[str]]:
     """The group headings and tool names the settings UI can actually show.