@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/provider_readiness.py

@@ -0,0 +1,112 @@
+"""Provider launch-readiness application service."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .architecture import ProviderAdapter, ProviderConfig, ProviderStatusPolicy
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderReadinessMode:
+    direct_native_anthropic: Callable[..., bool]
+    native_agy: Callable[..., bool]
+    native_codex: Callable[..., bool]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderReadinessCapabilities:
+    ultracode_enabled: Callable[..., bool]
+    supported_capabilities: Callable[..., list[str] | tuple[str, ...] | set[str]]
+    current_model: Callable[..., str]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderReadinessLmStudio:
+    ensure_model_loaded: Callable[..., Any]
+    save_config: Callable[..., Any]
+    runtime_info: Callable[..., dict[str, Any]]
+    positive_int: Callable[..., int | None]
+    minimum_context: int
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderReadinessServices:
+    mode: ProviderReadinessMode
+    capabilities: ProviderReadinessCapabilities
+    lm_studio: ProviderReadinessLmStudio
+    base_url_status: Callable[..., str]
+
+
+def launch_readiness_errors(
+    cfg: dict[str, Any],
+    provider: str,
+    pcfg: dict[str, Any],
+    adapter: ProviderAdapter,
+    contract_config: ProviderConfig,
+    status_policy: ProviderStatusPolicy,
+    *,
+    services: ProviderReadinessServices,
+) -> list[str]:
+    mode = services.mode
+    if (
+        mode.direct_native_anthropic(provider, pcfg)
+        or mode.native_agy(provider)
+        or mode.native_codex(provider)
+    ):
+        return []
+    status = services.base_url_status(provider, pcfg)
+    errors: list[str] = []
+    if any(marker in status.lower() for marker in ("unreachable", "placeholder", "missing")):
+        errors.extend((f"Launch blocked: {status}", status_policy.unreachable_hint))
+    api_key_error = adapter.launch_api_key_error(contract_config)
+    if api_key_error:
+        errors.append(api_key_error)
+    capabilities = services.capabilities
+    if capabilities.ultracode_enabled(provider, pcfg):
+        model = capabilities.current_model(provider, pcfg)
+        supported = set(capabilities.supported_capabilities(provider, pcfg, model))
+        if "xhigh_effort" not in supported:
+            errors.append(
+                "Launch blocked: ultracode requires a Claude Code model capability set that includes xhigh_effort. "
+                "Use a compatible Claude model or set claude_code_supported_capabilities after verifying the provider/model supports xhigh workflow thinking."
+            )
+    validators = {
+        "none": lambda: None,
+        "lm_studio": lambda: _validate_lm_studio(cfg, provider, pcfg, errors, services.lm_studio),
+    }
+    validators[status_policy.readiness_validation]()
+    return errors
+
+
+def _validate_lm_studio(
+    cfg: dict[str, Any],
+    provider: str,
+    pcfg: dict[str, Any],
+    errors: list[str],
+    services: ProviderReadinessLmStudio,
+) -> None:
+    try:
+        services.ensure_model_loaded(pcfg, timeout=1.5)
+        services.save_config(cfg)
+    except Exception as exc:
+        errors.append(
+            "Launch blocked: Ciel Runtime could not automatically load the selected LM Studio model "
+            f"with the recommended context ({type(exc).__name__}: {exc})."
+        )
+        return
+    info = services.runtime_info(provider, pcfg, timeout=1.5)
+    loaded = services.positive_int(info.get("loaded_context_len")) if info else None
+    state = str(info.get("state") or "") if info else ""
+    if loaded and loaded < services.minimum_context:
+        errors.append(
+            "Launch blocked: LM Studio loaded context is "
+            f"{loaded:,} tokens; Claude Code needs at least {services.minimum_context:,}. "
+            "Reload the model with a larger context length."
+        )
+    elif state and state != "loaded":
+        errors.append(
+            "Launch blocked: selected LM Studio model is not loaded, so the active context length cannot be verified. "
+            f"Load it with at least {services.minimum_context:,} context tokens."
+        )

package/ciel_runtime_support/provider_request_access.py

@@ -0,0 +1,131 @@
+"""Provider request credentials, headers, model aliases, and routing access."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from ciel_runtime_support.architecture import MessageProtocol, ProviderRequestPolicy
+from ciel_runtime_support.header_forwarding import project_end_to_end_request_headers
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderRequestAccessPorts:
+    request_policy: Callable[
+        [str, dict[str, Any]], ProviderRequestPolicy
+    ]
+    select_api_key: Callable[[str, dict[str, Any]], str | None]
+    meaningful_key: Callable[[str], bool]
+    adapter_headers: Callable[
+        [str, dict[str, Any], str | None], Mapping[str, str]
+    ]
+    inbound_credentials: Callable[
+        [str, Any | None], Mapping[str, str] | None
+    ]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderRequestAccessEffects:
+    user_agent_headers: Callable[[dict[str, str]], dict[str, str]]
+    ncp_model_id: Callable[[str], str]
+    normalize_provider: Callable[[Any], str]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderRequestAccessService:
+    ports: ProviderRequestAccessPorts
+    effects: ProviderRequestAccessEffects
+
+    def upstream_model(
+        self, provider: str, config: dict[str, Any], model: str
+    ) -> str:
+        strategy = self.ports.request_policy(
+            provider, config
+        ).model_alias_strategy
+        normalizers = {
+            "identity": lambda value: value,
+            "ncp": self.effects.ncp_model_id,
+        }
+        return normalizers[strategy](model)
+
+    def requires_streaming(
+        self, provider: str, config: dict[str, Any]
+    ) -> bool:
+        return self.ports.request_policy(provider, config).stream_required
+
+    @staticmethod
+    def key_from_headers(headers: Any) -> str:
+        try:
+            key = headers.get("x-api-key")
+            if key:
+                return str(key)
+            authorization = str(
+                headers.get("authorization")
+                or headers.get("Authorization")
+                or ""
+            )
+        except Exception:
+            return ""
+        if authorization.lower().startswith("bearer "):
+            return authorization[7:].strip()
+        return authorization.strip()
+
+    def headers(
+        self,
+        provider: str,
+        config: dict[str, Any],
+        inbound_headers: Any | None = None,
+        protocol: MessageProtocol | None = None,
+        preserve_inbound: bool = False,
+    ) -> dict[str, str]:
+        policy = self.ports.request_policy(provider, config)
+        passthrough = (
+            (protocol is not None or preserve_inbound)
+            and inbound_headers is not None
+        )
+        if passthrough:
+            headers = self.effects.user_agent_headers(
+                project_end_to_end_request_headers(
+                    inbound_headers,
+                    replace_credentials=True,
+                )
+            )
+        else:
+            headers = self.effects.user_agent_headers(
+                {
+                    "content-type": "application/json",
+                    "anthropic-version": "2023-06-01",
+                }
+            )
+        key = (
+            self.ports.select_api_key(provider, config)
+            or str(config.get("api_key") or "")
+            or "not-used"
+        )
+        meaningful = str(key) if self.ports.meaningful_key(str(key)) else None
+        if policy.credential_strategy == "anthropic_inbound":
+            credential_headers = self.ports.inbound_credentials(
+                meaningful or "", inbound_headers
+            )
+            if credential_headers is None:
+                raise RuntimeError(
+                    "Anthropic routed mode needs a configured API key "
+                    "or inbound Claude Code auth headers."
+                )
+            headers.update(credential_headers)
+        else:
+            headers.update(
+                self.ports.adapter_headers(
+                    provider, config, meaningful
+                )
+            )
+        return headers
+
+    def current_provider(
+        self, config: dict[str, Any]
+    ) -> tuple[str, dict[str, Any]]:
+        provider = self.effects.normalize_provider(
+            config.get("current_provider", "nvidia-hosted")
+        )
+        return provider, config["providers"][provider]

package/ciel_runtime_support/provider_request_builder.py

@@ -0,0 +1,250 @@
+"""Build provider wire requests from normalized Anthropic messages."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderRequestBudget:
+    context_limit: Callable[..., int]
+    positive_int: Callable[[Any], int]
+    configured_output: Callable[..., int]
+    cap_output_ratio: Callable[..., int]
+    reserve: Callable[..., int]
+    compact_anthropic: Callable[..., dict[str, Any]]
+    compact_messages: Callable[..., list[dict[str, Any]]]
+    compact_requested: Callable[[dict[str, Any]], bool]
+    cap_output: Callable[..., int]
+    write_usage: Callable[..., None]
+
+
+@dataclass(frozen=True, slots=True)
+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_enabled: Callable[[str | None, dict[str, Any]], bool]
+    # 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
+
+
+@dataclass(frozen=True, slots=True)
+class OpenAIRequestPorts:
+    messages: Callable[..., list[dict[str, Any]]]
+    tools: Callable[[Any], list[dict[str, Any]]]
+    context_limit: Callable[[str, dict[str, Any]], int]
+    reasoning_passback: Callable[[str, str, dict[str, Any]], bool]
+    repair_tools: Callable[[list[dict[str, Any]]], list[dict[str, Any]]]
+    reasoning_effort: Callable[..., str | None]
+    sampling_allowed: Callable[..., bool]
+    omit_tool_choice: Callable[..., bool]
+    tool_choice: Callable[[Any], Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderOptionPorts:
+    sampling_providers: frozenset[str]
+    sampling_options: tuple[str, ...]
+    anthropic_runtime_hints: Callable[[str], dict[str, Any]]
+    log: Callable[[str, str], None]
+
+
+class ProviderRequestBuilder:
+    def __init__(
+        self,
+        budget: ProviderRequestBudget,
+        ollama: OllamaRequestPorts,
+        openai: OpenAIRequestPorts,
+        options: ProviderOptionPorts,
+    ) -> None:
+        self.budget = budget
+        self.ollama = ollama
+        self.openai = openai
+        self.options = options
+
+    def cap_anthropic_body(
+        self, provider: str, config: dict[str, Any], body: dict[str, Any]
+    ) -> dict[str, Any]:
+        capped = dict(body)
+        if provider == "anthropic":
+            return capped
+        context_limit = (
+            self.budget.context_limit(provider, config)
+            or self.budget.positive_int(config.get("max_model_len"))
+            or self.budget.positive_int(config.get("context_window"))
+            or (32768 if provider == "vllm" else 0)
+        )
+        if not context_limit:
+            return capped
+        configured = self.budget.configured_output(config, capped)
+        ratio_capped = self.budget.cap_output_ratio(provider, config, configured)
+        if ratio_capped:
+            capped["max_tokens"] = ratio_capped
+        reserve = self.budget.reserve(config, context_limit)
+        output_reserve = self.budget.positive_int(capped.get("max_tokens")) or configured or 4096
+        input_budget = max(8192, context_limit - output_reserve - reserve)
+        capped = self.budget.compact_anthropic(
+            capped,
+            input_budget,
+            provider=provider,
+            pcfg=config,
+            model=str(capped.get("model") or config.get("current_model") or ""),
+            full_compact_request=self.budget.compact_requested(capped),
+        )
+        output_tokens = self.budget.cap_output(
+            config,
+            capped,
+            {key: value for key, value in capped.items() if key != "max_tokens"},
+            context_limit,
+            self.budget.positive_int(capped.get("max_tokens")) or configured,
+        )
+        if output_tokens:
+            capped["max_tokens"] = output_tokens
+        return capped
+
+    def apply_options(
+        self, provider: str, config: dict[str, Any], body: dict[str, Any]
+    ) -> dict[str, Any]:
+        if provider not in self.options.sampling_providers:
+            return body
+        projected = dict(body)
+        for key in self.options.sampling_options:
+            if config.get(key) is not None:
+                projected[key] = config[key]
+        return projected
+
+    def normalize_anthropic_options(
+        self,
+        provider: str,
+        body: dict[str, Any],
+        model_id: str,
+    ) -> dict[str, Any]:
+        if provider != "anthropic":
+            return body
+        unsupported = self.options.anthropic_runtime_hints(model_id).get(
+            "unsupported_sampling_parameters"
+        )
+        if not isinstance(unsupported, list) or not unsupported:
+            return body
+        projected = dict(body)
+        removed = [key for key in unsupported if isinstance(key, str) and key in projected]
+        for key in removed:
+            projected.pop(key, None)
+        if removed:
+            self.options.log(
+                "INFO",
+                f"anthropic_request_options_removed model={model_id} "
+                f"keys={','.join(removed)}",
+            )
+        return projected
+
+    def ollama_chat(
+        self,
+        model: str,
+        body: dict[str, Any],
+        config: dict[str, Any],
+        *,
+        stream: bool = True,
+        provider: str = "ollama",
+    ) -> dict[str, Any]:
+        messages = self.ollama.messages(body)
+        tools = self.ollama.tools(body.get("tools"))
+        context_limit = self.ollama.context_limit(config)
+        configured = self.budget.configured_output(config, body, "num_predict")
+        reserve = self.budget.reserve(config, context_limit)
+        output_reserve = configured or self.budget.positive_int(body.get("max_tokens")) or 4096
+        payload = {"messages": messages, "tools": tools}
+        messages = self.budget.compact_messages(
+            messages,
+            tools,
+            max(8192, context_limit - output_reserve - reserve),
+            provider=provider,
+            model=model,
+            pcfg=config,
+            full_compact_request=self.budget.compact_requested(body),
+            wire="ollama",
+        )
+        payload["messages"] = messages
+        self.budget.write_usage(provider, config, payload, "ollama_upstream")
+        request: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "stream": stream,
+            "think": self.ollama.think_enabled(model, config),
+        }
+        if config.get("keep_alive"):
+            request["keep_alive"] = str(config["keep_alive"])
+        if tools:
+            request["tools"] = tools
+        options = self.ollama.extra_options(config)
+        token_cache: dict[int, int] = {}
+        num_ctx = self.ollama.num_ctx(config, payload, _token_cache=token_cache)
+        num_predict = self.budget.cap_output(
+            config,
+            body,
+            payload,
+            num_ctx,
+            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
+
+    def openai_chat(
+        self,
+        provider: str,
+        model: str,
+        body: dict[str, Any],
+        config: dict[str, Any],
+        *,
+        stream: bool = False,
+    ) -> dict[str, Any]:
+        passback = self.openai.reasoning_passback(provider, model, config)
+        messages = self.openai.messages(body, reasoning_passback=passback)
+        tools = self.openai.tools(body.get("tools"))
+        context_limit = self.openai.context_limit(provider, config)
+        configured = self.budget.configured_output(config, body)
+        reserve = self.budget.reserve(config, context_limit)
+        output_reserve = configured or self.budget.positive_int(body.get("max_tokens")) or 4096
+        messages = self.budget.compact_messages(
+            messages,
+            tools,
+            max(8192, context_limit - output_reserve - reserve),
+            provider=provider,
+            model=model,
+            pcfg=config,
+            full_compact_request=self.budget.compact_requested(body),
+            wire="openai",
+        )
+        messages = self.openai.repair_tools(messages)
+        request: dict[str, Any] = {"model": model, "messages": messages, "stream": stream}
+        reasoning_effort = self.openai.reasoning_effort(
+            provider, model, body, config
+        )
+        if reasoning_effort:
+            request["reasoning_effort"] = reasoning_effort
+        if tools:
+            request["tools"] = tools
+        if body.get("tool_choice") is not None and not self.openai.omit_tool_choice(
+            provider, model, body, config
+        ):
+            request["tool_choice"] = self.openai.tool_choice(body.get("tool_choice"))
+        if configured:
+            request["max_tokens"] = configured
+        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

package/ciel_runtime_support/provider_responses_passthrough.py

@@ -0,0 +1,81 @@
+"""Native OpenAI Responses passthrough for compatible model providers."""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderResponsesPassthroughPorts:
+    project_channel_context: Callable[
+        [dict[str, Any]], tuple[dict[str, Any], dict[str, Any]]
+    ]
+    begin_channel_delivery: Callable[[Any, dict[str, Any]], None]
+    normalize_model: Callable[[str, dict[str, Any], str], str]
+    normalize_request: Callable[
+        [str, dict[str, Any], Mapping[str, Any]], Mapping[str, Any]
+    ]
+    upstream_base: Callable[[str, dict[str, Any]], str]
+    join_url: Callable[[str, str], str]
+    headers: Callable[[str, dict[str, Any], Any], dict[str, str]]
+    urlopen: Callable[..., Any]
+    timeout_seconds: Callable[[dict[str, Any]], float]
+    copy_response_headers: Callable[[Any, Any], None]
+
+
+class ProviderResponsesPassthrough:
+    """Forward Responses without collapsing typed items into another protocol."""
+
+    def __init__(self, ports: ProviderResponsesPassthroughPorts) -> None:
+        self._ports = ports
+
+    def forward(
+        self,
+        handler: Any,
+        provider: str,
+        config: dict[str, Any],
+        body: dict[str, Any],
+    ) -> dict[str, Any]:
+        upstream_body = dict(body)
+        upstream_body["model"] = self._ports.normalize_model(
+            provider, config, str(body.get("model") or "")
+        )
+        upstream_body = dict(
+            self._ports.normalize_request(provider, config, upstream_body)
+        )
+        upstream_body, delivery_body = self._ports.project_channel_context(
+            upstream_body
+        )
+        self._ports.begin_channel_delivery(handler, delivery_body)
+        url = self._ports.join_url(
+            self._ports.upstream_base(provider, config),
+            "/v1/responses",
+        )
+        request = urllib.request.Request(
+            url,
+            data=json.dumps(upstream_body, ensure_ascii=False).encode("utf-8"),
+            headers=self._ports.headers(provider, config, handler.headers),
+            method="POST",
+        )
+        with self._ports.urlopen(
+            request,
+            timeout=self._ports.timeout_seconds(config),
+            provider=provider,
+            pcfg=config,
+        ) as response:
+            handler.send_response(getattr(response, "status", 200))
+            self._ports.copy_response_headers(handler, response.headers)
+            handler.end_headers()
+            while chunk := response.read(65_536):
+                handler.wfile.write(chunk)
+                handler.wfile.flush()
+        return delivery_body
+
+
+__all__ = [
+    "ProviderResponsesPassthrough",
+    "ProviderResponsesPassthroughPorts",
+]

package/ciel_runtime_support/provider_runtime_info.py

@@ -0,0 +1,113 @@
+"""Provider-neutral runtime model metadata discovery service."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderRuntimeInfoPorts:
+    strategy: Callable[[str], str]
+    lm_studio_info: Callable[..., dict[str, Any] | None]
+    request_base: Callable[[str, dict[str, Any]], str]
+    current_model: Callable[[str, dict[str, Any]], str]
+    http_json: Callable[..., Any]
+    join_url: Callable[[str, str], str]
+    model_headers: Callable[[str, dict[str, Any]], dict[str, str]]
+    positive_int: Callable[[Any], int | None]
+    log: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderRuntimeInfoService:
+    ports: ProviderRuntimeInfoPorts
+
+    @staticmethod
+    def model_context(item: dict[str, Any]) -> int | None:
+        keys = (
+            "max_model_len",
+            "max_context_length",
+            "context_length",
+            "contextLength",
+            "max_context_tokens",
+            "max_position_embeddings",
+            "trainingContextLength",
+        )
+        for key in keys:
+            value = ProviderRuntimeInfoService._positive_int(item.get(key))
+            if value:
+                return value
+        for key, value in item.items():
+            if isinstance(key, str) and key.rsplit(".", 1)[-1] in keys:
+                fixed = ProviderRuntimeInfoService._positive_int(value)
+                if fixed:
+                    return fixed
+        details = item.get("details")
+        if isinstance(details, dict):
+            for key in keys:
+                value = ProviderRuntimeInfoService._positive_int(details.get(key))
+                if value:
+                    return value
+        return None
+
+    @staticmethod
+    def _positive_int(value: Any) -> int | None:
+        try:
+            fixed = int(value)
+        except (TypeError, ValueError, OverflowError):
+            return None
+        return fixed if fixed > 0 else None
+
+    def discover(
+        self,
+        provider: str,
+        provider_config: dict[str, Any],
+        timeout: float = 3.0,
+    ) -> dict[str, Any] | None:
+        strategy = self.ports.strategy(provider)
+        if not strategy:
+            return None
+        if strategy == "lm_studio":
+            info = self.ports.lm_studio_info(provider_config, timeout=timeout)
+            if info:
+                return info
+        base = self.ports.request_base(provider, provider_config)
+        if not base:
+            return None
+        current = self.ports.current_model(provider, provider_config)
+        models_url = self.ports.join_url(base, "/v1/models")
+        try:
+            data = self.ports.http_json(
+                models_url,
+                headers=self.ports.model_headers(provider, provider_config),
+                timeout=timeout,
+            )
+        except Exception as exc:
+            self.ports.log(
+                "WARN",
+                f"provider_runtime_info_failed provider={provider} error={type(exc).__name__}: {exc}",
+            )
+            return None
+        items = data.get("data") if isinstance(data, dict) else None
+        if not isinstance(items, list):
+            return None
+        candidates = [item for item in items if isinstance(item, dict)]
+        selected = next((item for item in candidates if str(item.get("id") or "") == current), None)
+        selected = selected or (candidates[0] if candidates else None)
+        if not selected:
+            return None
+        return {
+            "models_url": models_url,
+            "requested_model": current,
+            "runtime_model": str(selected.get("id") or ""),
+            "max_model_len": self.model_context(selected),
+            "owned_by": selected.get("owned_by"),
+            "root": selected.get("root"),
+        }
+
+    def context_limit(self, provider: str, provider_config: dict[str, Any], timeout: float = 3.0) -> int | None:
+        info = self.discover(provider, provider_config, timeout)
+        return self.ports.positive_int(info.get("max_model_len")) if info else None
+
+
+__all__ = ["ProviderRuntimeInfoPorts", "ProviderRuntimeInfoService"]