@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/provider_models.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class ModelCatalogStorage:
+    read_model_list_cache: Callable[..., Any]
+    write_model_list_cache: Callable[..., Any]
+    write_model_registry: Callable[..., Any]
+    router_log: Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ModelCatalogHttp:
+    http_json: Callable[..., Any]
+    join_url: Callable[..., Any]
+    with_upstream_user_agent: Callable[..., Any]
+    lm_studio_api_base: Callable[..., Any]
+    nvidia_hosted_list_headers: Callable[..., Any]
+    nvidia_upstream_base_url: Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderCatalogSources:
+    ANTHROPIC_MODEL_DOCS_URLS: Any
+    fetch_anthropic_api_model_ids: Callable[..., Any]
+    fetch_anthropic_public_model_ids: Callable[..., Any]
+    fetch_fireworks_model_ids: Callable[..., Any]
+    fireworks_account_id: Callable[..., Any]
+    fireworks_management_base_url: Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ModelCatalogResponseCodec:
+    model_ids_from_response: Callable[..., Any]
+    model_info_from_response: Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ModelCatalogPolicy:
+    normalize_model_id: Callable[..., Any]
+    ollama_catalog_model_ids: Callable[..., Any]
+    provider_has_api_key: Callable[..., Any]
+    provider_model_catalog_policy: Callable[..., Any]
+    provider_model_paths: Callable[..., Any]
+    provider_model_list_headers: Callable[..., Any]
+    provider_upstream_request_base: Callable[..., Any]
+    sorted_model_ids: Callable[..., Any]
+    unique_model_ids: Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderModelServices:
+    storage: ModelCatalogStorage
+    http: ModelCatalogHttp
+    sources: ProviderCatalogSources
+    response_codec: ModelCatalogResponseCodec
+    policy: ModelCatalogPolicy
+
+
+def fetch_upstream_model_ids(provider: str, pcfg: dict[str, Any], force_refresh: bool = False,
+    *,
+    services: ProviderModelServices,
+) -> list[str]:
+    ANTHROPIC_MODEL_DOCS_URLS = services.sources.ANTHROPIC_MODEL_DOCS_URLS
+    fetch_anthropic_api_model_ids = services.sources.fetch_anthropic_api_model_ids
+    fetch_anthropic_public_model_ids = services.sources.fetch_anthropic_public_model_ids
+    fetch_fireworks_model_ids = services.sources.fetch_fireworks_model_ids
+    fireworks_account_id = services.sources.fireworks_account_id
+    fireworks_management_base_url = services.sources.fireworks_management_base_url
+    http_json = services.http.http_json
+    join_url = services.http.join_url
+    lm_studio_api_base = services.http.lm_studio_api_base
+    model_ids_from_response = services.response_codec.model_ids_from_response
+    model_info_from_response = services.response_codec.model_info_from_response
+    normalize_model_id = services.policy.normalize_model_id
+    nvidia_hosted_list_headers = services.http.nvidia_hosted_list_headers
+    nvidia_upstream_base_url = services.http.nvidia_upstream_base_url
+    ollama_catalog_model_ids = services.policy.ollama_catalog_model_ids
+    provider_has_api_key = services.policy.provider_has_api_key
+    provider_model_catalog_policy = services.policy.provider_model_catalog_policy
+    provider_model_paths = services.policy.provider_model_paths
+    provider_model_list_headers = services.policy.provider_model_list_headers
+    provider_upstream_request_base = services.policy.provider_upstream_request_base
+    read_model_list_cache = services.storage.read_model_list_cache
+    router_log = services.storage.router_log
+    sorted_model_ids = services.policy.sorted_model_ids
+    unique_model_ids = services.policy.unique_model_ids
+    with_upstream_user_agent = services.http.with_upstream_user_agent
+    write_model_list_cache = services.storage.write_model_list_cache
+    write_model_registry = services.storage.write_model_registry
+    cached = None if force_refresh else read_model_list_cache(provider, pcfg)
+    if cached is not None:
+        return cached
+    catalog_policy = provider_model_catalog_policy(provider, pcfg)
+    if catalog_policy.kind == "configured":
+        ids = unique_model_ids(provider, [
+            *catalog_policy.fallback_models,
+            *(pcfg.get("custom_models", []) or []),
+            pcfg.get("current_model") or "",
+        ])
+        sorted_ids = sorted_model_ids(ids)
+        if sorted_ids:
+            write_model_list_cache(provider, pcfg, sorted_ids)
+        return sorted_ids
+    if catalog_policy.kind == "anthropic":
+        ids: list[str] = []
+        source = ""
+        if provider_has_api_key(provider, pcfg):
+            ids, source = fetch_anthropic_api_model_ids(pcfg, provider_model_list_headers(provider, pcfg), timeout=6.0)
+        if not ids:
+            ids = fetch_anthropic_public_model_ids()
+            source = "anthropic-docs"
+        if not ids:
+            return []
+        for mid in pcfg.get("custom_models", []) or []:
+            mid = normalize_model_id(provider, mid)
+            if mid and mid not in ids:
+                ids.append(mid)
+        cur = normalize_model_id(provider, pcfg.get("current_model") or "")
+        if cur and cur not in ids:
+            ids.insert(0, cur)
+        sorted_ids = unique_model_ids(provider, ids)
+        write_model_list_cache(provider, pcfg, sorted_ids)
+        write_model_registry(provider, pcfg, sorted_ids, source, {"urls": list(ANTHROPIC_MODEL_DOCS_URLS) if source == "anthropic-docs" else []})
+        return sorted_ids
+    if catalog_policy.kind == "fireworks":
+        headers = provider_model_list_headers(provider, pcfg)
+        model_info: dict[str, dict[str, Any]] = {}
+        source = ""
+        try:
+            ids, model_info, source = fetch_fireworks_model_ids(pcfg, headers, timeout=8.0)
+            fetched = bool(ids)
+        except Exception as exc:
+            router_log("DEBUG", f"fireworks model API fetch failed: {type(exc).__name__}: {exc}")
+            ids = []
+            fetched = False
+        if not fetched:
+            base = provider_upstream_request_base(provider, pcfg)
+            try:
+                data = http_json(join_url(base, "/v1/models"), headers=headers, timeout=6.0, provider=provider, pcfg=pcfg)
+                ids = [normalize_model_id(provider, mid) for mid in model_ids_from_response(data)]
+                model_info.update(model_info_from_response(provider, data))
+                fetched = bool(ids)
+                source = "fireworks:/v1/models"
+            except Exception as exc:
+                router_log("DEBUG", f"fireworks inference model list fetch failed: {type(exc).__name__}: {exc}")
+        if not fetched:
+            ids = unique_model_ids(provider, [
+                *(pcfg.get("custom_models", []) or []),
+                pcfg.get("current_model") or "",
+            ])
+            sorted_ids = sorted_model_ids(ids)
+            if sorted_ids:
+                write_model_list_cache(provider, pcfg, sorted_ids)
+            return sorted_ids
+        for mid in pcfg.get("custom_models", []) or []:
+            mid = normalize_model_id(provider, mid)
+            if mid and mid not in ids:
+                ids.append(mid)
+        cur = normalize_model_id(provider, pcfg.get("current_model") or "")
+        if cur and cur not in ids:
+            ids.insert(0, cur)
+        sorted_ids = sorted_model_ids(unique_model_ids(provider, ids))
+        metadata = {
+            "model_info": model_info,
+            "source": source,
+            "account_id": fireworks_account_id(pcfg),
+            "model_api_base_url": fireworks_management_base_url(pcfg),
+        }
+        write_model_list_cache(provider, pcfg, sorted_ids, metadata)
+        return sorted_ids
+    if catalog_policy.kind == "nvidia":
+        base = (pcfg.get("base_url") or nvidia_upstream_base_url()).rstrip("/")
+    else:
+        base = provider_upstream_request_base(provider, pcfg)
+    ids: list[str] = []
+    model_info: dict[str, dict[str, Any]] = {}
+    fetched = False
+    try:
+        if catalog_policy.kind == "nvidia":
+            data = http_json(join_url(base, "/v1/models"), headers=nvidia_hosted_list_headers(), timeout=8.0, provider=provider, pcfg=pcfg)
+            ids = model_ids_from_response(data)
+            model_info.update(model_info_from_response(provider, data))
+            fetched = True
+        else:
+            headers = provider_model_list_headers(provider, pcfg)
+            for path in provider_model_paths(provider, pcfg):
+                try:
+                    request_base = lm_studio_api_base(pcfg) if catalog_policy.kind == "lm_studio" and path.startswith("/api/") else base
+                    timeout = 2.0 if catalog_policy.kind == "lm_studio" else (4.0 if catalog_policy.kind == "ollama" else 6.0)
+                    data = http_json(join_url(request_base, path), headers=headers, timeout=timeout, provider=provider, pcfg=pcfg)
+                    ids = [normalize_model_id(provider, mid) for mid in model_ids_from_response(data)]
+                    model_info.update(model_info_from_response(provider, data))
+                    fetched = True
+                    if ids:
+                        break
+                except Exception:
+                    continue
+            if not fetched and catalog_policy.allow_public_without_auth:
+                # OpenCode publishes the model catalog at /v1/models. Keep the
+                # picker independent from key-specific auth/rate-limit failures.
+                try:
+                    public_headers = with_upstream_user_agent({"content-type": "application/json"})
+                    data = http_json(join_url(base, "/v1/models"), headers=public_headers, timeout=6.0, provider=provider, pcfg=pcfg)
+                    ids = model_ids_from_response(data)
+                    model_info.update(model_info_from_response(provider, data))
+                    fetched = True
+                except Exception as exc:
+                    router_log("DEBUG", f"{provider} public model catalog fetch failed: {type(exc).__name__}: {exc}")
+    except Exception:
+        ids = []
+    if catalog_policy.use_bundled_catalog_fallback and not ids:
+        ids = ollama_catalog_model_ids(provider)
+        fetched = bool(ids)
+    if not fetched and catalog_policy.allow_configured_fallback:
+        ids = unique_model_ids(provider, [
+            *(pcfg.get("custom_models", []) or []),
+            pcfg.get("current_model") or "",
+        ])
+        sorted_ids = sorted_model_ids(ids)
+        if sorted_ids:
+            write_model_list_cache(provider, pcfg, sorted_ids)
+        return sorted_ids
+    if not fetched and catalog_policy.fallback_models:
+        ids = list(catalog_policy.fallback_models)
+        fetched = True
+    if not fetched:
+        return []
+    for mid in catalog_policy.fallback_models:
+        mid = normalize_model_id(provider, mid)
+        if mid and mid not in ids:
+            ids.append(mid)
+    for mid in pcfg.get("custom_models", []) or []:
+        mid = normalize_model_id(provider, mid)
+        if mid and mid not in ids:
+            ids.append(mid)
+    cur = normalize_model_id(provider, pcfg.get("current_model") or "")
+    if cur and catalog_policy.kind != "nvidia" and cur.startswith(f"ciel-runtime-{provider}-"):
+        pass
+    elif cur and cur not in ids and not (catalog_policy.kind == "nvidia" and cur.startswith("claude-")):
+        ids.insert(0, cur)
+    if catalog_policy.kind == "nvidia" and cur and cur not in ids:
+        ids.insert(0, cur)
+    sorted_ids = unique_model_ids(provider, ids)
+    if catalog_policy.kind != "anthropic":
+        sorted_ids = sorted_model_ids(sorted_ids)
+    metadata = {"model_info": model_info} if model_info else None
+    write_model_list_cache(provider, pcfg, sorted_ids, metadata)
+    return sorted_ids
+
+
+__all__ = [
+    "ModelCatalogHttp",
+    "ModelCatalogPolicy",
+    "ModelCatalogResponseCodec",
+    "ModelCatalogStorage",
+    "ProviderCatalogSources",
+    "ProviderModelServices",
+    "fetch_upstream_model_ids",
+]

package/ciel_runtime_support/provider_network.py

@@ -0,0 +1,176 @@
+"""Provider HTTP identity, IP-family selection, and connectivity policy."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import socket
+import threading
+import urllib.parse
+import urllib.request
+from collections.abc import Iterable
+from typing import Any, Callable
+
+from ciel_runtime_support.providers.constants import OPENCODE_PROVIDER_NAMES
+
+
+DEFAULT_UPSTREAM_USER_AGENT = "claude-cli"
+IP_FAMILY_ALIASES = {
+    "": "auto",
+    "auto": "auto",
+    "default": "auto",
+    "system": "auto",
+    "any": "auto",
+    "4": "ipv4",
+    "v4": "ipv4",
+    "ipv4": "ipv4",
+    "inet": "ipv4",
+    "6": "ipv6",
+    "v6": "ipv6",
+    "ipv6": "ipv6",
+    "inet6": "ipv6",
+    "prefer4": "ipv4-preferred",
+    "prefer-v4": "ipv4-preferred",
+    "preferred4": "ipv4-preferred",
+    "ipv4-preferred": "ipv4-preferred",
+    "ipv4_preferred": "ipv4-preferred",
+    "prefer-ipv4": "ipv4-preferred",
+    "prefer6": "ipv6-preferred",
+    "prefer-v6": "ipv6-preferred",
+    "preferred6": "ipv6-preferred",
+    "ipv6-preferred": "ipv6-preferred",
+    "ipv6_preferred": "ipv6-preferred",
+    "prefer-ipv6": "ipv6-preferred",
+}
+IP_FAMILY_CHOICES = ("auto", "ipv4", "ipv6", "ipv4-preferred", "ipv6-preferred")
+
+_IP_FAMILY_LOCK = threading.Lock()
+
+
+def upstream_user_agent(environ: dict[str, str] | None = None) -> str:
+    values = os.environ if environ is None else environ
+    configured = str(values.get("CIEL_RUNTIME_UPSTREAM_USER_AGENT") or "").strip()
+    return configured or DEFAULT_UPSTREAM_USER_AGENT
+
+
+def with_upstream_user_agent(headers: dict[str, str] | None = None) -> dict[str, str]:
+    result = dict(headers or {})
+    if not any(str(key).lower() == "user-agent" for key in result):
+        result["user-agent"] = upstream_user_agent()
+    return result
+
+
+def normalize_ip_family(value: Any, default: str = "auto") -> str:
+    text = str(value if value is not None else default).strip().lower().replace("_", "-")
+    if family := IP_FAMILY_ALIASES.get(text):
+        return family
+    raise SystemExit(f"ip_family must be one of: {', '.join(IP_FAMILY_CHOICES)}")
+
+
+def default_provider_ip_family(provider: str) -> str:
+    return "ipv6-preferred" if provider in OPENCODE_PROVIDER_NAMES else "auto"
+
+
+def provider_ip_family(provider: str | None, config: dict[str, Any] | None) -> str:
+    if not provider or not isinstance(config, dict):
+        return "auto"
+    return normalize_ip_family(config.get("ip_family"), default_provider_ip_family(provider))
+
+
+@contextlib.contextmanager
+def socket_ip_family_policy(ip_family: str) -> Iterable[None]:
+    policy = normalize_ip_family(ip_family)
+    if policy == "auto":
+        yield
+        return
+    strict = policy in ("ipv4", "ipv6")
+    desired = socket.AF_INET6 if policy in ("ipv6", "ipv6-preferred") else socket.AF_INET
+    with _IP_FAMILY_LOCK:
+        original_getaddrinfo = socket.getaddrinfo
+
+        def filtered_getaddrinfo(
+            host: Any,
+            port: Any,
+            family: int = 0,
+            type: int = 0,
+            proto: int = 0,
+            flags: int = 0,
+        ) -> Any:
+            infos = original_getaddrinfo(host, port, family, type, proto, flags)
+            matches = [info for info in infos if info and info[0] == desired]
+            if strict:
+                if not matches:
+                    raise socket.gaierror(socket.EAI_NONAME, f"no {policy} address for {host}")
+                return matches
+            others = [info for info in infos if not info or info[0] != desired]
+            return sorted(matches, key=lambda info: (0 if info[0] == desired else 1, info[0])) + others
+
+        socket.getaddrinfo = filtered_getaddrinfo
+        try:
+            yield
+        finally:
+            socket.getaddrinfo = original_getaddrinfo
+
+
+def provider_urlopen(
+    request: urllib.request.Request,
+    timeout: float,
+    provider: str | None,
+    config: dict[str, Any] | None,
+    log: Callable[[str, str], None],
+) -> Any:
+    policy = provider_ip_family(provider, config)
+    if policy != "auto":
+        log("DEBUG", f"upstream_ip_family provider={provider or ''} policy={policy}")
+    with socket_ip_family_policy(policy):
+        return urllib.request.urlopen(request, timeout=timeout)
+
+
+def ip_family_connectivity(
+    host: str,
+    port: int,
+    family: int,
+    timeout: float = 1.5,
+) -> tuple[bool, str]:
+    try:
+        infos = socket.getaddrinfo(host, port, family, socket.SOCK_STREAM, socket.IPPROTO_TCP)
+    except Exception as error:
+        return False, f"dns:{type(error).__name__}"
+    if not infos:
+        return False, "dns:no-address"
+    last_error = ""
+    for address_family, socktype, protocol, _canonical_name, address in infos:
+        connection = socket.socket(address_family, socktype, protocol)
+        connection.settimeout(timeout)
+        try:
+            connection.connect(address)
+            return True, "connect:ok"
+        except Exception as error:
+            last_error = f"connect:{type(error).__name__}"
+        finally:
+            try:
+                connection.close()
+            except Exception:
+                pass
+    return False, last_error or "connect:failed"
+
+
+def provider_ip_family_probe_lines(
+    provider: str,
+    config: dict[str, Any],
+    default_base_url: Callable[[str], str | None],
+) -> list[str]:
+    if provider not in OPENCODE_PROVIDER_NAMES:
+        return []
+    base = str(config.get("base_url") or default_base_url(provider) or "").strip()
+    parsed = urllib.parse.urlparse(base)
+    if not parsed.hostname:
+        return [f"IP family: {provider_ip_family(provider, config)}; probe unavailable (base URL host missing)"]
+    port = parsed.port or (443 if parsed.scheme == "https" else 80)
+    ipv4_ok, ipv4_reason = ip_family_connectivity(parsed.hostname, port, socket.AF_INET)
+    ipv6_ok, ipv6_reason = ip_family_connectivity(parsed.hostname, port, socket.AF_INET6)
+    return [
+        f"IP family: {provider_ip_family(provider, config)}",
+        f"IPv4 connectivity: {'OK' if ipv4_ok else 'FAIL'} ({ipv4_reason})",
+        f"IPv6 connectivity: {'OK' if ipv6_ok else 'FAIL'} ({ipv6_reason})",
+    ]

package/ciel_runtime_support/provider_option_cli.py

@@ -0,0 +1,238 @@
+"""CLI controller for provider and Ollama option configuration."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Collection, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderOptionCliConfig:
+    load: Callable[[], dict[str, Any]]
+    save: Callable[[dict[str, Any]], None]
+    normalize_provider: Callable[[str], str]
+    clear_model_cache: Callable[[], None]
+    output: Callable[[str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class OllamaOptionCommands:
+    apply: Callable[[dict[str, Any], str], None]
+    apply_timeout: Callable[[str, dict[str, Any]], list[str]]
+    context_status: Callable[[dict[str, Any]], str]
+    rate_usage: Callable[[str, dict[str, Any]], tuple[int, int | None]]
+    options_status: Callable[[dict[str, Any]], str]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderOptionCommands:
+    apply: Callable[[str, dict[str, Any], str], None]
+    cap_context: Callable[[str, dict[str, Any]], list[str]]
+    cap_output: Callable[[str, dict[str, Any]], list[str]]
+    apply_timeout: Callable[[str, dict[str, Any]], list[str]]
+    status: Callable[[str, dict[str, Any]], str]
+
+
+_CONTEXT_KEYS = frozenset(("context_window", "context", "max_model_len"))
+_OLLAMA_CONTEXT_KEYS = frozenset(
+    (
+        "num_ctx",
+        "ctx",
+        "num_ctx_min",
+        "ctx_min",
+        "min",
+        "num_ctx_max",
+        "ctx_max",
+        "max",
+    )
+)
+_TIMEOUT_KEYS = frozenset(
+    (
+        "timeout",
+        "timeout_ms",
+        "request_timeout",
+        "request_timeout_ms",
+        "stream_idle_timeout",
+        "stream_idle_timeout_ms",
+        "idle_timeout",
+        "idle_timeout_ms",
+    )
+)
+_COMMON_PROVIDER_NOTES = (
+    "  max_output_tokens is passed to Claude Code as CLAUDE_CODE_MAX_OUTPUT_TOKENS.",
+    "  context_window is a ciel-runtime/router cap; native mode still cannot raise the real server limit.",
+    "  temperature/top_p/top_k are injected by ciel-runtime router mode when the provider supports them.",
+)
+_PROVIDER_EXAMPLES = (
+    "  ciel-runtimectl provider-options deepseek max_output_tokens=8192 context_window=1048576",
+    "  ciel-runtimectl provider-options opencode-go endpoint:custom-model=chat",
+    "  ciel-runtimectl provider-options opencode ip_family=ipv6-preferred",
+    "  ciel-runtimectl provider-options fireworks account_id=fireworks model_api_base_url=https://api.fireworks.ai",
+    "  ciel-runtimectl provider-options nvidia-hosted max_output_tokens=4096 temperature=0.7 top_p=0.8 timeout=300000 rate_limit_rpm=40",
+    "  ciel-runtimectl provider-options vllm max_output_tokens=4096 context_window=65536 timeout=300000",
+    "  ciel-runtimectl provider-options self-hosted-nim native=true max_output_tokens=4096",
+)
+_OLLAMA_EXAMPLES = (
+    "  ciel-runtimectl ollama-options num_ctx=auto min=32768 max=131072",
+    "  ciel-runtimectl ollama-options num_ctx=65536 temperature=0.7 top_p=0.8 max_tokens=32768 timeout=300000",
+    "  ciel-runtime --ca-ollama-option temperature=0.7 --ca-ollama-num-ctx 65536",
+)
+
+
+class ProviderOptionCliController:
+    def __init__(
+        self,
+        config: ProviderOptionCliConfig,
+        ollama: OllamaOptionCommands,
+        provider: ProviderOptionCommands,
+        *,
+        supported_providers: Collection[str],
+        ollama_providers: Collection[str],
+        provider_notes: Mapping[str, Sequence[str]],
+        unsupported_message: str,
+    ) -> None:
+        self.config = config
+        self.ollama = ollama
+        self.provider = provider
+        self.supported_providers = frozenset(supported_providers)
+        self.ollama_providers = frozenset(ollama_providers)
+        self.provider_notes = provider_notes
+        self.unsupported_message = unsupported_message
+
+    def native(self, args: Any) -> None:
+        config = self.config.load()
+        provider_config = config["providers"]["ollama"]
+        raw = getattr(args, "value", None)
+        if raw:
+            value = raw.lower()
+            if value in ("on", "enable", "enabled", "true", "1"):
+                provider_config["native_compat"] = True
+            elif value in ("off", "disable", "disabled", "false", "0"):
+                provider_config["native_compat"] = False
+            else:
+                raise SystemExit("Use: ciel-runtime ollama-native on|off|status")
+            self.config.save(config)
+        state = "on" if provider_config.get("native_compat", True) else "off"
+        self._lines(
+            (
+                f"ollama_native_compat: {state}",
+                f"base_url: {provider_config.get('base_url')}",
+                f"model: {provider_config.get('current_model')}",
+                'launch_env: ANTHROPIC_BASE_URL=<ollama>, ANTHROPIC_AUTH_TOKEN=ollama, ANTHROPIC_API_KEY=""',
+            )
+        )
+
+    def ollama_options(self, args: Any) -> None:
+        config = self.config.load()
+        values = list(getattr(args, "values", []) or [])
+        provider = self._selected_provider(
+            values,
+            str(config.get("current_provider", "ollama")),
+            self.ollama_providers,
+            "ollama",
+        )
+        provider_config = config["providers"][provider]
+        if values:
+            context_changed = self._contains_key(values, _OLLAMA_CONTEXT_KEYS)
+            explicit_timeout = self._contains_key(values, _TIMEOUT_KEYS)
+            for token in values:
+                self.ollama.apply(provider_config, token)
+            timeout_lines = (
+                self.ollama.apply_timeout(provider, provider_config)
+                if context_changed and not explicit_timeout
+                else []
+            )
+            self._persist(config)
+            self.config.output(f"Ollama options updated for {provider}.")
+            self._lines(timeout_lines)
+        self._ollama_status(provider, provider_config)
+
+    def provider_options(self, args: Any) -> None:
+        config = self.config.load()
+        values = list(getattr(args, "values", []) or [])
+        provider = self._selected_provider(
+            values,
+            str(config.get("current_provider", "vllm")),
+            self.supported_providers,
+        )
+        if provider not in self.supported_providers:
+            raise SystemExit(self.unsupported_message)
+        provider_config = config["providers"][provider]
+        if values:
+            context_changed = self._contains_key(values, _CONTEXT_KEYS)
+            explicit_timeout = self._contains_key(values, _TIMEOUT_KEYS)
+            for token in values:
+                self.provider.apply(provider, provider_config, token)
+            cap_lines = self.provider.cap_context(provider, provider_config)
+            cap_lines.extend(self.provider.cap_output(provider, provider_config))
+            timeout_lines = (
+                self.provider.apply_timeout(provider, provider_config)
+                if context_changed and not explicit_timeout
+                else []
+            )
+            self._persist(config)
+            self.config.output(f"Provider options updated for {provider}.")
+            self._lines((*cap_lines, *timeout_lines))
+        self.config.output(f"provider: {provider}")
+        self.config.output(
+            f"provider_options: {self.provider.status(provider, provider_config)}"
+        )
+        self.config.output("Notes:")
+        self._lines(_COMMON_PROVIDER_NOTES)
+        self._lines(self.provider_notes.get(provider, ()))
+        self.config.output("Examples:")
+        self._lines(_PROVIDER_EXAMPLES)
+
+    def _ollama_status(self, provider: str, config: dict[str, Any]) -> None:
+        self._lines(
+            (
+                f"provider: {provider}",
+                f"num_ctx: {self.ollama.context_status(config)}",
+                f"keep_alive: {config.get('keep_alive', 'default')}",
+                f"think: {bool(config.get('think', False))}",
+                f"request_timeout_ms: {config.get('request_timeout_ms', 'default')}",
+            )
+        )
+        used, limit = self.ollama.rate_usage(provider, config)
+        if limit is not None:
+            self.config.output(f"rate_limit_rpm: {limit}")
+            if bool(config.get("rate_limit_status", False)):
+                suffix = f"{used}/{limit}" if limit > 0 else f"{used}/min (unmanaged)"
+                self.config.output(f"rpm_used: {suffix}")
+        self.config.output(f"ollama_options: {self.ollama.options_status(config)}")
+        self.config.output("Examples:")
+        self._lines(_OLLAMA_EXAMPLES)
+
+    def _selected_provider(
+        self,
+        values: list[str],
+        current: str,
+        allowed: Collection[str],
+        fallback: str | None = None,
+    ) -> str:
+        provider = current if current in allowed else fallback or current
+        if values:
+            try:
+                candidate = self.config.normalize_provider(values[0])
+                if candidate in allowed:
+                    provider = candidate
+                    values.pop(0)
+            except SystemExit:
+                pass
+        return provider
+
+    @staticmethod
+    def _contains_key(values: Sequence[str], keys: Collection[str]) -> bool:
+        return any(
+            token.split("=", 1)[0].replace("unset:", "").strip() in keys
+            for token in values
+        )
+
+    def _persist(self, config: dict[str, Any]) -> None:
+        self.config.save(config)
+        self.config.clear_model_cache()
+
+    def _lines(self, lines: Sequence[str]) -> None:
+        for line in lines:
+            self.config.output(line)