@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/provider_context.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .architecture import ProviderContextPolicy
+
+
+@dataclass(frozen=True)
+class ProviderContextServices:
+    positive_int: Callable[[Any], int | None]
+    model_context_hint: Callable[[str], int | None]
+    anthropic_context_hint: Callable[[str], int | None]
+    nvidia_context_default: Callable[[str], int | None]
+    upstream_context_limit: Callable[..., int | None]
+    ollama_context_limit: Callable[[dict[str, Any]], int | None]
+
+
+@dataclass(frozen=True)
+class ContextPresetServices:
+    positive_int: Callable[[Any], int | None]
+    ollama_options: Callable[[dict[str, Any]], dict[str, Any]]
+    ollama_thinking_enabled: Callable[[str, dict[str, Any]], bool]
+
+
+def resolve_context_capacity(
+    provider: str,
+    config: dict[str, Any],
+    policy: ProviderContextPolicy,
+    services: ProviderContextServices,
+) -> int | None:
+    strategy = policy.capacity_strategy
+    model = str(config.get("current_model") or "")
+    positive_int = services.positive_int
+
+    def hint() -> int | None:
+        return services.model_context_hint(model)
+
+    def configured() -> int | None:
+        return positive_int(config.get("context_window"))
+
+    def maximum() -> int | None:
+        return positive_int(config.get("max_model_len"))
+    if strategy == "managed":
+        return None
+    if strategy == "nvidia":
+        return services.nvidia_context_default(model)
+    if strategy == "remote_first":
+        return (
+            services.upstream_context_limit(provider, config, timeout=1.0)
+            or maximum()
+            or hint()
+            or configured()
+        )
+    if strategy == "hint_first":
+        return hint() or maximum() or configured()
+    if strategy == "configured_first":
+        return maximum() or hint() or configured()
+    if strategy == "ollama":
+        return (
+            services.ollama_context_limit(config)
+            or hint()
+            or positive_int(config.get("num_ctx_max"))
+            or positive_int(config.get("num_ctx"))
+        )
+    if strategy == "anthropic_hint":
+        return configured() or maximum() or services.anthropic_context_hint(model)
+    return hint() or configured() or maximum()
+
+
+def cap_context_settings(
+    config: dict[str, Any],
+    capacity: int | None,
+    policy: ProviderContextPolicy,
+    *,
+    positive_int: Callable[[Any], int | None],
+) -> list[str]:
+    if not capacity:
+        return []
+    if policy.settings_strategy == "ollama":
+        maximum = positive_int(config.get("num_ctx_max"))
+        messages: list[str] = []
+        if maximum and maximum > capacity:
+            config["num_ctx_max"] = capacity
+            messages.append(f"Context max capped to selected model limit: {capacity:,} tokens.")
+        for key in ("num_ctx_min", "num_ctx"):
+            value = positive_int(config.get(key))
+            if value and value > capacity:
+                config[key] = capacity
+        return messages
+    if policy.settings_strategy == "standard":
+        context_window = positive_int(config.get("context_window"))
+        if context_window and context_window > capacity:
+            config["context_window"] = capacity
+            return [f"Context window capped to selected model limit: {capacity:,} tokens."]
+    return []
+
+
+def small_context_output_token_cap(
+    context_window: int | None,
+    *,
+    positive_int: Callable[[Any], int | None],
+) -> int | None:
+    context = positive_int(context_window)
+    if not context or context > 262144:
+        return None
+    divisor = 16 if context <= 131072 else 32
+    cap = max(1024, min(8192, context // divisor))
+    return max(1024, (cap // 1024) * 1024)
+
+
+def cap_output_tokens(
+    configured: int | None,
+    policy: ProviderContextPolicy,
+    context_window: int | None,
+    *,
+    positive_int: Callable[[Any], int | None],
+) -> int | None:
+    value = positive_int(configured)
+    if not value or policy.settings_strategy == "managed":
+        return value
+    cap = small_context_output_token_cap(
+        context_window,
+        positive_int=positive_int,
+    )
+    return min(value, cap) if cap else value
+
+
+def cap_output_settings(
+    config: dict[str, Any],
+    policy: ProviderContextPolicy,
+    context_window: int | None,
+    *,
+    positive_int: Callable[[Any], int | None],
+    format_context: Callable[[int | None], str],
+) -> list[str]:
+    if policy.settings_strategy == "managed":
+        return []
+    cap = small_context_output_token_cap(
+        context_window,
+        positive_int=positive_int,
+    )
+    if not cap:
+        return []
+    if policy.settings_strategy == "ollama":
+        options = config.setdefault("ollama_options", {})
+        current = positive_int(options.get("num_predict")) or positive_int(
+            config.get("max_output_tokens")
+        )
+        if current and current > cap:
+            options["num_predict"] = cap
+            config["max_output_tokens"] = cap
+            return [_output_cap_message(cap, context_window, format_context)]
+    elif policy.settings_strategy == "standard":
+        current = positive_int(config.get("max_output_tokens"))
+        if current and current > cap:
+            config["max_output_tokens"] = cap
+            return [_output_cap_message(cap, context_window, format_context)]
+    return []
+
+
+def _output_cap_message(
+    cap: int,
+    context_window: int | None,
+    format_context: Callable[[int | None], str],
+) -> str:
+    return (
+        f"Max output capped to {cap:,} tokens for context "
+        f"{format_context(context_window)}."
+    )
+
+
+def infer_context_preset(
+    config: dict[str, Any],
+    policy: ProviderContextPolicy,
+    services: ContextPresetServices,
+) -> str | None:
+    positive_int = services.positive_int
+    if policy.settings_strategy == "managed" and not policy.managed_preset_inference:
+        return None
+    if policy.settings_strategy == "ollama":
+        options = services.ollama_options(config)
+        output = positive_int(options.get("num_predict")) or 0
+        fixed_context = positive_int(config.get("num_ctx")) or 0
+        minimum = positive_int(config.get("num_ctx_min")) or 0
+        context = positive_int(config.get("num_ctx_max")) or 0
+        if services.ollama_thinking_enabled(str(config.get("current_model") or ""), config):
+            return "reasoning"
+    else:
+        output = positive_int(config.get("max_output_tokens")) or 0
+        fixed_context = 0
+        minimum = 0
+        context = positive_int(config.get("context_window")) or 0
+        if bool(config.get("think", False)):
+            return "reasoning"
+    if context >= 1_000_000:
+        return "million-context-1m"
+    if context >= 524288:
+        return "long-context-512k"
+    if context >= 307200:
+        return "long-context-300k"
+    if context >= 262144:
+        return "long-context-256k"
+    if context >= 131072 and output >= 8192:
+        return "long-context-128k"
+    if output >= 8192:
+        return "large-output"
+    if minimum >= 65536 or context >= 65536:
+        return "long-context-65k"
+    if fixed_context and fixed_context <= 32768 and output and output <= 2048:
+        return "fast"
+    if policy.settings_strategy != "ollama" and output and output <= 2048:
+        return "fast"
+    return None
+
+
+def classify_model_family(
+    config: dict[str, Any],
+    policy: ProviderContextPolicy,
+    capacity: int | None,
+    services: ContextPresetServices,
+) -> str:
+    model = str(config.get("current_model") or "").lower()
+    if any(marker in model for marker in ("coder", "codegemma", "starcoder", "devstral")):
+        return "coding"
+    if any(marker in model for marker in ("reason", "thinking", "r1", "qwq")):
+        return "reasoning"
+    if policy.context_family_before_size_markers:
+        return _context_family(capacity)
+    if any(marker in model for marker in ("1m", "v4-pro", "million")):
+        return "million-context"
+    if any(marker in model for marker in ("70b", "120b", "253b", "405b", "480b", "large", "ultra", "pro")):
+        return "large"
+    if policy.settings_strategy == "standard":
+        return _context_family(capacity)
+    if policy.settings_strategy == "ollama":
+        context = (
+            services.positive_int(config.get("num_ctx_max"))
+            or services.positive_int(config.get("num_ctx"))
+        )
+        return _context_family(context)
+    return "general"
+
+
+def recommended_preset(family: str, capacity: int | None) -> str:
+    if family in {"reasoning", "coding"}:
+        return family
+    if family == "million-context":
+        return "million-context-1m"
+    if family == "long-context":
+        if capacity and capacity >= 524288:
+            return "long-context-512k"
+        if capacity and capacity >= 307200:
+            return "long-context-300k"
+        if capacity and capacity >= 262144:
+            return "long-context-256k"
+        if capacity and capacity >= 131072:
+            return "long-context-128k"
+        return "long-context-65k"
+    return "balanced"
+
+
+def required_context_for_preset(preset_id: str, policy: ProviderContextPolicy) -> int | None:
+    profile = policy.preset_context_profile
+    if preset_id == "million-context-1m":
+        return 1_000_000
+    if preset_id == "humanities-researcher":
+        return 524288 if profile == "ollama" else 262144
+    if preset_id in {"novelist", "mathematician", "product-architect"}:
+        return 262144
+    if preset_id == "teacher":
+        return 131072
+    if preset_id == "reasoning":
+        return 262144 if profile == "nvidia" else 131072
+    if preset_id == "large-output":
+        if profile == "nvidia":
+            return 262144
+        return 131072 if profile == "ollama" else 65536
+    return {
+        "long-context-512k": 524288,
+        "long-context-300k": 307200,
+        "long-context-256k": 262144,
+        "long-context-128k": 131072,
+        "long-context-65k": 131072 if profile == "nvidia" else 65536,
+    }.get(preset_id)
+
+
+def _context_family(capacity: int | None) -> str:
+    if capacity and capacity >= 1_000_000:
+        return "million-context"
+    if capacity and capacity >= 65536:
+        return "long-context"
+    return "general"
+
+
+__all__ = [
+    "ContextPresetServices",
+    "ProviderContextServices",
+    "cap_context_settings",
+    "cap_output_settings",
+    "cap_output_tokens",
+    "infer_context_preset",
+    "classify_model_family",
+    "recommended_preset",
+    "required_context_for_preset",
+    "resolve_context_capacity",
+    "small_context_output_token_cap",
+]

package/ciel_runtime_support/provider_contract_projection.py

@@ -0,0 +1,73 @@
+"""Provider-neutral projection of registered adapter contracts."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .architecture import (
+    ProviderAdapter,
+    ProviderConfig,
+    ProviderConfigurationPolicy,
+    ProviderContextPolicy,
+    ProviderModelCatalogPolicy,
+    ProviderRequestPolicy,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderContractProjectionApi:
+    """Project provider contracts without provider-name dispatch in the facade."""
+
+    adapter: Callable[[str, dict[str, Any]], ProviderAdapter]
+    contract: Callable[[str, dict[str, Any]], ProviderConfig]
+    request_base: Callable[[str, dict[str, Any]], str]
+    join_url: Callable[[str, str], str]
+
+    def _parts(self, provider: str, pcfg: dict[str, Any]) -> tuple[ProviderAdapter, ProviderConfig]:
+        return self.adapter(provider, pcfg), self.contract(provider, pcfg)
+
+    def endpoint(self, provider: str, pcfg: dict[str, Any], operation: str) -> str:
+        adapter, contract = self._parts(provider, pcfg)
+        return self.join_url(self.request_base(provider, pcfg), adapter.resolve_endpoint(operation, contract))
+
+    def model_paths(self, provider: str, pcfg: dict[str, Any]) -> tuple[str, ...]:
+        adapter, contract = self._parts(provider, pcfg)
+        return adapter.model_paths(contract)
+
+    def request_policy(self, provider: str, pcfg: dict[str, Any]) -> ProviderRequestPolicy:
+        adapter, contract = self._parts(provider, pcfg)
+        return adapter.request_policy(contract)
+
+    def model_catalog_policy(self, provider: str, pcfg: dict[str, Any]) -> ProviderModelCatalogPolicy:
+        adapter, contract = self._parts(provider, pcfg)
+        return adapter.model_catalog_policy(contract)
+
+    def preserves_anthropic_thinking_contract(self, provider: str, pcfg: dict[str, Any]) -> bool:
+        adapter, contract = self._parts(provider, pcfg)
+        return adapter.preserves_anthropic_thinking(contract)
+
+    def context_compaction_available(self, provider: str, pcfg: dict[str, Any]) -> bool:
+        adapter, contract = self._parts(provider, pcfg)
+        return adapter.context_compaction_available(contract)
+
+    def context_policy(self, provider: str, pcfg: dict[str, Any]) -> ProviderContextPolicy:
+        adapter, contract = self._parts(provider, pcfg)
+        return adapter.context_policy(contract)
+
+    def configuration_policy(self, provider: str, pcfg: dict[str, Any]) -> ProviderConfigurationPolicy:
+        adapter, contract = self._parts(provider, pcfg)
+        return adapter.configuration_policy(contract)
+
+    def model_panel_badge(self, provider: str, pcfg: dict[str, Any], model: str) -> str:
+        adapter, contract = self._parts(provider, pcfg)
+        return adapter.model_panel_badge(contract, model)
+
+    def advisor_panel_notice(self, provider: str, pcfg: dict[str, Any]) -> tuple[tuple[str, ...], tuple[str, ...]] | None:
+        adapter, contract = self._parts(provider, pcfg)
+        return adapter.advisor_panel_notice(contract)
+
+    def advisor_model_badge(self, provider: str, pcfg: dict[str, Any], model: str) -> str:
+        adapter, contract = self._parts(provider, pcfg)
+        return adapter.advisor_model_badge(contract, model)

package/ciel_runtime_support/provider_descriptor.py

@@ -0,0 +1,82 @@
+"""Data-driven provider registration descriptors.
+
+Descriptors contain discovery metadata and adapter construction only. Runtime
+behavior remains in concrete adapters, so complex providers can use specialized
+implementations without growing a central conditional router.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from collections.abc import Callable
+from typing import Any
+
+from ciel_runtime_support.architecture import ProviderAdapter
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderDescriptor:
+    """Stable provider identity and its concrete adapter factory type."""
+
+    name: str
+    label: str
+    adapter_type: Callable[..., ProviderAdapter]
+    aliases: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.normalized_name:
+            raise ValueError("provider descriptor name cannot be empty")
+        if not self.label.strip():
+            raise ValueError(f"provider descriptor label cannot be empty: {self.name}")
+
+    @property
+    def normalized_name(self) -> str:
+        return normalize_provider_name(self.name)
+
+    def create(self, **kwargs: Any) -> ProviderAdapter:
+        base_url = str(kwargs.get("base_url") or "").strip()
+        return self.adapter_type(**({"base_url": base_url} if base_url else {}))
+
+
+def normalize_provider_name(name: str) -> str:
+    return str(name or "").strip().lower().replace("_", "-")
+
+
+class ProviderDescriptorRegistry:
+    """Read-only discovery index with normalized alias lookup."""
+
+    def __init__(self, descriptors: tuple[ProviderDescriptor, ...]) -> None:
+        self._descriptors: dict[str, ProviderDescriptor] = {}
+        self._canonical: dict[str, ProviderDescriptor] = {}
+        for descriptor in descriptors:
+            name = descriptor.normalized_name
+            if name in self._canonical:
+                raise ValueError(f"provider descriptor already registered: {name}")
+            self._canonical[name] = descriptor
+            for candidate in (name, *descriptor.aliases):
+                key = normalize_provider_name(candidate)
+                if not key:
+                    raise ValueError(f"provider alias cannot be empty: {name}")
+                if key in self._descriptors:
+                    raise ValueError(f"provider descriptor alias already registered: {key}")
+                self._descriptors[key] = descriptor
+
+    def get(self, name: str) -> ProviderDescriptor:
+        try:
+            return self._descriptors[normalize_provider_name(name)]
+        except KeyError as exc:
+            raise KeyError(f"unknown provider descriptor: {name}") from exc
+
+    def descriptors(self) -> tuple[ProviderDescriptor, ...]:
+        return tuple(self._canonical[name] for name in sorted(self._canonical))
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(sorted(self._canonical))
+
+    def aliases(self) -> dict[str, str]:
+        """Project every registered lookup token to its canonical provider name."""
+
+        return {
+            alias: descriptor.normalized_name
+            for alias, descriptor in self._descriptors.items()
+        }

package/ciel_runtime_support/provider_endpoint_policy.py

@@ -0,0 +1,130 @@
+"""Provider protocol endpoint override and presentation policy."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from ciel_runtime_support.runtime_constants import OPENCODE_ENDPOINT_ALIASES
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderEndpointPorts:
+    normalize_model_id: Callable[[str, str], str]
+    strip_context_suffix: Callable[[str], str]
+    alias_for: Callable[[str, str], str]
+    select_protocol: Callable[[str, dict[str, Any], str], str]
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderEndpointPresentation:
+    aliases: Mapping[str, str]
+    labels: Mapping[str, str]
+    routed_protocols: frozenset[str]
+
+
+def build_default_provider_endpoint_policy(
+    ports: ProviderEndpointPorts,
+) -> ProviderEndpointPolicy:
+    """Compose endpoint behavior with the runtime's standard presentation."""
+    return ProviderEndpointPolicy(
+        ports=ports,
+        presentation=ProviderEndpointPresentation(
+            aliases=OPENCODE_ENDPOINT_ALIASES,
+            labels={
+                "anthropic-messages": "messages",
+                "openai-chat": "chat",
+                "openai-responses": "responses",
+                "google-generative": "gemini",
+            },
+            routed_protocols=frozenset(
+                {"anthropic-messages", "openai-chat", "openai-responses"}
+            ),
+        ),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderEndpointPolicy:
+    ports: ProviderEndpointPorts
+    presentation: ProviderEndpointPresentation
+
+    def normalize_endpoint_kind(self, value: Any) -> str | None:
+        key = str(value or "").strip().lower().replace("_", "-")
+        return self.presentation.aliases.get(key)
+
+    def endpoint_override(
+        self,
+        provider: str,
+        model_id: str,
+        provider_config: dict[str, Any] | None = None,
+    ) -> str | None:
+        if not provider_config:
+            return None
+        overrides = provider_config.get("model_endpoints")
+        if not isinstance(overrides, dict):
+            return None
+        normalized = self.ports.normalize_model_id(provider, model_id)
+        candidates = (
+            model_id,
+            normalized,
+            self.ports.strip_context_suffix(model_id),
+            self.ports.alias_for(provider, normalized),
+        )
+        for candidate in candidates:
+            endpoint = self.normalize_endpoint_kind(overrides.get(candidate))
+            if endpoint:
+                return endpoint
+        return None
+
+    def endpoint_kind(
+        self,
+        provider: str,
+        model_id: str,
+        provider_config: dict[str, Any] | None = None,
+    ) -> str:
+        override = self.endpoint_override(provider, model_id, provider_config)
+        if override:
+            return override
+        config = provider_config or {}
+        protocol = self.ports.select_protocol(
+            provider,
+            config,
+            model_id,
+        )
+        return str(protocol).replace("_", "-")
+
+    def model_supported(
+        self,
+        provider: str,
+        model_id: str,
+        provider_config: dict[str, Any] | None = None,
+    ) -> bool:
+        return (
+            self.endpoint_kind(provider, model_id, provider_config)
+            in self.presentation.routed_protocols
+        )
+
+    def endpoint_display(
+        self,
+        provider: str,
+        model_id: str,
+        provider_config: dict[str, Any] | None = None,
+    ) -> str:
+        endpoint = self.endpoint_kind(provider, model_id, provider_config)
+        text = self.presentation.labels.get(endpoint, endpoint)
+        if endpoint not in self.presentation.routed_protocols:
+            text += " unsupported"
+        if self.endpoint_override(provider, model_id, provider_config):
+            text += " override"
+        return text
+
+    def zen_endpoint_kind(self, model_id: str) -> str:
+        return self.endpoint_kind("opencode", model_id)
+
+    def zen_model_supported(self, model_id: str) -> bool:
+        return self.model_supported("opencode", model_id)
+
+    def go_endpoint_kind(self, model_id: str) -> str:
+        return self.endpoint_kind("opencode-go", model_id)