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__.pynew file mode 100644index 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.pynew file mode 100644index 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__.pynew file mode 100644index 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.pysimilarity index 100%rename from src/services/watsonx_iam.pyrename to enhancements/providers/watsonx/iam.pydiff --git a/enhancements/providers/watsonx/onprem.py b/enhancements/providers/watsonx/onprem.pynew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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 && (<pdata-testid="provider-connection-error"diff --git a/frontend/components/models/catalog-models.ts b/frontend/components/models/catalog-models.tsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsindex 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 @34581await 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.tsindex 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 setupif (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 configuredelse if (await configureButton.isVisible()) {- logger.info(`${modelProvider} is not configured. Skipping removal.`);+ logger.info(`${providerName} is not configured. Skipping removal.`);}// Unexpected stateelse {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 setupif (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 setupif (await configureBtn.isVisible()) {await configureBtn.click();diff --git a/frontend/tests/utils/provider-detector.ts b/frontend/tests/utils/provider-detector.tsindex 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.pyindex 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 callerdiff --git a/src/api/provider_validation.py b/src/api/provider_validation.pyindex ef7b6372a..abad24f2b 100644--- a/src/api/provider_validation.py+++ b/src/api/provider_validation.py@@ -4,9 +4,11 @@ import asyncioimport jsonimport refrom typing import Any+from urllib.parse import urlparseimport httpx+from enhancements.providers.registry import get as get_provider_enhancementfrom utils.container_utils import transform_localhost_urlfrom 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_modelif 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.pyindex c78474d44..212f1459d 100644--- a/src/api/settings/endpoints.py+++ b/src/api/settings/endpoints.py@@ -13,7 +13,11 @@ import jsonfrom fastapi import Depends, HTTPException, Requestfrom 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, GenericProviderCconfigured = configured or stored.configuredreturn 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 changedif 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): valuesfor 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): valuesfor 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 settingsprovider_updated = Falsefor 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 = Trueprovider_updated = True@@ -1184,7 +1230,11 @@ async def onboarding(config_updated = Truefor 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 onboardingdiff --git a/src/api/settings/models.py b/src/api/settings/models.pyindex 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 = Noneremove_watsonx_config: bool | None = Noneprovider_credentials: dict[str, dict[str, str]] | None = None+ provider_auth_methods: dict[str, str] | None = Noneremove_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 = Noneclass CitationDisplayData(BaseModel):@@ -179,6 +181,7 @@ class OllamaProviderConfig(BaseModel):class GenericProviderConfig(BaseModel):configured: bool+ auth_method: str | None = Nonecredential_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.pyindex 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 Userfrom 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.pyindex 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 = Noneconfigured: bool = False@@ -193,7 +195,9 @@ class ProvidersConfig:return self.ollamareturn 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.returnprevious = 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_methodprevious.credentials.update(clean)previous.configured = Trueself.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.pyindex 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.yamlindex d159315fc..b0d91d7de 100644--- a/src/config/model_providers.yaml+++ b/src/config/model_providers.yaml@@ -56,6 +56,36 @@ providers:on_prem: truesaas: 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: anthropicdisplay_name: Anthropicmodes:@@ -65,9 +95,9 @@ providers:- name: azure_aidisplay_name: Azure AI Foundrymodes:- oss: true+ oss: falseon_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: trueon_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 Gatewaydiff --git a/src/services/docling_service.py b/src/services/docling_service.pyindex 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_tokenconfig = get_openrag_config()knowledge_config = config.knowledgediff --git a/src/services/llm_gateway.py b/src/services/llm_gateway.pyindex 2cd0dd42c..6acf8e026 100644--- a/src/services/llm_gateway.py+++ b/src/services/llm_gateway.py@@ -13,7 +13,7 @@ from collections.abc import AsyncIterator, Mappingfrom typing import Any, Literalfrom services import provider_error_log-from services.model_catalog import is_known_provider+from services.model_catalog import is_known_provider, litellm_provider_keyfrom utils.logging_config import get_loggerlogger = 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_ownersowner = 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 = requestedcredentials = 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 namereturn 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 theuser 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.pyindex 47a4d074f..5fa6fe376 100644--- a/src/services/model_catalog.py+++ b/src/services/model_catalog.py@@ -31,6 +31,13 @@ from functools import lru_cachefrom typing import Anyfrom 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_loggerlogger = 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 excspecs = _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 Truetry: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 Nonedef 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.pyindex 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.endpointsValidates error handling in update_docling_preset endpoint."""-from unittest.mock import AsyncMock, MagicMock+from unittest.mock import AsyncMock, MagicMock, patchimport pytestfrom 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.pynew file mode 100644index 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.pyindex 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`, whichLiteLLM 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 Nonedef 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.pyindex 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.pyindex 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.pyindex 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 AsyncMockimport httpximport 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 exceptionawait _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()