Skip to content

Self-improving AI Employees for everyone

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.json
index 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.py
index 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.toml
index 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.py
index 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: str
class 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_service
self.database = database
self.cache = cache
self.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:
+ raise
except 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_reason
result = {
"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.
+ raise
except 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__.py
index 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_messages
from 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__.py
index 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.py
new file mode 100644
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 False
diff --git a/server/tests/llm/test_unifier_incompatible_models_filter.py b/server/tests/llm/test_unifier_incompatible_models_filter.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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.fixture
def 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 sys
from 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 class
sys.modules["core.config"].Settings = MagicMock
from services.ai import AIService
@@ -37,12 +45,24 @@ def ai_service():
settings.ai_timeout = 30
auth = 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_resp
with (
- 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 True
assert 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_resp
with (
- 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.kwargs
assert call_kwargs["thinking"].enabled is True
assert call_kwargs["thinking"].budget == 4096