Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

feat: add watsonx.ai on-prem provider and update Azure OpenAI (#2339)

Edwin Josef8dd30537667
diff --git a/enhancements/providers/__init__.py b/enhancements/providers/__init__.py
new file mode 100644
index 000000000..ca71d72d0
--- /dev/null
+++ b/enhancements/providers/__init__.py
@@ -0,0 +1 @@
+"""Provider enhancements that extend the generic LiteLLM integration."""
diff --git a/enhancements/providers/registry.py b/enhancements/providers/registry.py
new file mode 100644
index 000000000..dd0297c9d
--- /dev/null
+++ b/enhancements/providers/registry.py
@@ -0,0 +1,44 @@
+"""Registry for provider-specific enhancements.
+
+Most providers use the declarative LiteLLM path. Entries here are reserved for
+deployment shapes that need their own credentials, route alias, model discovery,
+or validation protocol.
+"""
+
+from __future__ import annotations
+
+from types import ModuleType
+
+from enhancements.providers.watsonx import onprem
+
+_ENHANCEMENTS: dict[str, ModuleType] = {
+ onprem.PROVIDER_KEY: onprem,
+}
+
+
+def get(provider: str) -> ModuleType | None:
+ """Return the enhancement registered for an OpenRAG provider key."""
+ return _ENHANCEMENTS.get((provider or "").strip().lower())
+
+
+def route_aliases() -> dict[str, str]:
+ """OpenRAG provider keys that LiteLLM must route under another key."""
+ return {
+ key: enhancement.LITELLM_PROVIDER
+ for key, enhancement in _ENHANCEMENTS.items()
+ if hasattr(enhancement, "LITELLM_PROVIDER")
+ }
+
+
+def credential_field_overrides() -> dict[str, list[dict[str, object]]]:
+ """Settings forms supplied by provider enhancements instead of LiteLLM."""
+ return {
+ key: enhancement.CREDENTIAL_FIELDS
+ for key, enhancement in _ENHANCEMENTS.items()
+ if hasattr(enhancement, "CREDENTIAL_FIELDS")
+ }
+
+
+def enhancements() -> tuple[ModuleType, ...]:
+ """All registered enhancements, for generic catalogue refreshes."""
+ return tuple(_ENHANCEMENTS.values())
diff --git a/enhancements/providers/watsonx/__init__.py b/enhancements/providers/watsonx/__init__.py
new file mode 100644
index 000000000..a922acf78
--- /dev/null
+++ b/enhancements/providers/watsonx/__init__.py
@@ -0,0 +1 @@
+"""IBM watsonx.ai provider enhancements."""
diff --git a/src/services/watsonx_iam.py b/enhancements/providers/watsonx/iam.py
similarity index 100%
rename from src/services/watsonx_iam.py
rename to enhancements/providers/watsonx/iam.py
diff --git a/enhancements/providers/watsonx/onprem.py b/enhancements/providers/watsonx/onprem.py
new file mode 100644
index 000000000..3dc59b040
--- /dev/null
+++ b/enhancements/providers/watsonx/onprem.py
@@ -0,0 +1,659 @@
+"""IBM watsonx.ai running on-premises (Cloud Pak for Data / IBM Software Hub).
+
+The on-prem product speaks the same `/ml/v1/*` REST API as watsonx.ai on IBM
+Cloud, so it routes through LiteLLM's `watsonx` provider — no second transport.
+What differs is everything around the call:
+
+- **Authentication.** IBM Cloud mints an IAM bearer from an API key; a CPD
+ cluster has no IAM. It accepts `Authorization: ZenApiKey <base64(user:apikey)>`
+ instead, which is what an operator's cluster username and API key become here.
+ LiteLLM already knows that scheme (`zen_api_key`), and it is the *only* one
+ that survives both call paths in litellm 1.84: a `token=` kwarg is echoed back
+ into the request body, and a hand-set `Authorization` header is ignored on the
+ embeddings path, which then calls IBM Cloud IAM and fails on a cluster that
+ has no route to it.
+- **Credentials are per-deployment.** A cluster URL, not a region endpoint, and
+ the SaaS provider's `project_id` is usually a deployment `space_id` instead.
+ Most clusters require one: verified against a Cloud Pak for Data 5.x install,
+ every `/ml/v1/text/*` call without one is refused with "Missing either
+ space_id or project_id or wml_instance_crn", and `GET /v2/spaces` is what
+ lists the ids. The watsonx.ai lightweight engine is the exception and has
+ neither — see `install_litellm_compatibility` for what supporting that costs.
+- **Models are whatever the operator deployed**, so the catalogue ids come from
+ `config/model_providers.yaml` rather than LiteLLM's IBM Cloud price table.
+
+- **Models are listed from the cluster**, unfiltered, and split into the two
+ pickers here. The API's `filters` grammar is a SaaS convenience and a cluster
+ that rejects it would empty both pickers; splitting on each entry's own
+ `functions`/`task_ids` cannot fail that way.
+
+The provider key is OpenRAG's own; `LITELLM_PROVIDER` is what it routes as.
+Nothing here imports OpenRAG config — `config_manager`, `model_catalog` and
+`llm_gateway` all read this module, so it has to stay a leaf.
+
+Verified end to end against a Cloud Pak for Data 5.x cluster: ZenApiKey accepted
+on `/ml/v1`, model listing, chat, streaming chat, embeddings and tool calling.
+
+TLS: trusting a cluster's own CA
+--------------------------------
+A CPD cluster is usually fronted by an internal or self-signed CA, and the call
+then fails before it leaves the process::
+
+ litellm.InternalServerError: WatsonxException - Cannot connect to host
+ <cluster>:443 ssl:True [SSLCertVerificationError: ... certificate verify
+ failed: self-signed certificate in certificate chain]
+
+There is no per-provider setting for this, and no OpenRAG one either. LiteLLM
+resolves TLS trust from process-wide environment only — verified against
+litellm 1.84 with a self-signed server, chat and embeddings both:
+
+- ``SSL_CERT_FILE=<path>`` works. **This is the fix.**
+- ``SSL_VERIFY=false`` works, but turns verification off for *every*
+ provider in the process, OpenAI and Anthropic included. Development only.
+- ``ssl_verify=False`` as a per-call kwarg does **not** work: litellm threads it
+ through only some providers, and watsonx is not one of them. It is silently
+ ignored, so do not reach for it.
+
+``SSL_CERT_FILE`` *replaces* certifi's roots rather than adding to them, so
+pointing it at the cluster CA alone breaks every public provider. Concatenate::
+
+ cat "$(python -m certifi)" cluster-ca.crt > /etc/ssl/certs/openrag-ca.pem
+ export SSL_CERT_FILE=/etc/ssl/certs/openrag-ca.pem
+
+In Kubernetes, mount the cluster CA into the backend pod and build that bundle
+in the entrypoint; the operator's ConfigMap is the usual home for the CA. A
+failure that gets this far is reported by the gateway as a trust problem rather
+than as an outage — see ``_UPSTREAM_TLS_MESSAGE`` in ``services/llm_gateway``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import time
+from collections.abc import Mapping
+from typing import Any, NamedTuple, cast
+from urllib.parse import urlsplit, urlunsplit
+
+from utils.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+#: OpenRAG's key for the provider: the name in `model_providers.yaml`, in the
+#: settings payload, and in a `watsonx_onprem:<model>` id.
+PROVIDER_KEY = "watsonx_onprem"
+
+#: The LiteLLM provider it is routed as. `watsonx_onprem/<model>` is not a
+#: prefix LiteLLM can resolve, so the gateway swaps in this key when it builds
+#: the model string.
+LITELLM_PROVIDER = "watsonx"
+
+#: Credential form for the settings dialog. LiteLLM publishes a `watsonx` form,
+#: but it asks for an IBM Cloud API key and a pre-encoded Zen key — neither is
+#: what a CPD operator has in hand. These are the fields behind the cluster's
+#: own `/icp4d-api/v1/authorize` call: a username and an API key.
+CREDENTIAL_FIELDS: list[dict[str, Any]] = [
+ {
+ "key": "api_base",
+ "label": "Cluster URL",
+ "placeholder": "https://cpd-cluster.example.com",
+ "tooltip": "Base URL of the Cloud Pak for Data cluster, with no /ml/v1 suffix.",
+ "required": True,
+ "field_type": "text",
+ "options": None,
+ "default_value": None,
+ },
+ {
+ "key": "username",
+ "label": "Username",
+ "placeholder": None,
+ "tooltip": "Your Cloud Pak for Data username. Required alongside the API key: "
+ "the two are combined into the ZenApiKey the cluster authenticates with, and an "
+ "API key on its own cannot authenticate to a cluster. Not needed if you paste a "
+ "Zen API key below instead.",
+ "required": False,
+ "field_type": "text",
+ "options": None,
+ "default_value": None,
+ },
+ {
+ "key": "api_key",
+ "label": "API key",
+ "placeholder": None,
+ "tooltip": "Your Cloud Pak for Data API key (Profile and settings > API key).",
+ "required": False,
+ "field_type": "password",
+ "options": None,
+ "default_value": None,
+ },
+ {
+ "key": "zen_api_key",
+ "label": "Zen API key",
+ "placeholder": None,
+ "tooltip": "Optional. A pre-encoded base64(username:apikey). Leave blank to have "
+ "OpenRAG build it from the username and API key above.",
+ "required": False,
+ "field_type": "password",
+ "options": None,
+ "default_value": None,
+ },
+ {
+ "key": "space_id",
+ "label": "Deployment space ID",
+ "placeholder": None,
+ "tooltip": "The deployment space the models are served from. Most clusters "
+ "require this (or a project ID) and reject inference without it. Find it under "
+ "Deployments in the console, or with GET /v2/spaces on the cluster. Leave blank "
+ "only on a lightweight-engine install, which uses neither spaces nor projects.",
+ "required": False,
+ "field_type": "text",
+ "options": None,
+ "default_value": None,
+ },
+ {
+ "key": "project_id",
+ "label": "Project ID",
+ "placeholder": None,
+ "tooltip": "Optional. Set only if this cluster serves models from a project "
+ "rather than a deployment space.",
+ "required": False,
+ "field_type": "text",
+ "options": None,
+ "default_value": None,
+ },
+]
+
+#: Fields an operator fills in that are not LiteLLM kwargs. `username` is half
+#: of the Zen key and nothing else — forwarding it would land it in the request
+#: body, since LiteLLM passes kwargs it does not recognise straight through.
+_LOCAL_ONLY_FIELDS = frozenset({"username"})
+
+
+def zen_api_key(username: str | None, api_key: str | None) -> str:
+ """`base64(username:apikey)` — the value CPD expects after `ZenApiKey `.
+
+ Empty when either half is missing, so a half-filled form does not produce a
+ credential that looks valid and 401s on first use.
+ """
+ user = (username or "").strip()
+ key = (api_key or "").strip()
+ if not user or not key:
+ return ""
+ return base64.b64encode(f"{user}:{key}".encode()).decode("ascii")
+
+
+def litellm_credentials(stored: Mapping[str, Any]) -> dict[str, str]:
+ """Stored form values as LiteLLM kwargs for `watsonx`.
+
+ `api_key` is set to the Zen key as well as `zen_api_key`: the embeddings
+ path rejects the call before it ever reads the auth header if `api_key` is
+ unset, and the header it then builds comes from `zen_api_key`, so the two
+ have to travel together.
+ """
+ values = {
+ str(name): str(value).strip()
+ for name, value in (stored or {}).items()
+ if str(value or "").strip()
+ }
+ zen = values.get("zen_api_key") or zen_api_key(values.get("username"), values.get("api_key"))
+
+ credentials = {
+ name: value
+ for name, value in values.items()
+ if name not in _LOCAL_ONLY_FIELDS and name not in {"api_key", "zen_api_key"}
+ }
+ if zen:
+ credentials["zen_api_key"] = zen
+ credentials["api_key"] = zen
+ elif values.get("api_key"):
+ # No username to pair it with. Hand LiteLLM the raw key so a cluster
+ # fronted by IBM Cloud IAM still works, rather than dropping the only
+ # secret the operator supplied.
+ credentials["api_key"] = values["api_key"]
+ if credentials:
+ install_litellm_compatibility()
+ return credentials
+
+
+#: Catalogue endpoint used to check credentials. It needs no model, no project
+#: and no space, which is what makes it a health check the provider can pass
+#: before anything has been selected in Settings.
+MODEL_SPECS_PATH = "/ml/v1/foundation_model_specs"
+
+#: Pinned to what LiteLLM itself calls with, so the health check exercises the
+#: same API contract as real traffic rather than a newer one the cluster may
+#: not serve.
+API_VERSION = "2024-03-13"
+
+
+def auth_header(stored: Mapping[str, Any]) -> str:
+ """The `Authorization` value for OpenRAG's own calls to the cluster.
+
+ The health check talks to `/ml/v1` directly rather than through LiteLLM, so
+ it has to build the same header LiteLLM would.
+ """
+ credentials = litellm_credentials(stored)
+ if credentials.get("zen_api_key"):
+ return f"ZenApiKey {credentials['zen_api_key']}"
+ # Deliberately no `Bearer <api_key>` fallback. A Cloud Pak for Data API key
+ # is not a bearer token — the cluster issues one from `/icp4d-api/v1/authorize`
+ # in exchange for a *username and* an API key. Sending the raw key gets a
+ # 401 that looks like bad credentials rather than incomplete ones, and the
+ # caller quietly falls back to the configured model list with nothing on
+ # screen to say why. Returning nothing lets the health check say what is
+ # missing.
+ return ""
+
+
+def model_specs_url(api_base: str) -> str:
+ """The catalogue URL on `api_base`, however the operator typed the cluster URL.
+
+ Deliberately carries no query string. httpx *replaces* a URL's query when
+ it is given `params`, so a `?version=` baked in here is silently dropped by
+ any caller that also pages or filters — and the cluster answers
+ `invalid_version_date_pattern` for the empty version that results.
+ Everything goes through `model_specs_params` instead.
+ """
+ return f"{(api_base or '').rstrip('/')}{MODEL_SPECS_PATH}"
+
+
+def model_specs_params(**extra: Any) -> dict[str, Any]:
+ """Query parameters for the catalogue endpoint. `version` is mandatory."""
+ return {"version": API_VERSION, **extra}
+
+
+def _error_details(response: Any) -> str:
+ """Extract the concise error that Cloud Pak for Data returned."""
+ try:
+ body = response.json()
+ except (ValueError, TypeError):
+ return str(getattr(response, "text", ""))[:500]
+ if isinstance(body, dict):
+ errors = body.get("errors")
+ if isinstance(errors, list) and errors and isinstance(errors[0], dict):
+ return str(errors[0].get("message") or errors[0].get("code") or response.text[:500])
+ return str(
+ body.get("errorMessage")
+ or body.get("message")
+ or body.get("detail")
+ or response.text[:500]
+ )
+ return str(getattr(response, "text", ""))[:500]
+
+
+async def _http_request_with_retry(
+ method: str,
+ url: str,
+ *,
+ client: Any,
+ max_retries: int = 2,
+ backoff_factor: float = 0.5,
+ **kwargs: Any,
+) -> Any:
+ """Retry CPD catalogue reads without depending on API validation helpers."""
+ import httpx
+
+ for attempt in range(max_retries + 1):
+ try:
+ response = await client.request(method, url, **kwargs)
+ if response.status_code not in (429, 500, 502, 503, 504) or attempt == max_retries:
+ return response
+ except (httpx.TimeoutException, httpx.NetworkError, httpx.RemoteProtocolError) as exc:
+ if attempt == max_retries:
+ raise exc
+ await asyncio.sleep(backoff_factor * (2**attempt))
+ raise RuntimeError(f"CPD request to {url} failed after retries")
+
+
+async def lightweight_health_check(credentials: Mapping[str, Any]) -> None:
+ """Validate CPD connectivity and Zen credentials without selecting a model."""
+ import httpx
+
+ api_base = str(credentials.get("api_base") or "").strip()
+ if not api_base:
+ raise Exception("No cluster URL is configured for watsonx.ai on-prem")
+ header = auth_header(credentials)
+ if not header:
+ raise Exception(
+ "No credentials are configured for watsonx.ai on-prem. "
+ "Enter a username and API key, or a Zen API key."
+ )
+
+ url = model_specs_url(api_base)
+ try:
+ async with httpx.AsyncClient(verify=ssl_verify()) as client:
+ response = await _http_request_with_retry(
+ "GET",
+ url,
+ client=client,
+ headers={"Authorization": header, "Accept": "application/json"},
+ params=model_specs_params(limit=1),
+ timeout=10.0,
+ )
+ except httpx.TimeoutException:
+ logger.error("watsonx.ai on-prem health check timed out")
+ raise Exception("The watsonx.ai cluster did not respond in time") from None
+ except Exception:
+ logger.error("watsonx.ai on-prem health check could not reach the cluster", exc_info=True)
+ raise
+
+ if response.status_code == 200:
+ logger.info("watsonx.ai on-prem health check passed")
+ return
+ details = _error_details(response)
+ logger.error("watsonx.ai on-prem health check failed: %s - %s", response.status_code, details)
+ if response.status_code in (401, 403):
+ raise Exception(f"Invalid credentials for the watsonx.ai cluster: {details}")
+ raise Exception(details)
+
+
+def ssl_verify() -> bool | str:
+ """The TLS setting LiteLLM will use, so our own calls agree with real traffic.
+
+ A cluster behind its own CA is reached by pointing `SSL_CERT_FILE` at a
+ bundle (or, in development, by `SSL_VERIFY=false`). Both are read by
+ LiteLLM, not by httpx, so without this a direct call here could fail on a
+ certificate that the gateway accepts, or the reverse.
+ """
+ try:
+ from litellm.llms.custom_httpx.http_handler import get_ssl_verify
+
+ return get_ssl_verify()
+ except Exception:
+ logger.debug("Could not read LiteLLM's TLS setting; verifying normally", exc_info=True)
+ return True
+
+
+#: How long a fetched model list is reused. The set of deployed models changes
+#: when an administrator deploys one, not per request.
+MODELS_TTL_SECONDS = 300
+
+#: Page size asked for. A cluster serves tens of models, not thousands, but the
+#: endpoint pages by default and a truncated list silently hides models.
+MODELS_PAGE_LIMIT = 200
+
+#: Guard against following `next` for ever if a cluster paginates oddly.
+MAX_MODEL_PAGES = 10
+
+#: `functions` / `task_ids` markers that say which picker a model belongs in.
+#: The listing is fetched unfiltered and split here rather than with the API's
+#: `filters` parameter: the filter grammar is a SaaS convenience, and a cluster
+#: that does not accept it would answer 400 and leave both pickers empty.
+_EMBEDDING_FUNCTIONS = frozenset({"embedding", "embeddings"})
+_CHAT_FUNCTIONS = frozenset({"text_chat", "text_generation", "chat", "generation"})
+
+
+class ClusterModels(NamedTuple):
+ chat: tuple[str, ...]
+ embedding: tuple[str, ...]
+
+
+_models_cache: dict[str, Any] = {"key": None, "at": 0.0, "value": None}
+
+
+def cached_models() -> ClusterModels | None:
+ """The last model list fetched from the cluster, if it is still fresh."""
+ value = _models_cache["value"]
+ if value is None or time.monotonic() - _models_cache["at"] > MODELS_TTL_SECONDS:
+ return None
+ return value
+
+
+def _cache_key(credentials: Mapping[str, Any]) -> str:
+ """Identifies the cluster and the credentials a cached list was fetched with."""
+ values = litellm_credentials(credentials)
+ return f"{values.get('api_base', '')}|{values.get('api_key', '')}"
+
+
+def _resource_markers(resource: Mapping[str, Any]) -> set[str]:
+ """Everything a listing entry says about what it can do, lowercased."""
+ markers: set[str] = set()
+ for function in resource.get("functions") or []:
+ if isinstance(function, Mapping) and function.get("id"):
+ markers.add(str(function["id"]).lower())
+ elif isinstance(function, str):
+ markers.add(function.lower())
+ for task in resource.get("task_ids") or []:
+ markers.add(str(task).lower())
+ return markers
+
+
+def _is_withdrawn(resource: Mapping[str, Any]) -> bool:
+ """Whether the cluster still lists a model it has already retired."""
+ lifecycle = resource.get("lifecycle")
+ if isinstance(lifecycle, list):
+ return any(
+ isinstance(entry, Mapping) and str(entry.get("id", "")).lower() == "withdrawn"
+ for entry in lifecycle
+ )
+ return str(lifecycle or "").lower() == "withdrawn"
+
+
+def split_models(resources: Any) -> ClusterModels:
+ """Split one `foundation_model_specs` listing into the two picker lists.
+
+ Order is preserved and duplicates dropped. A model that advertises nothing
+ useful is treated as a text model: the great majority are, and leaving it
+ out would hide something the cluster actually serves.
+ """
+ chat: list[str] = []
+ embedding: list[str] = []
+ for resource in resources or []:
+ if not isinstance(resource, Mapping):
+ continue
+ model_id = str(resource.get("model_id") or "").strip()
+ if not model_id:
+ continue
+ # `tech_preview` is not requestable on every deployment, and the SaaS
+ # listing drops it for the same reason.
+ if resource.get("input_tier") == "tech_preview" or _is_withdrawn(resource):
+ continue
+ markers = _resource_markers(resource)
+ bucket = embedding if markers & _EMBEDDING_FUNCTIONS else chat
+ if markers & _EMBEDDING_FUNCTIONS and markers & _CHAT_FUNCTIONS:
+ # A model that does both belongs in both pickers.
+ if model_id not in chat:
+ chat.append(model_id)
+ if model_id not in bucket:
+ bucket.append(model_id)
+ return ClusterModels(chat=tuple(chat), embedding=tuple(embedding))
+
+
+async def fetch_models(credentials: Mapping[str, Any]) -> ClusterModels | None:
+ """Ask the cluster which foundation models it actually serves.
+
+ A cluster serves whatever its operator deployed, so this is the only
+ truthful source for the pickers — LiteLLM's bundled table describes IBM
+ Cloud, and the `models:` rows in `model_providers.yaml` are the fallback for
+ when the cluster cannot be reached.
+
+ The listing is fetched unfiltered and split locally, which keeps this
+ working on a lightweight-engine install that has no projects and may not
+ accept the SaaS `filters` grammar. Returns None on any failure, so a
+ catalogue request never fails because the cluster is unreachable; the caller
+ keeps whatever it had.
+ """
+ import httpx
+
+ values = litellm_credentials(credentials)
+ api_base = (values.get("api_base") or "").strip()
+ header = auth_header(credentials)
+ if not api_base or not header:
+ logger.warning(
+ "Not listing models on the watsonx.ai cluster: credentials are incomplete. "
+ "A cluster URL plus either a username and API key, or a Zen API key, is "
+ "needed; the configured model list is used until then.",
+ has_cluster_url=bool(api_base),
+ has_credentials=bool(header),
+ )
+ return None
+
+ key = _cache_key(credentials)
+ fresh = cached_models()
+ if fresh is not None and _models_cache["key"] == key:
+ return fresh
+
+ headers = {"Authorization": header, "Accept": "application/json"}
+ url = model_specs_url(api_base)
+ # Only the first request needs parameters built here; a `next` link already
+ # carries its own `version` and `start` in the query it comes back with.
+ params: dict[str, Any] | None = model_specs_params(limit=MODELS_PAGE_LIMIT)
+ resources: list[Any] = []
+ try:
+ async with httpx.AsyncClient(verify=ssl_verify(), timeout=15.0) as client:
+ for _ in range(MAX_MODEL_PAGES):
+ response = await client.get(url, headers=headers, params=params)
+ if response.status_code != 200:
+ logger.warning(
+ "watsonx.ai cluster rejected the model listing; "
+ "keeping the configured list",
+ status_code=response.status_code,
+ url=url,
+ body=response.text[:300],
+ )
+ return None
+ body = response.json()
+ if not isinstance(body, dict):
+ return None
+ resources.extend(body.get("resources") or [])
+ next_page = body.get("next")
+ href = next_page.get("href") if isinstance(next_page, Mapping) else None
+ if not href:
+ break
+ # Only the path and query are usable. A cluster answers with
+ # its own internal hostname here — this one returns
+ # `https://wx-inference-proxy-upstream/ml/v1/...`, which does
+ # not resolve outside the cluster — so the next page is
+ # re-based on the URL the operator gave us.
+ parsed = urlsplit(href)
+ url = f"{api_base.rstrip('/')}{urlunsplit(('', '', parsed.path, parsed.query, ''))}"
+ params = None
+ except Exception as exc:
+ logger.warning(
+ "Could not list models on the watsonx.ai cluster; keeping the configured list",
+ error=str(exc),
+ )
+ return None
+
+ models = split_models(resources)
+ if not models.chat and not models.embedding:
+ # Far more likely a listing we could not interpret than a cluster with
+ # nothing deployed. Emptying both pickers on that guess would be worse
+ # than showing the fallback.
+ logger.warning(
+ "watsonx.ai cluster listed no usable models; keeping the configured list",
+ resources=len(resources),
+ )
+ return None
+
+ _models_cache.update(key=key, at=time.monotonic(), value=models)
+ logger.info(
+ "Listed models on the watsonx.ai cluster",
+ chat=len(models.chat),
+ embedding=len(models.embedding),
+ )
+ return models
+
+
+def forget_models() -> None:
+ """Drop the cached cluster list. For tests and for a credential change."""
+ _models_cache.update(key=None, at=0.0, value=None)
+
+
+# --------------------------------------------------------------------------
+# LiteLLM compatibility
+# --------------------------------------------------------------------------
+
+#: Modules that bound `_get_api_params` at import time. Patching
+#: `common_utils._get_api_params` alone would miss all of them.
+_API_PARAM_CALL_SITES = (
+ "litellm.llms.watsonx.chat.handler",
+ "litellm.llms.watsonx.embed.transformation",
+ "litellm.llms.watsonx.completion.transformation",
+ "litellm.llms.watsonx.rerank.transformation",
+)
+
+_PATCH_MARKER = "_openrag_watsonx_onprem_patched"
+_installed = False
+
+
+def install_litellm_compatibility() -> None:
+ """Let a watsonx call proceed with no `project_id` and no `space_id`.
+
+ LiteLLM 1.84 raises 401 locally ("Watsonx project_id and space_id not set")
+ before sending anything, and stamps whichever one it has into every request
+ body. Both are correct for IBM Cloud. Neither holds for the watsonx.ai
+ lightweight engine, whose docs say to omit `project_id` outright — so
+ without this the provider cannot reach that install at all.
+
+ The change is deliberately the smallest one that unblocks it: the local
+ raise becomes "send it and let the cluster answer", and a `space_id` that
+ resolved to null is dropped from the payload instead of being serialised as
+ `"space_id": null`. A deployment that *does* have a space or project is
+ untouched — both values still flow through exactly as before. The only
+ behaviour lost is LiteLLM's client-side check, which on IBM Cloud now
+ surfaces as the provider's own error instead of a local one.
+
+ Idempotent, and a no-op on any LiteLLM whose internals have moved.
+ """
+ global _installed
+ if _installed:
+ return
+ _installed = True # one attempt per process, success or not
+
+ try:
+ import litellm.llms.watsonx.common_utils as common_utils
+ from litellm.types.llms.watsonx import WatsonXAPIParams
+ except Exception:
+ logger.warning(
+ "Could not patch LiteLLM for on-prem watsonx.ai; a deployment with no "
+ "space_id or project_id will be rejected before the call is sent",
+ exc_info=True,
+ )
+ return
+
+ original_get_api_params = common_utils._get_api_params
+ watsonx_error = common_utils.WatsonXAIError
+
+ def _get_api_params_allowing_no_scope(params: dict, model: str | None = None):
+ try:
+ return original_get_api_params(params=params, model=model)
+ except watsonx_error as exc:
+ if getattr(exc, "status_code", None) != 401 or "space_id" not in str(exc):
+ raise
+ # The guard already popped project_id/space_id/region off `params`,
+ # and both were absent — which is exactly the lightweight-engine
+ # shape. Carry on with an empty scope.
+ return WatsonXAPIParams(project_id=None, space_id=None, region_name=None)
+
+ setattr(_get_api_params_allowing_no_scope, _PATCH_MARKER, True)
+
+ patched = []
+ for module_name in _API_PARAM_CALL_SITES:
+ try:
+ module = cast(Any, __import__(module_name, fromlist=["_get_api_params"]))
+ except Exception:
+ continue
+ current = getattr(module, "_get_api_params", None)
+ if current is None or getattr(current, _PATCH_MARKER, False):
+ continue
+ module._get_api_params = _get_api_params_allowing_no_scope
+ patched.append(module_name)
+
+ mixin = cast(Any, common_utils.IBMWatsonXMixin)
+ if not getattr(mixin._prepare_payload, _PATCH_MARKER, False):
+ original_prepare_payload = mixin._prepare_payload
+
+ def _prepare_payload_without_null_scope(self, model: str, api_params) -> dict:
+ payload = original_prepare_payload(self, model=model, api_params=api_params)
+ if payload.get("space_id") is None:
+ # `{"space_id": null}` is not "no space"; watsonx rejects it.
+ payload.pop("space_id", None)
+ return payload
+
+ setattr(_prepare_payload_without_null_scope, _PATCH_MARKER, True)
+ mixin._prepare_payload = _prepare_payload_without_null_scope
+ patched.append("IBMWatsonXMixin._prepare_payload")
+
+ if patched:
+ logger.info("Enabled scope-less watsonx.ai calls for on-prem", patched=patched)
diff --git a/frontend/app/api/mutations/useOnboardingMutation.ts b/frontend/app/api/mutations/useOnboardingMutation.ts
index bd300dec3..a5831dcf1 100644
--- a/frontend/app/api/mutations/useOnboardingMutation.ts
+++ b/frontend/app/api/mutations/useOnboardingMutation.ts
@@ -23,6 +23,7 @@ export interface OnboardingVariables {
watsonx_project_id?: string;
ollama_endpoint?: string;
provider_credentials?: Record<string, Record<string, string>>;
+ provider_auth_methods?: Record<string, string>;
}
interface OnboardingResponse {
diff --git a/frontend/app/api/mutations/useUpdateSettingsMutation.ts b/frontend/app/api/mutations/useUpdateSettingsMutation.ts
index 8f8e8820a..2e6cae9fa 100644
--- a/frontend/app/api/mutations/useUpdateSettingsMutation.ts
+++ b/frontend/app/api/mutations/useUpdateSettingsMutation.ts
@@ -54,6 +54,7 @@ export interface UpdateSettingsRequest {
// Bypass the "this provider's embedding models are still in use" guard.
force_remove?: boolean;
provider_credentials?: Record<string, Record<string, string>>;
+ provider_auth_methods?: Record<string, string>;
remove_provider_config?: string;
}
diff --git a/frontend/app/api/queries/useGetModelProvidersQuery.ts b/frontend/app/api/queries/useGetModelProvidersQuery.ts
index 8980fe2f3..c6a0c1ccf 100644
--- a/frontend/app/api/queries/useGetModelProvidersQuery.ts
+++ b/frontend/app/api/queries/useGetModelProvidersQuery.ts
@@ -7,6 +7,7 @@ import {
export interface ModelProviderEntry {
name: string;
display_name: string;
+ badge?: string;
}
export interface ModelProvidersResponse {
@@ -32,7 +33,10 @@ export const useGetModelProvidersQuery = (
return useQuery(
{
- queryKey: ["models", "providers"] as const,
+ // The response now carries display metadata (for example provider
+ // badges). Version the cache key so an HMR session that cached the old
+ // two-field shape fetches the enriched response immediately.
+ queryKey: ["models", "providers", "v2"] as const,
queryFn: async (): Promise<ModelProvidersResponse> => {
const response = await fetch("/api/models/providers");
if (!response.ok) {
diff --git a/frontend/app/api/queries/useGetSettingsQuery.ts b/frontend/app/api/queries/useGetSettingsQuery.ts
index f4b54505f..bc1693a1a 100644
--- a/frontend/app/api/queries/useGetSettingsQuery.ts
+++ b/frontend/app/api/queries/useGetSettingsQuery.ts
@@ -60,6 +60,7 @@ export interface ProviderSettings {
configured?: boolean;
credential_values?: Record<string, string>;
secret_fields?: string[];
+ auth_method?: string | null;
}
>;
}
diff --git a/frontend/app/onboarding/_components/advanced.tsx b/frontend/app/onboarding/_components/advanced.tsx
index 596d6ca0e..86d93ea63 100644
--- a/frontend/app/onboarding/_components/advanced.tsx
+++ b/frontend/app/onboarding/_components/advanced.tsx
@@ -1,11 +1,5 @@
import { LabelWrapper } from "@/components/label-wrapper";
import { ModelSelector } from "@/components/models/model-selector";
-import {
- Accordion,
- AccordionContent,
- AccordionItem,
- AccordionTrigger,
-} from "@/components/ui/accordion";
export function AdvancedOnboarding({
icon,
@@ -34,46 +28,39 @@ export function AdvancedOnboarding({
setLanguageModel !== undefined;
return (
- <Accordion type="single" collapsible>
- <AccordionItem value="item-1">
- <AccordionTrigger data-testid="advanced-settings-button">
- Advanced settings
- </AccordionTrigger>
- <AccordionContent className="space-y-6">
- {hasEmbeddingModels && (
- <LabelWrapper
- label="Embedding model"
- helperText="Model used for knowledge ingest and retrieval"
- id="embedding-model"
- required={true}
- >
- <ModelSelector
- options={embeddingModels}
- data-testid="embedding-model-selector"
- icon={icon}
- value={embeddingModel}
- onValueChange={setEmbeddingModel}
- />
- </LabelWrapper>
- )}
- {hasLanguageModels && (
- <LabelWrapper
- label="Language model"
- helperText="Model used for chat"
- id="embedding-model"
- required={true}
- >
- <ModelSelector
- options={languageModels}
- data-testid="language-model-selector"
- icon={icon}
- value={languageModel}
- onValueChange={setLanguageModel}
- />
- </LabelWrapper>
- )}
- </AccordionContent>
- </AccordionItem>
- </Accordion>
+ <div className="space-y-6">
+ {hasEmbeddingModels && (
+ <LabelWrapper
+ label="Embedding model"
+ helperText="Model used for knowledge ingest and retrieval"
+ id="embedding-model"
+ required={true}
+ >
+ <ModelSelector
+ options={embeddingModels}
+ data-testid="embedding-model-selector"
+ icon={icon}
+ value={embeddingModel}
+ onValueChange={setEmbeddingModel}
+ />
+ </LabelWrapper>
+ )}
+ {hasLanguageModels && (
+ <LabelWrapper
+ label="Language model"
+ helperText="Model used for chat"
+ id="embedding-model"
+ required={true}
+ >
+ <ModelSelector
+ options={languageModels}
+ data-testid="language-model-selector"
+ icon={icon}
+ value={languageModel}
+ onValueChange={setLanguageModel}
+ />
+ </LabelWrapper>
+ )}
+ </div>
);
}
diff --git a/frontend/app/onboarding/_components/generic-onboarding.tsx b/frontend/app/onboarding/_components/generic-onboarding.tsx
index bf069dcc9..7f3a8be99 100644
--- a/frontend/app/onboarding/_components/generic-onboarding.tsx
+++ b/frontend/app/onboarding/_components/generic-onboarding.tsx
@@ -11,6 +11,8 @@ import {
import { getProviderChrome } from "@/components/models/model-helpers";
import type { OnboardingVariables } from "../../api/mutations/useOnboardingMutation";
import { AdvancedOnboarding } from "./advanced";
+import { GenericProviderCredentialFields } from "./generic-provider-credential-fields";
+import { AZURE_AUTH_GROUPS } from "./generic-provider-credential-fields.helpers";
/**
* Onboarding step for a provider with no hand-built component.
@@ -53,13 +55,36 @@ export function GenericOnboarding({
const [credentials, setCredentials] = useState<Record<string, string>>({});
const [model, setModel] = useState("");
+ const [azureAuthMethod, setAzureAuthMethod] = useState(
+ providers?.custom?.[provider]?.auth_method ?? "api_key",
+ );
+ const [onPremAuthMethod, setOnPremAuthMethod] = useState(
+ providers?.custom?.[provider]?.auth_method ?? "username_api_key",
+ );
const syncParentSettings = (
nextCredentials: Record<string, string>,
nextModel: string,
) => {
const submitted: Record<string, string> = {};
+ const activeAzureFields = new Set([
+ "api_base",
+ "api_version",
+ ...(AZURE_AUTH_GROUPS.find((group) => group.key === azureAuthMethod)
+ ?.fields ?? []),
+ ]);
+ const activeOnPremFields = new Set([
+ "api_base",
+ "space_id",
+ "project_id",
+ ...(onPremAuthMethod === "zen_api_key"
+ ? ["zen_api_key"]
+ : ["username", "api_key"]),
+ ]);
for (const [key, value] of Object.entries(nextCredentials)) {
+ if (provider === "azure" && !activeAzureFields.has(key)) continue;
+ if (provider === "watsonx_onprem" && !activeOnPremFields.has(key))
+ continue;
const trimmed = (value ?? "").trim();
if (trimmed !== "") {
submitted[key] = trimmed;
@@ -74,6 +99,22 @@ export function GenericOnboarding({
provider_credentials: Object.keys(submitted).length
? { ...prev.provider_credentials, [provider]: submitted }
: prev.provider_credentials,
+ ...(provider === "azure"
+ ? {
+ provider_auth_methods: {
+ ...prev.provider_auth_methods,
+ azure: azureAuthMethod,
+ },
+ }
+ : {}),
+ ...(provider === "watsonx_onprem"
+ ? {
+ provider_auth_methods: {
+ ...prev.provider_auth_methods,
+ watsonx_onprem: onPremAuthMethod,
+ },
+ }
+ : {}),
}));
};
@@ -120,37 +161,89 @@ export function GenericOnboarding({
syncParentSettings(credentials, newModel);
};
+ const handleAzureAuthMethodChange = (method: string) => {
+ setAzureAuthMethod(method);
+ // The closure still holds the previous method during this event; submit
+ // just the new method's fields explicitly so inactive values stay local.
+ const active = new Set([
+ "api_base",
+ "api_version",
+ ...(AZURE_AUTH_GROUPS.find((group) => group.key === method)?.fields ??
+ []),
+ ]);
+ const selected = Object.fromEntries(
+ Object.entries(credentials).filter(([key]) => active.has(key)),
+ );
+ setSettings((prev) => ({
+ ...prev,
+ provider_credentials: { ...prev.provider_credentials, azure: selected },
+ provider_auth_methods: { ...prev.provider_auth_methods, azure: method },
+ }));
+ };
+
+ const handleOnPremAuthMethodChange = (method: string) => {
+ setOnPremAuthMethod(method);
+ const active = new Set([
+ "api_base",
+ "space_id",
+ "project_id",
+ ...(method === "zen_api_key" ? ["zen_api_key"] : ["username", "api_key"]),
+ ]);
+ const selected = Object.fromEntries(
+ Object.entries(credentials).filter(([key]) => active.has(key)),
+ );
+ setSettings((prev) => ({
+ ...prev,
+ provider_credentials: {
+ ...prev.provider_credentials,
+ watsonx_onprem: selected,
+ },
+ provider_auth_methods: {
+ ...prev.provider_auth_methods,
+ watsonx_onprem: method,
+ },
+ }));
+ };
+
+ const renderField = (field: (typeof fields)[number]) => {
+ const isSecret =
+ field.field_type === "password" || field.field_type === "textarea";
+ const hasSaved = isSecret && savedSecrets.has(field.key);
+ return (
+ <div key={field.key} className="space-y-1">
+ <LabelInput
+ label={field.label}
+ helperText={field.tooltip ?? ""}
+ id={`onboarding-${provider}-${field.key}`}
+ type={field.field_type === "password" ? "password" : "text"}
+ required={field.required && !hasSaved}
+ placeholder={
+ hasSaved ? "•••••••••" : (field.placeholder ?? undefined)
+ }
+ value={credentials[field.key] ?? ""}
+ onChange={(e) => handleCredentialChange(field.key, e.target.value)}
+ />
+ {hasSaved && (
+ <p className="text-mmd text-muted-foreground">
+ A value is already saved. Leave this blank to keep it.
+ </p>
+ )}
+ </div>
+ );
+ };
+
return (
<>
<div className="space-y-5">
- {fields.map((field) => {
- const isSecret =
- field.field_type === "password" || field.field_type === "textarea";
- const hasSaved = isSecret && savedSecrets.has(field.key);
- return (
- <div key={field.key} className="space-y-1">
- <LabelInput
- label={field.label}
- helperText={field.tooltip ?? ""}
- id={`onboarding-${provider}-${field.key}`}
- type={field.field_type === "password" ? "password" : "text"}
- required={field.required && !hasSaved}
- placeholder={
- hasSaved ? "•••••••••" : (field.placeholder ?? undefined)
- }
- value={credentials[field.key] ?? ""}
- onChange={(e) =>
- handleCredentialChange(field.key, e.target.value)
- }
- />
- {hasSaved && (
- <p className="text-mmd text-muted-foreground">
- A value is already saved. Leave this blank to keep it.
- </p>
- )}
- </div>
- );
- })}
+ <GenericProviderCredentialFields
+ provider={provider}
+ fields={fields}
+ azureAuthMethod={azureAuthMethod}
+ onPremAuthMethod={onPremAuthMethod}
+ onAzureAuthMethodChange={handleAzureAuthMethodChange}
+ onOnPremAuthMethodChange={handleOnPremAuthMethodChange}
+ renderField={renderField}
+ />
{models.length === 0 && (
<p className="text-mmd text-muted-foreground">
{chrome.name} publishes no {isEmbedding ? "embedding" : "language"}{" "}
diff --git a/frontend/app/onboarding/_components/generic-provider-credential-fields.helpers.ts b/frontend/app/onboarding/_components/generic-provider-credential-fields.helpers.ts
new file mode 100644
index 000000000..8665ca25a
--- /dev/null
+++ b/frontend/app/onboarding/_components/generic-provider-credential-fields.helpers.ts
@@ -0,0 +1,35 @@
+import type { CatalogCredentialField } from "@/components/models/catalog-models";
+
+export const AZURE_AUTH_GROUPS = [
+ { key: "api_key", label: "API key", fields: ["api_key"] },
+ {
+ key: "entra_token",
+ label: "Microsoft Entra access token",
+ fields: ["azure_ad_token"],
+ },
+ {
+ key: "service_principal",
+ label: "Microsoft Entra service principal",
+ fields: ["tenant_id", "client_id", "client_secret"],
+ },
+] as const;
+
+export const ON_PREM_AUTH_GROUPS = [
+ {
+ key: "username_api_key",
+ label: "Username + API key",
+ fields: ["username", "api_key"],
+ },
+ { key: "zen_api_key", label: "Zen API key", fields: ["zen_api_key"] },
+] as const;
+
+export function fieldsForKeys(
+ fields: CatalogCredentialField[],
+ keys: readonly string[],
+) {
+ const byKey = new Map(fields.map((field) => [field.key, field]));
+ return keys.flatMap((key) => {
+ const field = byKey.get(key);
+ return field ? [field] : [];
+ });
+}
diff --git a/frontend/app/onboarding/_components/generic-provider-credential-fields.tsx b/frontend/app/onboarding/_components/generic-provider-credential-fields.tsx
new file mode 100644
index 000000000..a0d65efb6
--- /dev/null
+++ b/frontend/app/onboarding/_components/generic-provider-credential-fields.tsx
@@ -0,0 +1,109 @@
+import type { ReactNode } from "react";
+import type { CatalogCredentialField } from "@/components/models/catalog-models";
+import {
+ Accordion,
+ AccordionContent,
+ AccordionItem,
+ AccordionTrigger,
+} from "@/components/ui/accordion";
+import {
+ AZURE_AUTH_GROUPS,
+ fieldsForKeys,
+ ON_PREM_AUTH_GROUPS,
+} from "./generic-provider-credential-fields.helpers";
+
+export function GenericProviderCredentialFields({
+ provider,
+ fields,
+ azureAuthMethod,
+ onPremAuthMethod,
+ onAzureAuthMethodChange,
+ onOnPremAuthMethodChange,
+ renderField,
+}: {
+ provider: string;
+ fields: CatalogCredentialField[];
+ azureAuthMethod: string;
+ onPremAuthMethod: string;
+ onAzureAuthMethodChange: (method: string) => void;
+ onOnPremAuthMethodChange: (method: string) => void;
+ renderField: (field: CatalogCredentialField) => ReactNode;
+}) {
+ if (provider === "azure") {
+ return (
+ <>
+ {fieldsForKeys(fields, ["api_base"]).map(renderField)}
+ <Accordion
+ type="single"
+ value={azureAuthMethod}
+ onValueChange={(method) => method && onAzureAuthMethodChange(method)}
+ className="space-y-2"
+ >
+ {AZURE_AUTH_GROUPS.map((group) => (
+ <AccordionItem key={group.key} value={group.key}>
+ <AccordionTrigger>
+ {group.label}
+ {group.key === "api_key" && (
+ <span className="ml-2 rounded bg-muted px-2 py-0.5 text-xs">
+ Recommended
+ </span>
+ )}
+ </AccordionTrigger>
+ <AccordionContent className="space-y-4">
+ {fieldsForKeys(fields, group.fields).map(renderField)}
+ </AccordionContent>
+ </AccordionItem>
+ ))}
+ </Accordion>
+ <Accordion type="single" collapsible className="space-y-2">
+ <AccordionItem value="advanced">
+ <AccordionTrigger>Advanced settings</AccordionTrigger>
+ <AccordionContent className="space-y-4">
+ {fieldsForKeys(fields, ["api_version"]).map(renderField)}
+ </AccordionContent>
+ </AccordionItem>
+ </Accordion>
+ </>
+ );
+ }
+ if (provider === "watsonx_onprem") {
+ return (
+ <>
+ {fieldsForKeys(fields, ["api_base"]).map(renderField)}
+ <Accordion
+ type="single"
+ value={onPremAuthMethod}
+ onValueChange={(method) => method && onOnPremAuthMethodChange(method)}
+ className="space-y-2"
+ >
+ {ON_PREM_AUTH_GROUPS.map((group) => (
+ <AccordionItem key={group.key} value={group.key}>
+ <AccordionTrigger>
+ {group.label}
+ {group.key === "username_api_key" && (
+ <span className="ml-2 rounded bg-muted px-2 py-0.5 text-xs">
+ Recommended
+ </span>
+ )}
+ </AccordionTrigger>
+ <AccordionContent className="space-y-4">
+ {fieldsForKeys(fields, group.fields).map(renderField)}
+ </AccordionContent>
+ </AccordionItem>
+ ))}
+ </Accordion>
+ <Accordion type="single" collapsible className="space-y-2">
+ <AccordionItem value="advanced">
+ <AccordionTrigger>Advanced settings</AccordionTrigger>
+ <AccordionContent className="space-y-4">
+ {fieldsForKeys(fields, ["space_id", "project_id"]).map(
+ renderField,
+ )}
+ </AccordionContent>
+ </AccordionItem>
+ </Accordion>
+ </>
+ );
+ }
+ return <>{fields.map(renderField)}</>;
+}
diff --git a/frontend/app/onboarding/_components/onboarding-card.tsx b/frontend/app/onboarding/_components/onboarding-card.tsx
index 14f8a0133..5e53f0e96 100644
--- a/frontend/app/onboarding/_components/onboarding-card.tsx
+++ b/frontend/app/onboarding/_components/onboarding-card.tsx
@@ -94,6 +94,13 @@ const OnboardingCard = ({
),
[availableProviders],
);
+ const providerBadges = useMemo(
+ () =>
+ Object.fromEntries(
+ availableProviders.map(({ name, badge }) => [name, badge]),
+ ),
+ [availableProviders],
+ );
const providerKeys = useMemo(
() =>
orderProviders(
@@ -540,6 +547,10 @@ const OnboardingCard = ({
if (generic && Object.keys(generic).length > 0) {
onboardingData.provider_credentials = { [currentProvider]: generic };
}
+ const authMethod = settings.provider_auth_methods?.[currentProvider];
+ if (authMethod) {
+ onboardingData.provider_auth_methods = { [currentProvider]: authMethod };
+ }
trackButton({
CTA: isEmbedding ? "Complete - Embedding Setup" : "Complete - LLM Setup",
@@ -644,6 +655,11 @@ const OnboardingCard = ({
/>
</div>
{chrome.name}
+ {providerBadges[providerKey] && (
+ <span className="absolute right-0 top-0 rounded border border-muted-foreground/40 bg-muted px-1.5 py-0.5 text-xs font-medium text-muted-foreground">
+ {providerBadges[providerKey]}
+ </span>
+ )}
</TabTrigger>
</TabsTrigger>
);
diff --git a/frontend/app/settings/_components/model-provider-card.tsx b/frontend/app/settings/_components/model-provider-card.tsx
index fe011b5f8..89256680f 100644
--- a/frontend/app/settings/_components/model-provider-card.tsx
+++ b/frontend/app/settings/_components/model-provider-card.tsx
@@ -14,6 +14,7 @@ export interface ModelProviderCardData {
logo: (props: React.SVGProps<SVGSVGElement>) => React.ReactNode;
logoColor: string;
logoBgColor: string;
+ badge?: string;
}
interface ModelProviderCardProps {
@@ -30,11 +31,19 @@ export default function ModelProviderCard({
onConfigure,
}: ModelProviderCardProps) {
const isCloudBrand = useIsCloudBrand();
- const { providerKey, name, logo: Logo, logoColor, logoBgColor } = provider;
+ const {
+ providerKey,
+ name,
+ logo: Logo,
+ logoColor,
+ logoBgColor,
+ badge,
+ } = provider;
const isEditSetup = isConfigured && !isUnhealthy;
return (
<Card
+ data-testid={`model-provider-card-${providerKey}`}
className={cn(
"group relative flex flex-col transition-colors",
isCloudBrand
@@ -46,6 +55,11 @@ export default function ModelProviderCard({
(isCloudBrand ? "ring-2 ring-destructive" : "border-destructive"),
)}
>
+ {badge && (
+ <span className="absolute right-4 top-4 rounded border border-muted-foreground/40 bg-muted px-2 py-0.5 text-xs font-medium text-muted-foreground">
+ {badge}
+ </span>
+ )}
<CardHeader>
<div className="flex flex-col items-start justify-between">
<div className="flex flex-col gap-3">
diff --git a/frontend/app/settings/_components/model-providers.tsx b/frontend/app/settings/_components/model-providers.tsx
index a7c06491f..6c55ba526 100644
--- a/frontend/app/settings/_components/model-providers.tsx
+++ b/frontend/app/settings/_components/model-providers.tsx
@@ -100,7 +100,7 @@ export const ModelProviders = () => {
return (
<>
<div className="grid gap-6 xs:grid-cols-1 md:grid-cols-2 lg:grid-cols-4">
- {providers.map(({ name: providerKey, display_name }) => {
+ {providers.map(({ name: providerKey, display_name, badge }) => {
const isLlmProvider = providerKey === currentLlmProvider;
const isEmbeddingProvider = providerKey === currentEmbeddingProvider;
const isProviderUnhealthy =
@@ -113,6 +113,7 @@ export const ModelProviders = () => {
provider={{
providerKey,
...getProviderChrome(providerKey, display_name),
+ badge,
}}
// `providers.custom` carries every provider the backend knows,
// legacy four included, so one lookup covers config-added ones.
diff --git a/frontend/app/settings/_components/provider-settings-dialog.tsx b/frontend/app/settings/_components/provider-settings-dialog.tsx
index 08854d6f7..552e33713 100644
--- a/frontend/app/settings/_components/provider-settings-dialog.tsx
+++ b/frontend/app/settings/_components/provider-settings-dialog.tsx
@@ -2,7 +2,7 @@
import { AnimatePresence, domAnimation, LazyMotion, m } from "motion/react";
import { useRouter } from "next/navigation";
-import { useEffect, useState } from "react";
+import { useMemo, useState } from "react";
import { FormProvider, useForm } from "react-hook-form";
import { toast } from "sonner";
import {
@@ -61,6 +61,8 @@ const ProviderSettingsDialog = ({
const [affectedModels, setAffectedModels] = useState<
AffectedEmbeddingModel[] | undefined
>(undefined);
+ const [azureAuthMethod, setAzureAuthMethod] = useState("api_key");
+ const [onPremAuthMethod, setOnPremAuthMethod] = useState("username_api_key");
const router = useRouter();
const { data: settings = {} } = useGetSettingsQuery({
@@ -79,6 +81,20 @@ const ProviderSettingsDialog = ({
const saved = settings.providers?.custom?.[provider];
const isConfigured = saved?.configured === true;
const savedSecretFields = saved?.secret_fields ?? [];
+ const formValues = useMemo(
+ () =>
+ open
+ ? {
+ credentials: Object.fromEntries(
+ fields.map((field) => [
+ field.key,
+ saved?.credential_values?.[field.key] ?? "",
+ ]),
+ ),
+ }
+ : { credentials: {} },
+ [fields, open, saved],
+ );
// Removing the last configured provider with an embedding model would leave
// the agent with nothing to embed documents, so require another one first.
@@ -86,25 +102,20 @@ const ProviderSettingsDialog = ({
const methods = useForm<ProviderSettingsFormData>({
mode: "onSubmit",
- defaultValues: { credentials: {} },
+ values: formValues,
});
- // Seed on open, and again if the catalogue or the saved settings land after
- // it. Both are react-query results, so their identity is stable while the
- // dialog is open and this cannot stomp on what the user is typing.
- useEffect(() => {
- if (!open) {
- return;
+ const savedAuthMethod = saved?.auth_method;
+ const authMethodSeed = `${open}:${provider}:${savedAuthMethod ?? ""}`;
+ const [previousAuthMethodSeed, setPreviousAuthMethodSeed] =
+ useState<string>();
+ if (authMethodSeed !== previousAuthMethodSeed) {
+ setPreviousAuthMethodSeed(authMethodSeed);
+ if (provider === "azure") setAzureAuthMethod(savedAuthMethod ?? "api_key");
+ if (provider === "watsonx_onprem") {
+ setOnPremAuthMethod(savedAuthMethod ?? "username_api_key");
}
- methods.reset({
- credentials: Object.fromEntries(
- fields.map((field) => [
- field.key,
- saved?.credential_values?.[field.key] ?? "",
- ]),
- ),
- });
- }, [open, fields, saved, methods]);
+ }
const { handleSubmit } = methods;
@@ -143,7 +154,30 @@ const ProviderSettingsDialog = ({
// Blank means "leave the stored value alone": the backend ignores empty
// values, and secrets are never echoed back for us to resubmit.
const credentials: Record<string, string> = {};
+ const azureAuthFields: Record<string, Set<string>> = {
+ api_key: new Set(["api_key"]),
+ entra_token: new Set(["azure_ad_token"]),
+ service_principal: new Set(["tenant_id", "client_id", "client_secret"]),
+ };
+ const allowedAzureFields = new Set([
+ "api_base",
+ "api_version",
+ ...(azureAuthFields[azureAuthMethod] ?? []),
+ ]);
+ const allowedOnPremFields = new Set([
+ "api_base",
+ "space_id",
+ "project_id",
+ ...(onPremAuthMethod === "zen_api_key"
+ ? ["zen_api_key"]
+ : ["username", "api_key"]),
+ ]);
for (const [key, value] of Object.entries(data.credentials ?? {})) {
+ if (provider === "azure" && !allowedAzureFields.has(key)) {
+ continue;
+ }
+ if (provider === "watsonx_onprem" && !allowedOnPremFields.has(key))
+ continue;
const trimmed = (value ?? "").trim();
if (trimmed !== "") {
credentials[key] = trimmed;
@@ -157,6 +191,11 @@ const ProviderSettingsDialog = ({
settingsMutation.mutate({
provider_credentials: { [provider]: credentials },
+ ...(provider === "azure"
+ ? { provider_auth_methods: { azure: azureAuthMethod } }
+ : provider === "watsonx_onprem"
+ ? { provider_auth_methods: { watsonx_onprem: onPremAuthMethod } }
+ : {}),
});
};
@@ -191,10 +230,15 @@ const ProviderSettingsDialog = ({
<div className="flex-1 min-h-0 overflow-y-auto min-w-0 px-1 -mx-1 py-1 space-y-4">
<ProviderSettingsForm
+ provider={provider}
providerName={chrome.name}
fields={fields}
savedSecretFields={savedSecretFields}
saveError={methods.formState.errors.root?.message}
+ azureAuthMethod={azureAuthMethod}
+ onAzureAuthMethodChange={setAzureAuthMethod}
+ onPremAuthMethod={onPremAuthMethod}
+ onOnPremAuthMethodChange={setOnPremAuthMethod}
/>
<LazyMotion features={domAnimation}>
@@ -206,7 +250,10 @@ const ProviderSettingsDialog = ({
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: -10 }}
>
- <p className="rounded-lg border border-destructive p-4 min-w-0 [overflow-wrap:anywhere]">
+ <p
+ data-testid="provider-connection-error"
+ className="rounded-lg border border-destructive p-4 min-w-0 [overflow-wrap:anywhere]"
+ >
{settingsMutation.error?.message}
</p>
</m.div>
diff --git a/frontend/app/settings/_components/provider-settings-form.tsx b/frontend/app/settings/_components/provider-settings-form.tsx
index 2da3a4649..dfc9cced2 100644
--- a/frontend/app/settings/_components/provider-settings-form.tsx
+++ b/frontend/app/settings/_components/provider-settings-form.tsx
@@ -1,6 +1,12 @@
import { useFormContext } from "react-hook-form";
import { LabelWrapper } from "@/components/label-wrapper";
import type { CatalogCredentialField } from "@/components/models/catalog-models";
+import {
+ Accordion,
+ AccordionContent,
+ AccordionItem,
+ AccordionTrigger,
+} from "@/components/ui/accordion";
import { Input } from "@/components/ui/input";
import { Textarea } from "@/components/ui/textarea";
@@ -8,6 +14,29 @@ export interface ProviderSettingsFormData {
credentials: Record<string, string>;
}
+const AZURE_AUTH_GROUPS = [
+ { key: "api_key", label: "API key", fields: ["api_key"] },
+ {
+ key: "entra_token",
+ label: "Microsoft Entra access token",
+ fields: ["azure_ad_token"],
+ },
+ {
+ key: "service_principal",
+ label: "Microsoft Entra service principal",
+ fields: ["tenant_id", "client_id", "client_secret"],
+ },
+] as const;
+
+const ON_PREM_AUTH_GROUPS = [
+ {
+ key: "username_api_key",
+ label: "Username + API key",
+ fields: ["username", "api_key"],
+ },
+ { key: "zen_api_key", label: "Zen API key", fields: ["zen_api_key"] },
+] as const;
+
/**
* Credential form for a provider with no bespoke dialog, rendered from the
* field spec `/api/models/catalog` publishes for it. A provider added to
@@ -15,15 +44,25 @@ export interface ProviderSettingsFormData {
* further frontend work.
*/
export function ProviderSettingsForm({
+ provider,
providerName,
fields,
savedSecretFields,
saveError,
+ azureAuthMethod,
+ onAzureAuthMethodChange,
+ onPremAuthMethod,
+ onOnPremAuthMethodChange,
}: {
+ provider: string;
providerName: string;
fields: CatalogCredentialField[];
savedSecretFields: string[];
saveError?: string | null;
+ azureAuthMethod?: string;
+ onAzureAuthMethodChange?: (method: string) => void;
+ onPremAuthMethod?: string;
+ onOnPremAuthMethodChange?: (method: string) => void;
}) {
const {
register,
@@ -32,70 +71,169 @@ export function ProviderSettingsForm({
const saved = new Set(savedSecretFields);
- return (
- <div className="min-w-0 space-y-4">
- {fields.map((field) => {
- const error = errors.credentials?.[field.key]?.message;
- const isSecret =
- field.field_type === "password" || field.field_type === "textarea";
- const hasSaved = isSecret && saved.has(field.key);
- // A stored secret is never sent back to the browser, so an empty box
- // means "keep what is saved" rather than "no value" — required only
- // bites when nothing is stored yet.
- const required = field.required && !hasSaved;
+ const renderField = (field: CatalogCredentialField) => {
+ const error = errors.credentials?.[field.key]?.message;
+ const isSecret =
+ field.field_type === "password" || field.field_type === "textarea";
+ const hasSaved = isSecret && saved.has(field.key);
+ // A stored secret is never sent back to the browser, so an empty box
+ // means "keep what is saved" rather than "no value" — required only
+ // bites when nothing is stored yet.
+ const required = field.required && !hasSaved;
- return (
- <div key={field.key} className="min-w-0 space-y-2">
- <LabelWrapper
- label={field.label}
- helperText={field.tooltip ?? undefined}
- required={required}
+ return (
+ <div key={field.key} className="min-w-0 space-y-2">
+ <LabelWrapper
+ label={field.label}
+ helperText={field.tooltip ?? undefined}
+ required={required}
+ id={`provider-field-${field.key}`}
+ >
+ {field.field_type === "textarea" ? (
+ <Textarea
+ {...register(`credentials.${field.key}`, {
+ required: required ? `${field.label} is required` : false,
+ })}
+ className={error ? "!border-destructive" : ""}
+ id={`provider-field-${field.key}`}
+ placeholder={
+ hasSaved ? "•••••••••" : (field.placeholder ?? undefined)
+ }
+ />
+ ) : (
+ <Input
+ {...register(`credentials.${field.key}`, {
+ required: required ? `${field.label} is required` : false,
+ })}
+ className={error ? "!border-destructive" : ""}
id={`provider-field-${field.key}`}
- >
- {field.field_type === "textarea" ? (
- <Textarea
- {...register(`credentials.${field.key}`, {
- required: required ? `${field.label} is required` : false,
- })}
- className={error ? "!border-destructive" : ""}
- id={`provider-field-${field.key}`}
- placeholder={
- hasSaved ? "•••••••••" : (field.placeholder ?? undefined)
- }
- />
- ) : (
- <Input
- {...register(`credentials.${field.key}`, {
- required: required ? `${field.label} is required` : false,
- })}
- className={error ? "!border-destructive" : ""}
- id={`provider-field-${field.key}`}
- type={field.field_type === "password" ? "password" : "text"}
- autoComplete={
- field.field_type === "password" ? "new-password" : "off"
- }
- placeholder={
- hasSaved ? "•••••••••" : (field.placeholder ?? undefined)
- }
- />
- )}
- </LabelWrapper>
- {hasSaved && (
- <p className="text-sm text-muted-foreground">
- A value is already saved. Leave this blank to keep it.
- </p>
- )}
- {error && (
- <p
- data-testid="provider-connection-error"
- className="text-sm text-destructive min-w-0 [overflow-wrap:anywhere]"
- >
- {error}
- </p>
- )}
- </div>
- );
- })}
+ type={field.field_type === "password" ? "password" : "text"}
+ autoComplete={
+ field.field_type === "password" ? "new-password" : "off"
+ }
+ placeholder={
+ hasSaved ? "•••••••••" : (field.placeholder ?? undefined)
+ }
+ />
+ )}
+ </LabelWrapper>
+ {hasSaved && (
+ <p className="text-sm text-muted-foreground">
+ A value is already saved. Leave this blank to keep it.
+ </p>
+ )}
+ {error && (
+ <p
+ data-testid="provider-connection-error"
+ className="text-sm text-destructive min-w-0 [overflow-wrap:anywhere]"
+ >
+ {error}
+ </p>
+ )}
+ </div>
+ );
+ };
+
+ const azureConnectionFields = fields.filter(
+ (field) => field.key === "api_base",
+ );
+ const azureAdvancedFields = fields.filter(
+ (field) => field.key === "api_version",
+ );
+ const onPremConnectionFields = fields.filter(
+ (field) => field.key === "api_base",
+ );
+ const onPremAdvancedFields = fields.filter((field) =>
+ ["space_id", "project_id"].includes(field.key),
+ );
+
+ return (
+ <div className="min-w-0 space-y-4">
+ {provider === "azure" ? (
+ <>
+ {azureConnectionFields.map(renderField)}
+ <Accordion
+ type="single"
+ value={azureAuthMethod ?? "api_key"}
+ onValueChange={(method) =>
+ method && onAzureAuthMethodChange?.(method)
+ }
+ className="space-y-2"
+ >
+ {AZURE_AUTH_GROUPS.map((group) => (
+ <AccordionItem key={group.key} value={group.key}>
+ <AccordionTrigger>
+ {group.label}
+ {group.key === "api_key" && (
+ <span className="ml-2 rounded bg-muted px-2 py-0.5 text-xs">
+ Recommended
+ </span>
+ )}
+ </AccordionTrigger>
+ <AccordionContent className="space-y-4">
+ {group.fields
+ .map((key) => fields.find((field) => field.key === key))
+ .filter((field): field is CatalogCredentialField =>
+ Boolean(field),
+ )
+ .map(renderField)}
+ </AccordionContent>
+ </AccordionItem>
+ ))}
+ </Accordion>
+ <Accordion type="single" collapsible className="space-y-2">
+ <AccordionItem value="advanced">
+ <AccordionTrigger>Advanced settings</AccordionTrigger>
+ <AccordionContent className="space-y-4">
+ {azureAdvancedFields.map(renderField)}
+ </AccordionContent>
+ </AccordionItem>
+ </Accordion>
+ </>
+ ) : provider === "watsonx_onprem" ? (
+ <>
+ {onPremConnectionFields.map(renderField)}
+ <Accordion
+ type="single"
+ value={onPremAuthMethod ?? "username_api_key"}
+ onValueChange={(method) =>
+ method && onOnPremAuthMethodChange?.(method)
+ }
+ className="space-y-2"
+ >
+ {ON_PREM_AUTH_GROUPS.map((group) => (
+ <AccordionItem key={group.key} value={group.key}>
+ <AccordionTrigger>
+ {group.label}
+ {group.key === "username_api_key" && (
+ <span className="ml-2 rounded bg-muted px-2 py-0.5 text-xs">
+ Recommended
+ </span>
+ )}
+ </AccordionTrigger>
+ <AccordionContent className="space-y-4">
+ {group.fields
+ .map((key) => fields.find((field) => field.key === key))
+ .filter((field): field is CatalogCredentialField =>
+ Boolean(field),
+ )
+ .map(renderField)}
+ </AccordionContent>
+ </AccordionItem>
+ ))}
+ </Accordion>
+ <Accordion type="single" collapsible className="space-y-2">
+ <AccordionItem value="advanced">
+ <AccordionTrigger>Advanced settings</AccordionTrigger>
+ <AccordionContent className="space-y-4">
+ {onPremAdvancedFields.map(renderField)}
+ </AccordionContent>
+ </AccordionItem>
+ </Accordion>
+ </>
+ ) : (
+ fields.map(renderField)
+ )}
{saveError && (
<p
data-testid="provider-connection-error"
diff --git a/frontend/components/models/catalog-models.ts b/frontend/components/models/catalog-models.ts
index 0675f2d94..3bfdef715 100644
--- a/frontend/components/models/catalog-models.ts
+++ b/frontend/components/models/catalog-models.ts
@@ -329,6 +329,7 @@ export interface SavedProviderSnapshot {
project_id?: string;
credential_values?: Record<string, string>;
secret_fields?: string[];
+ auth_method?: string | null;
}
export interface SavedProvidersSnapshot {
diff --git a/frontend/components/models/model-features.tsx b/frontend/components/models/model-features.tsx
index ac54326d0..b395ff5b9 100644
--- a/frontend/components/models/model-features.tsx
+++ b/frontend/components/models/model-features.tsx
@@ -34,6 +34,7 @@ const PROVIDER_LOGOS: Record<
openai: OpenAILogo,
anthropic: AnthropicLogo,
watsonx: IBMLogo,
+ watsonx_onprem: IBMLogo,
ollama: OllamaLogo,
// Both Azure rows: `azure_ai` is Foundry, `azure` is Azure OpenAI Service,
// and Microsoft draws the two differently.
diff --git a/frontend/components/models/model-helpers.tsx b/frontend/components/models/model-helpers.tsx
index de449795e..d518180e7 100644
--- a/frontend/components/models/model-helpers.tsx
+++ b/frontend/components/models/model-helpers.tsx
@@ -23,6 +23,7 @@ export const KNOWN_PROVIDERS = [
"anthropic",
"ollama",
"watsonx",
+ "watsonx_onprem",
"azure_ai",
"azure",
"local",
@@ -154,6 +155,14 @@ const PROVIDER_CHROME: Record<string, ProviderChrome> = {
logoColor: "text-white",
logoBgColor: "bg-[#1063FE]",
},
+ // Same product on a Cloud Pak for Data cluster, so the same mark. The two
+ // cards are told apart by the display name the API sends.
+ watsonx_onprem: {
+ name: "IBM watsonx.ai (on-prem)",
+ logo: IBMLogo,
+ logoColor: "text-white",
+ logoBgColor: "bg-[#1063FE]",
+ },
// Microsoft draws the two Azure model services differently, and neither is
// the generic Azure logo. AiFoundryLogo paints its own gradient, so
// logoColor does nothing for it and the tile stays white.
@@ -206,7 +215,7 @@ export function getModelLogo(modelValue: string, provider?: string) {
return <AnthropicLogo className="w-4 h-4" />;
} else if (provider === "ollama") {
return <OllamaLogo className="w-4 h-4" />;
- } else if (provider === "watsonx") {
+ } else if (provider === "watsonx" || provider === "watsonx_onprem") {
return <IBMLogo className="w-4 h-4" />;
} else if (provider === "azure") {
return <AzureOpenAILogo className="w-4 h-4" />;
diff --git a/frontend/components/models/model-selector.tsx b/frontend/components/models/model-selector.tsx
index 10622d4d1..c96a04a61 100644
--- a/frontend/components/models/model-selector.tsx
+++ b/frontend/components/models/model-selector.tsx
@@ -320,6 +320,11 @@ export function ModelSelector({
<div className="w-4 h-4">{group.icon}</div>
)}
<span>{group.group}</span>
+ {groupProvider === "watsonx_onprem" && (
+ <Badge variant="secondary" className="text-xs">
+ On-prem
+ </Badge>
+ )}
</div>
}
>
@@ -371,8 +376,10 @@ export function ModelSelector({
)}
/>
<div className="flex items-center gap-2">
- {option.icon && (
- <span className="h-4 w-4">{option.icon}</span>
+ {(option.icon ?? group.icon) && (
+ <span className="h-4 w-4">
+ {option.icon ?? group.icon}
+ </span>
)}
{option.label}
</div>
diff --git a/frontend/tests/core/z_update_model_providers.spec.ts b/frontend/tests/core/z_update_model_providers.spec.ts
index 9f66ee501..ecfe9536c 100644
--- a/frontend/tests/core/z_update_model_providers.spec.ts
+++ b/frontend/tests/core/z_update_model_providers.spec.ts
@@ -34,7 +34,7 @@ test.describe("Update model providers to watsonx.ai and Azure OpenAI @33219219,
await navigateToSettings(page);
await settings.clickTab("Providers");
await settings.configureWatsonxai();
- await settings.removeModelProviderSetup("Azure OpenAI");
+ await settings.removeModelProviderSetup("azure", "Azure OpenAI");
await settings.clickTab("Agent");
await settings.selectModel("Language model", "ibm/granite-4-h-small");
await settings.clickTab("Ingestion");
@@ -66,7 +66,7 @@ test.describe("Update model providers to watsonx.ai and Azure OpenAI @33219219,
await navigateToSettings(page);
await settings.clickTab("Providers");
await settings.configureAzureOpenAI();
- await settings.removeModelProviderSetup("IBM watsonx.ai");
+ await settings.removeModelProviderSetup("watsonx", "IBM watsonx.ai");
await settings.clickTab("Agent");
await settings.selectModel("Language model", AZURE_CONFIG.language);
await settings.clickTab("Ingestion");
@@ -96,7 +96,7 @@ test.describe("Verify invalid credentials are not accepted for watsonx.ai @34581
await navigateToSettings(page);
await settings.clickTab("Providers");
//Remove existing watsonx.ai setup if present
- await settings.removeModelProviderSetup("IBM watsonx.ai");
+ await settings.removeModelProviderSetup("watsonx", "IBM watsonx.ai");
await settings.configureWatsonxaiInvalidCredentials(
"https://us-south.ml.cloud.ibm.com",
"4865-b94f-d0a80ad0f62a",
diff --git a/frontend/tests/pages/Settings.ts b/frontend/tests/pages/Settings.ts
index c692291ac..73d6c4e58 100644
--- a/frontend/tests/pages/Settings.ts
+++ b/frontend/tests/pages/Settings.ts
@@ -1,4 +1,5 @@
import { expect, Page } from "@playwright/test";
+import type { ModelProvider } from "@/components/models/model-helpers";
import config from "../config/test.config";
import logger from "../utils/logger";
@@ -35,6 +36,8 @@ export class Settings {
private readonly watsonxProjectIDInput = () =>
this.page.locator("#project-id");
private readonly apiKeyInput = () => this.page.locator("#api-key");
+ private readonly providerApiKeyInput = () =>
+ this.page.locator("#provider-field-api_key");
private readonly watsonxEndPointCombobox = () =>
this.page.getByRole("combobox");
private readonly saveModelProviderButton = () =>
@@ -55,36 +58,30 @@ export class Settings {
/**
* Get locator for a provider's card.
*
- * `hasText` matches substrings, so filtering on "OpenAI" also selected the
- * "Azure OpenAI" tile once both providers shipped, and any button lookup
- * inside it blew up under strict mode. Anchor on the card heading, which
- * carries the provider name exactly.
- * @param providerName - Name of the model provider
+ * Card headings are not unique: IBM watsonx.ai and its on-prem variant use
+ * the same visible name. The provider key is stable and uniquely identifies
+ * the card without depending on presentation copy.
+ * @param providerKey - Backend model-provider key
* @returns Locator for the provider card
*/
- private getProviderCard(providerName: string) {
- return this.page.locator("div.rounded-xl, div.border-border.group").filter({
- has: this.page.getByRole("heading", {
- name: providerName,
- exact: true,
- }),
- });
+ private getProviderCard(providerKey: ModelProvider) {
+ return this.page.getByTestId(`model-provider-card-${providerKey}`);
}
/**
* Get locator for configure button by provider name
- * @param providerName - Name of the model provider
+ * @param providerKey - Backend model-provider key
* @returns Locator for the configure button
*/
- private getConfigureButton(providerName: string) {
- return this.getProviderCard(providerName).getByRole("button", {
+ private getConfigureButton(providerKey: ModelProvider) {
+ return this.getProviderCard(providerKey).getByRole("button", {
name: "Configure",
});
}
/**
* Get locator for setup heading by provider name
- * @param providerName - Name of the model provider
+ * @param providerKey - Backend model-provider key
* @returns Locator for the setup heading
*/
private getSetupHeading(providerName: string) {
@@ -117,8 +114,8 @@ export class Settings {
* @param providerName - Name of the model provider
* @returns Locator for the edit setup button
*/
- private getEditSetupButton(providerName: string) {
- return this.getProviderCard(providerName).getByRole("button", {
+ private getEditSetupButton(providerKey: ModelProvider) {
+ return this.getProviderCard(providerKey).getByRole("button", {
name: "Edit Setup",
});
}
@@ -381,8 +378,8 @@ export class Settings {
*/
async configureWatsonxai() {
logger.info("Configuring watsonx.ai settings");
- const configureBtn = this.getConfigureButton("IBM watsonx.ai");
- const editBtn = this.getEditSetupButton("IBM watsonx.ai");
+ const configureBtn = this.getConfigureButton("watsonx");
+ const editBtn = this.getEditSetupButton("watsonx");
// If Configure button is visible -> do setup
if (await configureBtn.isVisible()) {
await configureBtn.click();
@@ -453,29 +450,32 @@ export class Settings {
/**
* Remove model provider configuration
*/
- async removeModelProviderSetup(modelProvider: string) {
- const editButton = this.getEditSetupButton(modelProvider);
- const configureButton = this.getConfigureButton(modelProvider);
+ async removeModelProviderSetup(
+ providerKey: ModelProvider,
+ providerName: string,
+ ) {
+ const editButton = this.getEditSetupButton(providerKey);
+ const configureButton = this.getConfigureButton(providerKey);
// If already configured (Edit Setup visible)
if (await editButton.isVisible()) {
- logger.info(`${modelProvider} is configured. Removing setup...`);
+ logger.info(`${providerName} is configured. Removing setup...`);
await editButton.click();
await this.removeModelProviderButton().click();
await this.getRemoveConfigButton().click();
await this.clickRemoveAnywayIfDisplayed();
await expect(
- this.getToastByText(`${modelProvider} configuration removed`),
+ this.getToastByText(`${providerName} configuration removed`),
).toBeVisible({ timeout: 15000 });
await this.page.waitForTimeout(10000);
}
// If not configured
else if (await configureButton.isVisible()) {
- logger.info(`${modelProvider} is not configured. Skipping removal.`);
+ logger.info(`${providerName} is not configured. Skipping removal.`);
}
// Unexpected state
else {
throw new Error(
- `No Configure/Edit Setup button found for ${modelProvider}`,
+ `No Configure/Edit Setup button found for ${providerName}`,
);
}
}
@@ -504,8 +504,8 @@ export class Settings {
*/
async configureOpenAPI() {
logger.info("Configuring Openai settings");
- const configureBtn = this.getConfigureButton("OpenAI");
- const editBtn = this.getEditSetupButton("OpenAI");
+ const configureBtn = this.getConfigureButton("openai");
+ const editBtn = this.getEditSetupButton("openai");
// If Configure button is visible -> do setup
if (await configureBtn.isVisible()) {
@@ -537,8 +537,8 @@ export class Settings {
*/
async configureAzureOpenAI() {
logger.info("Configuring Azure OpenAI settings");
- const configureBtn = this.getConfigureButton("Azure OpenAI");
- const editBtn = this.getEditSetupButton("Azure OpenAI");
+ const configureBtn = this.getConfigureButton("azure");
+ const editBtn = this.getEditSetupButton("azure");
await this.page.waitForTimeout(500);
if (await configureBtn.isVisible()) {
@@ -555,10 +555,9 @@ export class Settings {
}
}
if (apiKey) {
- const apiKeyInput = this.apiKeyInput();
- if (await apiKeyInput.isVisible()) {
- await apiKeyInput.fill(apiKey);
- }
+ const apiKeyInput = this.providerApiKeyInput();
+ await expect(apiKeyInput).toBeVisible();
+ await apiKeyInput.fill(apiKey);
}
await this.saveModelProviderButton().click();
await this.awaitProviderConfigResult(
@@ -586,7 +585,7 @@ export class Settings {
apiKey: string,
) {
logger.info("Configuring watsonx.ai settings with invalid credentials");
- const configureBtn = this.getConfigureButton("IBM watsonx.ai");
+ const configureBtn = this.getConfigureButton("watsonx");
// If Configure button is visible -> do setup
if (await configureBtn.isVisible()) {
await configureBtn.click();
diff --git a/frontend/tests/utils/provider-detector.ts b/frontend/tests/utils/provider-detector.ts
index e428528a5..93306bfe8 100644
--- a/frontend/tests/utils/provider-detector.ts
+++ b/frontend/tests/utils/provider-detector.ts
@@ -1,6 +1,11 @@
import { Page } from "@playwright/test";
import { Settings } from "../pages/Settings";
+/** Escape a provider name so it can anchor a whole-string heading match. */
+function escapeRegExp(value: string): string {
+ return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
/**
* Utility to detect which model providers are configured
*/
@@ -24,11 +29,13 @@ export class ProviderDetector {
.getByText("Providers")
.waitFor({ state: "visible", timeout: 10000 });
- // Find the heading that matches the provider name exactly
- const providerHeading = this.page.getByRole("heading", {
- name: providerName,
- exact: true,
- });
+ // Match the heading exactly, the way Settings.getProviderCard does. A
+ // substring match picks up every card whose name starts with this one —
+ // "IBM watsonx.ai" would also match "IBM watsonx.ai (on-prem)" wherever
+ // both are offered, and the ambiguous locator fails strict mode.
+ const providerHeading = this.page
+ .locator("h3")
+ .filter({ hasText: new RegExp(`^${escapeRegExp(providerName)}$`) });
try {
await providerHeading.waitFor({ state: "visible", timeout: 10000 });
diff --git a/src/api/models.py b/src/api/models.py
index d06c4122e..bef65c3b0 100644
--- a/src/api/models.py
+++ b/src/api/models.py
@@ -249,6 +249,7 @@ async def get_model_catalog(
CATALOG_UNAVAILABLE_MESSAGE,
CatalogUnavailableError,
catalog,
+ refresh_live_models,
)
# `no-store` for the same reason as /models/providers: the catalogue is
@@ -256,6 +257,9 @@ async def get_model_catalog(
# was supposed to apply the edit. LiteLLM's table is cached in-process, so
# rebuilding this response is cheap.
try:
+ # A cluster-hosted provider is the only source for its own model list,
+ # so ask it before building the payload the pickers read.
+ await refresh_live_models()
return JSONResponse(catalog(), headers={"Cache-Control": "no-store"})
except CatalogUnavailableError as e:
# Log the cause, but never echo exception text back to the caller
diff --git a/src/api/provider_validation.py b/src/api/provider_validation.py
index ef7b6372a..abad24f2b 100644
--- a/src/api/provider_validation.py
+++ b/src/api/provider_validation.py
@@ -4,9 +4,11 @@ import asyncio
import json
import re
from typing import Any
+from urllib.parse import urlparse
import httpx
+from enhancements.providers.registry import get as get_provider_enhancement
from utils.container_utils import transform_localhost_url
from utils.logging_config import get_logger
@@ -127,6 +129,31 @@ def is_provider_credential_error(text: str | BaseException | None) -> bool:
return any(marker in lowered for marker in _PROVIDER_CREDENTIAL_ERROR_MARKERS)
+#: Markers for a TLS trust failure, which is neither a bad credential nor an
+#: unreachable host: the request never left because this deployment does not
+#: trust the certificate the provider presented. Common on an on-prem cluster
+#: fronted by an internal or self-signed CA.
+_PROVIDER_TLS_ERROR_MARKERS = (
+ "certificate_verify_failed",
+ "certificate verify failed",
+ "sslcertverificationerror",
+ "ssl: certificate",
+ "self-signed certificate",
+ "self signed certificate",
+ "unable to get local issuer certificate",
+ "certificate has expired",
+ "hostname mismatch",
+)
+
+
+def is_provider_tls_error(text: str | BaseException | None) -> bool:
+ """True when the call failed because the provider's certificate is not trusted."""
+ if text is None:
+ return False
+ lowered = (str(text) if not isinstance(text, str) else text).lower()
+ return any(marker in lowered for marker in _PROVIDER_TLS_ERROR_MARKERS)
+
+
_GENERIC_UPSTREAM_ERROR_MARKERS = (
"an unknown error occurred",
"an error occurred while generating a response",
@@ -609,6 +636,23 @@ def _extract_error_details(response: httpx.Response) -> str:
return response_text
+#: Providers with a validation path of their own, so they are never handed to
+#: the generic LiteLLM probe. Everything else is validated by making a real call,
+#: which needs a model name.
+_NATIVELY_VALIDATED_PROVIDERS = frozenset({"openai", "azure", "watsonx", "ollama", "anthropic"})
+
+
+def is_azure_ai_foundry_endpoint(api_base: str | None) -> bool:
+ """Whether ``api_base`` is an Azure AI Foundry resource endpoint.
+
+ LiteLLM accepts the resource root and appends its own Foundry request path.
+ Such an endpoint must not use the Azure OpenAI-specific HTTP health check.
+ """
+ if not api_base:
+ return False
+ return (urlparse(api_base).hostname or "").endswith(".services.ai.azure.com")
+
+
async def validate_provider_setup(
provider: str,
api_key: str = None,
@@ -649,7 +693,25 @@ async def validate_provider_setup(
f"Starting validation for provider: {provider_lower} (test_completion={test_completion})"
)
- if provider_lower not in {"openai", "watsonx", "ollama", "anthropic"}:
+ # watsonx.ai on-prem has no bespoke model probe of its own: a real call
+ # through LiteLLM *is* its model probe, and it is what makes switching to
+ # a model the cluster does not serve fail instead of saving silently. Its
+ # catalogue check is only for the case there is no model to probe with,
+ # which is the one that used to report "A model is required".
+ enhancement = get_provider_enhancement(provider_lower)
+ azure_ai_foundry_endpoint = provider_lower == "azure" and is_azure_ai_foundry_endpoint(
+ supplied.get("api_base")
+ )
+ probes_the_model = (
+ bool(embedding_model or llm_model)
+ if enhancement is not None
+ else (
+ provider_lower not in _NATIVELY_VALIDATED_PROVIDERS
+ # Preserve main's Azure/LiteLLM route for Foundry resource URLs.
+ or (azure_ai_foundry_endpoint and bool(embedding_model or llm_model))
+ )
+ )
+ if probes_the_model:
await _test_litellm_provider(
provider=provider_lower,
credentials=supplied,
@@ -657,6 +719,18 @@ async def validate_provider_setup(
llm_model=llm_model,
)
elif test_completion:
+ if provider_lower == "azure":
+ # Azure deployments are user-defined, so a model completion is
+ # not a safe generic probe during onboarding. The deployments
+ # request still verifies the selected authentication method.
+ await test_lightweight_health(
+ provider=provider_lower,
+ api_key=api_key,
+ endpoint=endpoint,
+ project_id=project_id,
+ credentials=supplied,
+ )
+ return
# Full validation with completion/embedding tests (consumes credits)
if embedding_model:
# Test embedding
@@ -683,6 +757,7 @@ async def validate_provider_setup(
api_key=api_key,
endpoint=endpoint,
project_id=project_id,
+ credentials=supplied,
)
logger.info(f"Validation successful for provider: {provider_lower}")
@@ -703,14 +778,24 @@ async def _test_litellm_provider(
"""Validate arbitrary providers through the same LiteLLM adapter used at runtime."""
import litellm
+ from services.model_catalog import litellm_provider_key
+
model = embedding_model or llm_model
if not model:
raise ValueError("A model is required to validate the provider")
- litellm_model = f"{provider}/{model}"
+ # Same aliasing the gateway applies, so the probe hits the route the real
+ # call will: `watsonx_onprem/<model>` is not a prefix LiteLLM can resolve.
+ litellm_model = f"{litellm_provider_key(provider)}/{model}"
if embedding_model:
await litellm.aembedding(
model=litellm_model,
- input="OpenRAG provider validation",
+ # A list, never a bare string. OpenAI accepts either and LiteLLM
+ # forwards whatever it is given, so a string reaches watsonx.ai as
+ # `"inputs": "..."` where it requires `[]string` — the cluster then
+ # answers "Mismatch type []string with value string" and the
+ # pre-save check fails for every embedding model, which leaves a
+ # wrongly-chosen one impossible to change.
+ input=["OpenRAG provider validation"],
**credentials,
)
return
@@ -727,17 +812,24 @@ async def test_lightweight_health(
api_key: str = None,
endpoint: str = None,
project_id: str = None,
+ credentials: dict[str, str] | None = None,
) -> None:
"""Test provider health with lightweight check (no credits consumed)."""
if provider == "openai":
await _test_openai_lightweight_health(api_key)
+ elif provider == "azure":
+ await _test_azure_lightweight_health(
+ credentials or {"api_key": api_key, "api_base": endpoint}
+ )
elif provider == "watsonx":
await _test_watsonx_lightweight_health(api_key, endpoint, project_id)
elif provider == "ollama":
await _test_ollama_lightweight_health(endpoint)
elif provider == "anthropic":
await _test_anthropic_lightweight_health(api_key)
+ elif enhancement := get_provider_enhancement(provider):
+ await enhancement.lightweight_health_check(credentials or {})
else:
raise ValueError(f"Unknown provider: {provider}")
@@ -894,6 +986,61 @@ async def _test_openai_lightweight_health(api_key: str) -> None:
raise
+async def _test_azure_lightweight_health(credentials: dict[str, str]) -> None:
+ """Validate Azure OpenAI credentials without selecting or billing a deployment.
+
+ Azure deployment enumeration is an Azure Resource Manager operation, not an
+ Azure OpenAI data-plane operation. The data plane does provide ``models``;
+ use that endpoint so a valid resource is not rejected with ResourceNotFound.
+ """
+ api_base = credentials.get("api_base")
+ api_version = credentials.get("api_version")
+ api_key = credentials.get("api_key")
+ access_token = credentials.get("azure_ad_token")
+ if not (api_key or access_token or credentials.get("client_secret")):
+ raise ValueError("Azure credentials are required")
+ if not api_base:
+ raise ValueError("API Base is required")
+
+ if not access_token and credentials.get("client_secret"):
+ tenant_id = credentials.get("tenant_id")
+ client_id = credentials.get("client_id")
+ if not tenant_id or not client_id:
+ raise ValueError("tenant_id and client_id are required for Azure service principal")
+ token_response = await _http_request_with_retry(
+ "POST",
+ f"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token",
+ data={
+ "client_id": client_id,
+ "client_secret": credentials["client_secret"],
+ "grant_type": "client_credentials",
+ "scope": "https://cognitiveservices.azure.com/.default",
+ },
+ headers={"Content-Type": "application/x-www-form-urlencoded"},
+ timeout=30.0,
+ )
+ if token_response.status_code != 200:
+ raise Exception(_extract_error_details(token_response))
+ access_token = token_response.json().get("access_token")
+ if not access_token:
+ raise ValueError("Azure service principal did not return an access token")
+
+ headers = {"Content-Type": "application/json"}
+ if access_token:
+ headers["Authorization"] = f"Bearer {access_token}"
+ else:
+ headers["api-key"] = api_key or ""
+ response = await _http_request_with_retry(
+ "GET",
+ f"{api_base.rstrip('/')}/openai/models",
+ headers=headers,
+ params={"api-version": api_version or "2024-10-21"},
+ timeout=30.0,
+ )
+ if response.status_code != 200:
+ raise Exception(_extract_error_details(response))
+
+
async def _test_openai_completion_with_tools(api_key: str, llm_model: str) -> None:
"""Test OpenAI completion with tool calling."""
try:
diff --git a/src/api/settings/endpoints.py b/src/api/settings/endpoints.py
index c78474d44..212f1459d 100644
--- a/src/api/settings/endpoints.py
+++ b/src/api/settings/endpoints.py
@@ -13,7 +13,11 @@ import json
from fastapi import Depends, HTTPException, Request
from fastapi.responses import JSONResponse
-from api.provider_validation import sanitize_provider_error_content, validate_provider_setup
+from api.provider_validation import (
+ is_azure_ai_foundry_endpoint,
+ sanitize_provider_error_content,
+ validate_provider_setup,
+)
from api.settings.helpers import (
_affected_embedding_models,
_create_openrag_docs_filter,
@@ -143,6 +147,7 @@ def _custom_providers_for_settings(openrag_config) -> dict[str, GenericProviderC
configured = configured or stored.configured
return GenericProviderConfig(
configured=configured,
+ auth_method=getattr(stored, "auth_method", None),
credential_values={key: value for key, value in values.items() if value},
secret_fields=list(dict.fromkeys(secrets)),
)
@@ -456,6 +461,40 @@ async def update_settings(
try:
logger.info("Running provider validation before modifying config")
+ # A generic provider save normally has no selected model to
+ # probe. Native Azure OpenAI is the exception: its models route
+ # validates the endpoint and API key without consuming tokens.
+ # Foundry resource URLs instead follow LiteLLM's model route,
+ # preserving the behavior they had on main.
+ for provider, submitted in (body.provider_credentials or {}).items():
+ provider_key = _provider_key(provider)
+ credentials = current_config.providers.pending_credentials(
+ provider_key, submitted
+ )
+ if provider_key == "azure":
+ auth_method = (body.provider_auth_methods or {}).get(provider_key)
+ required_by_method = {
+ "api_key": {"api_key"},
+ "entra_token": {"azure_ad_token"},
+ "service_principal": {"tenant_id", "client_id", "client_secret"},
+ }
+ required = required_by_method.get(auth_method or "")
+ if required is None:
+ raise ValueError("Choose an Azure authentication method")
+ missing = sorted(
+ name for name in required | {"api_base"} if not credentials.get(name)
+ )
+ if missing:
+ raise ValueError(f"{', '.join(missing)} is required for Azure OpenAI")
+ if not is_azure_ai_foundry_endpoint(credentials.get("api_base")):
+ await validate_provider_setup(
+ provider=provider_key,
+ api_key=credentials.get("api_key")
+ or credentials.get("azure_ad_token"),
+ endpoint=credentials.get("api_base"),
+ credentials=credentials,
+ )
+
# Validate LLM provider if being changed
if body.llm_provider is not None or body.llm_model is not None:
llm_provider = (
@@ -481,8 +520,9 @@ async def update_settings(
_provider_key(name): values
for name, values in (body.provider_credentials or {}).items()
}
- credentials = current_config.providers.credential_values(llm_provider_key)
- credentials.update(submitted_credentials.get(llm_provider_key, {}))
+ credentials = current_config.providers.pending_credentials(
+ llm_provider_key, submitted_credentials.get(llm_provider_key, {})
+ )
api_key = credentials.get("api_key", api_key)
endpoint = credentials.get("api_base", endpoint)
project_id = credentials.get("project_id", project_id)
@@ -534,8 +574,10 @@ async def update_settings(
_provider_key(name): values
for name, values in (body.provider_credentials or {}).items()
}
- credentials = current_config.providers.credential_values(embedding_provider_key)
- credentials.update(submitted_credentials.get(embedding_provider_key, {}))
+ credentials = current_config.providers.pending_credentials(
+ embedding_provider_key,
+ submitted_credentials.get(embedding_provider_key, {}),
+ )
api_key = credentials.get("api_key", api_key)
endpoint = credentials.get("api_base", endpoint)
project_id = credentials.get("project_id", project_id)
@@ -838,7 +880,11 @@ async def update_settings(
# Update provider-specific settings
provider_updated = False
for provider, credentials in (body.provider_credentials or {}).items():
- working_config.providers.set_credentials(provider, credentials)
+ working_config.providers.set_credentials(
+ provider,
+ credentials,
+ auth_method=(body.provider_auth_methods or {}).get(_provider_key(provider)),
+ )
config_updated = True
provider_updated = True
@@ -1184,7 +1230,11 @@ async def onboarding(
config_updated = True
for provider, credentials in (body.provider_credentials or {}).items():
- current_config.providers.set_credentials(provider, credentials)
+ current_config.providers.set_credentials(
+ provider,
+ credentials,
+ auth_method=(body.provider_auth_methods or {}).get(_provider_key(provider)),
+ )
config_updated = True
# Mark providers as configured if they were chosen during onboarding
diff --git a/src/api/settings/models.py b/src/api/settings/models.py
index d2e31c5ec..23a1dc639 100644
--- a/src/api/settings/models.py
+++ b/src/api/settings/models.py
@@ -51,6 +51,7 @@ class SettingsUpdateBody(BaseModel):
remove_anthropic_config: bool | None = None
remove_watsonx_config: bool | None = None
provider_credentials: dict[str, dict[str, str]] | None = None
+ provider_auth_methods: dict[str, str] | None = None
remove_provider_config: str | None = None
# Explicit confirmation that the caller accepts removing a provider whose
# embedding models are still in use by indexed documents. Without this,
@@ -70,6 +71,7 @@ class OnboardingBody(BaseModel):
watsonx_project_id: str | None = Field(None, min_length=1)
ollama_endpoint: str | None = Field(None, min_length=1)
provider_credentials: dict[str, dict[str, str]] | None = None
+ provider_auth_methods: dict[str, str] | None = None
class CitationDisplayData(BaseModel):
@@ -179,6 +181,7 @@ class OllamaProviderConfig(BaseModel):
class GenericProviderConfig(BaseModel):
configured: bool
+ auth_method: str | None = None
credential_values: dict[str, str] = Field(default_factory=dict)
secret_fields: list[str] = Field(default_factory=list)
diff --git a/src/api/v1/llm.py b/src/api/v1/llm.py
index d7373fc9e..8a1331a8c 100644
--- a/src/api/v1/llm.py
+++ b/src/api/v1/llm.py
@@ -16,6 +16,7 @@ from services.model_catalog import (
CatalogUnavailableError,
catalog,
openai_models_list,
+ refresh_live_models,
)
from session_manager import User
from utils.logging_config import get_logger
@@ -46,6 +47,8 @@ async def list_openai_models_endpoint(
):
"""OpenAI-compatible model inventory. GET /v1/models"""
try:
+ # A cluster-hosted provider is the only source for its own model list.
+ await refresh_live_models()
return JSONResponse(openai_models_list())
except CatalogUnavailableError as exc:
# Log the cause, but never echo exception text back to the caller
@@ -63,6 +66,7 @@ async def model_catalog_endpoint(
# was supposed to apply the edit. LiteLLM's table is cached in-process, so
# rebuilding this response is cheap.
try:
+ await refresh_live_models()
return JSONResponse(catalog(), headers={"Cache-Control": "no-store"})
except CatalogUnavailableError as exc:
logger.error("Model catalogue unavailable", error=str(exc))
diff --git a/src/config/config_manager.py b/src/config/config_manager.py
index f15ef64dc..99562406e 100644
--- a/src/config/config_manager.py
+++ b/src/config/config_manager.py
@@ -156,6 +156,8 @@ class GenericProviderConfig:
"""Credentials for any LiteLLM provider not covered by legacy fields."""
credentials: dict[str, str] = field(default_factory=dict)
+ # Provider-specific metadata which must not be forwarded to LiteLLM.
+ auth_method: str | None = None
configured: bool = False
@@ -193,7 +195,9 @@ class ProvidersConfig:
return self.ollama
return self.custom.get(provider_lower, GenericProviderConfig())
- def set_credentials(self, provider: str, credentials: dict[str, str]) -> None:
+ def set_credentials(
+ self, provider: str, credentials: dict[str, str], *, auth_method: str | None = None
+ ) -> None:
"""Upsert arbitrary LiteLLM credentials while preserving legacy config."""
key = provider.strip().lower()
clean = {
@@ -208,6 +212,38 @@ class ProvidersConfig:
# picked as a fallback provider and called with no key at all.
return
previous = self.custom.get(key, GenericProviderConfig())
+ if key == "azure" and auth_method:
+ methods = {
+ "api_key": {"api_key"},
+ "entra_token": {"azure_ad_token"},
+ "service_principal": {"tenant_id", "client_id", "client_secret"},
+ }
+ active = methods.get(auth_method)
+ if active is None:
+ raise ValueError(f"Unknown Azure authentication method: {auth_method}")
+ shared = {"api_base", "api_version", "base_model"}
+ # Credentials for another authentication method must not leak into
+ # LiteLLM's call kwargs after the user switches methods.
+ previous.credentials = {
+ name: value
+ for name, value in previous.credentials.items()
+ if name in shared or name in active
+ }
+ previous.auth_method = auth_method
+ if key == "watsonx_onprem" and auth_method:
+ methods = {
+ "username_api_key": {"username", "api_key"},
+ "zen_api_key": {"zen_api_key"},
+ }
+ active = methods.get(auth_method)
+ if active is None:
+ raise ValueError(f"Unknown watsonx.ai on-prem authentication method: {auth_method}")
+ previous.credentials = {
+ name: value
+ for name, value in previous.credentials.items()
+ if name in {"api_base", "space_id", "project_id"} or name in active
+ }
+ previous.auth_method = auth_method
previous.credentials.update(clean)
previous.configured = True
self.custom[key] = previous
@@ -226,8 +262,39 @@ class ProvidersConfig:
self.ollama.endpoint = clean.get("api_base", self.ollama.endpoint)
self.ollama.configured = bool(self.ollama.endpoint)
+ def pending_credentials(
+ self, provider: str, submitted: dict[str, str] | None = None
+ ) -> dict[str, str]:
+ """LiteLLM kwargs for `provider` as it would be once `submitted` is saved.
+
+ Validation runs before the write, so it has to reason about the union of
+ what is stored and what the request carries. For a provider whose stored
+ form is not already LiteLLM's — watsonx.ai on-prem keeps a username and
+ an API key, and hands LiteLLM the ZenApiKey built from them — the two
+ halves have to be merged *before* the translation, or a request that
+ changes the API key would be validated against a stale credential built
+ from the old one.
+ """
+ from enhancements.providers.registry import get as get_provider_enhancement
+
+ key = provider.strip().lower()
+ clean = {
+ str(name): str(value).strip()
+ for name, value in (submitted or {}).items()
+ if str(name).strip() and str(value).strip()
+ }
+ enhancement = get_provider_enhancement(key)
+ if enhancement:
+ stored = self.custom.get(key, GenericProviderConfig()).credentials
+ return enhancement.litellm_credentials({**stored, **clean})
+ values = self.credential_values(key)
+ values.update(clean)
+ return values
+
def credential_values(self, provider: str) -> dict[str, str]:
"""Return LiteLLM keyword arguments for a configured provider."""
+ from enhancements.providers.registry import get as get_provider_enhancement
+
key = provider.strip().lower()
custom = dict(self.custom.get(key, GenericProviderConfig()).credentials)
if key == "openai":
@@ -254,6 +321,13 @@ class ProvidersConfig:
if endpoint:
custom.setdefault("api_base", endpoint)
return custom
+ enhancement = get_provider_enhancement(key)
+ if enhancement:
+ # The stored form is what a Cloud Pak for Data operator has in hand
+ # (cluster URL, username, API key); LiteLLM wants a ZenApiKey. The
+ # translation lives with the provider so the gateway, the health
+ # check and the validator all issue the same call.
+ return enhancement.litellm_credentials(custom)
return custom
@@ -358,6 +432,7 @@ class OpenRAGConfig:
credentials[key] = decrypt_secret(credentials[key])
return GenericProviderConfig(
credentials=credentials,
+ auth_method=p_data.get("auth_method"),
configured=bool(p_data.get("configured", credentials)),
)
diff --git a/src/config/model_providers.py b/src/config/model_providers.py
index d96adaeb6..bee0584bd 100644
--- a/src/config/model_providers.py
+++ b/src/config/model_providers.py
@@ -138,9 +138,11 @@ def _normalize(entry: Any, seen: set[str]) -> dict[str, Any] | None:
if not isinstance(raw_modes, dict):
raw_modes = {}
display_name = str(entry.get("display_name") or "").strip() or name
+ badge = str(entry.get("badge") or "").strip()
return {
"name": name,
"display_name": display_name,
+ "badge": badge,
# Missing keys stay missing here; `is_visible` reads them as False.
"modes": {str(mode).strip().lower(): _as_bool(value) for mode, value in raw_modes.items()},
# Optional: ids the catalogue cannot learn from LiteLLM's static table.
@@ -271,7 +273,11 @@ def provider_visibility_payload(run_mode: str | None = None) -> dict[str, Any]:
return {
"run_mode": mode,
"providers": [
- {"name": entry["name"], "display_name": entry["display_name"]}
+ {
+ "name": entry["name"],
+ "display_name": entry["display_name"],
+ "badge": entry["badge"],
+ }
for entry in visible_providers(mode)
],
}
diff --git a/src/config/model_providers.yaml b/src/config/model_providers.yaml
index d159315fc..b0d91d7de 100644
--- a/src/config/model_providers.yaml
+++ b/src/config/model_providers.yaml
@@ -56,6 +56,36 @@ providers:
on_prem: true
saas: true
+ # watsonx.ai running on a Cloud Pak for Data / IBM Software Hub cluster. It
+ # is a second front door onto the same `/ml/v1` API as the row above, kept
+ # separate because the two need their own credentials: the cluster
+ # authenticates with a ZenApiKey built from a CPD username and API key, not
+ # with an IBM Cloud IAM key, and it is reached at a cluster URL rather than a
+ # region endpoint. OpenRAG routes it through LiteLLM's `watsonx` provider —
+ # see `enhancements/providers/watsonx/onprem.py`.
+ #
+ # The two lists below are a *fallback*, not the catalogue. OpenRAG asks the
+ # cluster itself what it serves (`GET /ml/v1/foundation_model_specs`) and
+ # shows that in the pickers, so a model the cluster does not have is never
+ # offered. These rows are what it falls back to while the cluster is
+ # unreachable or before any credentials are entered — keep them plausible for
+ # your fleet, but there is no need to keep them exact.
+ - name: watsonx_onprem
+ display_name: IBM watsonx.ai
+ badge: On-prem
+ modes:
+ oss: false
+ on_prem: false
+ saas: false # a cluster-hosted deployment has no place in multi-tenant SaaS
+ # Checked against a Cloud Pak for Data 5.x cluster, which serves exactly
+ # these two. Note the embedding id has no `-v2` suffix: `slate-30m-
+ # english-rtrvr-v2` is an IBM Cloud id and 404s here, which is the kind of
+ # near-miss that makes a guessed fallback worse than none.
+ models:
+ - openai/gpt-oss-120b
+ embedding_models:
+ - ibm/slate-30m-english-rtrvr
+
- name: anthropic
display_name: Anthropic
modes:
@@ -65,9 +95,9 @@ providers:
- name: azure_ai
display_name: Azure AI Foundry
modes:
- oss: true
+ oss: false
on_prem: false
- saas: false # local inference is not offered in SaaS
+ saas: false
# Azure OpenAI Service, which LiteLLM keys separately from Foundry above:
# `azure_ai` is the Foundry catalogue (Llama, Phi, Mistral, Cohere, and the
@@ -78,7 +108,7 @@ providers:
modes:
oss: true
on_prem: false
- saas: false
+ saas: true
# Azure serves the same OpenAI models, so it needs the same exclusions.
# The plain name covers the regional ids (`eu/`, `us/`, `global/`) too.
exclude_models:
@@ -95,10 +125,12 @@ providers:
# A self-hosted OpenAI-compatible endpoint (vLLM, LM Studio, an internal
# gateway). Use one of LiteLLM's passthrough provider keys — `openai_like`,
# `hosted_vllm`, `lm_studio`, `llamafile`, `custom_openai` — rather than
- # inventing a name: the key has to be one LiteLLM can route, or the
+ # inventing a name: the key has to be one the gateway can route, or the
# `provider:model` ids it publishes resolve to the default provider and get
- # called with the wrong credentials. The endpoint and key are entered in
- # Settings; only the model ids belong here.
+ # called with the wrong credentials. (A name of OpenRAG's own works only if
+ # it is registered in `PROVIDER_ROUTE_ALIASES` in `services/model_catalog.py`
+ # alongside the LiteLLM key it routes as, the way `watsonx_onprem` is.) The
+ # endpoint and key are entered in Settings; only the model ids belong here.
#
# - name: openai_like
# display_name: Internal LLM Gateway
diff --git a/src/services/docling_service.py b/src/services/docling_service.py
index ab1b8f22d..88f92fa35 100644
--- a/src/services/docling_service.py
+++ b/src/services/docling_service.py
@@ -157,7 +157,7 @@ class DoclingService:
preview_mode: bool = False,
) -> dict[str, Any]:
"""Build the options payload for docling from OpenRAG configs, incorporating VLM settings if enabled."""
- from services.watsonx_iam import WatsonxIamError, get_iam_token
+ from enhancements.providers.watsonx.iam import WatsonxIamError, get_iam_token
config = get_openrag_config()
knowledge_config = config.knowledge
diff --git a/src/services/llm_gateway.py b/src/services/llm_gateway.py
index 2cd0dd42c..6acf8e026 100644
--- a/src/services/llm_gateway.py
+++ b/src/services/llm_gateway.py
@@ -13,7 +13,7 @@ from collections.abc import AsyncIterator, Mapping
from typing import Any, Literal
from services import provider_error_log
-from services.model_catalog import is_known_provider
+from services.model_catalog import is_known_provider, litellm_provider_key
from utils.logging_config import get_logger
logger = get_logger(__name__)
@@ -95,12 +95,23 @@ def split_model_id(model: str) -> tuple[str | None, str]:
# also part of vendor-qualified names. When the whole string names exactly
# one catalogue model, that provider owns it — `openai/gpt-oss-120b` is
# watsonx's model, not OpenAI's `gpt-oss-120b`.
- from services.model_catalog import catalog_owner
+ from services.model_catalog import catalog_owner, catalog_owners
owner = catalog_owner(raw)
if owner:
return owner, raw
+ if catalog_owners(raw):
+ # More than one provider serves this exact id, so the text before the
+ # slash is part of the model's own name and not a provider tag. A
+ # deployment offering both watsonx.ai on IBM Cloud and on a cluster has
+ # `openai/gpt-oss-120b` twice; splitting it would hand the id to OpenAI
+ # — with OpenAI's key, for a model OpenAI does not serve. Leaving it
+ # untagged sends it to the configured default provider whole, which is
+ # right whenever that provider is one of the two and a clean "no such
+ # model" when it is not.
+ return None, raw
+
prefix, rest = raw.split("/", 1)
prefix_lower = prefix.lower()
if is_known_provider(prefix_lower):
@@ -222,7 +233,11 @@ def resolve_call(
provider = default_provider(kind, cfg)
name = requested
credentials = provider_credentials(provider, cfg)
- litellm_model = f"{provider}/{name}" if provider != "openai" else name
+ # An OpenRAG provider that LiteLLM does not know by that name is routed
+ # under the key it aliases (`watsonx_onprem` -> `watsonx`). The OpenRAG key
+ # is still what the caller sees and what credentials are stored under.
+ route = litellm_provider_key(provider)
+ litellm_model = f"{route}/{name}" if route != "openai" else name
return litellm_model, provider, credentials
@@ -230,6 +245,14 @@ _UPSTREAM_FAILURE_MESSAGE = "The model provider could not be reached. Please try
_UPSTREAM_CREDENTIAL_MESSAGE = (
"The configured API key is invalid or has been revoked. Update it in Settings and retry."
)
+#: A TLS trust failure reads as an outage otherwise — the request never left the
+#: process, so there is no provider error to quote and the text collapses to
+#: "could not be reached", which sends an operator hunting for a network fault.
+#: Nothing in Settings fixes this, so the message says who has to act.
+_UPSTREAM_TLS_MESSAGE = (
+ "The provider's TLS certificate is not trusted by this deployment. An operator needs to "
+ "add the provider's CA certificate to OpenRAG's trust store."
+)
#: Longest upstream explanation we will echo. Provider bodies can embed a whole
@@ -258,7 +281,16 @@ _ANSI_PATTERN = re.compile(r"\x1b\[[0-9;]*m")
def _call_label(provider: str, model: str) -> str:
- """`provider/model` for humans, without repeating a prefix LiteLLM already added."""
+ """`provider/model` for humans, without repeating a prefix LiteLLM already added.
+
+ The model here is the routed id, so for an aliased provider it carries the
+ *LiteLLM* prefix rather than the OpenRAG one — naively joining them gives
+ "watsonx_onprem/watsonx/openai/gpt-oss-120b", which names two providers and
+ reads like a bug in the error it appears in.
+ """
+ route = litellm_provider_key(provider) if provider else ""
+ if route and route != provider and model.startswith(f"{route}/"):
+ model = model[len(route) + 1 :]
if model and provider and not model.startswith(f"{provider}/"):
return f"{provider}/{model}"
return model or provider or "provider"
@@ -390,9 +422,18 @@ def _upstream_client_message(
credential failure keeps its actionable message so onboarding can tell the
user to fix the key.
"""
- from api.provider_validation import is_generic_upstream_error, is_provider_credential_error
+ from api.provider_validation import (
+ is_generic_upstream_error,
+ is_provider_credential_error,
+ is_provider_tls_error,
+ )
label = _call_label(provider, model)
+ # Checked before the credential branch: a TLS failure often carries
+ # "unauthorized"-adjacent wording from the transport wrapper, and telling
+ # someone to rotate a working API key wastes the trip.
+ if is_provider_tls_error(detail):
+ return f"{_UPSTREAM_TLS_MESSAGE} ({label})"
if is_provider_credential_error(detail):
return f"{_UPSTREAM_CREDENTIAL_MESSAGE} ({label})"
upstream = _provider_error_text(detail, exc)
@@ -974,6 +1015,19 @@ def _log_stream_shape(tally: _StreamTally, provider: str, model: str) -> None:
logger.debug("Could not summarise stream shape", exc_info=True)
+def _embedding_input(value: Any) -> Any:
+ """OpenAI's `input`, in the shape every provider behind us accepts.
+
+ OpenAI takes a bare string as well as an array, so its clients send both —
+ and LiteLLM forwards whichever it is given. watsonx.ai takes only an array
+ and rejects a string with "Mismatch type []string with value string", so a
+ client that sends one gets a failure that reads like a bug in its own
+ request. Wrapping is a no-op for a provider that already accepted the
+ string, and token-array inputs are left exactly as they are.
+ """
+ return [value] if isinstance(value, str) else value
+
+
async def embeddings(body: Mapping[str, Any], *, config=None) -> dict[str, Any]:
"""OpenAI `POST /v1/embeddings`."""
cfg = config or _get_config()
@@ -985,7 +1039,7 @@ async def embeddings(body: Mapping[str, Any], *, config=None) -> dict[str, Any]:
result = await litellm.aembedding(
model=litellm_model,
- input=body.get("input"),
+ input=_embedding_input(body.get("input")),
**credentials,
)
except LlmGatewayError:
diff --git a/src/services/model_catalog.py b/src/services/model_catalog.py
index 47a4d074f..5fa6fe376 100644
--- a/src/services/model_catalog.py
+++ b/src/services/model_catalog.py
@@ -31,6 +31,13 @@ from functools import lru_cache
from typing import Any
from config.model_providers import ProviderEntry, visible_provider_entries
+from enhancements.providers.registry import (
+ credential_field_overrides,
+ route_aliases,
+)
+from enhancements.providers.registry import (
+ enhancements as provider_enhancements,
+)
from utils.logging_config import get_logger
logger = get_logger(__name__)
@@ -88,6 +95,23 @@ GENERIC_CREDENTIAL_FIELDS: list[dict[str, Any]] = [
KNOWN_FIELD_TYPES = frozenset({"text", "password", "select", "textarea", "upload"})
+#: OpenRAG provider keys LiteLLM cannot route under their own name, mapped to
+#: the key it routes them as. A row here is for a deployment shape that needs
+#: its own credentials and its own model list but reaches the same API — the
+#: alternative, reusing the upstream key, would make the two share one set of
+#: stored credentials.
+PROVIDER_ROUTE_ALIASES: dict[str, str] = route_aliases()
+
+#: Credential forms LiteLLM's `provider_create_fields.json` cannot supply,
+#: because the provider is one of OpenRAG's own aliases.
+_CREDENTIAL_FIELD_OVERRIDES: dict[str, list[dict[str, Any]]] = credential_field_overrides()
+
+
+def litellm_provider_key(provider: str) -> str:
+ """The name LiteLLM routes `provider` under, which is usually itself."""
+ key = (provider or "").strip().lower()
+ return PROVIDER_ROUTE_ALIASES.get(key, key)
+
class CatalogUnavailableError(RuntimeError):
"""LiteLLM is not importable, so no catalogue can be built.
@@ -155,8 +179,12 @@ def _normalize_field(field: dict[str, Any]) -> dict[str, Any]:
def credential_fields(provider: str) -> list[dict[str, Any]]:
"""The form spec for `provider`, normalized, never empty."""
+ key = (provider or "").strip().lower()
+ override = _CREDENTIAL_FIELD_OVERRIDES.get(key)
+ if override is not None:
+ return [_normalize_field(field) for field in override]
try:
- spec = _provider_field_specs().get((provider or "").strip().lower())
+ spec = _provider_field_specs().get(key)
except Exception:
logger.warning("Could not read LiteLLM's provider field specs", exc_info=True)
return [dict(field) for field in GENERIC_CREDENTIAL_FIELDS]
@@ -241,6 +269,12 @@ def _catalog(providers: tuple[ProviderEntry, ...]) -> dict[str, Any]:
raise CatalogUnavailableError("litellm is not installed on the server") from exc
specs = _provider_field_specs()
+ # Matched on OpenRAG's own key, never the aliased LiteLLM one: a provider
+ # that routes as `watsonx` but serves whatever an operator deployed on
+ # their cluster must not inherit IBM Cloud's catalogue. Two providers
+ # sharing model ids would also leave `catalog_owner` unable to say which of
+ # them owns an id, and a legacy slash-form id would resolve to neither.
+ # An aliased provider's models come from its `models:` rows instead.
keys = {entry.name for entry in providers}
chat_by_provider: dict[str, list[dict[str, Any]]] = {}
embed_by_provider: dict[str, list[dict[str, Any]]] = {}
@@ -371,6 +405,58 @@ def hide_excluded_live_models(provider: str, payload: Any) -> Any:
return filtered
+def _catalog_entries() -> tuple[ProviderEntry, ...]:
+ """The visible providers, with a live model list swapped in where we have one.
+
+ A Cloud Pak for Data cluster serves whatever its operator deployed, so its
+ `models:` rows in `model_providers.yaml` can only ever be a guess. Once the
+ cluster has said what it actually has, that wins — a model it does not
+ serve must not sit in the picker waiting to be chosen. The configured rows
+ stay as the fallback for when it cannot be reached.
+
+ Entries are the `_catalog()` cache key, so substituting here rebuilds the
+ payload rather than serving a stale one.
+ """
+ entries = visible_provider_entries()
+ live_models = {
+ enhancement.PROVIDER_KEY: enhancement.cached_models()
+ for enhancement in provider_enhancements()
+ if hasattr(enhancement, "cached_models")
+ }
+ return tuple(
+ entry._replace(models=live.chat, embedding_models=live.embedding)
+ if (live := live_models.get(entry.name)) is not None
+ else entry
+ for entry in entries
+ )
+
+
+async def refresh_live_models() -> None:
+ """Re-list the models on any provider that can only answer for itself.
+
+ Called by the catalogue routes before the payload is built. The provider
+ caches with a TTL, so this is a network call once every few minutes rather
+ than once per request, and a failure leaves the previous answer — or the
+ configured fallback — in place.
+ """
+ from config.settings import get_openrag_config
+
+ for enhancement in provider_enhancements():
+ if enhancement.PROVIDER_KEY not in supported_provider_keys() or not hasattr(
+ enhancement, "fetch_models"
+ ):
+ continue
+ try:
+ credentials = get_openrag_config().providers.credential_values(enhancement.PROVIDER_KEY)
+ except Exception:
+ logger.debug(
+ "Could not read credentials for %s", enhancement.PROVIDER_KEY, exc_info=True
+ )
+ continue
+ if credentials:
+ await enhancement.fetch_models(credentials)
+
+
def supported_provider_keys() -> frozenset[str]:
"""The providers this run mode publishes, per `config/model_providers.yaml`."""
return frozenset(entry.name for entry in visible_provider_entries())
@@ -378,14 +464,21 @@ def supported_provider_keys() -> frozenset[str]:
def catalog(today: datetime.date | None = None) -> dict[str, Any]:
"""Picker payload for the providers this run mode exposes, and their models."""
- return _catalog_for(today or datetime.date.today(), visible_provider_entries())
+ return _catalog_for(today or datetime.date.today(), _catalog_entries())
def is_known_provider(provider: str) -> bool:
- """Whether LiteLLM recognises `provider` at all."""
+ """Whether `provider` names a route the gateway can resolve.
+
+ That is LiteLLM's own provider list, plus OpenRAG's aliases — an alias is
+ routable by definition, since it is only ever a second front door onto a
+ provider LiteLLM already knows.
+ """
key = (provider or "").strip().lower()
if not key:
return False
+ if key in PROVIDER_ROUTE_ALIASES:
+ return True
try:
import litellm
@@ -424,20 +517,25 @@ def _model_owners(providers: tuple[ProviderEntry, ...]) -> dict[str, tuple[str,
return {model: tuple(sorted(keys)) for model, keys in owners.items()}
+def catalog_owners(model: str) -> tuple[str, ...]:
+ """Every provider in this run mode whose catalogue lists `model`."""
+ name = (model or "").strip()
+ if not name:
+ return ()
+ try:
+ return _model_owners(_catalog_entries()).get(name) or ()
+ except Exception:
+ return ()
+
+
def catalog_owner(model: str) -> str | None:
"""The single provider that serves `model`, if exactly one does.
Used to disambiguate vendor-qualified names such as `openai/gpt-oss-120b`,
which watsonx serves and whose own prefix names a different provider.
"""
- name = (model or "").strip()
- if not name:
- return None
- try:
- owners = _model_owners(visible_provider_entries()).get(name)
- except Exception:
- return None
- return owners[0] if owners and len(owners) == 1 else None
+ owners = catalog_owners(model)
+ return owners[0] if len(owners) == 1 else None
def PROVIDER_SEPARATOR_SAFE_CHECK() -> list[str]:
@@ -447,7 +545,7 @@ def PROVIDER_SEPARATOR_SAFE_CHECK() -> list[str]:
Exposed so a test can fail loudly if a future model id breaks the property.
"""
ambiguous = []
- for model in _model_owners(visible_provider_entries()):
+ for model in _model_owners(_catalog_entries()):
head, sep, rest = model.partition(":")
if sep and rest and is_known_provider(head.lower()):
ambiguous.append(model)
diff --git a/tests/unit/api/test_settings_endpoints.py b/tests/unit/api/test_settings_endpoints.py
index 57180c35e..169d4565e 100644
--- a/tests/unit/api/test_settings_endpoints.py
+++ b/tests/unit/api/test_settings_endpoints.py
@@ -3,7 +3,7 @@ Unit tests for api.settings.endpoints
Validates error handling in update_docling_preset endpoint.
"""
-from unittest.mock import AsyncMock, MagicMock
+from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from fastapi import HTTPException
@@ -187,6 +187,77 @@ async def test_update_settings_vlm_azure_configured():
assert saved_config.knowledge.vlm_model == "azure/gpt-4.1"
+async def test_update_settings_rejects_azure_without_an_api_key():
+ """The API must enforce the Azure form requirement, not only the browser."""
+ from api.settings.endpoints import update_settings
+ from config.config_manager import OpenRAGConfig
+
+ config = OpenRAGConfig.from_dict({})
+ config.edited = True
+ body = SettingsUpdateBody(
+ provider_credentials={"azure": {"api_base": "https://example.openai.azure.com"}},
+ provider_auth_methods={"azure": "api_key"},
+ )
+ rbac = MagicMock()
+ rbac.has_permission = AsyncMock(return_value=True)
+
+ with patch("api.settings.endpoints.get_openrag_config", return_value=config):
+ response = await update_settings(
+ body=body,
+ session_manager=AsyncMock(),
+ user=MagicMock(spec=User),
+ models_service=MagicMock(),
+ rbac=rbac,
+ )
+
+ assert response.status_code == 400
+ assert b"api_key" in response.body
+
+
+async def test_update_settings_validates_azure_credentials_before_saving():
+ """A bad Azure endpoint/key must not become a configured provider."""
+ from api.settings.endpoints import update_settings
+ from config.config_manager import OpenRAGConfig
+
+ config = OpenRAGConfig.from_dict({})
+ config.edited = True
+ body = SettingsUpdateBody(
+ provider_credentials={
+ "azure": {
+ "api_key": "wrong-key",
+ "api_base": "https://example.openai.azure.com",
+ }
+ },
+ provider_auth_methods={"azure": "api_key"},
+ )
+ rbac = MagicMock()
+ rbac.has_permission = AsyncMock(return_value=True)
+
+ with (
+ patch("api.settings.endpoints.get_openrag_config", return_value=config),
+ patch(
+ "api.settings.endpoints.validate_provider_setup",
+ new_callable=AsyncMock,
+ side_effect=Exception("Access denied due to invalid subscription key"),
+ ) as validate,
+ patch("api.settings.endpoints.config_manager.save_config_file") as save,
+ ):
+ response = await update_settings(
+ body=body,
+ session_manager=AsyncMock(),
+ user=MagicMock(spec=User),
+ models_service=MagicMock(),
+ rbac=rbac,
+ )
+
+ assert response.status_code == 400
+ assert b"invalid subscription key" in response.body
+ validate.assert_awaited_once()
+ save.assert_not_called()
+
+
@pytest.mark.parametrize(
"provider",
["openai", "watsonx", "anthropic", "local", "ollama", "azure", "azure_ai", "openai_like"],
diff --git a/tests/unit/enhancements/providers/watsonx/test_onprem.py b/tests/unit/enhancements/providers/watsonx/test_onprem.py
new file mode 100644
index 000000000..2cdb29ddb
--- /dev/null
+++ b/tests/unit/enhancements/providers/watsonx/test_onprem.py
@@ -0,0 +1,764 @@
+"""watsonx.ai on a Cloud Pak for Data cluster, routed through LiteLLM's watsonx provider."""
+
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+
+import config.model_providers as model_providers
+from config.config_manager import (
+ AnthropicConfig,
+ GenericProviderConfig,
+ OllamaConfig,
+ OpenAIConfig,
+ ProvidersConfig,
+ WatsonXConfig,
+)
+from enhancements.providers.watsonx import onprem as watsonx_onprem
+from services import model_catalog
+from services.llm_gateway import resolve_call, split_model_id
+
+PROVIDER = watsonx_onprem.PROVIDER_KEY
+
+
[email protected](autouse=True)
+def _reload_provider_config():
+ model_providers.reload()
+ yield
+ model_providers.reload()
+
+
+def _providers(**credentials) -> ProvidersConfig:
+ return ProvidersConfig(
+ openai=OpenAIConfig(),
+ anthropic=AnthropicConfig(),
+ watsonx=WatsonXConfig(),
+ ollama=OllamaConfig(),
+ custom={PROVIDER: GenericProviderConfig(credentials=dict(credentials), configured=True)},
+ )
+
+
+def test_zen_api_key_is_the_base64_cpd_docs_describe() -> None:
+ # `echo "<username>:<apikey>" | base64`, which is what the cluster expects
+ # after `Authorization: ZenApiKey `.
+ assert watsonx_onprem.zen_api_key("cpduser", "APIKEY") == "Y3BkdXNlcjpBUElLRVk="
+
+
[email protected]("username, api_key", [("", "APIKEY"), ("cpduser", ""), (None, None)])
+def test_a_half_filled_form_yields_no_zen_key(username, api_key) -> None:
+ """Better no credential than one that looks valid and 401s on first use."""
+ assert watsonx_onprem.zen_api_key(username, api_key) == ""
+
+
+def test_username_never_reaches_litellm() -> None:
+ """LiteLLM forwards kwargs it does not recognise, so a stray field lands in the body."""
+ credentials = watsonx_onprem.litellm_credentials(
+ {"api_base": "https://cpd.example.com", "username": "cpduser", "api_key": "APIKEY"}
+ )
+
+ assert "username" not in credentials
+ assert credentials["api_base"] == "https://cpd.example.com"
+ # Both, and the same value: the embeddings path refuses the call outright
+ # when api_key is unset, and builds its auth header from zen_api_key.
+ assert credentials["zen_api_key"] == "Y3BkdXNlcjpBUElLRVk="
+ assert credentials["api_key"] == "Y3BkdXNlcjpBUElLRVk="
+
+
+def test_a_pasted_zen_key_is_used_as_given() -> None:
+ credentials = watsonx_onprem.litellm_credentials(
+ {"api_base": "https://cpd.example.com", "zen_api_key": "cHJlOmVuY29kZWQ="}
+ )
+
+ assert credentials["zen_api_key"] == "cHJlOmVuY29kZWQ="
+ assert credentials["api_key"] == "cHJlOmVuY29kZWQ="
+
+
+def test_an_api_key_with_no_username_authenticates_to_nothing() -> None:
+ """Username is optional on the form, and leaving it blank used to fail silently.
+
+ A Cloud Pak for Data API key is not a bearer token — the cluster trades a
+ username *and* a key for one. Sending the raw key got a 401 that read as bad
+ credentials rather than incomplete ones, and the model listing then fell
+ back to the configured list with nothing on screen to say why.
+ """
+ stored = {"api_base": "https://cpd.example.com", "api_key": "APIKEY"}
+
+ # Still handed to LiteLLM, which is free to make its own attempt with it.
+ assert watsonx_onprem.litellm_credentials(stored)["api_key"] == "APIKEY"
+ assert "zen_api_key" not in watsonx_onprem.litellm_credentials(stored)
+ # But OpenRAG's own calls send no header, so the health check reports
+ # missing credentials instead of the cluster reporting bad ones.
+ assert watsonx_onprem.auth_header(stored) == ""
+ assert watsonx_onprem.auth_header({**stored, "username": "cpduser"}).startswith("ZenApiKey ")
+
+
+def test_a_deployment_scope_is_passed_through_untouched() -> None:
+ credentials = watsonx_onprem.litellm_credentials(
+ {
+ "api_base": "https://cpd.example.com",
+ "username": "cpduser",
+ "api_key": "APIKEY",
+ "space_id": "space-1",
+ "project_id": "proj-1",
+ }
+ )
+
+ assert credentials["space_id"] == "space-1"
+ assert credentials["project_id"] == "proj-1"
+
+
+def test_credential_values_translates_the_stored_form() -> None:
+ providers = _providers(api_base="https://cpd.example.com", username="cpduser", api_key="APIKEY")
+
+ assert providers.credential_values(PROVIDER) == {
+ "api_base": "https://cpd.example.com",
+ "zen_api_key": "Y3BkdXNlcjpBUElLRVk=",
+ "api_key": "Y3BkdXNlcjpBUElLRVk=",
+ }
+
+
+def test_pending_credentials_rebuilds_the_zen_key_from_a_submitted_change() -> None:
+ """Validation runs before the write, on the union of stored and submitted.
+
+ Merging after the translation would validate a new API key against a Zen
+ key still built from the old one.
+ """
+ providers = _providers(api_base="https://cpd.example.com", username="cpduser", api_key="OLDKEY")
+
+ pending = providers.pending_credentials(PROVIDER, {"api_key": "NEWKEY"})
+
+ assert pending["zen_api_key"] == watsonx_onprem.zen_api_key("cpduser", "NEWKEY")
+ assert pending["api_base"] == "https://cpd.example.com"
+
+
+def test_the_gateway_routes_it_as_watsonx() -> None:
+ """`watsonx_onprem/<model>` is not a prefix LiteLLM can resolve."""
+ config = SimpleNamespace(
+ providers=_providers(
+ api_base="https://cpd.example.com", username="cpduser", api_key="APIKEY"
+ ),
+ agent=SimpleNamespace(llm_model="", llm_provider="openai"),
+ knowledge=SimpleNamespace(embedding_model="", embedding_provider="openai"),
+ )
+
+ litellm_model, provider, credentials = resolve_call(
+ f"{PROVIDER}:ibm/granite-3-3-8b-instruct", kind="chat", config=config
+ )
+
+ assert litellm_model == "watsonx/ibm/granite-3-3-8b-instruct"
+ # The OpenRAG key is what the caller and the credential store still see.
+ assert provider == PROVIDER
+ assert credentials["zen_api_key"] == "Y3BkdXNlcjpBUElLRVk="
+
+
+def test_the_alias_is_routable_so_ids_are_not_billed_to_the_default_provider() -> None:
+ assert model_catalog.is_known_provider(PROVIDER)
+ assert model_catalog.litellm_provider_key(PROVIDER) == "watsonx"
+ assert model_catalog.litellm_provider_key("openai") == "openai"
+
+
+def test_it_ships_on_prem_and_never_in_saas(monkeypatch) -> None:
+ """on_prem is the mode it exists for; SaaS is the one it must never reach.
+
+ Nothing is asserted about `oss`: that row gets flipped on for local testing
+ the way `azure_ai`'s is, and a test that pins it only breaks the next person
+ who needs the card in their dev stack.
+ """
+ monkeypatch.setenv("OPENRAG_RUN_MODE", "on_prem")
+ assert PROVIDER in model_providers.visible_provider_keys()
+
+ monkeypatch.setenv("OPENRAG_RUN_MODE", "saas")
+ assert PROVIDER not in model_providers.visible_provider_keys()
+
+
+def test_the_settings_form_asks_for_cluster_credentials_not_ibm_cloud_ones() -> None:
+ fields = {field["key"]: field for field in model_catalog.credential_fields(PROVIDER)}
+
+ assert fields["api_base"]["required"] is True
+ assert set(fields) == {
+ "api_base",
+ "username",
+ "api_key",
+ "zen_api_key",
+ "space_id",
+ "project_id",
+ }
+ assert model_catalog.secret_field_keys(PROVIDER) == {"api_key", "zen_api_key"}
+
+
+def test_its_models_come_from_config_not_ibm_clouds_price_table(monkeypatch) -> None:
+ """Two providers sharing model ids would leave `catalog_owner` unable to pick one."""
+ monkeypatch.setenv("OPENRAG_RUN_MODE", "on_prem")
+ entries = {entry["key"]: entry for entry in model_catalog.catalog()["providers"]}
+
+ onprem = entries[PROVIDER]
+ declared = {entry.name: entry for entry in model_providers.visible_provider_entries()}[PROVIDER]
+
+ assert {entry["model"] for entry in onprem["models"]} == set(declared.models)
+ assert {entry["model"] for entry in onprem["embedding_models"]} == set(
+ declared.embedding_models
+ )
+ assert onprem["embedding_models"], "an embedding provider with no ids can never be selected"
+
+
+def test_an_id_both_watsonx_rows_serve_is_never_handed_to_its_prefix(monkeypatch) -> None:
+ """`openai/gpt-oss-120b` is watsonx's model, not OpenAI's.
+
+ A cluster that also serves it puts the id under two providers, so
+ `catalog_owner` cannot pick one. The old fallback split on the slash and
+ routed it to OpenAI — with OpenAI's key, for a model OpenAI does not have.
+ """
+ monkeypatch.setenv("OPENRAG_RUN_MODE", "on_prem")
+ model = "openai/gpt-oss-120b"
+
+ if len(model_catalog.catalog_owners(model)) < 2:
+ pytest.skip("this deployment's config does not list the id under both watsonx rows")
+
+ assert model_catalog.catalog_owner(model) is None
+ # Untagged, so it goes to the configured default provider whole rather than
+ # to whichever provider the prefix happens to name.
+ assert split_model_id(model) == (None, model)
+
+
+def test_a_scopeless_cluster_call_carries_no_null_space_id() -> None:
+ """The lightweight engine uses neither a project nor a space.
+
+ LiteLLM 1.84 refuses the call locally and, past that, serialises the absent
+ space as `"space_id": null`. Both are wrong for that install.
+ """
+ watsonx_onprem.install_litellm_compatibility()
+
+ from litellm.llms.watsonx.chat.handler import _get_api_params
+ from litellm.llms.watsonx.chat.transformation import IBMWatsonXChatConfig
+
+ api_params = _get_api_params(params={}, model="ibm/granite-3-3-8b-instruct")
+ payload = IBMWatsonXChatConfig()._prepare_payload(
+ model="ibm/granite-3-3-8b-instruct", api_params=api_params
+ )
+
+ assert payload == {"model_id": "ibm/granite-3-3-8b-instruct"}
+
+
+def test_a_scope_that_is_set_still_reaches_the_cluster() -> None:
+ watsonx_onprem.install_litellm_compatibility()
+
+ from litellm.llms.watsonx.chat.handler import _get_api_params
+ from litellm.llms.watsonx.chat.transformation import IBMWatsonXChatConfig
+
+ api_params = _get_api_params(
+ params={"space_id": "space-1"}, model="ibm/granite-3-3-8b-instruct"
+ )
+ payload = IBMWatsonXChatConfig()._prepare_payload(
+ model="ibm/granite-3-3-8b-instruct", api_params=api_params
+ )
+
+ assert payload == {"model_id": "ibm/granite-3-3-8b-instruct", "space_id": "space-1"}
+
+
+def test_a_self_signed_cluster_cert_is_reported_as_a_trust_problem() -> None:
+ """The request never leaves the process, so there is no provider error to quote.
+
+ Without this the message collapses to "could not be reached", which sends an
+ operator hunting for a network fault instead of a missing CA.
+ """
+ from services.llm_gateway import _upstream_client_message
+
+ detail = (
+ "InternalServerError: WatsonxException - Cannot connect to host "
+ "cpd.example.com:443 ssl:True [SSLCertVerificationError: (1, '[SSL: "
+ "CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed "
+ "certificate in certificate chain (_ssl.c:1032)')]"
+ )
+
+ message = _upstream_client_message(detail, PROVIDER, "watsonx/ibm/granite-3-3-8b-instruct")
+
+ assert "TLS certificate is not trusted" in message
+ assert "CA certificate" in message
+ # Not mistaken for a bad key: rotating a working ZenApiKey fixes nothing.
+ assert "API key" not in message
+
+
+def test_a_revoked_key_still_reads_as_a_credential_problem() -> None:
+ from services.llm_gateway import _upstream_client_message
+
+ message = _upstream_client_message(
+ 'InternalServerError: {"errorCode":"BXNIM0415E","errorMessage":"Provided API key '
+ 'could not be found."}',
+ PROVIDER,
+ "watsonx/ibm/granite-3-3-8b-instruct",
+ )
+
+ assert "API key is invalid" in message
+
+
+def test_a_shared_id_reaches_the_cluster_under_the_selected_provider(monkeypatch) -> None:
+ """The real failure: `openai/gpt-oss-120b` picked while watsonx_onprem is selected.
+
+ Settings stores the provider and the bare model id separately, so the id
+ arrives untagged. Splitting it on the slash threw away the selected provider
+ and called OpenAI with OpenAI's key for a model OpenAI does not serve.
+ """
+ monkeypatch.setenv("OPENRAG_RUN_MODE", "on_prem")
+ model = "openai/gpt-oss-120b"
+ if len(model_catalog.catalog_owners(model)) < 2:
+ pytest.skip("this deployment's config does not list the id under both watsonx rows")
+
+ config = SimpleNamespace(
+ providers=_providers(
+ api_base="https://cpd.example.com", username="cpduser", api_key="APIKEY"
+ ),
+ agent=SimpleNamespace(llm_model=model, llm_provider=PROVIDER),
+ knowledge=SimpleNamespace(embedding_model="", embedding_provider="openai"),
+ )
+
+ litellm_model, provider, credentials = resolve_call(None, kind="chat", config=config)
+
+ assert provider == PROVIDER
+ assert litellm_model == f"watsonx/{model}"
+ assert credentials["zen_api_key"] == "Y3BkdXNlcjpBUElLRVk="
+
+
+async def test_health_needs_no_model_selected(monkeypatch) -> None:
+ """The banner reported "A model is required to validate the provider".
+
+ Every generic provider is validated by making a real call, so one that is
+ configured but has no model chosen yet failed validation and surfaced as a
+ provider error — pointing at the credentials dialog for something that was
+ never a credentials problem. The cluster's catalogue endpoint needs no
+ model, no project and no space.
+ """
+ from api import provider_validation
+
+ called: dict[str, Any] = {}
+
+ async def _fake_request(method, url, **kwargs):
+ called["method"] = method
+ called["url"] = url
+ called["params"] = kwargs.get("params") or {}
+ called["auth"] = kwargs.get("headers", {}).get("Authorization")
+ return SimpleNamespace(status_code=200, text="{}", json=lambda: {"resources": []})
+
+ monkeypatch.setattr(watsonx_onprem, "_http_request_with_retry", _fake_request)
+
+ credentials = watsonx_onprem.litellm_credentials(
+ {"api_base": "https://cpd.example.com/", "username": "cpduser", "api_key": "APIKEY"}
+ )
+ await provider_validation.validate_provider_setup(
+ provider=PROVIDER, credentials=credentials, llm_model=None, embedding_model=None
+ )
+
+ assert called["method"] == "GET"
+ # No query on the URL: httpx replaces a URL's query when it is given
+ # `params`, and a `?version=` baked into the URL is then silently dropped —
+ # the cluster answers `invalid_version_date_pattern` for the empty version
+ # that results.
+ assert called["url"] == "https://cpd.example.com/ml/v1/foundation_model_specs"
+ assert called["params"]["version"] == watsonx_onprem.API_VERSION
+ assert called["auth"] == "ZenApiKey Y3BkdXNlcjpBUElLRVk="
+
+
+async def test_health_reports_a_rejected_zen_key_as_a_credential_problem(monkeypatch) -> None:
+ from api import provider_validation
+ from api.provider_validation import is_provider_credential_error
+
+ async def _fake_request(method, url, **kwargs):
+ return SimpleNamespace(
+ status_code=401,
+ text='{"errors":[{"message":"Failed to authenticate the request"}]}',
+ json=lambda: {"errors": [{"message": "Failed to authenticate the request"}]},
+ )
+
+ monkeypatch.setattr(watsonx_onprem, "_http_request_with_retry", _fake_request)
+
+ credentials = watsonx_onprem.litellm_credentials(
+ {"api_base": "https://cpd.example.com", "username": "cpduser", "api_key": "APIKEY"}
+ )
+ with pytest.raises(Exception) as excinfo:
+ await provider_validation.validate_provider_setup(
+ provider=PROVIDER, credentials=credentials, llm_model=None, embedding_model=None
+ )
+
+ # Classified as a credential failure so the banner offers "update the key"
+ # rather than "the provider could not be reached".
+ assert is_provider_credential_error(str(excinfo.value))
+
+
+def test_the_health_probe_uses_the_same_tls_setting_as_real_traffic(monkeypatch) -> None:
+ """`SSL_CERT_FILE`/`SSL_VERIFY` are read by LiteLLM, not by httpx.
+
+ Without this the banner could sit red on a certificate error while chat
+ through the gateway works, or the reverse.
+ """
+ monkeypatch.setenv("SSL_VERIFY", "false")
+ assert watsonx_onprem.ssl_verify() is False
+
+ monkeypatch.setenv("SSL_VERIFY", "true")
+ monkeypatch.delenv("SSL_CERT_FILE", raising=False)
+ assert watsonx_onprem.ssl_verify() is True
+
+
+async def test_switching_to_a_model_the_cluster_lacks_is_still_blocked(monkeypatch) -> None:
+ """Settings validates before it writes and returns 400 on failure.
+
+ The catalogue check added for the no-model case must not become the check
+ for *every* case: with a model in hand the probe has to be a real call, or a
+ switch to a model the cluster does not serve saves silently and only fails
+ later in chat.
+ """
+ import litellm
+
+ from api import provider_validation
+
+ probes: list[str] = []
+
+ async def _unexpected_http(method, url, **kwargs):
+ probes.append("catalogue")
+ return SimpleNamespace(status_code=200, text="{}", json=lambda: {"resources": []})
+
+ async def _fake_completion(**kwargs):
+ probes.append("real-call")
+ raise Exception('{"errors":[{"message":"Model \'ibm/nope\' is not supported"}]}')
+
+ monkeypatch.setattr(watsonx_onprem, "_http_request_with_retry", _unexpected_http)
+ monkeypatch.setattr(litellm, "acompletion", _fake_completion)
+
+ credentials = watsonx_onprem.litellm_credentials(
+ {"api_base": "https://cpd.example.com", "username": "cpduser", "api_key": "APIKEY"}
+ )
+ with pytest.raises(Exception, match="not supported"):
+ await provider_validation.validate_provider_setup(
+ provider=PROVIDER, credentials=credentials, llm_model="ibm/nope", embedding_model=None
+ )
+
+ assert probes == ["real-call"], "a model in hand must be probed for real"
+
+
+async def test_switching_an_embedding_model_is_probed_for_real(monkeypatch) -> None:
+ import litellm
+
+ from api import provider_validation
+
+ probes: list[str] = []
+
+ async def _fake_embedding(**kwargs):
+ probes.append(kwargs.get("model"))
+ return {"data": []}
+
+ monkeypatch.setattr(litellm, "aembedding", _fake_embedding)
+
+ credentials = watsonx_onprem.litellm_credentials(
+ {"api_base": "https://cpd.example.com", "username": "cpduser", "api_key": "APIKEY"}
+ )
+ await provider_validation.validate_provider_setup(
+ provider=PROVIDER,
+ credentials=credentials,
+ llm_model=None,
+ embedding_model="ibm/slate-125m-english-rtrvr-v2",
+ )
+
+ assert probes == ["watsonx/ibm/slate-125m-english-rtrvr-v2"]
+
+
+def _forget_cluster_models():
+ watsonx_onprem.forget_models()
+ yield
+ watsonx_onprem.forget_models()
+
+
+def _specs_response(resources, status_code=200):
+ return SimpleNamespace(
+ status_code=status_code,
+ text="",
+ json=lambda: {"resources": [dict(entry) for entry in resources]},
+ )
+
+
+#: Trimmed from a real Cloud Pak for Data cluster's `foundation_model_specs`
+#: response. The shapes matter: `functions` is a list of `{"id": ...}`,
+#: `lifecycle` is a list rather than a string, and the chat model's own name
+#: begins with another provider's key.
+CLUSTER_RESOURCES = [
+ {
+ "model_id": "ibm/slate-30m-english-rtrvr",
+ "functions": [{"id": "embedding"}, {"id": "rerank"}, {"id": "similarity"}],
+ "lifecycle": [{"id": "available", "current_state": True}],
+ "input_tier": "class_c1",
+ },
+ {
+ "model_id": "openai/gpt-oss-120b",
+ "functions": [{"id": "autoai_rag"}, {"id": "text_chat"}],
+ "task_ids": ["summarization", "generation", "function_calling"],
+ "lifecycle": [{"id": "available", "current_state": True}],
+ "input_tier": "class_8",
+ },
+ {
+ "model_id": "ibm/granite-preview",
+ "functions": [{"id": "text_chat"}],
+ "input_tier": "tech_preview",
+ },
+ {
+ "model_id": "ibm/granite-retired",
+ "functions": [{"id": "text_chat"}],
+ "lifecycle": [{"id": "withdrawn", "current_state": True}],
+ },
+]
+
+
+def test_a_cluster_listing_is_split_into_the_two_pickers() -> None:
+ """Split locally rather than with the API's `filters` grammar.
+
+ The grammar is a SaaS convenience; a cluster that does not accept it would
+ answer 400 and leave both pickers empty.
+ """
+ models = watsonx_onprem.split_models(CLUSTER_RESOURCES)
+
+ assert models.chat == ("openai/gpt-oss-120b",)
+ assert models.embedding == ("ibm/slate-30m-english-rtrvr",)
+ # tech_preview is not requestable on every deployment; withdrawn is retired.
+ assert "ibm/granite-preview" not in models.chat
+ assert "ibm/granite-retired" not in models.chat
+
+
+async def test_the_picker_shows_what_the_cluster_serves(
+ monkeypatch, _forget_cluster_models
+) -> None:
+ """A cluster serves whatever its operator deployed.
+
+ The configured `models:` rows can only ever be a guess, so a model the
+ cluster does not have would otherwise sit in the picker waiting to be
+ chosen and fail at the first call.
+ """
+ monkeypatch.setenv("OPENRAG_RUN_MODE", "on_prem")
+ seen: dict[str, Any] = {}
+
+ class _Client:
+ def __init__(self, **kwargs):
+ pass
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, *exc):
+ return False
+
+ async def get(self, url, headers=None, params=None):
+ seen["url"] = url
+ seen["params"] = dict(params or {})
+ assert headers["Authorization"].startswith("ZenApiKey ")
+ return _specs_response(CLUSTER_RESOURCES)
+
+ monkeypatch.setattr("httpx.AsyncClient", _Client)
+
+ models = await watsonx_onprem.fetch_models(
+ {"api_base": "https://cpd.example.com", "username": "u", "api_key": "k"}
+ )
+
+ # The version has to travel in `params`; httpx would drop it from the URL.
+ assert seen["url"] == "https://cpd.example.com/ml/v1/foundation_model_specs"
+ assert seen["params"]["version"] == watsonx_onprem.API_VERSION
+ # No project: a lightweight-engine install has none, and sending one 404s.
+ assert "project_id" not in seen["params"]
+
+ assert models.chat == ("openai/gpt-oss-120b",)
+ assert models.embedding == ("ibm/slate-30m-english-rtrvr",)
+
+ entry = {e["key"]: e for e in model_catalog.catalog()["providers"]}[PROVIDER]
+ assert [m["model"] for m in entry["models"]] == ["openai/gpt-oss-120b"]
+ assert [m["model"] for m in entry["embedding_models"]] == ["ibm/slate-30m-english-rtrvr"]
+
+
+async def test_a_next_page_is_re_based_on_the_operators_cluster_url(
+ monkeypatch, _forget_cluster_models
+) -> None:
+ """A cluster names itself internally in its own pagination links.
+
+ This one answers `https://wx-inference-proxy-upstream/ml/v1/...`, which does
+ not resolve outside the cluster. Following it verbatim strands the listing
+ on page one.
+ """
+ urls: list[str] = []
+
+ class _Client:
+ def __init__(self, **kwargs):
+ pass
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, *exc):
+ return False
+
+ async def get(self, url, headers=None, params=None):
+ urls.append(url)
+ if len(urls) == 1:
+ return SimpleNamespace(
+ status_code=200,
+ text="",
+ json=lambda: {
+ "resources": [CLUSTER_RESOURCES[1]],
+ "next": {
+ "href": "https://wx-inference-proxy-upstream"
+ "/ml/v1/foundation_model_specs?version=2024-03-13&start=2"
+ },
+ },
+ )
+ return _specs_response([CLUSTER_RESOURCES[0]])
+
+ monkeypatch.setattr("httpx.AsyncClient", _Client)
+
+ models = await watsonx_onprem.fetch_models(
+ {"api_base": "https://cpd.example.com", "username": "u", "api_key": "k"}
+ )
+
+ assert urls[1].startswith("https://cpd.example.com/ml/v1/foundation_model_specs")
+ assert "wx-inference-proxy-upstream" not in urls[1]
+ assert "start=2" in urls[1]
+ assert models.chat == ("openai/gpt-oss-120b",)
+ assert models.embedding == ("ibm/slate-30m-english-rtrvr",)
+
+
+async def test_an_unreachable_cluster_keeps_the_configured_fallback(
+ monkeypatch, _forget_cluster_models
+) -> None:
+ """A catalogue request must never fail because the cluster is down."""
+ monkeypatch.setenv("OPENRAG_RUN_MODE", "on_prem")
+
+ class _Client:
+ def __init__(self, **kwargs):
+ pass
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, *exc):
+ return False
+
+ async def get(self, url, headers=None, params=None):
+ raise OSError("cluster unreachable")
+
+ monkeypatch.setattr("httpx.AsyncClient", _Client)
+
+ assert (
+ await watsonx_onprem.fetch_models(
+ {"api_base": "https://cpd.example.com", "username": "u", "api_key": "k"}
+ )
+ is None
+ )
+
+ declared = {e.name: e for e in model_providers.visible_provider_entries()}[PROVIDER]
+ entry = {e["key"]: e for e in model_catalog.catalog()["providers"]}[PROVIDER]
+ assert {m["model"] for m in entry["models"]} == set(declared.models)
+
+
+async def test_an_empty_listing_is_treated_as_a_bad_filter_not_an_empty_cluster(
+ monkeypatch, _forget_cluster_models
+) -> None:
+ """Emptying both pickers on a guess would be worse than showing the fallback."""
+
+ class _Client:
+ def __init__(self, **kwargs):
+ pass
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, *exc):
+ return False
+
+ async def get(self, url, headers=None, params=None):
+ return _specs_response([])
+
+ monkeypatch.setattr("httpx.AsyncClient", _Client)
+
+ assert (
+ await watsonx_onprem.fetch_models(
+ {"api_base": "https://cpd.example.com", "username": "u", "api_key": "k"}
+ )
+ is None
+ )
+ assert watsonx_onprem.cached_models() is None
+
+
+async def test_validating_an_embedding_model_sends_a_list_not_a_string(monkeypatch) -> None:
+ """watsonx.ai takes `inputs` only as an array.
+
+ OpenAI accepts a bare string, so the validator sent one and LiteLLM
+ forwarded it verbatim. The cluster answered "Mismatch type []string with
+ value string", which failed the pre-save check for *every* embedding model
+ and left a wrongly-chosen one impossible to change.
+ """
+ import litellm
+
+ from api import provider_validation
+
+ sent: dict[str, object] = {}
+
+ async def _fake_embedding(**kwargs):
+ sent.update(kwargs)
+ return {"data": [{"embedding": [0.1]}]}
+
+ monkeypatch.setattr(litellm, "aembedding", _fake_embedding)
+
+ await provider_validation.validate_provider_setup(
+ provider=PROVIDER,
+ credentials=watsonx_onprem.litellm_credentials(
+ {"api_base": "https://cpd.example.com", "username": "u", "api_key": "k"}
+ ),
+ llm_model=None,
+ embedding_model="ibm/slate-30m-english-rtrvr",
+ )
+
+ assert isinstance(sent["input"], list), sent["input"]
+
+
+async def test_a_client_sending_a_bare_string_input_still_embeds(monkeypatch) -> None:
+ """OpenAI's own contract allows a string, so clients send one."""
+ import litellm
+
+ from services.llm_gateway import embeddings
+
+ sent: dict[str, object] = {}
+
+ async def _fake_embedding(**kwargs):
+ sent.update(kwargs)
+ return {"data": [{"embedding": [0.1]}], "model": "m", "object": "list"}
+
+ monkeypatch.setattr(litellm, "aembedding", _fake_embedding)
+
+ config = SimpleNamespace(
+ providers=_providers(
+ api_base="https://cpd.example.com", username="cpduser", api_key="APIKEY"
+ ),
+ agent=SimpleNamespace(llm_model="", llm_provider=PROVIDER),
+ knowledge=SimpleNamespace(
+ embedding_model="ibm/slate-30m-english-rtrvr",
+ embedding_provider=PROVIDER,
+ legacy_embedding_provider_map={},
+ ),
+ )
+ await embeddings(
+ {"model": f"{PROVIDER}:ibm/slate-30m-english-rtrvr", "input": "hello"}, config=config
+ )
+
+ assert sent["input"] == ["hello"]
+
+
+def test_a_token_array_input_is_left_alone() -> None:
+ """Only a string is wrapped; OpenAI's token-array forms pass through."""
+ from services.llm_gateway import _embedding_input
+
+ assert _embedding_input("hello") == ["hello"]
+ assert _embedding_input(["a", "b"]) == ["a", "b"]
+ assert _embedding_input([[1, 2], [3]]) == [[1, 2], [3]]
+ assert _embedding_input([1, 2, 3]) == [1, 2, 3]
diff --git a/tests/unit/services/test_llm_gateway.py b/tests/unit/services/test_llm_gateway.py
index 3bb896178..a8be49969 100644
--- a/tests/unit/services/test_llm_gateway.py
+++ b/tests/unit/services/test_llm_gateway.py
@@ -593,10 +593,25 @@ def test_a_vendor_qualified_name_is_not_mistaken_for_a_provider_tag():
Splitting on the slash routed it to OpenAI as a bare `gpt-oss-120b`, which
LiteLLM rejects with "LLM Provider NOT provided", surfacing to the user as
"The model provider could not be reached."
+
+ Whether the id names one owner or several depends on the deployment's
+ provider config — a cluster row that also lists it makes two — so what is
+ asserted here is the part that must hold either way: the id is never handed
+ to the provider its prefix happens to name.
"""
from services.llm_gateway import split_model_id
-
- assert split_model_id("openai/gpt-oss-120b") == ("watsonx", "openai/gpt-oss-120b")
+ from services.model_catalog import catalog_owners
+
+ provider, name = split_model_id("openai/gpt-oss-120b")
+
+ assert name == "openai/gpt-oss-120b"
+ owners = catalog_owners("openai/gpt-oss-120b")
+ if len(owners) == 1:
+ assert provider == owners[0]
+ else:
+ # Untagged; `resolve_call` picks between the owners with the config in
+ # hand. Either way it is not "openai".
+ assert provider is None
def test_model_ids_served_by_v1_models_round_trip():
diff --git a/tests/unit/services/test_model_catalog.py b/tests/unit/services/test_model_catalog.py
index b3e5c4203..e82644e78 100644
--- a/tests/unit/services/test_model_catalog.py
+++ b/tests/unit/services/test_model_catalog.py
@@ -72,6 +72,11 @@ def test_openai_form_is_the_plain_one_not_the_compatible_variant() -> None:
assert required == ["api_key"]
+def test_azure_openai_leaves_auth_fields_optional_for_method_selection() -> None:
+ """The UI selects one complete Azure auth method over LiteLLM's flat form."""
+ assert model_catalog.required_field_keys("azure") == ["api_base"]
+
+
def test_an_unknown_provider_still_gets_a_usable_form() -> None:
fields = model_catalog.credential_fields("some-private-gateway")
assert [field["key"] for field in fields] == ["api_key", "api_base"]
diff --git a/tests/unit/test_docling_service.py b/tests/unit/test_docling_service.py
index 4e8b57457..27d2da89a 100644
--- a/tests/unit/test_docling_service.py
+++ b/tests/unit/test_docling_service.py
@@ -293,7 +293,9 @@ async def test_build_vlm_options_watsonx(docling_service):
mock_config = _vlm_mock_config("watsonx")
with (
patch("services.docling_service.get_openrag_config", return_value=mock_config),
- patch("services.watsonx_iam.get_iam_token", new_callable=AsyncMock) as mock_token,
+ patch(
+ "enhancements.providers.watsonx.iam.get_iam_token", new_callable=AsyncMock
+ ) as mock_token,
):
mock_token.return_value = "iam-token"
options = await docling_service._build_docling_options_async()
diff --git a/tests/unit/test_openai_provider_check_retry.py b/tests/unit/test_openai_provider_check_retry.py
index ff411d668..340694f3e 100644
--- a/tests/unit/test_openai_provider_check_retry.py
+++ b/tests/unit/test_openai_provider_check_retry.py
@@ -7,7 +7,12 @@ from unittest.mock import AsyncMock
import httpx
import pytest
-from api.provider_validation import _http_request_with_retry, _test_openai_lightweight_health
+from api.provider_validation import (
+ _http_request_with_retry,
+ _test_azure_lightweight_health,
+ _test_openai_lightweight_health,
+ validate_provider_setup,
+)
@pytest.mark.asyncio
@@ -125,3 +130,54 @@ async def test_openai_lightweight_health_succeeds_with_retry(monkeypatch):
# Should run cleanly without raising exception
await _test_openai_lightweight_health("sk-test-key")
assert attempts == 1
+
+
+async def test_azure_lightweight_health_checks_endpoint_and_key(monkeypatch):
+ captured = {}
+
+ async def fake_retry(method, url, **kwargs):
+ captured.update(method=method, url=url, **kwargs)
+ return httpx.Response(200, json={"data": []})
+
+ monkeypatch.setattr("api.provider_validation._http_request_with_retry", fake_retry)
+
+ await _test_azure_lightweight_health(
+ {
+ "api_key": "azure-key",
+ "api_base": "https://example.openai.azure.com/",
+ "api_version": "2024-10-21",
+ }
+ )
+
+ assert captured["method"] == "GET"
+ assert captured["url"] == "https://example.openai.azure.com/openai/models"
+ assert captured["headers"]["api-key"] == "azure-key"
+ assert captured["params"] == {"api-version": "2024-10-21"}
+
+
+async def test_azure_lightweight_health_rejects_missing_credentials():
+ with pytest.raises(ValueError, match="Azure credentials are required"):
+ await _test_azure_lightweight_health({"api_base": "https://example.openai.azure.com"})
+
+
+async def test_azure_foundry_endpoint_uses_the_litellm_route(monkeypatch):
+ """Foundry resource roots must retain main's Azure/LiteLLM behavior."""
+ litellm_probe = AsyncMock()
+ health_check = AsyncMock()
+ monkeypatch.setattr("api.provider_validation._test_litellm_provider", litellm_probe)
+ monkeypatch.setattr("api.provider_validation.test_lightweight_health", health_check)
+
+ await validate_provider_setup(
+ provider="azure",
+ llm_model="gpt-4.1",
+ credentials={
+ "api_key": "azure-key",
+ "api_base": "https://example.services.ai.azure.com/",
+ },
+ )
+
+ litellm_probe.assert_awaited_once()
+ health_check.assert_not_awaited()