@oneciel-ai/ciel-runtime 0.2.2 → 0.2.4

package/ciel_runtime_support/provider_models.py

@@ -91,10 +91,45 @@ def fetch_upstream_model_ids(provider: str, pcfg: dict[str, Any], force_refresh:
     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
+    catalog_policy = provider_model_catalog_policy(provider, pcfg)
+
+    def supplement_model_aliases(
+        model_ids: list[str], model_info: dict[str, dict[str, Any]] | None = None
+    ) -> list[str]:
+        """Add provider-declared wire aliases without weakening catalog authority."""
+        supplemented = list(model_ids)
+        for source_id, alias_id in catalog_policy.supplemental_model_aliases:
+            source = normalize_model_id(provider, source_id)
+            alias = normalize_model_id(provider, alias_id)
+            if not source or not alias or source not in supplemented:
+                continue
+            if alias not in supplemented:
+                supplemented.append(alias)
+            if model_info is not None and source in model_info and alias not in model_info:
+                model_info[alias] = dict(model_info[source])
+        return supplemented
+
     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)
+        supplemented = sorted_model_ids(
+            unique_model_ids(provider, supplement_model_aliases(cached))
+        )
+        cached = supplemented
+        if (
+            catalog_policy.authoritative_upstream_catalog
+            or not catalog_policy.allow_configured_fallback
+        ):
+            return cached
+        ids = unique_model_ids(provider, [
+            *cached,
+            *catalog_policy.fallback_models,
+            *(pcfg.get("custom_models", []) or []),
+            pcfg.get("current_model") or "",
+        ])
+        sorted_ids = sorted_model_ids(ids)
+        if sorted_ids != cached:
+            write_model_list_cache(provider, pcfg, sorted_ids)
+        return sorted_ids
     if catalog_policy.kind == "configured":
         ids = unique_model_ids(provider, [
             *catalog_policy.fallback_models,
@@ -212,11 +247,18 @@ def fetch_upstream_model_ids(provider: str, pcfg: dict[str, Any], force_refresh:
                     router_log("DEBUG", f"{provider} public model catalog fetch failed: {type(exc).__name__}: {exc}")
     except Exception:
         ids = []
+    if fetched and ids and catalog_policy.authoritative_upstream_catalog:
+        ids = supplement_model_aliases(ids, model_info)
+        sorted_ids = sorted_model_ids(unique_model_ids(provider, ids))
+        metadata = {"model_info": model_info} if model_info else None
+        write_model_list_cache(provider, pcfg, sorted_ids, metadata)
+        return sorted_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, [
+            *catalog_policy.fallback_models,
             *(pcfg.get("custom_models", []) or []),
             pcfg.get("current_model") or "",
         ])
@@ -244,6 +286,7 @@ def fetch_upstream_model_ids(provider: str, pcfg: dict[str, Any], force_refresh:
         ids.insert(0, cur)
     if catalog_policy.kind == "nvidia" and cur and cur not in ids:
         ids.insert(0, cur)
+    ids = supplement_model_aliases(ids, model_info)
     sorted_ids = unique_model_ids(provider, ids)
     if catalog_policy.kind != "anthropic":
         sorted_ids = sorted_model_ids(sorted_ids)

package/ciel_runtime_support/provider_option_cli.py

@@ -79,6 +79,25 @@ _OLLAMA_EXAMPLES = (
     "  ciel-runtime --ca-ollama-option temperature=0.7 --ca-ollama-num-ctx 65536",
 )
 
+DEFAULT_PROVIDER_NOTES: Mapping[str, Sequence[str]] = {
+    "opencode": (
+        "  OpenCode endpoint override: endpoint:<model-id>=messages|chat|responses|gemini",
+        "  OpenCode ip_family options: auto, ipv4, ipv6, ipv4-preferred, ipv6-preferred",
+    ),
+    "opencode-go": (
+        "  OpenCode endpoint override: endpoint:<model-id>=messages|chat|responses|gemini",
+        "  OpenCode ip_family options: auto, ipv4, ipv6, ipv4-preferred, ipv6-preferred",
+    ),
+    "fireworks": (
+        "  Fireworks model list options: account_id=fireworks, model_api_base_url=https://api.fireworks.ai",
+    ),
+}
+DEFAULT_UNSUPPORTED_MESSAGE = (
+    "Provider options are available for anthropic, ollama, ollama-cloud, "
+    "deepseek, opencode, opencode-go, kimi, z.ai, fireworks, vllm, "
+    "lm-studio, nvidia-hosted, self-hosted-nim, and openrouter."
+)
+
 
 class ProviderOptionCliController:
     def __init__(

package/ciel_runtime_support/provider_policy.py

@@ -94,7 +94,7 @@ def normalize_provider_request(provider: str, pcfg: dict[str, Any], body: dict[s
     out = sanitize_assistant_pseudo_tool_text_history(out)
     out = normalize_anthropic_tool_turns_for_provider(provider, pcfg, out)
     if profile.get("upstream_format") == "anthropic-messages":
-        out = normalize_anthropic_system_role_messages(out)
+        out = normalize_anthropic_system_role_messages(provider, pcfg, out)
     return out
 
 

package/ciel_runtime_support/provider_readiness_context.py

@@ -0,0 +1,189 @@
+"""Provider configuration status and launch-readiness bounded context.
+
+This module owns the application-level coordination between provider adapters,
+status projection, and launch-readiness validation.  The compatibility facade
+supplies concrete ports; no support module reaches back into ``ciel_runtime``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping
+
+from .architecture import ProviderAdapter, ProviderConfig
+from .provider_readiness import (
+    ProviderReadinessServices,
+    launch_readiness_errors as evaluate_provider_readiness,
+)
+from .provider_status import (
+    ProviderStatusServices,
+    base_url_status_line as project_provider_base_url_status,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderDefaultsPorts:
+    nvidia_upstream_base_url: Callable[[], str]
+    adapter_exists: Callable[[str], bool]
+    adapter_default_base_url: Callable[[str], str]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderCredentialPorts:
+    key_count: Callable[[str, dict[str, Any]], int]
+    primary_key: Callable[[str, dict[str, Any]], str]
+    mask_secret: Callable[[str], str]
+    secret_fingerprint: Callable[[str], str]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderConfigurationPorts:
+    load: Callable[[], dict[str, Any]]
+    current: Callable[[dict[str, Any]], tuple[str, dict[str, Any]]]
+    adapter: Callable[[str, dict[str, Any]], ProviderAdapter]
+    contract: Callable[[str, dict[str, Any]], ProviderConfig]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderProjectionPorts:
+    status_services: Callable[[], ProviderStatusServices]
+    readiness_services: Callable[[], ProviderReadinessServices]
+    notes: Mapping[str, Mapping[str, list[str]]]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderReadinessContext:
+    defaults: ProviderDefaultsPorts
+    credentials: ProviderCredentialPorts
+    configuration: ProviderConfigurationPorts
+    projection: ProviderProjectionPorts
+
+    def default_base_url(self, provider: str) -> str:
+        if provider == "nvidia-hosted":
+            return self.defaults.nvidia_upstream_base_url()
+        if self.defaults.adapter_exists(provider):
+            configured = self.defaults.adapter_default_base_url(provider)
+            if configured:
+                return configured
+        return "http://localhost:8000"
+
+    @staticmethod
+    def meaningful_key(value: str | None) -> bool:
+        text = str(value or "").strip()
+        return bool(text and text.lower() not in {"none", "null"})
+
+    def api_key_status_line(self, provider: str, pcfg: dict[str, Any]) -> str:
+        key_count = self.credentials.key_count(provider, pcfg)
+        primary = self.credentials.primary_key(provider, pcfg)
+        primary_detail = (
+            f"; primary {self.credentials.mask_secret(primary)}; "
+            f"fp {self.credentials.secret_fingerprint(primary)}"
+            if key_count
+            else ""
+        )
+        adapter = self.configuration.adapter(provider, pcfg)
+        return adapter.api_key_status(
+            self.configuration.contract(provider, pcfg),
+            key_count=key_count,
+            primary_detail=primary_detail,
+        )
+
+    def base_url_status_line(self, provider: str, pcfg: dict[str, Any]) -> str:
+        adapter = self.configuration.adapter(provider, pcfg)
+        status_policy = adapter.status_policy(
+            self.configuration.contract(provider, pcfg)
+        )
+        return project_provider_base_url_status(
+            provider,
+            pcfg,
+            status_policy,
+            services=self.projection.status_services(),
+        )
+
+    def preflight_lines(self) -> list[str]:
+        cfg = self.configuration.load()
+        provider, pcfg = self.configuration.current(cfg)
+        lang = str(cfg.get("language") or "en")
+        localized = self.projection.notes.get(
+            lang, self.projection.notes.get("en", {})
+        )
+        notes = localized.get(provider, [])
+        return [
+            self.base_url_status_line(provider, pcfg),
+            self.api_key_status_line(provider, pcfg),
+            *notes,
+        ]
+
+    def launch_readiness_errors(
+        self, cfg: dict[str, Any] | None = None
+    ) -> list[str]:
+        cfg = cfg or self.configuration.load()
+        provider, pcfg = self.configuration.current(cfg)
+        adapter = self.configuration.adapter(provider, pcfg)
+        contract = self.configuration.contract(provider, pcfg)
+        status_policy = adapter.status_policy(contract)
+        return evaluate_provider_readiness(
+            cfg,
+            provider,
+            pcfg,
+            adapter,
+            contract,
+            status_policy,
+            services=self.projection.readiness_services(),
+        )
+
+    @staticmethod
+    def launch_blockers_require_api_key(blockers: list[str]) -> bool:
+        return any(
+            "requires" in line.lower() and "api key" in line.lower()
+            for line in blockers
+        )
+
+    def settings_ready_except_api_key(self) -> bool:
+        cfg = self.configuration.load()
+        provider, pcfg = self.configuration.current(cfg)
+        if provider == "codex":
+            return True
+        base = pcfg.get("base_url", "")
+        model = pcfg.get("current_model", "")
+        return bool(provider and base and model and "your-" not in base)
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderReadinessCompatibilityApi:
+    """Late-bound facade API that preserves patchable composition ports."""
+
+    context: Callable[[], ProviderReadinessContext]
+
+    def default_base_url(self, provider: str) -> str:
+        return self.context().default_base_url(provider)
+
+    def api_key_status_line(self, provider: str, pcfg: dict[str, Any]) -> str:
+        return self.context().api_key_status_line(provider, pcfg)
+
+    def base_url_status_line(self, provider: str, pcfg: dict[str, Any]) -> str:
+        return self.context().base_url_status_line(provider, pcfg)
+
+    def preflight_lines(self) -> list[str]:
+        return self.context().preflight_lines()
+
+    def launch_readiness_errors(
+        self, cfg: dict[str, Any] | None = None
+    ) -> list[str]:
+        return self.context().launch_readiness_errors(cfg)
+
+    def launch_blockers_require_api_key(self, blockers: list[str]) -> bool:
+        return self.context().launch_blockers_require_api_key(blockers)
+
+    def settings_ready_except_api_key(self) -> bool:
+        return self.context().settings_ready_except_api_key()
+
+
+__all__ = [
+    "ProviderConfigurationPorts",
+    "ProviderCredentialPorts",
+    "ProviderDefaultsPorts",
+    "ProviderProjectionPorts",
+    "ProviderReadinessCompatibilityApi",
+    "ProviderReadinessContext",
+]

package/ciel_runtime_support/provider_request_builder.py

@@ -25,16 +25,9 @@ class ProviderRequestBudget:
 class OllamaRequestPorts:
     messages: Callable[[dict[str, Any]], list[dict[str, Any]]]
     tools: Callable[[Any], list[dict[str, Any]]]
-    extra_options: Callable[[dict[str, Any]], dict[str, Any]]
     context_limit: Callable[[dict[str, Any]], int]
-    num_ctx: Callable[..., int]
-    think_value: Callable[
-        [str, str | None, dict[str, Any], dict[str, Any]], bool | str | None
-    ]
-    # Model-card provenance gate for num_predict: None = omit the parameter
-    # entirely so the server default applies (operator 2026-07-29). The
-    # default implementation passes the capped value through unchanged.
-    num_predict: Callable[[dict[str, Any], int | None], int | None] = lambda _config, capped: capped
+    num_ctx: Callable[..., int | None]
+    apply_optional: Callable[..., dict[str, Any]]
 
 
 @dataclass(frozen=True, slots=True)
@@ -48,6 +41,7 @@ class OpenAIRequestPorts:
     sampling_allowed: Callable[..., bool]
     omit_tool_choice: Callable[..., bool]
     tool_choice: Callable[[Any], Any]
+    normalize_request: Callable[[str, dict[str, Any], dict[str, Any]], dict[str, Any]]
 
 
 @dataclass(frozen=True, slots=True)
@@ -180,20 +174,12 @@ class ProviderRequestBuilder:
             "messages": messages,
             "stream": stream,
         }
-        think = self.ollama.think_value(provider, model, config, body)
-        if think is not None:
-            request["think"] = think
-        if config.get("keep_alive"):
-            request["keep_alive"] = str(config["keep_alive"])
         if tools:
             request["tools"] = tools
-        options = self.ollama.extra_options(config)
-        # num_predict is governed by the output-budget policy below. Remove a
-        # persisted/default copy so a deliberate provider-default decision can
-        # actually omit it from the wire request.
-        options.pop("num_predict", None)
         token_cache: dict[int, int] = {}
         num_ctx = self.ollama.num_ctx(config, payload, _token_cache=token_cache)
+        if not num_ctx:
+            num_ctx = self.ollama.context_limit(config)
         num_predict = self.budget.cap_output(
             config,
             body,
@@ -202,14 +188,14 @@ class ProviderRequestBuilder:
             configured,
             _token_cache=token_cache,
         )
-        num_predict = self.ollama.num_predict(config, num_predict)
-        if num_predict:
-            options["num_predict"] = num_predict
-        if num_ctx:
-            options.setdefault("num_ctx", num_ctx)
-        if options:
-            request["options"] = options
-        return request
+        return self.ollama.apply_optional(
+            request,
+            provider,
+            model,
+            config,
+            body,
+            output_limit=num_predict,
+        )
 
     def openai_chat(
         self,
@@ -252,7 +238,57 @@ class ProviderRequestBuilder:
             request["tool_choice"] = self.openai.tool_choice(body.get("tool_choice"))
         if configured:
             request["max_tokens"] = configured
+        if isinstance(body.get("response_format"), dict):
+            request["response_format"] = dict(body["response_format"])
         for key in ("temperature", "top_p"):
             if self.openai.sampling_allowed(provider, config) and config.get(key) is not None:
                 request[key] = config[key]
-        return request
+        return self.openai.normalize_request(provider, config, request)
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderRequestCompatibilityApi:
+    builder: Callable[[], ProviderRequestBuilder]
+
+    def cap_anthropic_body(
+        self, provider: str, config: dict[str, Any], body: dict[str, Any]
+    ) -> dict[str, Any]:
+        return self.builder().cap_anthropic_body(provider, config, body)
+
+    def apply_options(
+        self, provider: str, config: dict[str, Any], body: dict[str, Any]
+    ) -> dict[str, Any]:
+        return self.builder().apply_options(provider, config, body)
+
+    def normalize_anthropic_options(
+        self,
+        provider: str,
+        config: dict[str, Any],
+        body: dict[str, Any],
+        model_id: str,
+    ) -> dict[str, Any]:
+        return self.builder().normalize_anthropic_options(provider, body, model_id)
+
+    def ollama_chat(
+        self,
+        model: str,
+        body: dict[str, Any],
+        config: dict[str, Any],
+        stream: bool = True,
+        provider: str = "ollama",
+    ) -> dict[str, Any]:
+        return self.builder().ollama_chat(
+            model, body, config, stream=stream, provider=provider
+        )
+
+    def openai_chat(
+        self,
+        provider: str,
+        model: str,
+        body: dict[str, Any],
+        config: dict[str, Any],
+        stream: bool = False,
+    ) -> dict[str, Any]:
+        return self.builder().openai_chat(
+            provider, model, body, config, stream=stream
+        )

package/ciel_runtime_support/provider_responses_passthrough.py

@@ -7,6 +7,10 @@ import urllib.request
 from dataclasses import dataclass
 from typing import Any, Callable, Mapping
 
+from .responses_usage_observer import ResponsesUsageObserver
+from .responses_input_compatibility import repair_replayed_response_items
+from .upstream_dump import dump_upstream_request
+
 
 @dataclass(frozen=True, slots=True)
 class ProviderResponsesPassthroughPorts:
@@ -24,6 +28,10 @@ class ProviderResponsesPassthroughPorts:
     urlopen: Callable[..., Any]
     timeout_seconds: Callable[[dict[str, Any]], float]
     copy_response_headers: Callable[[Any, Any], None]
+    record_usage: Callable[[str, str, dict[str, int]], None] = (
+        lambda _provider, _model, _usage: None
+    )
+    log: Callable[[str, str], Any] = lambda _level, _message: None
 
 
 class ProviderResponsesPassthrough:
@@ -39,7 +47,7 @@ class ProviderResponsesPassthrough:
         config: dict[str, Any],
         body: dict[str, Any],
     ) -> dict[str, Any]:
-        upstream_body = dict(body)
+        upstream_body = dict(repair_replayed_response_items(body))
         upstream_body["model"] = self._ports.normalize_model(
             provider, config, str(body.get("model") or "")
         )
@@ -54,9 +62,11 @@ class ProviderResponsesPassthrough:
             self._ports.upstream_base(provider, config),
             "/v1/responses",
         )
+        data = json.dumps(upstream_body, ensure_ascii=False).encode("utf-8")
+        dump_upstream_request(url, data, self._ports.log)
         request = urllib.request.Request(
             url,
-            data=json.dumps(upstream_body, ensure_ascii=False).encode("utf-8"),
+            data=data,
             headers=self._ports.headers(provider, config, handler.headers),
             method="POST",
         )
@@ -66,12 +76,21 @@ class ProviderResponsesPassthrough:
             provider=provider,
             pcfg=config,
         ) as response:
+            usage = ResponsesUsageObserver()
             handler.send_response(getattr(response, "status", 200))
             self._ports.copy_response_headers(handler, response.headers)
             handler.end_headers()
             while chunk := response.read(65_536):
+                usage.feed(chunk)
                 handler.wfile.write(chunk)
                 handler.wfile.flush()
+            observed = usage.finish()
+            if observed:
+                self._ports.record_usage(
+                    provider,
+                    str(upstream_body.get("model") or ""),
+                    observed,
+                )
         return delivery_body
 
 

package/ciel_runtime_support/provider_timeout_policy.py

@@ -182,3 +182,57 @@ class ProviderTimeoutPolicy:
             f"Auto timeout: {timeout_ms}ms for context {self.ports.format_context(context)}.",
             f"stream_idle_timeout_ms: {idle_ms}",
         ]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderTimeoutCompatibilityApi:
+    policy: Callable[[], ProviderTimeoutPolicy]
+
+    def configured_context(
+        self, provider: str, config: dict[str, Any]
+    ) -> int | None:
+        return self.policy().configured_context(provider, config)
+
+    def configured_output(
+        self, provider: str, config: dict[str, Any]
+    ) -> int | None:
+        return self.policy().configured_output(provider, config)
+
+    def clamp(self, milliseconds: int | float | None) -> int:
+        return self.policy().clamp(milliseconds)
+
+    def calculated(
+        self,
+        provider: str,
+        config: dict[str, Any],
+        timeout_candidates: list[int] | None = None,
+    ) -> int:
+        return self.policy().calculated(provider, config, timeout_candidates)
+
+    def recommended(
+        self,
+        provider: str,
+        config: dict[str, Any],
+        use_context_fallback: bool = True,
+    ) -> int:
+        return self.policy().recommended(
+            provider, config, use_context_fallback=use_context_fallback
+        )
+
+    def apply(
+        self,
+        provider: str,
+        config: dict[str, Any],
+        use_context_fallback: bool = True,
+    ) -> list[str]:
+        return self.policy().apply(
+            provider, config, use_context_fallback=use_context_fallback
+        )
+
+
+__all__ = [
+    "ProviderTimeoutCompatibilityApi",
+    "ProviderTimeoutPolicy",
+    "ProviderTimeoutPorts",
+    "ProviderTimeoutSettings",
+]

package/ciel_runtime_support/provider_tool_policy.py

@@ -44,7 +44,12 @@ class ProviderToolPolicy:
             }
         adapter, contract = self._adapter(provider, config)
         if adapter.capabilities(contract).blocks_default_tools:
-            return set(self.default_blocked_tools)
+            blocked = set(self.default_blocked_tools)
+            if adapter.supports_server_web_tools(contract):
+                blocked.difference_update(
+                    {"WebSearch", "web_search", "WebFetch", "web_fetch"}
+                )
+            return blocked
         return set()
 
     def normalize_anthropic_stream_tool_use(
@@ -66,6 +71,9 @@ class ProviderToolPolicy:
         )
         model = self.strip_context_suffix(raw_model).lower()
         adapter, contract = self._adapter(provider, config)
+        request_support = getattr(adapter, "supports_tool_choice_for_request", None)
+        if callable(request_support):
+            return request_support(contract, model, body)
         return adapter.supports_tool_choice(contract, model)
 
     def tool_choice_status(

package/ciel_runtime_support/providers/__init__.py

@@ -31,6 +31,10 @@ from .anthropic_catalog import (
     CatalogAnthropicProviderAdapter,
 )
 from .cloud import AzureOpenAIProviderAdapter, CodeBuddyCnProviderAdapter
+from .alibaba import (
+    AlibabaIndividualTokenPlanProviderAdapter,
+    AlibabaTokenPlanProviderAdapter,
+)
 
 __all__ = [
     "ANTHROPIC_COMPATIBLE_PROVIDER_SPECS",
@@ -40,6 +44,8 @@ __all__ = [
     "CodeBuddyCnProviderAdapter",
     "HttpBearerProviderAdapter",
     "AnthropicProviderAdapter",
+    "AlibabaTokenPlanProviderAdapter",
+    "AlibabaIndividualTokenPlanProviderAdapter",
     "NoAuthProviderAdapter",
     "OpenAICompatibleProviderAdapter",
     "PROVIDER_DEFAULT_BASE_URLS",