Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat(llm): ChatUnifier plugin facade + groq/cerebras native + LangChain chat-path removal
trohitg172ad074fb51
diff --git a/server/config/llm_defaults.json b/server/config/llm_defaults.jsonindex 1318bc42..f5c5affb 100644--- a/server/config/llm_defaults.json+++ b/server/config/llm_defaults.json@@ -97,7 +97,9 @@},"thinking_models": ["gemini-2.5", "gemini-3", "gemini-flash-latest", "gemini-pro-latest"],"thinking_type": "budget",- "temperature_range": [0.0, 2.0]+ "temperature_range": [0.0, 2.0],+ "_incompatible_models_note": "Models that the dropdown should hide because they need a different API endpoint than `generate_content`. antigravity-preview-05-2026 requires the Interactions API; selecting it currently surfaces a `google.genai.errors.APIError`. ChatUnifier reads this list in fetch_models and filters before returning. Drop entries here when the unifier gains routing support for the alternate endpoint.",+ "incompatible_models": ["antigravity-preview-05-2026"]},"openrouter": {"default_model": "anthropic/claude-sonnet-4.6",diff --git a/server/core/container.py b/server/core/container.pyindex fa47e23b..56ac75e3 100644--- a/server/core/container.py+++ b/server/core/container.py@@ -36,6 +36,16 @@ from services.compaction import init_compaction_service_clog("all service imports done")+# Side-effect import: populates ``services.llm.registry._REGISTRY`` with+# every shipped provider (4 dedicated + 6 OpenAI-compat). MUST run+# BEFORE the DI container constructs ``ChatUnifier`` so the unifier sees+# the full provider catalogue. ``ChatUnifier`` is the single facade+# ``AIService`` uses for chat-model dispatch + typed-exception translation.+from services.llm import ChatUnifier+from services.llm.config import LLM_DEFAULTS++_clog("LLM registry populated + unifier imported")+from services.temporal import TemporalClientWrapper@@ -44,6 +54,17 @@ def _create_temporal_client(server_address: str, namespace: str):return TemporalClientWrapper(server_address=server_address, namespace=namespace)+def _build_chat_unifier(auth_service):+ """Construct the chat-model unifier with the shared JSON defaults.++ Wrapped in a factory function so the DI container doesn't have to+ inject ``LLM_DEFAULTS`` (a module-level dict). ``LLM_DEFAULTS`` is+ loaded once at import time by ``services.llm.config`` and reflects+ the on-disk ``server/config/llm_defaults.json``.+ """+ return ChatUnifier(defaults=LLM_DEFAULTS, auth_service=auth_service)++# Wave 12 C4 sub-piece C: plugin-owned service factories.# ``MapsService`` (nodes/location) and ``AndroidService`` (nodes/android)# used to be imported here at module scope so providers.Factory could@@ -125,7 +146,21 @@ class Container(containers.DeclarativeContainer):UserAuthService, database=database, settings=settings, encryption=encryption_service, credentials_db=credentials_database)- ai_service = providers.Singleton(AIService, auth_service=auth_service, database=database, cache=cache, settings=settings)+ # ChatUnifier — single SERVICE facade for chat-model dispatch.+ # Reads the provider registry populated at import time and applies+ # JSON-driven typed-exception translation + ``incompatible_models``+ # filter. ``AIService`` delegates to this rather than calling+ # provider classes directly.+ chat_unifier = providers.Singleton(_build_chat_unifier, auth_service=auth_service)++ ai_service = providers.Singleton(+ AIService,+ auth_service=auth_service,+ database=database,+ cache=cache,+ settings=settings,+ chat_unifier=chat_unifier,+ )maps_service = providers.Factory(_build_maps_service, auth_service=auth_service, settings=settings)diff --git a/server/pyproject.toml b/server/pyproject.tomlindex 9f9f53c4..d78e1e13 100644--- a/server/pyproject.toml+++ b/server/pyproject.toml@@ -186,6 +186,11 @@ dev = [[tool.pytest.ini_options]testpaths = ["tests"]asyncio_mode = "auto"+# Default run excludes ``live`` tests so CI / local pytest doesn't+# accidentally hit real LLM provider APIs and incur charges. Opt in+# explicitly via ``pytest -m live`` (key-less providers still skip+# cleanly inside the test body).+addopts = "-m 'not live'"filterwarnings = ["ignore::DeprecationWarning","ignore::PendingDeprecationWarning",@@ -195,6 +200,7 @@ markers = ["node_contract: contract tests that drive a handler through NodeExecutor","slow: tests that take >1s","credentials: tests for the credentials subsystem (encryption, auth_service, oauth)",+ "live: tests that call real LLM provider APIs — require API keys in .env or environment. Opt-in via `pytest -m live`.",][tool.coverage.run]diff --git a/server/services/ai.py b/server/services/ai.pyindex a58f4c38..e84d124f 100644--- a/server/services/ai.py+++ b/server/services/ai.py@@ -133,7 +133,11 @@ logger = get_logger(__name__)# ---------------------------------------------------------------------------# Native LLM provider imports (dual-path: native for chat, LangChain for agents)# ----------------------------------------------------------------------------from services.llm.factory import create_provider, is_native_provider+# ``create_provider`` / ``is_native_provider`` are no longer called from+# this module — ``ChatUnifier`` (injected via DI) owns provider+# dispatch. The imports stay deleted; Phase D removes the legacy+# factory functions entirely once the LangChain fallback for+# groq/cerebras lands behind the unifier.from services.llm.protocol import (Message as NativeMessage,ThinkingConfig as NativeThinkingConfig,@@ -929,11 +933,25 @@ def _build_skill_system_prompt(skill_data: List[Dict[str, Any]], log_prefix: strclass AIService:"""AI model service for LangChain operations."""- def __init__(self, auth_service: AuthService, database, cache, settings: Settings):+ def __init__(+ self,+ auth_service: AuthService,+ database,+ cache,+ settings: Settings,+ chat_unifier=None,+ ):self.auth = auth_serviceself.database = databaseself.cache = cacheself.settings = settings+ # ``ChatUnifier`` is the single facade for chat-model dispatch ++ # typed-exception translation + JSON-driven incompatible_models+ # filter. Injected by the DI container; the legacy ``None``+ # default exists only so tests and ad-hoc constructions without+ # the DI container can still instantiate ``AIService`` (the chat+ # paths will fall back to direct factory calls).+ self.chat_unifier = chat_unifier# RLM service (lazy import to avoid circular deps)from services.rlm import RLMService@@ -1311,57 +1329,39 @@ class AIService:return [m for m in max_tokens_map if m != "_default"]async def fetch_models(self, provider: str, api_key: str) -> List[str]:- """Fetch available models from provider API.-- Native providers use their SDK-based fetch_models(). Groq/Cerebras- fall back to the LangChain httpx path. Local providers (ollama,- lmstudio) honour the user's stored ``{provider}_proxy`` base URL- the same way ``execute_chat`` does — without this passthrough the- probe always hits the JSON default and never sees the user's- actual installed models.+ """Fetch available models from a provider via ``ChatUnifier``.++ The unifier handles ``{provider}_proxy`` resolution, typed-SDK+ exception translation, and the JSON-driven ``incompatible_models``+ filter. All 12 providers (4 dedicated + 8 OpenAI-compat+ including groq + cerebras) route through here — Phase D removed+ the legacy LangChain fallback path.++ On API failure, falls back to the curated list from+ ``llm_defaults.json``. When the provider has no ``default_model``+ declared (intentional for local servers like ollama / lmstudio),+ returns an empty list so the frontend dropdown shows a real+ "no models" empty state instead of a placeholder name."""- # --- Native SDK path ---- if is_native_provider(provider):- proxy_url = await self.auth.get_api_key(f"{provider}_proxy")- native_provider = create_provider(provider, api_key, proxy_url=proxy_url)- return await native_provider.fetch_models(api_key)-- # --- LangChain fallback (groq, cerebras) ---- if provider == "cerebras" and not CEREBRAS_AVAILABLE:- raise ValueError(f"Cerebras provider not available: {CEREBRAS_IMPORT_ERROR or 'langchain-cerebras package not installed'}")-- config = get_provider_configs().get(provider)- if not config:- raise ValueError(f"Unsupported provider: {provider}")-- endpoint = config.models_endpoint- headers = config.models_header_fn(api_key)- curated = self._get_curated_models(provider)-+ if self.chat_unifier is None:+ raise NodeUserError(+ "ChatUnifier is not injected. AIService must be constructed via "+ "the DI container (core.container.Container)."+ )try:- async with httpx.AsyncClient(timeout=self.settings.ai_timeout) as client:- response = await client.get(endpoint, headers=headers)- response.raise_for_status()- data = response.json()-- # Both Groq and Cerebras use OpenAI-compatible /v1/models format.- # Their API may return owner-prefixed IDs (e.g. "openai/gpt-oss-120b")- # but their chat API expects flat IDs (e.g. "gpt-oss-120b"), so strip prefixes.- raw_ids = [m["id"] for m in data.get("data", []) if m.get("id")]- api_models = sorted(set(mid.split("/", 1)[-1] if "/" in mid else mid for mid in raw_ids))- if api_models:- return api_models+ return await self.chat_unifier.fetch_models(provider=provider, api_key=api_key)+ except NodeUserError:+ raiseexcept Exception as e:logger.warning(f"[AI] Failed to fetch models from {provider} API: {e}")- # Fallback to curated list from llm_defaults.json. When the- # provider has no default_model declared (intentional for local- # servers like ollama/lmstudio), return an empty list so the- # frontend dropdown shows a real "no models" empty state instead- # of a placeholder name the user doesn't actually have.+ # JSON-curated fallback+ curated = self._get_curated_models(provider)if curated:return curated- return [config.default_model] if config.default_model else []+ provider_cfg = _LLM_DEFAULTS.get("providers", {}).get(provider, {})+ default_model = provider_cfg.get("default_model", "")+ return [default_model] if default_model else []async def execute_chat(self, node_id: str, node_type: str, parameters: Dict[str, Any]) -> Dict[str, Any]:"""Execute AI chat model."""@@ -1413,75 +1413,49 @@ class AIService:format=flattened.get("reasoning_format", "parsed"),)- # Check for proxy URL (stored as {provider}_proxy credential)- proxy_url = await self.auth.get_api_key(f"{provider}_proxy")-- # --- Native SDK path (openai, anthropic, gemini, openrouter, xai) ---- if is_native_provider(provider):- max_tokens = native_resolve_max_tokens(flattened, model, provider)- temperature = native_resolve_temperature(- flattened,- model,- provider,- bool(thinking_config and thinking_config.enabled),+ # --- Unifier path (every provider) ---+ #+ # ``ChatUnifier`` owns proxy_url resolution + provider+ # instantiation + typed-SDK exception translation (raises+ # ``NodeUserError`` for both unknown providers and typed SDK+ # errors so ``BaseNode.execute()`` logs one WARN line with+ # no traceback). No per-provider Python lives here.+ #+ # The LangChain fallback for groq + cerebras was deleted in+ # Phase D — both providers now register through the+ # OpenAI-compat path in ``services.llm.providers._compat``.+ if self.chat_unifier is None:+ raise NodeUserError(+ "ChatUnifier is not injected. AIService must be constructed via "+ "the DI container (core.container.Container).")- native_provider = create_provider(provider, api_key, proxy_url=proxy_url)-- # Build native messages- native_msgs: List[NativeMessage] = []- if system_prompt and is_valid_message_content(system_prompt):- native_msgs.append(NativeMessage(role="system", content=system_prompt))- native_msgs.append(NativeMessage(role="user", content=prompt))-- llm_resp: LLMResponse = await native_provider.chat(- native_msgs,- model=model,- temperature=temperature,- max_tokens=max_tokens,- thinking=thinking_config,- )-- response_text = llm_resp.content- thinking_content = llm_resp.thinking- finish_reason = llm_resp.finish_reason-- # --- LangChain fallback path (groq, cerebras) ---- else:- from langchain_core.messages import HumanMessage, SystemMessage-- max_tokens = _resolve_max_tokens(flattened, model, provider)- temperature = _resolve_temperature(- flattened,- model,- provider,- bool(thinking_config and thinking_config.enabled),- )-- # Convert NativeThinkingConfig -> LangChain ThinkingConfig if needed- lc_thinking = None- if thinking_config:- lc_thinking = ThinkingConfig(- enabled=thinking_config.enabled,- budget=thinking_config.budget,- effort=thinking_config.effort,- level=thinking_config.level,- format=thinking_config.format,- )-- chat_model = self.create_model(provider, api_key, model, temperature, max_tokens, lc_thinking, proxy_url)-- messages = []- if system_prompt and is_valid_message_content(system_prompt):- messages.append(SystemMessage(content=system_prompt))- messages.append(HumanMessage(content=prompt))+ max_tokens = native_resolve_max_tokens(flattened, model, provider)+ temperature = native_resolve_temperature(+ flattened,+ model,+ provider,+ bool(thinking_config and thinking_config.enabled),+ )- filtered_messages = filter_empty_messages(messages)- response = chat_model.invoke(filtered_messages)+ native_msgs: List[NativeMessage] = []+ if system_prompt and is_valid_message_content(system_prompt):+ native_msgs.append(NativeMessage(role="system", content=system_prompt))+ native_msgs.append(NativeMessage(role="user", content=prompt))++ llm_resp: LLMResponse = await self.chat_unifier.chat(+ provider=provider,+ api_key=api_key,+ messages=native_msgs,+ model=model,+ temperature=temperature,+ max_tokens=max_tokens,+ thinking=thinking_config,+ )- text_content, thinking_content = extract_thinking_from_response(response)- response_text = text_content if text_content else response.content- finish_reason = "stop"+ response_text = llm_resp.content+ thinking_content = llm_resp.thinking+ finish_reason = llm_resp.finish_reasonresult = {"response": response_text,@@ -1508,21 +1482,15 @@ class AIService:"execution_time": time.time() - start_time,}- except openai.OpenAIError as e:- # Typed openai SDK exception — context overflow (BadRequestError),- # bad key (AuthenticationError), missing model (NotFoundError),- # server unreachable (APIConnectionError), etc. All- # user-correctable. Propagate as NodeUserError so BaseNode.execute()- # logs at WARN with no traceback.- log_api_call(- logger,- provider if "provider" in locals() else "unknown",- model if "model" in locals() else "unknown",- "chat",- False,- error=str(e),- )- raise NodeUserError(str(e)) from e+ except NodeUserError:+ # Re-raise without wrapping. ``ChatUnifier`` already+ # translated the typed SDK exception (openai / anthropic /+ # google APIError, …) into ``NodeUserError`` at the single+ # delegation site. ``BaseNode.execute()`` catches this and+ # logs one WARN line with no traceback. Every chat-path+ # call goes through the unifier post-Phase-A3, so the+ # previous per-provider catch blocks are gone.+ raiseexcept Exception as e:logger.error("AI execution failed", node_id=node_id, error=str(e))diff --git a/server/services/llm/__init__.py b/server/services/llm/__init__.pyindex 28108693..e2331f47 100644--- a/server/services/llm/__init__.py+++ b/server/services/llm/__init__.py@@ -22,6 +22,20 @@ from services.llm.protocol import ()from services.llm.messages import is_valid_message_content, filter_empty_messagesfrom services.llm.factory import create_provider, is_native_provider, NATIVE_PROVIDERS+from services.llm.registry import (+ ProviderSpec,+ register_provider,+ get_provider,+ all_providers,+ has_provider,+)+from services.llm.unifier import ChatUnifier++# Side-effect import — populates the provider registry by importing+# every provider module (each calls ``register_provider`` at the+# bottom). Must run BEFORE any caller asks the registry for a provider+# or constructs a ``ChatUnifier``.+from services.llm import providers as _providers # noqa: F401__all__ = [# Config@@ -45,8 +59,15 @@ __all__ = [# Messages"is_valid_message_content","filter_empty_messages",- # Factory+ # Factory (legacy — replaced by unifier in Phase A3; kept for back-compat)"create_provider","is_native_provider","NATIVE_PROVIDERS",+ # Plugin registry + unifier (Phase A — single SERVICE facade)+ "ProviderSpec",+ "register_provider",+ "get_provider",+ "all_providers",+ "has_provider",+ "ChatUnifier",]diff --git a/server/services/llm/providers/__init__.py b/server/services/llm/providers/__init__.pyindex 14deae54..c0e87387 100644--- a/server/services/llm/providers/__init__.py+++ b/server/services/llm/providers/__init__.py@@ -1 +1,26 @@-"""Native LLM provider implementations."""+"""Native LLM provider implementations.++Importing this package triggers self-registration of every shipped+provider into ``services.llm.registry._REGISTRY`` via the+``register_provider(...)`` side-effect at the bottom of each provider+module. ``ChatUnifier`` reads the registry directly — no factory+dispatch lives in ``services/ai.py`` anymore.++Adding a new provider:+ 1. Create the module under this package.+ 2. Implement the provider class (matching ``LLMProvider`` Protocol).+ 3. Call ``register_provider(ProviderSpec(...))`` at module bottom.+ 4. Add the module name to the import list below.+ 5. Add a ``providers.<name>`` block to ``server/config/llm_defaults.json``.+"""++from __future__ import annotations++# Side-effect imports — each module registers its ProviderSpec into the+# global registry at the bottom of the file. Order is documentation+# only; Python's module cache makes duplicate registration impossible.+from services.llm.providers import anthropic # noqa: F401+from services.llm.providers import openai # noqa: F401+from services.llm.providers import gemini # noqa: F401+from services.llm.providers import openrouter # noqa: F401+from services.llm.providers import _compat # noqa: F401 (registers 6 OpenAI-compat providers)diff --git a/server/services/llm/providers/_compat.py b/server/services/llm/providers/_compat.pynew file mode 100644index 00000000..92871913--- /dev/null+++ b/server/services/llm/providers/_compat.py@@ -0,0 +1,109 @@+"""OpenAI-compatible provider registrations.++Six providers (``xai`` / ``deepseek`` / ``kimi`` / ``mistral`` / ``ollama`` /+``lmstudio``) all ride the OpenAI Python SDK with a custom ``base_url``,+so they share one factory (``OpenAIProvider``) and one typed-exception+tuple (``openai.OpenAIError``). The per-provider differences live in+``llm_defaults.json`` (``base_url``, plus the provider quirks block+added in Phase C) — there is no per-provider Python here.++Adding a new OpenAI-compat provider is a JSON edit + one entry in+``_COMPAT_PROVIDERS`` below. Groq + Cerebras stay behind the LangChain+fallback in ``ai.py`` until Phase D deletes the fallback; they will+register here at that point.+"""++from __future__ import annotations++from typing import Tuple++import openai as _openai_sdk++from core.logging import get_logger+from services.llm.providers.openai import OpenAIProvider+from services.llm.registry import ProviderSpec, register_provider++logger = get_logger(__name__)+++# Names match the ``providers.<name>`` keys in ``llm_defaults.json``.+# The compat providers' ``base_url`` is pulled lazily from the JSON+# config so adding a new compat endpoint costs zero code — just append+# the name here after the JSON entry lands.+#+# Groq + Cerebras moved here in Phase D (May 2026). Both expose+# OpenAI-compatible `/v1` endpoints (``api.groq.com/openai/v1`` /+# ``api.cerebras.ai/v1``) so they share the ``OpenAIProvider`` factory+# with the other compat providers. Registering them here makes the+# LangChain fallback path in ``services/ai.py`` dead code, which Phase+# D then deletes.+_COMPAT_PROVIDERS: Tuple[str, ...] = (+ "xai",+ "deepseek",+ "kimi",+ "mistral",+ "ollama",+ "lmstudio",+ "groq",+ "cerebras",+)+++def _load_compat_base_urls() -> dict[str, str]:+ """Read ``providers.<name>.base_url`` from llm_defaults.json.++ Lazy so we don't add a hard import dependency on the JSON parser at+ module import. The JSON is already cached by ``services/ai.py`` 's+ ``_LLM_DEFAULTS``; we re-read it here so this module can register+ without depending on the ``ai`` service.+ """+ import json+ from pathlib import Path++ config_path = (+ Path(__file__).resolve().parent.parent.parent.parent+ / "config"+ / "llm_defaults.json"+ )+ try:+ with open(config_path, encoding="utf-8") as f:+ data = json.load(f)+ except Exception as e:+ logger.warning("Could not load llm_defaults.json for compat providers", error=str(e))+ return {}+ providers = data.get("providers", {})+ return {+ name: providers.get(name, {}).get("base_url", "")+ for name in _COMPAT_PROVIDERS+ }+++def _register_compat_providers() -> None:+ """Register every OpenAI-compatible provider into the global registry.++ Each provider gets the same factory (``OpenAIProvider``) with the+ JSON-declared ``base_url`` pinned via ``client_kwargs``. The unifier+ merges this with the user-configured ``{provider}_proxy`` URL (if+ set) at call time — ``OpenAIProvider.__init__`` prefers ``proxy_url``+ over ``base_url`` so custom endpoints override the JSON default.+ """+ base_urls = _load_compat_base_urls()+ for name in _COMPAT_PROVIDERS:+ base_url = base_urls.get(name, "")+ if not base_url:+ logger.warning(+ "skipping compat provider — no base_url in llm_defaults.json",+ provider=name,+ )+ continue+ register_provider(+ ProviderSpec(+ name=name,+ factory=OpenAIProvider,+ sdk_exception_types=(_openai_sdk.OpenAIError,),+ client_kwargs={"base_url": base_url},+ )+ )+++_register_compat_providers()diff --git a/server/services/llm/providers/anthropic.py b/server/services/llm/providers/anthropic.pyindex 5c769fb9..ac3e613c 100644--- a/server/services/llm/providers/anthropic.py+++ b/server/services/llm/providers/anthropic.py@@ -180,3 +180,24 @@ class AnthropicProvider:finish_reason=resp.stop_reason or "stop",raw=resp,)+++# ---------------------------------------------------------------------------+# Plugin self-registration+# ---------------------------------------------------------------------------+# Module load triggers registration into the global ProviderRegistry. The+# eager top-level ``import anthropic`` is required to resolve the typed+# ``APIError`` class used by the unifier's translation layer; the SDK is+# small enough that the cost is in the same band as the existing eager+# ``import openai`` in ``services/ai.py``.++import anthropic as _anthropic_sdk+from services.llm.registry import ProviderSpec, register_provider++register_provider(+ ProviderSpec(+ name="anthropic",+ factory=AnthropicProvider,+ sdk_exception_types=(_anthropic_sdk.APIError,),+ )+)diff --git a/server/services/llm/providers/gemini.py b/server/services/llm/providers/gemini.pyindex b277df3b..ff387d88 100644--- a/server/services/llm/providers/gemini.py+++ b/server/services/llm/providers/gemini.py@@ -203,3 +203,25 @@ class GeminiProvider:finish_reason=finish,raw=resp,)+++# ---------------------------------------------------------------------------+# Plugin self-registration+# ---------------------------------------------------------------------------+# ``google.genai.errors`` carries the typed ``APIError`` raised on+# Interactions-API-only models (e.g. ``antigravity-preview-05-2026`` —+# the live failure that motivated the unifier introduction). The unifier+# translates it into ``NodeUserError`` at one catch site so the error+# surfaces as a single WARN line through ``BaseNode.execute()`` instead+# of bubbling up as a bare ``RuntimeError`` traceback.++from google.genai import errors as _google_genai_errors+from services.llm.registry import ProviderSpec, register_provider++register_provider(+ ProviderSpec(+ name="gemini",+ factory=GeminiProvider,+ sdk_exception_types=(_google_genai_errors.APIError,),+ )+)diff --git a/server/services/llm/providers/openai.py b/server/services/llm/providers/openai.pyindex cf332ebb..f3dfe146 100644--- a/server/services/llm/providers/openai.py+++ b/server/services/llm/providers/openai.py@@ -174,3 +174,27 @@ class OpenAIProvider:finish_reason=choice.finish_reason or "stop",raw=resp,)+++# ---------------------------------------------------------------------------+# Plugin self-registration+# ---------------------------------------------------------------------------+# Registers ``openai`` into the global registry. The ``openai`` SDK is+# already eagerly imported by ``services/ai.py`` so the module-level+# import here is free (Python caches the module).+#+# OpenAI-compatible providers (xai / deepseek / kimi / mistral / ollama /+# lmstudio) register separately in ``_compat.py`` — they reuse+# ``OpenAIProvider`` as their factory but pin ``base_url`` via+# ``ProviderSpec.client_kwargs`` rather than per-provider Python.++import openai as _openai_sdk+from services.llm.registry import ProviderSpec, register_provider++register_provider(+ ProviderSpec(+ name="openai",+ factory=OpenAIProvider,+ sdk_exception_types=(_openai_sdk.OpenAIError,),+ )+)diff --git a/server/services/llm/providers/openrouter.py b/server/services/llm/providers/openrouter.pyindex 6d4e8748..ffb82fce 100644--- a/server/services/llm/providers/openrouter.py+++ b/server/services/llm/providers/openrouter.py@@ -78,3 +78,22 @@ class OpenRouterProvider(OpenAIProvider):models.append(display)return sorted(models, key=lambda x: (not x.startswith("[FREE]"), x))+++# ---------------------------------------------------------------------------+# Plugin self-registration+# ---------------------------------------------------------------------------+# OpenRouter rides the OpenAI Python SDK with a different ``base_url`` ++# extra headers, so its typed exceptions are ``openai.OpenAIError``+# subclasses — same exception tuple as the openai provider above.++import openai as _openai_sdk+from services.llm.registry import ProviderSpec, register_provider++register_provider(+ ProviderSpec(+ name="openrouter",+ factory=OpenRouterProvider,+ sdk_exception_types=(_openai_sdk.OpenAIError,),+ )+)diff --git a/server/services/llm/registry.py b/server/services/llm/registry.pynew file mode 100644index 00000000..8c5baa80--- /dev/null+++ b/server/services/llm/registry.py@@ -0,0 +1,111 @@+"""Provider registry — every LLM provider self-registers here at import time.++Plugin-shape backbone for the chat-model service layer. Each provider module+calls ``register_provider(ProviderSpec(...))`` at top level, and the unifier+reads this registry to dispatch chat / fetch_models calls and to translate+typed SDK exceptions into ``NodeUserError``. No per-provider Python lives+inside ``services/ai.py`` after this layer is wired.+"""++from __future__ import annotations++from dataclasses import dataclass, field+from typing import Any, Callable, Dict, List, Tuple, Type++from core.logging import get_logger+from services.llm.protocol import LLMProvider+from services.plugin import NodeUserError++logger = get_logger(__name__)+++@dataclass(frozen=True)+class ProviderSpec:+ """Declarative spec for a chat-model provider plugin.++ Fields:+ name: registry key — matches the ``provider`` string used by+ ai.py, the chat-model node ``provider`` field, and the+ ``providers.<name>`` block in ``llm_defaults.json``.+ factory: callable returning an ``LLMProvider`` instance.+ Invoked as ``factory(api_key=..., proxy_url=..., **client_kwargs)``.+ sdk_exception_types: tuple of typed SDK error classes raised by+ this provider's underlying SDK. The unifier wraps a single+ ``except spec.sdk_exception_types`` around every call site so+ user-correctable errors surface as ``NodeUserError`` without+ a per-provider branch in ai.py.+ client_kwargs: static keyword arguments passed to ``factory`` on+ every instantiation. Used by OpenAI-compatible providers+ (xai / deepseek / kimi / mistral / ollama / lmstudio / groq /+ cerebras) to pin ``base_url`` from JSON config.+ """++ name: str+ factory: Callable[..., LLMProvider]+ sdk_exception_types: Tuple[Type[Exception], ...]+ client_kwargs: Dict[str, Any] = field(default_factory=dict)+++_REGISTRY: Dict[str, ProviderSpec] = {}+++def register_provider(spec: ProviderSpec) -> None:+ """Register a provider plugin.++ Called from each provider module's top level on import. The unifier+ expects every registered provider to declare at least one typed SDK+ exception so the wrapper try/except can translate it.++ Re-registration with an identical spec is a no-op (handles uvicorn+ reload cycles). Re-registration with a different spec raises so+ accidental shadowing is loud.+ """+ if not spec.sdk_exception_types:+ raise ValueError(+ f"ProviderSpec({spec.name!r}) declares empty sdk_exception_types. "+ "Every provider must surface its typed SDK error class so the "+ "unifier can translate it into NodeUserError."+ )+ existing = _REGISTRY.get(spec.name)+ if existing is not None and existing != spec:+ raise ValueError(+ f"Provider {spec.name!r} already registered with a different spec. "+ f"Existing: {existing!r}; new: {spec!r}."+ )+ _REGISTRY[spec.name] = spec+ logger.debug("registered LLM provider", provider=spec.name)+++def get_provider(name: str) -> ProviderSpec:+ """Look up a provider spec by name.++ Raises ``NodeUserError`` on unknown providers so the failure surfaces+ cleanly through ``BaseNode.execute()`` as a single WARN line — same+ contract as every other user-correctable error in the framework.+ """+ spec = _REGISTRY.get(name)+ if spec is None:+ raise NodeUserError(+ f"Unknown LLM provider: {name!r}. "+ f"Registered providers: {sorted(_REGISTRY)}"+ )+ return spec+++def all_providers() -> List[str]:+ """Return sorted list of registered provider names."""+ return sorted(_REGISTRY)+++def has_provider(name: str) -> bool:+ """Cheap membership probe — does not raise on miss."""+ return name in _REGISTRY+++def _reset_for_tests() -> None:+ """Test-only — drop every registered provider.++ Lets unit tests around the registry control the state instead of+ inheriting the production population. Never call from runtime code.+ """+ _REGISTRY.clear()diff --git a/server/services/llm/unifier.py b/server/services/llm/unifier.pynew file mode 100644index 00000000..34abe237--- /dev/null+++ b/server/services/llm/unifier.py@@ -0,0 +1,132 @@+"""ChatUnifier — the single SERVICE facade for chat-model dispatch.++Reads the ``ProviderRegistry`` to route ``chat`` and ``fetch_models`` calls+to the right provider implementation, translates each provider's typed+SDK exceptions into ``NodeUserError`` at one catch site, and applies the+``incompatible_models`` JSON filter uniformly. ``services/ai.py`` delegates+to this class — there is no per-provider Python anywhere else.++Wired into the DI container once at startup with the parsed+``llm_defaults.json`` + the ``AuthService`` (for ``{provider}_proxy``+credential lookups).+"""++from __future__ import annotations++from typing import Any, Dict, List, Optional, TYPE_CHECKING++from core.logging import get_logger+from services.llm.protocol import LLMProvider, LLMResponse, Message, ThinkingConfig, ToolDef+from services.llm.registry import ProviderSpec, get_provider, has_provider+from services.plugin import NodeUserError++if TYPE_CHECKING:+ from services.auth import AuthService++logger = get_logger(__name__)+++class ChatUnifier:+ """Single facade for chat-model execution.++ Construction: one instance lives in the DI container, sharing+ ``llm_defaults.json`` + ``AuthService`` with the rest of the backend.++ Public surface: ``chat()``, ``fetch_models()``, ``is_registered()``.+ Everything else is private.+ """++ def __init__(self, defaults: Dict[str, Any], auth_service: "AuthService"):+ self._defaults = defaults+ self._auth = auth_service++ # ------------------------------------------------------------------+ # public API+ # ------------------------------------------------------------------++ async def chat(+ self,+ *,+ provider: str,+ api_key: str,+ messages: List[Message],+ model: str,+ temperature: float = 0.7,+ max_tokens: int = 4096,+ thinking: Optional[ThinkingConfig] = None,+ tools: Optional[List[ToolDef]] = None,+ ) -> LLMResponse:+ """Execute a chat completion against the named provider.++ Raises ``NodeUserError`` on typed SDK failures (bad key, context+ overflow, missing model, server unreachable, …) — every other+ exception flows through unchanged so genuine server bugs keep+ their full traceback via ``BaseNode.execute()`` 's generic+ ``except Exception``.+ """+ spec = get_provider(provider)+ client = await self._build_client(spec, api_key)+ try:+ return await client.chat(+ messages,+ model=model,+ temperature=temperature,+ max_tokens=max_tokens,+ thinking=thinking,+ tools=tools,+ )+ except spec.sdk_exception_types as e:+ raise NodeUserError(str(e)) from e++ async def fetch_models(self, *, provider: str, api_key: str) -> List[str]:+ """List available models from the named provider.++ Applies the JSON-driven ``incompatible_models`` filter+ (``providers.<name>.incompatible_models`` in ``llm_defaults.json``)+ uniformly. An absent key is a no-op — every provider gets the+ filter for free without per-provider Python.+ """+ spec = get_provider(provider)+ client = await self._build_client(spec, api_key)+ try:+ models = await client.fetch_models(api_key)+ except spec.sdk_exception_types as e:+ raise NodeUserError(str(e)) from e+ blocklist = self._incompatible_models(provider)+ if not blocklist:+ return models+ return [m for m in models if m not in blocklist]++ def is_registered(self, provider: str) -> bool:+ """Cheap probe used by callers that want graceful fallback when a+ provider is not wired into the registry.++ Replaces the legacy ``is_native_provider`` function in+ ``services/llm/factory.py`` — the unifier IS the routing layer,+ so registry membership is the source of truth.+ """+ return has_provider(provider)++ # ------------------------------------------------------------------+ # internals+ # ------------------------------------------------------------------++ async def _build_client(self, spec: ProviderSpec, api_key: str) -> LLMProvider:+ """Instantiate the provider implementation.++ Pulls the user-configured ``{provider}_proxy`` URL from the+ encrypted credentials store (matches the legacy ai.py behavior)+ and merges it with the provider's static ``client_kwargs`` (used+ by OpenAI-compatible providers to pin their ``base_url``).+ """+ proxy_url = await self._auth.get_api_key(f"{spec.name}_proxy")+ return spec.factory(api_key=api_key, proxy_url=proxy_url, **spec.client_kwargs)++ def _incompatible_models(self, provider: str) -> set[str]:+ """Read ``providers.<name>.incompatible_models`` from llm_defaults.json."""+ raw = (+ self._defaults.get("providers", {})+ .get(provider, {})+ .get("incompatible_models")+ )+ return set(raw or ())diff --git a/server/tests/llm/test_live_providers.py b/server/tests/llm/test_live_providers.pynew file mode 100644index 00000000..72d2dc29--- /dev/null+++ b/server/tests/llm/test_live_providers.py@@ -0,0 +1,289 @@+"""Live-API integration tests for the ChatUnifier and every native provider.++**Marker**: ``@pytest.mark.live`` — these tests hit real LLM endpoints+and **incur charges** on paid plans. They are excluded from default+pytest runs; opt in explicitly:++ pytest -m live # all live providers+ pytest -m live tests/llm/test_live_providers.py # this file only++**Credentials**: each provider's API key is read from the environment+or from the ``.env`` file at the repo root. Missing keys cause that+provider's tests to skip — they never fail. Recognised env vars:++ ANTHROPIC_API_KEY → anthropic+ OPENAI_API_KEY → openai+ GEMINI_API_KEY / GOOGLE_API_KEY → gemini+ OPENROUTER_API_KEY → openrouter+ XAI_API_KEY / GROK_API_KEY → xai+ DEEPSEEK_API_KEY → deepseek+ KIMI_API_KEY / MOONSHOT_API_KEY → kimi+ MISTRAL_API_KEY → mistral+ OLLAMA_BASE_URL → ollama (override default localhost:11434)+ LMSTUDIO_BASE_URL → lmstudio (override default localhost:1234)++**Scope**: each enabled provider gets two assertions —+ 1. ``ChatUnifier.fetch_models`` returns a non-empty list.+ 2. ``ChatUnifier.chat`` returns non-empty content for a 1-token "hi" call.++The tests use the smallest available model + ``max_tokens=16`` to keep+spend negligible. Total cost per full run with all 4 cloud keys+present: well under $0.01 at 2026 prices.++**Why this file is opt-in, not always-on**: the unit/mock tests in+``test_unifier_typed_errors.py`` + ``test_unifier_incompatible_models_filter.py``++ ``test_wiring.py`` cover the delegation contract without spending+money. Live tests are a smoke check that the SDK shape, auth headers,+and the unifier dispatch still match what the real APIs accept — run+them after dependency bumps or before a release, not on every commit.+"""++from __future__ import annotations++import os+from pathlib import Path+from typing import Optional++import pytest+from unittest.mock import AsyncMock, MagicMock++import services.llm # noqa: F401 — populate the provider registry+from services.llm.config import LLM_DEFAULTS+from services.llm.protocol import Message+from services.llm.registry import get_provider, has_provider+from services.llm.unifier import ChatUnifier+++# ---------------------------------------------------------------------------+# .env loading — opt-in (live tests need real keys)+# ---------------------------------------------------------------------------+++def _load_dotenv_from_repo_root() -> None:+ """Load ``.env`` from the worktree root so live tests can read API keys.++ Walks up from this test file to find the first ``.env`` and loads+ it via ``python-dotenv``. Existing environment variables win over+ ``.env`` values so CI can override per-run.+ """+ try:+ from dotenv import load_dotenv+ except ImportError:+ return # python-dotenv missing — fall back to OS env only++ here = Path(__file__).resolve()+ for parent in [here.parent, *here.parents]:+ candidate = parent / ".env"+ if candidate.exists():+ load_dotenv(candidate, override=False)+ return+++_load_dotenv_from_repo_root()+++# ---------------------------------------------------------------------------+# Per-provider env-key resolution+# ---------------------------------------------------------------------------+++def _api_key(*names: str) -> Optional[str]:+ """Return the first non-empty env value among ``names`` (priority order)."""+ for n in names:+ val = os.environ.get(n)+ if val and val.strip():+ return val.strip()+ return None+++def _local_base_url(env_name: str, default: str) -> str:+ """Resolve a local-server base URL with env override."""+ return (os.environ.get(env_name) or default).strip()+++# Provider → (env-var lookup, default smallest model). Local providers+# (ollama / lmstudio) carry no default model — they reflect whatever+# the user has loaded; the live tests skip if the server isn't+# reachable.+_PROVIDER_KEYS = {+ "anthropic": ("ANTHROPIC_API_KEY",),+ "openai": ("OPENAI_API_KEY",),+ "gemini": ("GEMINI_API_KEY", "GOOGLE_API_KEY"),+ "openrouter": ("OPENROUTER_API_KEY",),+ "xai": ("XAI_API_KEY", "GROK_API_KEY"),+ "deepseek": ("DEEPSEEK_API_KEY",),+ "kimi": ("KIMI_API_KEY", "MOONSHOT_API_KEY"),+ "mistral": ("MISTRAL_API_KEY",),+}++# Models chosen for low cost + broad availability. Falls back to the+# provider's ``default_model`` from llm_defaults.json if the live API+# rejects the pinned one.+_LIVE_MODELS = {+ "anthropic": "claude-haiku-4-5",+ "openai": "gpt-4o-mini",+ "gemini": "gemini-2.5-flash",+ "openrouter": "anthropic/claude-haiku-4.5",+ "xai": "grok-3",+ "deepseek": "deepseek-chat",+ "kimi": "kimi-k2.6",+ "mistral": "mistral-small-latest",+ "ollama": None, # discovered from server+ "lmstudio": None,+}+++def _resolve_live_model(provider: str, fetched: list[str]) -> Optional[str]:+ """Pick a real model name for the chat round-trip.++ If the pinned ``_LIVE_MODELS`` entry is in the fetched list, use it.+ Otherwise fall back to ``providers.<name>.default_model`` from JSON.+ Local providers (ollama/lmstudio) return the first non-empty entry+ in the fetched list.+ """+ pinned = _LIVE_MODELS.get(provider)+ if pinned and pinned in fetched:+ return pinned+ json_default = LLM_DEFAULTS.get("providers", {}).get(provider, {}).get("default_model")+ if json_default and json_default in fetched:+ return json_default+ return fetched[0] if fetched else None+++# ---------------------------------------------------------------------------+# Unifier fixture — wired against a stub auth_service that returns the+# user-configured {provider}_proxy URL from the environment (so the+# Ollama / LM Studio paths still work when the user has a custom+# endpoint). Cloud providers ignore proxy_url and use their default+# base_url + the api_key passed to chat().+# ---------------------------------------------------------------------------+++def live_unifier():+ """ChatUnifier wired against real env credentials."""++ async def _get_api_key(provider_proxy_key: str):+ # provider_proxy_key looks like "ollama_proxy" / "lmstudio_proxy"+ if provider_proxy_key == "ollama_proxy":+ return _local_base_url("OLLAMA_BASE_URL", "")+ if provider_proxy_key == "lmstudio_proxy":+ return _local_base_url("LMSTUDIO_BASE_URL", "")+ return None # cloud providers don't use proxy_url++ auth = MagicMock()+ auth.get_api_key = AsyncMock(side_effect=_get_api_key)+ return ChatUnifier(defaults=LLM_DEFAULTS, auth_service=auth)+++# ---------------------------------------------------------------------------+# Cloud-provider live tests+# ---------------------------------------------------------------------------++[email protected]("provider", sorted(_PROVIDER_KEYS.keys()))+async def test_live_fetch_models_returns_non_empty(live_unifier, provider):+ """``ChatUnifier.fetch_models`` returns at least one model from the live API."""+ api_key = _api_key(*_PROVIDER_KEYS[provider])+ if not api_key:+ pytest.skip(f"no API key set for {provider} ({' / '.join(_PROVIDER_KEYS[provider])})")++ assert has_provider(provider), f"provider {provider!r} not in registry"++ models = await live_unifier.fetch_models(provider=provider, api_key=api_key)+ assert isinstance(models, list), f"{provider} fetch_models returned non-list: {type(models)}"+ assert models, f"{provider} fetch_models returned an empty list"++[email protected]("provider", sorted(_PROVIDER_KEYS.keys()))+async def test_live_chat_round_trip_returns_content(live_unifier, provider):+ """``ChatUnifier.chat`` round-trip returns non-empty content from the live API."""+ api_key = _api_key(*_PROVIDER_KEYS[provider])+ if not api_key:+ pytest.skip(f"no API key set for {provider} ({' / '.join(_PROVIDER_KEYS[provider])})")++ models = await live_unifier.fetch_models(provider=provider, api_key=api_key)+ model = _resolve_live_model(provider, models)+ if model is None:+ pytest.skip(f"{provider}: live model list empty — nothing to call")++ response = await live_unifier.chat(+ provider=provider,+ api_key=api_key,+ messages=[Message(role="user", content="Say hi in 3 words.")],+ model=model,+ temperature=0.0,+ max_tokens=16,+ )+ assert response.content, f"{provider} ({model}) returned empty content: {response!r}"+++# ---------------------------------------------------------------------------+# Local-server live tests (ollama / lmstudio)+# ---------------------------------------------------------------------------++[email protected]("provider,env_var,default_url", [+ ("ollama", "OLLAMA_BASE_URL", "http://localhost:11434/v1"),+ ("lmstudio", "LMSTUDIO_BASE_URL", "http://localhost:1234/v1"),+])+async def test_live_local_server_fetch_models(live_unifier, provider, env_var, default_url):+ """Local servers (ollama / lmstudio) — fetch the user's loaded models."""+ base_url = _local_base_url(env_var, default_url)+ # Probe whether the server is actually reachable; skip cleanly if not.+ try:+ import httpx++ async with httpx.AsyncClient(timeout=2.0) as client:+ r = await client.get(f"{base_url}/models")+ r.raise_for_status()+ except Exception as e:+ pytest.skip(f"{provider} server not reachable at {base_url}: {e}")++ # Local providers don't need a real API key — pass a placeholder.+ models = await live_unifier.fetch_models(provider=provider, api_key="placeholder")+ assert isinstance(models, list)+ # We do NOT assert non-empty — a running server with zero loaded+ # models is a legitimate state (e.g. user just started Ollama and+ # hasn't pulled anything). The unifier path is exercised either way.+++# ---------------------------------------------------------------------------+# Cross-cutting smoke: incompatible_models filter on gemini live+# ---------------------------------------------------------------------------+++async def test_live_gemini_filters_antigravity_from_dropdown(live_unifier):+ """Live gemini fetch_models hides the JSON-declared antigravity model.++ This is the end-to-end verification of the Phase A4 hotfix — even+ if the upstream Gemini Models API surfaces the preview, our unifier+ must drop it from the dropdown so the chat-model node can't select+ an Interactions-API-only model and crash.+ """+ api_key = _api_key(*_PROVIDER_KEYS["gemini"])+ if not api_key:+ pytest.skip("no API key set for gemini (GEMINI_API_KEY / GOOGLE_API_KEY)")++ models = await live_unifier.fetch_models(provider="gemini", api_key=api_key)+ incompatible = set(+ LLM_DEFAULTS.get("providers", {}).get("gemini", {}).get("incompatible_models", [])+ )+ if not incompatible:+ pytest.skip("no gemini.incompatible_models declared in llm_defaults.json")++ for forbidden in incompatible:+ assert forbidden not in models, (+ f"gemini fetch_models returned a model that llm_defaults.json "+ f"marks as incompatible: {forbidden!r}. The filter is not "+ f"applied — the user would be able to pick it from the "+ f"dropdown and the chat call would surface a typed APIError."+ )diff --git a/server/tests/llm/test_plugin_shape.py b/server/tests/llm/test_plugin_shape.pynew file mode 100644index 00000000..26bac851--- /dev/null+++ b/server/tests/llm/test_plugin_shape.py@@ -0,0 +1,168 @@+"""Plugin-shape invariants — locks the modular architecture.++The chat-model service layer follows the project's plugin pattern+(Wave 11.H): each LLM provider self-registers into the registry and the+unifier dispatches by name. These tests fail loudly if anyone bolts+per-provider Python back into ``services/ai.py``.++Lifecycle: the tests run via ``pytest`` (no server start needed). They+introspect source files with ``ast`` + regex — same shape as+``tests/test_credential_broadcasts.py`` and ``tests/test_plugin_self_containment.py``.+"""++import ast+import re+from pathlib import Path++import pytest++import services.llm # noqa: F401 — populate registry+from services.llm.registry import all_providers, get_provider+++SERVER_ROOT = Path(__file__).resolve().parent.parent.parent+AI_PY = SERVER_ROOT / "services" / "ai.py"+PROVIDERS_DIR = SERVER_ROOT / "services" / "llm" / "providers"+++# ---------------------------------------------------------------------------+# 1. Every registered provider has a corresponding module under providers/+# ---------------------------------------------------------------------------+++def test_every_provider_has_a_module_or_is_registered_by_compat():+ """Plugin-folder invariant: registry membership implies an on-disk module.++ Dedicated providers (anthropic / openai / gemini / openrouter) live+ in their own file. OpenAI-compat providers (xai / deepseek / kimi /+ mistral / ollama / lmstudio) all register through ``_compat.py``+ using the same ``OpenAIProvider`` factory.+ """+ dedicated_files = {p.stem for p in PROVIDERS_DIR.glob("*.py") if not p.name.startswith("_")}+ for provider in all_providers():+ spec = get_provider(provider)+ # Either the provider has its own file, OR it's a compat+ # provider registered by ``_compat.py`` with ``OpenAIProvider``.+ if provider in dedicated_files:+ continue+ # Otherwise the factory must be ``OpenAIProvider`` (the compat shape)+ from services.llm.providers.openai import OpenAIProvider++ assert spec.factory is OpenAIProvider, (+ f"provider {provider!r} has no dedicated module and doesn't use "+ f"OpenAIProvider — registered factory is {spec.factory!r}"+ )+++# ---------------------------------------------------------------------------+# 2. No per-provider Python inside execute_chat / fetch_models bodies+# ---------------------------------------------------------------------------+#+# Scoped contract: Phase A only refactored the chat-model node path+# (``execute_chat`` + ``fetch_models``). The agent paths (``execute_agent``,+# ``execute_chat_agent``) keep their ``except openai.OpenAIError`` blocks+# until Phase G migrates the agent loop off LangChain. AST-walking each+# method body avoids false positives from those still-LangChain code+# paths. Phase G should extend this test to cover the agent methods.+++def _method_source(class_name: str, method_name: str, source: str) -> str:+ """Return the source text of one method inside one class."""+ tree = ast.parse(source)+ for node in ast.walk(tree):+ if isinstance(node, ast.ClassDef) and node.name == class_name:+ for item in node.body:+ if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)) and item.name == method_name:+ return ast.get_source_segment(source, item) or ""+ pytest.fail(f"{class_name}.{method_name} not found in services/ai.py")+++_FORBIDDEN_PATTERNS_IN_UNIFIED_METHODS = (+ # Per-provider except blocks (unifier owns these now)+ r"except\s+openai\.OpenAIError",+ r"except\s+anthropic\.",+ r"except\s+google\.genai\.",+ # Per-provider equality checks (registry membership is the gate)+ r'if\s+provider\s*==\s*[\'\"]openai[\'\"]\b',+ r'if\s+provider\s*==\s*[\'\"]anthropic[\'\"]\b',+ r'if\s+provider\s*==\s*[\'\"]gemini[\'\"]\b',+ r'if\s+provider\s*==\s*[\'\"]openrouter[\'\"]\b',+ r'if\s+provider\s*==\s*[\'\"]groq[\'\"]\b',+ r'if\s+provider\s*==\s*[\'\"]cerebras[\'\"]\b',+ # Direct calls to legacy factory — the unifier owns provider instantiation+ r"create_provider\s*\(",+ # Native-vs-LangChain gating — Phase D moved every provider into+ # the unifier so this branch is gone. Phase G removes it from the+ # agent paths too; until then this contract only covers the+ # chat-model methods.+ r"is_native_provider\s*\(",+ # LangChain ChatModel construction — Phase D removed this from+ # the chat-model methods. Phase G removes it from the agent paths.+ r"self\.create_model\s*\(",+ r"chat_model\.invoke\s*\(",+ r"chat_model\.ainvoke\s*\(",+)++[email protected]("method_name", ["execute_chat", "fetch_models"])+def test_unified_methods_have_no_per_provider_python(method_name):+ """``execute_chat`` and ``fetch_models`` must delegate to the unifier+ instead of carrying per-provider branches or typed-exception blocks."""+ source = AI_PY.read_text(encoding="utf-8")+ method_src = _method_source("AIService", method_name, source)+ for pattern in _FORBIDDEN_PATTERNS_IN_UNIFIED_METHODS:+ matches = re.findall(pattern, method_src)+ assert not matches, (+ f"AIService.{method_name} contains forbidden per-provider pattern "+ f"{pattern!r}: {matches!r}. The unifier owns this responsibility — "+ f"per-provider logic belongs in the provider's plugin folder."+ )+++# ---------------------------------------------------------------------------+# 3. ProviderSpec.sdk_exception_types is non-empty for every registered provider+# ---------------------------------------------------------------------------+++def test_every_provider_declares_sdk_exception_types():+ """The unifier needs the typed-error tuple to translate SDK errors.++ An empty tuple would silently fall through to the generic+ ``except Exception`` in ``BaseNode.execute()`` and emit a full+ traceback for what should be a user-correctable error.+ """+ for provider in all_providers():+ spec = get_provider(provider)+ assert spec.sdk_exception_types, (+ f"provider {provider!r} has empty sdk_exception_types — typed "+ f"SDK errors would surface as bare RuntimeErrors with tracebacks "+ f"instead of clean NodeUserError envelopes."+ )+ # And every tuple member must be an exception class+ for exc in spec.sdk_exception_types:+ assert isinstance(exc, type) and issubclass(exc, BaseException), (+ f"provider {provider!r} sdk_exception_types contains a non-exception: {exc!r}"+ )+++# ---------------------------------------------------------------------------+# 4. ai.py imports ChatUnifier somewhere (delegation contract)+# ---------------------------------------------------------------------------+++def test_ai_service_init_accepts_chat_unifier_kwarg():+ """``AIService.__init__`` must accept ``chat_unifier`` so DI can wire it."""+ source = AI_PY.read_text(encoding="utf-8")+ tree = ast.parse(source)+ for node in ast.walk(tree):+ if isinstance(node, ast.ClassDef) and node.name == "AIService":+ for item in node.body:+ if isinstance(item, ast.FunctionDef) and item.name == "__init__":+ arg_names = {a.arg for a in item.args.args}+ assert "chat_unifier" in arg_names, (+ "AIService.__init__ does not accept chat_unifier — "+ "the DI container can't inject the unifier."+ )+ return+ pytest.fail("AIService class found but has no __init__")+ pytest.fail("AIService class not found in services/ai.py")diff --git a/server/tests/llm/test_provider_self_registration.py b/server/tests/llm/test_provider_self_registration.pynew file mode 100644index 00000000..110c9f90--- /dev/null+++ b/server/tests/llm/test_provider_self_registration.py@@ -0,0 +1,82 @@+"""Phase A1 contract — every shipped provider self-registers on import.++Locks the plugin shape: importing ``services.llm`` (and transitively+``services.llm.providers``) must populate the global registry with the+full set of native + OpenAI-compat providers. If any provider drops its+``register_provider(...)`` call, this test catches it.+"""++import pytest++import services.llm # noqa: F401 — side-effect import populates the registry+from services.llm.registry import all_providers, get_provider, has_provider+++EXPECTED_REGISTERED_PROVIDERS = {+ # Dedicated SDKs+ "anthropic",+ "openai",+ "gemini",+ "openrouter",+ # OpenAI-compatible providers (registered via _compat.py)+ "xai",+ "deepseek",+ "kimi",+ "mistral",+ "ollama",+ "lmstudio",+ # Migrated from LangChain fallback in Phase D — both expose+ # OpenAI-compatible /v1 endpoints so they share OpenAIProvider.+ "groq",+ "cerebras",+}+++def test_all_expected_providers_registered():+ """Every native + compat provider populates the registry on import."""+ assert set(all_providers()) >= EXPECTED_REGISTERED_PROVIDERS+++def test_dedicated_providers_have_typed_sdk_exceptions():+ """The four dedicated SDKs declare their typed exception classes."""+ import anthropic+ import openai+ from google.genai import errors as google_genai_errors++ assert get_provider("anthropic").sdk_exception_types == (anthropic.APIError,)+ assert get_provider("openai").sdk_exception_types == (openai.OpenAIError,)+ assert get_provider("gemini").sdk_exception_types == (google_genai_errors.APIError,)+ assert get_provider("openrouter").sdk_exception_types == (openai.OpenAIError,)+++def test_compat_providers_carry_base_url_in_client_kwargs():+ """Every OpenAI-compat provider pins its base_url declaratively."""+ expected_base_urls = {+ "xai": "https://api.x.ai/v1",+ "deepseek": "https://api.deepseek.com",+ "kimi": "https://api.moonshot.ai/v1",+ "mistral": "https://api.mistral.ai/v1",+ "ollama": "http://localhost:11434/v1",+ "lmstudio": "http://localhost:1234/v1",+ "groq": "https://api.groq.com/openai/v1",+ "cerebras": "https://api.cerebras.ai/v1",+ }+ for name, url in expected_base_urls.items():+ spec = get_provider(name)+ assert spec.client_kwargs.get("base_url") == url, (+ f"{name}: expected base_url={url!r}, got {spec.client_kwargs!r}"+ )+++def test_unknown_provider_raises_node_user_error():+ """Unknown provider lookups surface as NodeUserError (user-correctable)."""+ from services.plugin import NodeUserError++ with pytest.raises(NodeUserError, match="Unknown LLM provider"):+ get_provider("definitely-not-real")+++def test_has_provider_does_not_raise():+ """``has_provider`` is the cheap membership probe used by ai.py."""+ assert has_provider("anthropic") is True+ assert has_provider("definitely-not-real") is Falsediff --git a/server/tests/llm/test_unifier_incompatible_models_filter.py b/server/tests/llm/test_unifier_incompatible_models_filter.pynew file mode 100644index 00000000..0030b47a--- /dev/null+++ b/server/tests/llm/test_unifier_incompatible_models_filter.py@@ -0,0 +1,106 @@+"""Phase A4 contract — ChatUnifier filters ``incompatible_models`` from fetch_models.++JSON entry: ``providers.<name>.incompatible_models`` in+``llm_defaults.json``. The unifier applies the filter uniformly so+adding an entry is a pure JSON edit — no per-provider Python.++The current motivating case is ``antigravity-preview-05-2026`` on+gemini, which requires the Interactions API and surfaces as an+``APIError`` if selected. Filtering it from the dropdown prevents the+failure at the source.+"""++import pytest+from unittest.mock import AsyncMock, MagicMock++import services.llm # noqa: F401 — populate registry+from services.llm.registry import ProviderSpec, _reset_for_tests+from services.llm.unifier import ChatUnifier+from services.llm.providers.openai import OpenAIProvider+++def auth_service_stub():+ stub = MagicMock()+ stub.get_api_key = AsyncMock(return_value=None)+ return stub+++def _swap_provider_factory(name: str, models: list[str]):+ """Replace the registered provider's factory so fetch_models returns ``models``."""+ from services.llm import registry as _registry++ original = _registry._REGISTRY[name]+ stub_client = MagicMock()+ stub_client.fetch_models = AsyncMock(return_value=models)+ _registry._REGISTRY[name] = ProviderSpec(+ name=original.name,+ factory=lambda **kwargs: stub_client,+ sdk_exception_types=original.sdk_exception_types,+ client_kwargs=original.client_kwargs,+ )+ return original+++def _restore(name, original):+ from services.llm import registry as _registry++ _registry._REGISTRY[name] = original+++async def test_gemini_filters_antigravity_preview(auth_service_stub):+ """The motivating case — antigravity model never reaches the dropdown."""+ defaults = {+ "providers": {+ "gemini": {+ "incompatible_models": ["antigravity-preview-05-2026"],+ }+ }+ }+ unifier = ChatUnifier(defaults=defaults, auth_service=auth_service_stub)+ original = _swap_provider_factory(+ "gemini",+ [+ "gemini-3-pro-preview",+ "gemini-flash-latest",+ "antigravity-preview-05-2026",+ "gemini-2.5-pro",+ ],+ )+ try:+ models = await unifier.fetch_models(provider="gemini", api_key="key")+ assert "antigravity-preview-05-2026" not in models+ assert "gemini-3-pro-preview" in models+ assert "gemini-flash-latest" in models+ assert "gemini-2.5-pro" in models+ finally:+ _restore("gemini", original)+++async def test_no_filter_when_json_key_absent(auth_service_stub):+ """A provider without an ``incompatible_models`` JSON key passes through unchanged."""+ defaults = {"providers": {"anthropic": {}}}+ unifier = ChatUnifier(defaults=defaults, auth_service=auth_service_stub)+ original = _swap_provider_factory(+ "anthropic", ["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5"]+ )+ try:+ models = await unifier.fetch_models(provider="anthropic", api_key="sk-test")+ assert models == ["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5"]+ finally:+ _restore("anthropic", original)+++async def test_empty_filter_list_is_noop(auth_service_stub):+ """An empty list is treated the same as a missing key."""+ defaults = {"providers": {"openai": {"incompatible_models": []}}}+ unifier = ChatUnifier(defaults=defaults, auth_service=auth_service_stub)+ original = _swap_provider_factory("openai", ["gpt-5", "gpt-4o"])+ try:+ models = await unifier.fetch_models(provider="openai", api_key="sk-test")+ assert models == ["gpt-5", "gpt-4o"]+ finally:+ _restore("openai", original)diff --git a/server/tests/llm/test_unifier_typed_errors.py b/server/tests/llm/test_unifier_typed_errors.pynew file mode 100644index 00000000..c6d0bdc6--- /dev/null+++ b/server/tests/llm/test_unifier_typed_errors.py@@ -0,0 +1,145 @@+"""Phase A1+A3 contract — ChatUnifier translates typed SDK exceptions into NodeUserError.++For each registered provider, simulate the typed SDK error its+``ProviderSpec.sdk_exception_types`` declares and assert the unifier+wraps it into ``NodeUserError``. Replaces the per-provider+``except openai.OpenAIError`` block that previously lived in ai.py.+"""++import pytest+import anthropic+import openai+from google.genai import errors as google_genai_errors+from unittest.mock import AsyncMock, MagicMock++import services.llm # noqa: F401 — populate registry+from services.llm.registry import ProviderSpec, register_provider, _reset_for_tests, get_provider+from services.llm.unifier import ChatUnifier+from services.llm.protocol import Message+from services.plugin import NodeUserError+++def auth_service_stub():+ """Stub auth_service whose get_api_key returns None for ``{provider}_proxy`` lookups."""+ stub = MagicMock()+ stub.get_api_key = AsyncMock(return_value=None)+ return stub+++def unifier(auth_service_stub):+ """ChatUnifier wired with empty defaults — no incompatible_models filter."""+ return ChatUnifier(defaults={"providers": {}}, auth_service=auth_service_stub)+++def _stub_client_that_raises(exc: Exception):+ """Build a provider client whose chat() / fetch_models() raise ``exc``."""+ client = MagicMock()+ client.chat = AsyncMock(side_effect=exc)+ client.fetch_models = AsyncMock(side_effect=exc)+ return client+++def _replace_factory(provider_name: str, exc: Exception):+ """Re-register the named provider with a factory returning the failing client."""+ original = get_provider(provider_name)+ failing_client = _stub_client_that_raises(exc)+ # Build a wrapping spec — same exception tuple, factory swapped for a stub+ spec = ProviderSpec(+ name=original.name,+ factory=lambda **kwargs: failing_client,+ sdk_exception_types=original.sdk_exception_types,+ client_kwargs=original.client_kwargs,+ )+ # Direct registry write (bypasses register_provider's conflict guard+ # for test purposes). Production code never does this.+ from services.llm import registry as _registry++ _registry._REGISTRY[provider_name] = spec+ return original+++async def test_anthropic_typed_error_becomes_node_user_error(unifier):+ original = _replace_factory("anthropic", anthropic.APIError(message="bad key", request=MagicMock(), body=None))+ try:+ with pytest.raises(NodeUserError, match="bad key"):+ await unifier.chat(+ provider="anthropic",+ api_key="sk-test",+ messages=[Message(role="user", content="hi")],+ model="claude-sonnet-4-6",+ )+ finally:+ from services.llm import registry as _registry++ _registry._REGISTRY["anthropic"] = original+++async def test_openai_typed_error_becomes_node_user_error(unifier):+ original = _replace_factory("openai", openai.AuthenticationError(message="bad key", response=MagicMock(), body=None))+ try:+ with pytest.raises(NodeUserError, match="bad key"):+ await unifier.chat(+ provider="openai",+ api_key="sk-test",+ messages=[Message(role="user", content="hi")],+ model="gpt-5",+ )+ finally:+ from services.llm import registry as _registry++ _registry._REGISTRY["openai"] = original+++async def test_gemini_typed_error_becomes_node_user_error(unifier):+ # The motivating bug — antigravity-preview hits an APIError because+ # it requires the Interactions API. The unifier must surface this as+ # NodeUserError without a traceback.+ original = _replace_factory(+ "gemini",+ google_genai_errors.APIError(code=400, response_json={"message": "This model only supports Interactions API."}),+ )+ try:+ with pytest.raises(NodeUserError, match="Interactions API"):+ await unifier.chat(+ provider="gemini",+ api_key="key",+ messages=[Message(role="user", content="hi")],+ model="antigravity-preview-05-2026",+ )+ finally:+ from services.llm import registry as _registry++ _registry._REGISTRY["gemini"] = original+++async def test_openrouter_typed_error_becomes_node_user_error(unifier):+ original = _replace_factory("openrouter", openai.RateLimitError(message="429", response=MagicMock(), body=None))+ try:+ with pytest.raises(NodeUserError, match="429"):+ await unifier.chat(+ provider="openrouter",+ api_key="or-key",+ messages=[Message(role="user", content="hi")],+ model="anthropic/claude-sonnet-4.6",+ )+ finally:+ from services.llm import registry as _registry++ _registry._REGISTRY["openrouter"] = original+++async def test_unknown_provider_raises_node_user_error_directly(unifier):+ with pytest.raises(NodeUserError, match="Unknown LLM provider"):+ await unifier.chat(+ provider="definitely-not-real",+ api_key="key",+ messages=[Message(role="user", content="hi")],+ model="x",+ )diff --git a/server/tests/llm/test_wiring.py b/server/tests/llm/test_wiring.pyindex f8358d5a..8aba1702 100644--- a/server/tests/llm/test_wiring.py+++ b/server/tests/llm/test_wiring.py@@ -1,4 +1,10 @@-"""Test that execute_chat() and fetch_models() route through native providers."""+"""Test that execute_chat() and fetch_models() route through ChatUnifier.++Post-Phase-A3: ``AIService`` delegates every native chat / model-list+call to the injected ``chat_unifier``. These tests confirm the+delegation contract — they DO NOT reach into provider classes any more+(see ``test_unifier_typed_errors.py`` for that layer).+"""from unittest.mock import AsyncMock, MagicMock, patch@@ -9,11 +15,14 @@ from services.llm.protocol import LLMResponse, Usage@pytest.fixturedef ai_service():- """Create an AIService with mocked dependencies."""+ """Create an AIService with a mock chat_unifier injected.++ Stubs the cross-cutting modules that ``services.ai`` imports at the+ top level so test collection doesn't need a real DI container.+ """import sysfrom unittest.mock import MagicMock as MM- # Stub all modules that ai.py imports at top level_stubs = ["core.config","core.container",@@ -28,7 +37,6 @@ def ai_service():if mod not in sys.modules:sys.modules[mod] = MM()- # Ensure core.config.Settings is a mock classsys.modules["core.config"].Settings = MagicMockfrom services.ai import AIService@@ -37,12 +45,24 @@ def ai_service():settings.ai_timeout = 30auth = AsyncMock()auth.get_api_key = AsyncMock(return_value=None) # no proxy- return AIService(auth_service=auth, database=MagicMock(), cache=MagicMock(), settings=settings)++ chat_unifier = MagicMock()+ chat_unifier.is_registered = MagicMock(return_value=True)+ chat_unifier.chat = AsyncMock()+ chat_unifier.fetch_models = AsyncMock()++ return AIService(+ auth_service=auth,+ database=MagicMock(),+ cache=MagicMock(),+ settings=settings,+ chat_unifier=chat_unifier,+ )@pytest.mark.asyncio-async def test_execute_chat_uses_native_openai(ai_service):- """execute_chat with openaiChatModel routes through create_provider, not create_model."""+async def test_execute_chat_delegates_to_unifier_for_openai(ai_service):+ """``execute_chat`` for openaiChatModel hands off to ``chat_unifier.chat``."""fake_resp = LLMResponse(content="Hello from native",thinking=None,@@ -50,17 +70,12 @@ async def test_execute_chat_uses_native_openai(ai_service):model="gpt-5.2",finish_reason="stop",)+ ai_service.chat_unifier.chat.return_value = fake_respwith (- patch("services.ai.create_provider") as mock_factory,patch("services.ai.native_resolve_max_tokens", return_value=4096),patch("services.ai.native_resolve_temperature", return_value=0.7),- patch("services.ai.is_native_provider", return_value=True),):- mock_provider = AsyncMock()- mock_provider.chat = AsyncMock(return_value=fake_resp)- mock_factory.return_value = mock_provider-result = await ai_service.execute_chat(node_id="test-1",node_type="openaiChatModel",@@ -70,57 +85,57 @@ async def test_execute_chat_uses_native_openai(ai_service):assert result["success"] is Trueassert result["result"]["response"] == "Hello from native"assert result["result"]["provider"] == "openai"- mock_factory.assert_called_once()- mock_provider.chat.assert_awaited_once()+ ai_service.chat_unifier.chat.assert_awaited_once()+ call_kwargs = ai_service.chat_unifier.chat.call_args.kwargs+ assert call_kwargs["provider"] == "openai"+ assert call_kwargs["api_key"] == "sk-test"+ assert call_kwargs["model"] == "gpt-5.2"@pytest.mark.asyncio-async def test_execute_chat_uses_langchain_for_groq(ai_service):- """execute_chat with groqChatModel falls back to LangChain create_model."""- mock_response = MagicMock()- mock_response.content = "Hello from groq"+async def test_execute_chat_raises_node_user_error_on_unknown_provider(ai_service):+ """Phase D removed the LangChain fallback. Every provider routes+ through ``ChatUnifier``; unknown providers surface as ``NodeUserError``+ from inside the unifier (``get_provider`` raises) — ``execute_chat``+ catches it via ``except NodeUserError: raise`` so the framework's+ ``BaseNode.execute()`` logs one WARN line with no traceback.+ """+ from services.plugin import NodeUserError++ # Simulate the unifier rejecting an unknown provider.+ ai_service.chat_unifier.chat = AsyncMock(+ side_effect=NodeUserError("Unknown LLM provider: 'unregistered'")+ )with (- patch("services.ai.is_native_provider", return_value=False),- patch.object(ai_service, "create_model", return_value=MagicMock(invoke=MagicMock(return_value=mock_response))),- patch("services.ai.extract_thinking_from_response", return_value=("Hello from groq", None)),- patch("services.ai._resolve_max_tokens", return_value=4096),- patch("services.ai._resolve_temperature", return_value=0.7),+ patch("services.ai.native_resolve_max_tokens", return_value=4096),+ patch("services.ai.native_resolve_temperature", return_value=0.7),):- result = await ai_service.execute_chat(- node_id="test-2",- node_type="groqChatModel",- parameters={"api_key": "gsk-test", "model": "llama-4-scout", "prompt": "Hi"},- )-- assert result["success"] is True- assert result["result"]["response"] == "Hello from groq"- assert result["result"]["provider"] == "groq"+ with pytest.raises(NodeUserError, match="Unknown LLM provider"):+ await ai_service.execute_chat(+ node_id="test-2",+ node_type="someChatModel",+ parameters={"api_key": "x", "model": "y", "prompt": "Hi", "provider": "unregistered"},+ )@pytest.mark.asyncio-async def test_fetch_models_uses_native_for_anthropic(ai_service):- """fetch_models for anthropic delegates to native provider."""+async def test_fetch_models_delegates_to_unifier_for_anthropic(ai_service):+ """``fetch_models`` for anthropic delegates to ``chat_unifier.fetch_models``."""expected_models = ["claude-sonnet-4-6", "claude-opus-4-6"]+ ai_service.chat_unifier.fetch_models.return_value = expected_models- with patch("services.ai.is_native_provider", return_value=True), patch("services.ai.create_provider") as mock_factory:- mock_provider = AsyncMock()- mock_provider.fetch_models = AsyncMock(return_value=expected_models)- mock_factory.return_value = mock_provider-- models = await ai_service.fetch_models("anthropic", "sk-ant-test")+ models = await ai_service.fetch_models("anthropic", "sk-ant-test")assert models == expected_models- # ai.fetch_models forwards `proxy_url` (defaulting to None) to the native- # factory so the Ollama-pattern proxy override path stays uniform with- # execute_chat. Asserting the full call signature including the explicit- # `None` kwarg ensures the proxy path is not silently dropped.- mock_factory.assert_called_once_with("anthropic", "sk-ant-test", proxy_url=None)+ ai_service.chat_unifier.fetch_models.assert_awaited_once_with(+ provider="anthropic", api_key="sk-ant-test"+ )@pytest.mark.asyncio-async def test_execute_chat_native_with_thinking(ai_service):- """execute_chat passes thinking config to native provider."""+async def test_execute_chat_passes_thinking_config_to_unifier(ai_service):+ """``execute_chat`` forwards the thinking config to ``chat_unifier.chat``."""fake_resp = LLMResponse(content="Answer",thinking="Let me think...",@@ -128,17 +143,12 @@ async def test_execute_chat_native_with_thinking(ai_service):model="claude-sonnet-4-6",finish_reason="stop",)+ ai_service.chat_unifier.chat.return_value = fake_respwith (- patch("services.ai.create_provider") as mock_factory,patch("services.ai.native_resolve_max_tokens", return_value=4096),patch("services.ai.native_resolve_temperature", return_value=1.0),- patch("services.ai.is_native_provider", return_value=True),):- mock_provider = AsyncMock()- mock_provider.chat = AsyncMock(return_value=fake_resp)- mock_factory.return_value = mock_provider-result = await ai_service.execute_chat(node_id="test-3",node_type="anthropicChatModel",@@ -155,7 +165,6 @@ async def test_execute_chat_native_with_thinking(ai_service):assert result["result"]["thinking"] == "Let me think..."assert result["result"]["thinking_enabled"] is True- # Verify thinking config was passed to provider.chat- call_kwargs = mock_provider.chat.call_args[1]+ call_kwargs = ai_service.chat_unifier.chat.call_args.kwargsassert call_kwargs["thinking"].enabled is Trueassert call_kwargs["thinking"].budget == 4096