@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/provider_catalog_sources.py

@@ -0,0 +1,316 @@
+"""Provider model-catalog response projection and remote source adapters."""
+
+from __future__ import annotations
+
+import html
+import re
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from ciel_runtime_support.model_catalog_projection import (
+    ModelCatalogProjectionServices,
+    project_model_info,
+)
+from ciel_runtime_support.runtime_constants import (
+    ANTHROPIC_LIMITED_ACCESS_MODEL_IDS,
+    ANTHROPIC_MODEL_DOCS_URLS,
+    ANTHROPIC_PUBLIC_MODEL_DEFAULT_IDS,
+    ANTHROPIC_PUBLIC_MODEL_FALLBACK_IDS,
+    FIREWORKS_API_BASE_URL,
+    FIREWORKS_DEFAULT_ACCOUNT_ID,
+    FIREWORKS_INFERENCE_BASE_URL,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ModelCatalogProjectionPorts:
+    normalize_model_id: Callable[[str, Any], str]
+    model_context: Callable[[dict[str, Any]], Any]
+    positive_int: Callable[[Any], int | None]
+    provider_metadata: Callable[[str], Callable[..., dict[str, Any]]]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderCatalogHttpPorts:
+    http_json: Callable[..., Any]
+    join_url: Callable[[str, str], str]
+    upstream_base: Callable[[str, dict[str, Any]], str]
+    request_headers: Callable[[], dict[str, str]]
+    urlopen: Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderCatalogPolicyPorts:
+    unique_model_ids: Callable[[str, list[str]], list[str]]
+    log: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class AnthropicCatalogPolicy:
+    docs_urls: tuple[str, ...]
+    default_ids: tuple[str, ...]
+    limited_ids: tuple[str, ...]
+    fallback_ids: tuple[str, ...]
+    public_id_pattern: re.Pattern[str]
+
+
+@dataclass(frozen=True, slots=True)
+class FireworksCatalogPolicy:
+    default_account_id: str
+    api_base_url: str
+    inference_base_url: str
+    max_pages: int = 20
+
+
+def build_default_provider_catalog_source_service(
+    projection: ModelCatalogProjectionPorts,
+    http: ProviderCatalogHttpPorts,
+    policy: ProviderCatalogPolicyPorts,
+) -> ProviderCatalogSourceService:
+    """Compose catalog sources with the runtime's immutable provider defaults."""
+    return ProviderCatalogSourceService(
+        projection=projection,
+        http=http,
+        policy=policy,
+        anthropic=AnthropicCatalogPolicy(
+            docs_urls=ANTHROPIC_MODEL_DOCS_URLS,
+            default_ids=ANTHROPIC_PUBLIC_MODEL_DEFAULT_IDS,
+            limited_ids=ANTHROPIC_LIMITED_ACCESS_MODEL_IDS,
+            fallback_ids=ANTHROPIC_PUBLIC_MODEL_FALLBACK_IDS,
+            public_id_pattern=ANTHROPIC_PUBLIC_MODEL_ID_RE,
+        ),
+        fireworks=FireworksCatalogPolicy(
+            default_account_id=FIREWORKS_DEFAULT_ACCOUNT_ID,
+            api_base_url=FIREWORKS_API_BASE_URL,
+            inference_base_url=FIREWORKS_INFERENCE_BASE_URL,
+        ),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderCatalogSourceService:
+    projection: ModelCatalogProjectionPorts
+    http: ProviderCatalogHttpPorts
+    policy: ProviderCatalogPolicyPorts
+    anthropic: AnthropicCatalogPolicy
+    fireworks: FireworksCatalogPolicy
+
+    @staticmethod
+    def model_ids_from_response(data: Any) -> list[str]:
+        ids: list[str] = []
+        candidates: Any
+        if isinstance(data, dict):
+            candidates = data.get("data")
+            if candidates is None:
+                candidates = data.get("models")
+            if candidates is None:
+                candidates = data.get("model")
+        else:
+            candidates = data
+        if isinstance(candidates, str):
+            candidates = [candidates]
+        if not isinstance(candidates, list):
+            return ids
+        for item in candidates:
+            if isinstance(item, str):
+                model_id = item
+            elif isinstance(item, dict):
+                model_id = (
+                    item.get("id")
+                    or item.get("key")
+                    or item.get("name")
+                    or item.get("model")
+                )
+            else:
+                model_id = None
+            if model_id and str(model_id).strip():
+                ids.append(str(model_id).strip())
+        return ids
+
+    def model_info_from_response(
+        self, provider: str, data: Any
+    ) -> dict[str, dict[str, Any]]:
+        return project_model_info(
+            provider,
+            data,
+            ModelCatalogProjectionServices(
+                normalize_model_id=self.projection.normalize_model_id,
+                model_context=self.projection.model_context,
+                positive_int=self.projection.positive_int,
+                project_metadata=self.projection.provider_metadata(provider),
+            ),
+        )
+
+    def fireworks_account_id(self, provider_config: dict[str, Any]) -> str:
+        configured = str(provider_config.get("account_id") or "").strip()
+        if configured:
+            return configured
+        values = (
+            provider_config.get("current_model"),
+            *(provider_config.get("custom_models", []) or []),
+        )
+        for value in values:
+            match = re.match(
+                r"^accounts/([^/]+)/models/[^/]+$", str(value or "")
+            )
+            if match:
+                return match.group(1)
+        return self.fireworks.default_account_id
+
+    def fireworks_management_base_url(
+        self, provider_config: dict[str, Any]
+    ) -> str:
+        configured = str(
+            provider_config.get("model_api_base_url") or ""
+        ).strip().rstrip("/")
+        base = str(
+            provider_config.get("base_url") or self.fireworks.inference_base_url
+        ).strip().rstrip("/")
+        parsed = urllib.parse.urlparse(base)
+        if configured and (
+            configured != self.fireworks.api_base_url
+            or not (parsed.scheme and parsed.netloc)
+            or parsed.netloc.endswith("fireworks.ai")
+        ):
+            return configured
+        if parsed.scheme and parsed.netloc:
+            return f"{parsed.scheme}://{parsed.netloc}"
+        return configured or self.fireworks.api_base_url
+
+    def fetch_fireworks_model_ids(
+        self,
+        provider_config: dict[str, Any],
+        headers: dict[str, str],
+        timeout: float = 8.0,
+    ) -> tuple[list[str], dict[str, dict[str, Any]], str]:
+        account_id = self.fireworks_account_id(provider_config)
+        base = self.fireworks_management_base_url(provider_config)
+        models: list[str] = []
+        model_info: dict[str, dict[str, Any]] = {}
+        page_token = ""
+        source = f"fireworks:{account_id}"
+        for _ in range(self.fireworks.max_pages):
+            query = {"pageSize": "200"}
+            if page_token:
+                query["pageToken"] = page_token
+            account = urllib.parse.quote(account_id, safe="")
+            encoded_query = urllib.parse.urlencode(query)
+            path = f"/v1/accounts/{account}/models?{encoded_query}"
+            data = self.http.http_json(
+                self.http.join_url(base, path),
+                headers=headers,
+                timeout=timeout,
+                provider="fireworks",
+                pcfg=provider_config,
+            )
+            ids = [
+                self.projection.normalize_model_id("fireworks", model_id)
+                for model_id in self.model_ids_from_response(data)
+            ]
+            for model_id in ids:
+                if model_id and model_id not in models:
+                    models.append(model_id)
+            model_info.update(self.model_info_from_response("fireworks", data))
+            if not isinstance(data, dict):
+                break
+            page_token = str(data.get("nextPageToken") or "").strip()
+            if not page_token:
+                break
+        return models, model_info, source
+
+    def fetch_text_url(self, url: str, timeout: float = 8.0) -> str:
+        request = urllib.request.Request(url, headers=self.http.request_headers())
+        with self.http.urlopen(request, timeout=timeout) as response:
+            return response.read(5_000_000).decode("utf-8", errors="replace")
+
+    def anthropic_model_ids_from_docs_text(self, text: str) -> list[str]:
+        ids: list[str] = []
+        seen: set[str] = set()
+        for match in self.anthropic.public_id_pattern.finditer(html.unescape(text or "")):
+            model_id = match.group(0)
+            key = model_id.casefold()
+            if key in seen:
+                continue
+            seen.add(key)
+            ids.append(model_id)
+        return ids
+
+    def filter_anthropic_default_model_ids(self, ids: list[str]) -> list[str]:
+        allowed = set(self.anthropic.default_ids)
+        limited = set(self.anthropic.limited_ids)
+        out: list[str] = []
+        seen: set[str] = set()
+        for raw in ids:
+            model_id = self.projection.normalize_model_id("anthropic", raw)
+            key = model_id.casefold()
+            if not model_id or key in seen or model_id in limited or model_id not in allowed:
+                continue
+            out.append(model_id)
+            seen.add(key)
+        return out
+
+    def fetch_anthropic_public_model_ids(self, timeout: float = 8.0) -> list[str]:
+        ids: list[str] = []
+        errors: list[str] = []
+        for url in self.anthropic.docs_urls:
+            try:
+                text = self.fetch_text_url(url, timeout=timeout)
+                ids.extend(self.anthropic_model_ids_from_docs_text(text))
+            except Exception as exc:
+                errors.append(f"{url}: {type(exc).__name__}: {exc}")
+        unique = self.policy.unique_model_ids("anthropic", ids)
+        out = self.filter_anthropic_default_model_ids(unique)
+        if out:
+            return out
+        if errors:
+            self.policy.log(
+                "WARN", "anthropic model docs fetch failed: " + " ; ".join(errors)
+            )
+        return list(self.anthropic.fallback_ids)
+
+    def fetch_anthropic_api_model_ids(
+        self,
+        provider_config: dict[str, Any],
+        headers: dict[str, str],
+        timeout: float = 6.0,
+    ) -> tuple[list[str], str]:
+        base = self.http.upstream_base("anthropic", provider_config)
+        errors: list[str] = []
+        for path in ("/v1/models", "/models"):
+            try:
+                data = self.http.http_json(
+                    self.http.join_url(base, path),
+                    headers=headers,
+                    timeout=timeout,
+                )
+                ids = self.policy.unique_model_ids(
+                    "anthropic", self.model_ids_from_response(data)
+                )
+                if ids:
+                    return ids, f"api:{path}"
+            except Exception as exc:
+                errors.append(f"{path}: {type(exc).__name__}: {exc}")
+        if errors:
+            self.policy.log(
+                "DEBUG", "anthropic model API fetch failed: " + " ; ".join(errors)
+            )
+        return [], ""
+
+
+ANTHROPIC_PUBLIC_MODEL_ID_RE = re.compile(
+    r"(?<![A-Za-z0-9_.@:-])"
+    r"(?:"
+    r"claude-(?:fable|mythos)-\d+(?:-\d+)?(?:-\d{8})?|"
+    r"claude-mythos-preview|"
+    r"claude-(?:opus|sonnet|haiku)-\d+-\d+-\d{8}|"
+    r"claude-(?:opus|sonnet|haiku)-\d+-\d{8}|"
+    r"claude-(?:opus|sonnet|haiku)-\d+-\d+|"
+    r"claude-(?:opus|sonnet|haiku)-\d+(?:-\d+)?-latest|"
+    r"claude-\d+(?:-\d+){0,2}-(?:opus|sonnet|haiku)-(?:\d{8}|latest)|"
+    r"claude-(?:opus|sonnet|haiku)-\d+"
+    r")"
+    r"(?![A-Za-z0-9_.@:-])"
+)

package/ciel_runtime_support/provider_choice.py

@@ -0,0 +1,201 @@
+"""Provider/runtime choice normalization and selection strategies."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .architecture import ProviderAdapter, ProviderConfig
+
+
+ANTHROPIC_NATIVE_PROVIDER_CHOICE = "anthropic:native"
+ANTHROPIC_ROUTED_PROVIDER_CHOICE = "anthropic:routed"
+AGY_NATIVE_PROVIDER_CHOICE = "agy:native"
+AGY_ROUTED_PROVIDER_CHOICE = "agy:routed"
+CODEX_NATIVE_PROVIDER_CHOICE = "codex:native"
+CODEX_ROUTED_PROVIDER_CHOICE = "codex:routed"
+KIMI_NATIVE_PROVIDER_CHOICE = "kimi:native"
+KIMI_ROUTED_PROVIDER_CHOICE = "kimi:routed"
+
+
+CHOICE_ALIASES = {
+    "anthropic-native": ANTHROPIC_NATIVE_PROVIDER_CHOICE,
+    "claude-native": ANTHROPIC_NATIVE_PROVIDER_CHOICE,
+    "native": ANTHROPIC_NATIVE_PROVIDER_CHOICE,
+    "claude-code": ANTHROPIC_NATIVE_PROVIDER_CHOICE,
+    "anthropic-routed": ANTHROPIC_ROUTED_PROVIDER_CHOICE,
+    "anthropic-router": ANTHROPIC_ROUTED_PROVIDER_CHOICE,
+    "claude-routed": ANTHROPIC_ROUTED_PROVIDER_CHOICE,
+    "claude-router": ANTHROPIC_ROUTED_PROVIDER_CHOICE,
+    "agy": AGY_NATIVE_PROVIDER_CHOICE,
+    "agy-native": AGY_NATIVE_PROVIDER_CHOICE,
+    "native-agy": AGY_NATIVE_PROVIDER_CHOICE,
+    "antigravity": AGY_NATIVE_PROVIDER_CHOICE,
+    "google-antigravity": AGY_NATIVE_PROVIDER_CHOICE,
+    "agy-routed": AGY_ROUTED_PROVIDER_CHOICE,
+    "agy-router": AGY_ROUTED_PROVIDER_CHOICE,
+    "routed-agy": AGY_ROUTED_PROVIDER_CHOICE,
+    "antigravity-routed": AGY_ROUTED_PROVIDER_CHOICE,
+    "codex": CODEX_NATIVE_PROVIDER_CHOICE,
+    "codex-native": CODEX_NATIVE_PROVIDER_CHOICE,
+    "native-codex": CODEX_NATIVE_PROVIDER_CHOICE,
+    "codex-routed": CODEX_ROUTED_PROVIDER_CHOICE,
+    "codex-router": CODEX_ROUTED_PROVIDER_CHOICE,
+    "routed-codex": CODEX_ROUTED_PROVIDER_CHOICE,
+    "kimi-native": KIMI_NATIVE_PROVIDER_CHOICE,
+    "native-kimi": KIMI_NATIVE_PROVIDER_CHOICE,
+    "kimi-code": KIMI_NATIVE_PROVIDER_CHOICE,
+    "kimi-routed": KIMI_ROUTED_PROVIDER_CHOICE,
+    "kimi-router": KIMI_ROUTED_PROVIDER_CHOICE,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderChoiceStrategy:
+    provider: str
+    routed: bool
+    status_lines: tuple[str, ...]
+    missing_api_key_line: str = ""
+
+
+CHOICE_STRATEGIES = {
+    ANTHROPIC_NATIVE_PROVIDER_CHOICE: ProviderChoiceStrategy(
+        provider="anthropic",
+        routed=False,
+        status_lines=(
+            "Provider set to anthropic (Claude Native).",
+            "mode: anthropic-native",
+            "Claude Code OAuth/Max can be used directly, but ciel-runtime router features such as /advisor are unavailable.",
+        ),
+    ),
+    ANTHROPIC_ROUTED_PROVIDER_CHOICE: ProviderChoiceStrategy(
+        provider="anthropic",
+        routed=True,
+        status_lines=(
+            "Provider set to anthropic (Anthropic routed).",
+            "mode: anthropic-routed",
+        ),
+        missing_api_key_line="Anthropic routed mode will use Claude Code OAuth/API auth headers when available.",
+    ),
+    AGY_NATIVE_PROVIDER_CHOICE: ProviderChoiceStrategy(
+        provider="agy",
+        routed=False,
+        status_lines=(
+            "Provider set to agy (AGY).",
+            "mode: agy-native",
+            "AGY runs with its own native settings; Ciel Runtime router features are unavailable.",
+        ),
+    ),
+    AGY_ROUTED_PROVIDER_CHOICE: ProviderChoiceStrategy(
+        provider="agy",
+        routed=True,
+        status_lines=(
+            "Provider set to agy (AGY routed).",
+            "mode: agy-routed",
+            "AGY uses native Google Antigravity auth/settings; Ciel Runtime adds channel/PTY wake support only.",
+        ),
+    ),
+    CODEX_NATIVE_PROVIDER_CHOICE: ProviderChoiceStrategy(
+        provider="codex",
+        routed=False,
+        status_lines=(
+            "Provider set to codex (Codex Native).",
+            "mode: codex-native",
+            "Codex runs with its own native settings; ciel-runtime router features are unavailable.",
+        ),
+    ),
+    CODEX_ROUTED_PROVIDER_CHOICE: ProviderChoiceStrategy(
+        provider="codex",
+        routed=True,
+        status_lines=(
+            "Provider set to codex (Codex routed).",
+            "mode: codex-routed",
+            "Codex uses its native OpenAI account/config, with base URL routed through ciel-runtime.",
+        ),
+    ),
+    KIMI_NATIVE_PROVIDER_CHOICE: ProviderChoiceStrategy(
+        provider="kimi", routed=False,
+        status_lines=("Provider set to kimi (Kimi Native).", "mode: kimi-native", "Kimi Code uses its official OAuth/config directly."),
+    ),
+    KIMI_ROUTED_PROVIDER_CHOICE: ProviderChoiceStrategy(
+        provider="kimi", routed=True,
+        status_lines=("Provider set to kimi (Kimi Routed).", "mode: kimi-routed", "Kimi Code requests are routed through ciel-runtime."),
+        missing_api_key_line="Kimi Routed requires Kimi OAuth login or a Kimi API key; open API key setup to authenticate.",
+    ),
+}
+
+
+def normalize_provider_choice(name: str) -> str | None:
+    raw = str(name or "").strip().lower().replace("_", "-").replace(" ", "-")
+    if raw in CHOICE_STRATEGIES:
+        return raw
+    return CHOICE_ALIASES.get(raw.replace(":", "-"))
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderChoicePorts:
+    load_config: Callable[[], dict[str, Any]]
+    save_config: Callable[[dict[str, Any]], None]
+    clear_model_cache: Callable[[], None]
+    provider_has_api_key: Callable[[str, dict[str, Any]], bool]
+    configured_adapter: Callable[[str, dict[str, Any]], ProviderAdapter]
+    contract_config: Callable[[str, dict[str, Any]], ProviderConfig]
+    provider_label: Callable[[str], str]
+
+
+class ProviderChoiceController:
+    def __init__(self, ports: ProviderChoicePorts) -> None:
+        self._ports = ports
+
+    def select(self, choice: str) -> list[str]:
+        normalized = normalize_provider_choice(choice) or choice
+        strategy = CHOICE_STRATEGIES.get(normalized)
+        if strategy is None:
+            return self.select_standard(normalized)
+        config = self._ports.load_config()
+        config["current_provider"] = strategy.provider
+        provider_config = config["providers"][strategy.provider]
+        provider_config["route_through_router"] = strategy.routed
+        self._ports.save_config(config)
+        self._ports.clear_model_cache()
+        lines = list(strategy.status_lines)
+        if (
+            strategy.missing_api_key_line
+            and not self._ports.provider_has_api_key(strategy.provider, provider_config)
+        ):
+            lines.append(strategy.missing_api_key_line)
+        return lines
+
+    def select_standard(self, provider: str) -> list[str]:
+        """Select a provider while delegating normalization to its adapter."""
+
+        config = self._ports.load_config()
+        config["current_provider"] = provider
+        provider_config = config["providers"][provider]
+        adapter = self._ports.configured_adapter(provider, provider_config)
+        contract = self._ports.contract_config(provider, provider_config)
+        updates = adapter.selection_config_updates(contract)
+        provider_config.update(updates)
+        self._ports.save_config(config)
+        self._ports.clear_model_cache()
+        selected_contract = self._ports.contract_config(provider, provider_config)
+        lines = [f"Provider set to {provider} ({self._ports.provider_label(provider)})."]
+        lines.extend(adapter.selection_status_lines(selected_contract))
+        lines.extend(adapter.selection_update_status_lines(selected_contract, updates))
+        return lines
+
+
+__all__ = [
+    "AGY_NATIVE_PROVIDER_CHOICE",
+    "AGY_ROUTED_PROVIDER_CHOICE",
+    "ANTHROPIC_NATIVE_PROVIDER_CHOICE",
+    "ANTHROPIC_ROUTED_PROVIDER_CHOICE",
+    "CODEX_NATIVE_PROVIDER_CHOICE",
+    "CODEX_ROUTED_PROVIDER_CHOICE",
+    "KIMI_NATIVE_PROVIDER_CHOICE",
+    "KIMI_ROUTED_PROVIDER_CHOICE",
+    "ProviderChoiceController",
+    "ProviderChoicePorts",
+    "ProviderChoiceStrategy",
+    "normalize_provider_choice",
+]

package/ciel_runtime_support/provider_compatibility.py

@@ -0,0 +1,165 @@
+"""Provider compatibility strategies kept separate from transport adapters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Mapping
+
+from .architecture import ProviderConfig
+
+
+FailureDiagnosis = Callable[[int | None, str], str | None]
+ToolUseBlocker = Callable[[str], str]
+RuntimeMetadataProjection = Callable[[Mapping[str, object]], tuple[str, ...]]
+AutoWebSearchPolicy = Callable[[ProviderConfig], bool]
+
+
+def _no_diagnosis(code: int | None, message: str) -> str | None:
+    del code, message
+    return None
+
+
+def _no_tool_use_blocker(model: str) -> str:
+    del model
+    return ""
+
+
+def _no_runtime_metadata(info: Mapping[str, object]) -> tuple[str, ...]:
+    del info
+    return ()
+
+
+def _allow_auto_web_search(config: ProviderConfig) -> bool:
+    del config
+    return True
+
+
+@dataclass(frozen=True)
+class ProviderCompatibilityPolicy:
+    advisor_transport: str = ""
+    runtime_model_info_strategy: str = ""
+    auto_web_search: AutoWebSearchPolicy = _allow_auto_web_search
+    requires_compat_prompt: bool = True
+    failure_diagnosis: FailureDiagnosis = _no_diagnosis
+    tool_use_blocker: ToolUseBlocker = _no_tool_use_blocker
+    runtime_metadata: RuntimeMetadataProjection = _no_runtime_metadata
+
+    @property
+    def exposes_runtime_info(self) -> bool:
+        return bool(self.runtime_model_info_strategy)
+
+
+@dataclass(frozen=True)
+class ProviderCompatibilityRegistry:
+    policies: Mapping[str, ProviderCompatibilityPolicy] = field(default_factory=dict)
+    default: ProviderCompatibilityPolicy = ProviderCompatibilityPolicy()
+
+    def resolve(self, provider: str) -> ProviderCompatibilityPolicy:
+        return self.policies.get(provider, self.default)
+
+
+def _vllm_failure_diagnosis(code: int | None, message: str) -> str | None:
+    del code
+    lower = message.lower()
+    if "tool" not in lower and "parse" not in lower and "parser" not in lower:
+        return None
+    return (
+        "Diagnosis: vLLM tool calling depends on the server's model-specific --tool-call-parser and chat template. "
+        "For Qwen3-Coder models, current vLLM docs recommend --tool-call-parser qwen3_xml; Hermes is for Hermes-style models "
+        "and some older Qwen tool templates."
+    )
+
+
+def _nvidia_failure_diagnosis(code: int | None, message: str) -> str | None:
+    lower = message.lower()
+    if code == 404:
+        return (
+            "Diagnosis: NVIDIA API Catalog does not expose this request path/model for the current account. "
+            "Use the default router mode for nvidia-hosted, or pick another hosted model."
+        )
+    if code in (502, 503, 504):
+        return (
+            "Diagnosis: NVIDIA API Catalog or the hosted model backend returned a transient upstream error. "
+            "Retry the compatibility test, or choose another NVIDIA hosted model if it repeats."
+        )
+    if any(
+        marker in lower
+        for marker in (
+            "remotedisconnected",
+            "remote end closed connection",
+            "connection reset",
+            "gateway timeout",
+        )
+    ):
+        return (
+            "Diagnosis: the NVIDIA hosted upstream closed the request without a complete response. "
+            "This is usually a transient API Catalog/backend issue rather than a local ciel-runtime configuration error. "
+            "Retry the test, or choose another hosted model if it repeats."
+        )
+    if "function" in lower and "not found" in lower:
+        return (
+            "Diagnosis: NVIDIA returned a missing function for this hosted model. The model is visible in /v1/models "
+            "but is not callable with the current account."
+        )
+    return None
+
+
+def _zai_tool_use_blocker(model: str) -> str:
+    if str(model or "").strip().lower() != "glm-4.7-flash":
+        return ""
+    return (
+        "Z.AI GLM-4.7-Flash responds to text requests but direct Anthropic tool-use probes time out. "
+        "Claude Code requires tool calling for normal work; use glm-4.5-flash for a Flash/free model, "
+        "or use glm-4.7/glm-5.2 if your Z.AI account can access them."
+    )
+
+
+def _lm_studio_runtime_metadata(info: Mapping[str, object]) -> tuple[str, ...]:
+    lines: list[str] = []
+    if info.get("loaded_context_len"):
+        lines.append(f"Runtime loaded_context_length: {info['loaded_context_len']}")
+    if info.get("state"):
+        lines.append(f"Runtime model state: {info['state']}")
+    return tuple(lines)
+
+
+def _zai_auto_web_search(config: ProviderConfig) -> bool:
+    return not bool(config.options.get("managed_mcp", True))
+
+
+PROVIDER_COMPATIBILITY = ProviderCompatibilityRegistry(
+    policies={
+        "anthropic": ProviderCompatibilityPolicy(
+            advisor_transport="anthropic",
+            auto_web_search=lambda _config: False,
+            requires_compat_prompt=False,
+        ),
+        "ollama": ProviderCompatibilityPolicy(advisor_transport="ollama"),
+        "ollama-cloud": ProviderCompatibilityPolicy(advisor_transport="ollama"),
+        "lm-studio": ProviderCompatibilityPolicy(
+            advisor_transport="openai-compatible",
+            runtime_model_info_strategy="lm_studio",
+            runtime_metadata=_lm_studio_runtime_metadata,
+        ),
+        "vllm": ProviderCompatibilityPolicy(
+            runtime_model_info_strategy="openai",
+            failure_diagnosis=_vllm_failure_diagnosis,
+        ),
+        "nvidia-hosted": ProviderCompatibilityPolicy(
+            advisor_transport="openai-compatible",
+            failure_diagnosis=_nvidia_failure_diagnosis,
+        ),
+        "self-hosted-nim": ProviderCompatibilityPolicy(runtime_model_info_strategy="openai"),
+        "zai": ProviderCompatibilityPolicy(
+            auto_web_search=_zai_auto_web_search,
+            tool_use_blocker=_zai_tool_use_blocker,
+        ),
+    }
+)
+
+
+__all__ = [
+    "PROVIDER_COMPATIBILITY",
+    "ProviderCompatibilityPolicy",
+    "ProviderCompatibilityRegistry",
+]