@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/api_key_cooldown.py

@@ -0,0 +1,159 @@
+"""Per-credential rate-limit cooldown policy and application service."""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from . import rate_limit_policy
+from .rate_limit_repository import RateLimitRepository
+
+
+RATE_LIMIT_RESET_HEADER_NAMES = (
+    "x-ratelimit-reset-requests",
+    "x-rate-limit-reset-requests",
+    "ratelimit-reset",
+    "rate-limit-reset",
+    "x-ratelimit-reset",
+    "x-rate-limit-reset",
+)
+API_KEY_COOLDOWN_MAX_SECONDS = 90_000.0
+API_KEY_COOLDOWN_DEFAULT_SECONDS = 60.0
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyCooldownPorts:
+    repository: RateLimitRepository
+    rotation_name: Callable[[str, dict[str, Any]], str]
+    config_keys: Callable[[str, dict[str, Any]], list[str]]
+    meaningful_key: Callable[[str], bool]
+    log: Callable[[str, str], None]
+    now: Callable[[], float] = time.time
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyCooldownService:
+    ports: ApiKeyCooldownPorts
+
+    def state_key(self, provider: str, config: dict[str, Any], key: str) -> str:
+        digest = hashlib.sha256(str(key).encode("utf-8")).hexdigest()[:12]
+        return f"{self.ports.rotation_name(provider, config)}:__key__:{digest}"
+
+    @staticmethod
+    def reset_seconds(headers: Any) -> float:
+        reset = rate_limit_policy.reset_seconds(
+            rate_limit_policy.first_header(headers, list(RATE_LIMIT_RESET_HEADER_NAMES))
+        )
+        if reset is None or reset <= 0:
+            reset = rate_limit_policy.retry_after_seconds(
+                rate_limit_policy.first_header(headers, ["Retry-After", "retry-after"])
+            )
+        if reset is None or reset <= 0:
+            reset = API_KEY_COOLDOWN_DEFAULT_SECONDS
+        return max(1.0, min(float(reset), API_KEY_COOLDOWN_MAX_SECONDS))
+
+    def register(
+        self,
+        provider: str,
+        config: dict[str, Any],
+        key: str,
+        headers: Any,
+    ) -> float:
+        if not self.ports.meaningful_key(key):
+            return 0.0
+        reset = self.reset_seconds(headers)
+        state_key = self.state_key(provider, config, key)
+        self.ports.repository.register_cooldown(state_key, reset)
+        self.ports.log(
+            "WARN",
+            f"api_key_cooldown provider={provider} "
+            f"key_hash={state_key.rsplit(':', 1)[-1]} rest={reset:.0f}s",
+        )
+        return reset
+
+    def cooldown_until(self, provider: str, config: dict[str, Any], key: str) -> float:
+        if not self.ports.meaningful_key(key):
+            return 0.0
+        return self.ports.repository.cooldown_until(self.state_key(provider, config, key))
+
+    def live_key_count(self, provider: str, config: dict[str, Any]) -> int:
+        keys = self.ports.config_keys(provider, config)
+        if len(keys) <= 1:
+            return len(keys)
+        now = self.ports.now()
+        return sum(1 for key in keys if self.cooldown_until(provider, config, key) <= now)
+
+    def has_live_key(self, provider: str, config: dict[str, Any]) -> bool:
+        return self.live_key_count(provider, config) > 0
+
+    def reset_for_router_start(self) -> int:
+        removed = self.ports.repository.reset_key_cooldowns()
+        if removed:
+            self.ports.log(
+                "INFO",
+                f"api_key_cooldown_reset_on_router_start removed={removed}",
+            )
+        return removed
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyCooldownCompatibilityApi:
+    """Explicit facade surface that resolves the current repository per call."""
+
+    service_factory: Callable[[], ApiKeyCooldownService]
+
+    def state_key(self, provider: str, config: dict[str, Any], key: str) -> str:
+        return self.service_factory().state_key(provider, config, key)
+
+    @staticmethod
+    def reset_seconds(headers: Any) -> float:
+        return ApiKeyCooldownService.reset_seconds(headers)
+
+    def register(
+        self,
+        provider: str,
+        config: dict[str, Any],
+        key: str,
+        headers: Any,
+    ) -> float:
+        return self.service_factory().register(provider, config, key, headers)
+
+    def cooldown_until(
+        self, provider: str, config: dict[str, Any], key: str
+    ) -> float:
+        return self.service_factory().cooldown_until(provider, config, key)
+
+    def live_key_count(self, provider: str, config: dict[str, Any]) -> int:
+        return self.service_factory().live_key_count(provider, config)
+
+    def has_live_key(self, provider: str, config: dict[str, Any]) -> bool:
+        return self.service_factory().has_live_key(provider, config)
+
+    def reset_for_router_start(self) -> int:
+        return self.service_factory().reset_for_router_start()
+
+    @staticmethod
+    def retry_after_exceeds_request_timeout(
+        headers: Any, timeout: float
+    ) -> tuple[bool, float | None]:
+        retry_after = rate_limit_policy.first_header(
+            headers, ["Retry-After", "retry-after"]
+        )
+        seconds = rate_limit_policy.retry_after_seconds(retry_after)
+        if seconds is None:
+            return False, None
+        threshold = max(1.0, float(timeout) - 1.0)
+        return seconds >= threshold, seconds
+
+
+__all__ = [
+    "API_KEY_COOLDOWN_DEFAULT_SECONDS",
+    "API_KEY_COOLDOWN_MAX_SECONDS",
+    "ApiKeyCooldownCompatibilityApi",
+    "ApiKeyCooldownPorts",
+    "ApiKeyCooldownService",
+    "RATE_LIMIT_RESET_HEADER_NAMES",
+]

package/ciel_runtime_support/architecture.py

@@ -19,11 +19,18 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from pathlib import Path
+import re
 from typing import Any, Literal, Mapping, Sequence
 
 
 LaunchMode = Literal["native", "routed", "router"]
-MessageProtocol = Literal["anthropic_messages", "openai_chat", "openai_responses"]
+MessageProtocol = Literal[
+    "anthropic_messages",
+    "openai_chat",
+    "openai_responses",
+    "ollama_chat",
+    "google_generative",
+]
 
 
 @dataclass(frozen=True)
@@ -100,6 +107,132 @@ class RateLimitState:
     detail: str | None = None
 
 
+@dataclass(frozen=True)
+class ProviderCapabilities:
+    """Provider-owned features that affect routing without naming providers."""
+
+    upstream_protocol: MessageProtocol = "openai_chat"
+    supports_streaming: bool = True
+    supports_tools: bool = True
+    supports_tool_choice: bool = True
+    supports_thinking: bool = False
+    preserves_anthropic_thinking: bool = False
+    requires_api_key: bool = False
+    local: bool = False
+    blocks_default_tools: bool = True
+    repairs_anthropic_tool_input: bool = False
+
+    @property
+    def supported_protocols(self) -> frozenset[MessageProtocol]:
+        return frozenset({self.upstream_protocol})
+
+
+@dataclass(frozen=True)
+class ProviderRequestPolicy:
+    """Provider-owned endpoint and transport defaults."""
+
+    chat_path: str
+    models_path: str
+    model_info_path: str | None = None
+    default_timeout_seconds: float = 60.0
+    model_alias_strategy: Literal["identity", "ncp"] = "identity"
+    credential_strategy: Literal["adapter", "anthropic_inbound"] = "adapter"
+    stream_required: bool = False
+    normalize_historical_tool_turns: bool = True
+    managed_service: Literal["none", "nvidia_proxy"] = "none"
+    probe_strategy: Literal["anthropic", "ollama", "opencode"] = "anthropic"
+
+
+@dataclass(frozen=True)
+class ProviderModelCatalogPolicy:
+    """Select a reusable model-catalog strategy without provider-name branching."""
+
+    kind: Literal["configured", "anthropic", "openai", "ollama", "lm_studio", "nvidia", "fireworks"] = "openai"
+    fallback_models: tuple[str, ...] = ()
+    allow_configured_fallback: bool = False
+    allow_public_without_auth: bool = False
+    use_bundled_catalog_fallback: bool = False
+
+
+@dataclass(frozen=True)
+class ProviderConfigurationPolicy:
+    """Provider-owned configuration mutation capabilities."""
+
+    mutation_strategy: Literal["common", "ollama"] = "common"
+    supports_route_through_router: bool = False
+    supports_model_endpoint_overrides: bool = False
+    native_compat_error: str | None = None
+    text_option_aliases: Mapping[str, str] = field(default_factory=dict)
+    strip_trailing_slash_fields: frozenset[str] = frozenset()
+    status_fields: tuple[str, ...] = ()
+    uses_ollama_status: bool = False
+    runtime_owns_model: bool = False
+    restricts_runtime_options: bool = False
+
+
+@dataclass(frozen=True)
+class ProviderStatusPolicy:
+    """Provider-owned base URL status projection strategy."""
+
+    kind: Literal["generic", "native_codex", "native_agy", "nvidia", "configured", "catalog"] = "generic"
+    label: str = ""
+    configured_description: str = ""
+    catalog_path: str = ""
+    catalog_count_key: Literal["data", "models"] = "data"
+    catalog_scope: Literal["configured", "fireworks_management"] = "configured"
+    catalog_count_label: str = "models"
+    unreachable_hint: str = "Set a reachable Base URL before launching Claude Code."
+    readiness_validation: Literal["none", "lm_studio"] = "none"
+
+
+@dataclass(frozen=True)
+class ProviderContextPolicy:
+    """Provider-owned context capacity and configuration strategy."""
+
+    capacity_strategy: Literal[
+        "managed", "nvidia", "remote_first", "hint_first", "configured_first", "ollama", "hint_configured", "anthropic_hint"
+    ] = "managed"
+    settings_strategy: Literal["managed", "ollama", "standard"] = "managed"
+    hosted_timeout: bool = False
+    timeout_weight: float = 1.0
+    uses_catalog_timeout: bool = False
+    managed_preset_inference: bool = False
+    context_family_before_size_markers: bool = False
+    preset_context_profile: Literal["default", "ollama", "nvidia"] = "default"
+    status_capacity_strategy: Literal[
+        "configured", "ollama_budget", "openai_budget", "provider"
+    ] = "configured"
+
+
+@dataclass(frozen=True)
+class ProviderOptionPresentationPolicy:
+    """Provider-owned option status capabilities."""
+
+    show_rate_limit: bool = False
+    show_native: bool = False
+    show_route: bool = False
+    show_tool_choice: bool = False
+    show_sampling: bool = False
+    show_stream: bool = False
+    show_ip_family: bool = False
+    show_rate_limit_controls: bool = False
+    show_sampling_controls: bool = False
+    show_ip_family_control: bool = False
+
+
+@dataclass(frozen=True)
+class ProviderUiPolicy:
+    """Provider-owned labels used by shared menus."""
+
+    menu_label: str = ""
+    routed_menu_label: str = ""
+    native_choice: str = ""
+    routed_choice: str = ""
+    model_placeholder: str = ""
+    advisor_placeholder: str = ""
+    uses_native_advisor: bool = False
+
+
 class RuntimeAdapter(ABC):
     """Adapter for a local/interactive coding runtime.
 
@@ -136,6 +269,22 @@ class ProviderAdapter(ABC):
     def default_base_url(self) -> str:
         """Return the provider default API base URL."""
 
+    def normalize_base_url(self, value: str) -> str:
+        """Normalize a user-supplied endpoint before it is persisted."""
+
+        return str(value or "").rstrip("/")
+
+    def default_configuration(self) -> Mapping[str, Any]:
+        """Return the minimal persisted configuration for a newly registered provider."""
+
+        return {
+            "base_url": self.default_base_url(),
+            "api_key": "",
+            "current_model": "",
+            "advisor_model": "",
+            "custom_models": [],
+        }
+
     @abstractmethod
     def list_models(self, config: ProviderConfig) -> Sequence[ModelInfo]:
         """Return known models for this provider."""
@@ -149,6 +298,343 @@ class ProviderAdapter(ABC):
 
         return None
 
+    def capabilities(self, config: ProviderConfig) -> ProviderCapabilities:
+        """Return routing capabilities for this configured provider."""
+
+        del config
+        return ProviderCapabilities()
+
+    def request_policy(self, config: ProviderConfig) -> ProviderRequestPolicy:
+        """Return endpoint and transport defaults for this provider."""
+
+        del config
+        return ProviderRequestPolicy(chat_path="/v1/chat/completions", models_path="/v1/models")
+
+    def resolve_endpoint(self, operation: str, config: ProviderConfig) -> str:
+        """Resolve a provider operation to a path without exposing provider conditionals."""
+
+        policy = self.request_policy(config)
+        paths = {
+            "chat": policy.chat_path,
+            "models": policy.models_path,
+            "model_info": policy.model_info_path,
+            "anthropic_messages": "/v1/messages",
+            "openai_chat": "/v1/chat/completions",
+            "openai_responses": "/v1/responses",
+            "ollama_chat": "/api/chat",
+        }
+        path = paths.get(operation)
+        if not path:
+            raise KeyError(f"{self.name} does not support provider operation: {operation}")
+        return path
+
+    def build_model_headers(self, config: ProviderConfig, api_key: str | None) -> Mapping[str, str]:
+        """Build headers for model discovery; providers may override request auth."""
+
+        return self.build_headers(config, api_key)
+
+    def model_paths(self, config: ProviderConfig) -> tuple[str, ...]:
+        """Return model discovery paths in provider-preferred fallback order."""
+
+        primary = self.request_policy(config).models_path
+        return (primary,) if primary == "/models" else (primary, "/models")
+
+    def supported_protocols(self, config: ProviderConfig, model: str | None = None) -> frozenset[MessageProtocol]:
+        """Return protocols this provider can use for the selected model."""
+
+        del model
+        return self.capabilities(config).supported_protocols
+
+    def select_protocol(
+        self,
+        operation: MessageProtocol,
+        config: ProviderConfig,
+        model: str | None = None,
+    ) -> MessageProtocol:
+        """Choose the upstream protocol for an inbound protocol operation."""
+
+        supported = self.supported_protocols(config, model)
+        if operation in supported:
+            return operation
+        return self.capabilities(config).upstream_protocol
+
+    def supports_tool_choice(self, config: ProviderConfig, model: str | None = None) -> bool:
+        configured = config.options.get("supports_tool_choice")
+        if configured is not None:
+            return bool(configured)
+        del model
+        return self.capabilities(config).supports_tool_choice
+
+    def normalizes_anthropic_tool_use(
+        self,
+        config: ProviderConfig,
+    ) -> bool:
+        configured = config.options.get("normalize_anthropic_tool_use")
+        if configured is not None:
+            return bool(configured)
+        capabilities = self.capabilities(config)
+        return (
+            capabilities.upstream_protocol != "anthropic_messages"
+            and not capabilities.preserves_anthropic_thinking
+        )
+
+    def preserves_anthropic_thinking(self, config: ProviderConfig) -> bool:
+        configured = config.options.get("preserve_anthropic_thinking")
+        if configured is not None:
+            return bool(configured)
+        return self.capabilities(config).preserves_anthropic_thinking
+
+    def openai_reasoning_passback_enabled(
+        self, config: ProviderConfig, model: str | None = None
+    ) -> bool:
+        """Whether OpenAI reasoning_content should survive history conversion."""
+
+        del config, model
+        return False
+
+    def model_catalog_policy(self, config: ProviderConfig) -> ProviderModelCatalogPolicy:
+        del config
+        return ProviderModelCatalogPolicy()
+
+    def project_model_metadata(self, raw: Mapping[str, Any]) -> Mapping[str, Any]:
+        """Project provider response fields into the shared model metadata shape."""
+
+        return {
+            key: raw[key]
+            for key in ("owned_by", "root", "object")
+            if raw.get(key) is not None
+        }
+
+    def project_router_model_metadata(
+        self, config: ProviderConfig, model_id: str
+    ) -> Mapping[str, Any]:
+        """Project provider-specific metadata exposed by the router model catalog."""
+
+        del config, model_id
+        return {}
+
+    def normalize_model_id(self, model_id: str) -> str:
+        """Normalize a configured/catalog model id for shared runtime use."""
+
+        text = str(model_id or "").strip()
+        return re.sub(r"\[(?:1m)\]\s*$", "", text, flags=re.IGNORECASE).strip()
+
+    def upstream_api_model_id(self, model_id: str) -> str:
+        """Return the provider's wire-level model id."""
+
+        return str(model_id or "").strip()
+
+    def preserves_claude_model_alias(self, model_id: str) -> bool:
+        """Whether an already Claude-facing model id must remain unchanged."""
+
+        del model_id
+        return False
+
+    def display_model_name(self, model_id: str, provider_label: str) -> str:
+        """Project a provider model id into the shared human-readable label."""
+
+        cleaned = str(model_id).replace("/", " ").replace("-", " ").replace("_", " ")
+        return (
+            f"{provider_label.replace('-', ' ')} {cleaned}"
+            .title()
+            .replace("Vllm", "vLLM")
+            .replace("Nvidia", "Nvidia")
+        )
+
+    def launch_model_strategy(self, config: ProviderConfig) -> str:
+        """Return the provider-owned launch alias strategy."""
+
+        del config
+        return "alias"
+
+    def requires_catalog_model_selection(self, config: ProviderConfig) -> bool:
+        """Whether placeholder model ids must be replaced from provider discovery."""
+
+        del config
+        return False
+
+    def placeholder_model_ids(self) -> frozenset[str]:
+        """Return non-routable placeholder model ids accepted in configuration."""
+
+        return frozenset({"", "model"})
+
+    def routing_mode_update(self, enabled: bool) -> tuple[str, ...]:
+        """Describe a persisted route-through-router mode change."""
+
+        state = "routed through ciel-runtime router" if enabled else "direct provider mode"
+        return ("Provider routing mode updated.", f"mode: {state}")
+
+    def selection_config_updates(self, config: ProviderConfig) -> Mapping[str, Any]:
+        """Return provider-owned defaults applied when this provider is selected."""
+
+        del config
+        return {}
+
+    def selection_update_status_lines(
+        self, config: ProviderConfig, updates: Mapping[str, Any]
+    ) -> tuple[str, ...]:
+        """Describe provider-owned normalization performed during selection."""
+
+        del config, updates
+        return ()
+
+    def model_selection_config_updates(
+        self, config: ProviderConfig, model_id: str
+    ) -> Mapping[str, Any]:
+        """Return provider-owned config updates for an explicit model choice."""
+
+        del config, model_id
+        return {}
+
+    def selection_status_lines(self, config: ProviderConfig) -> tuple[str, ...]:
+        """Return provider-owned status details after selection."""
+
+        del config
+        return ()
+
+    def configuration_policy(self, config: ProviderConfig) -> ProviderConfigurationPolicy:
+        """Return provider-owned option mutation behavior."""
+
+        del config
+        return ProviderConfigurationPolicy()
+
+    def status_policy(self, config: ProviderConfig) -> ProviderStatusPolicy:
+        """Return provider-owned base URL status behavior."""
+
+        request = self.request_policy(config)
+        count_key = "models" if request.models_path == "/api/tags" else "data"
+        return ProviderStatusPolicy(catalog_path=request.models_path, catalog_count_key=count_key)
+
+    def context_policy(self, config: ProviderConfig) -> ProviderContextPolicy:
+        """Return provider-owned context capacity and mutation behavior."""
+
+        del config
+        return ProviderContextPolicy()
+
+    def option_presentation_policy(self, config: ProviderConfig) -> ProviderOptionPresentationPolicy:
+        del config
+        return ProviderOptionPresentationPolicy()
+
+    def ui_policy(self, config: ProviderConfig) -> ProviderUiPolicy:
+        """Return provider-owned presentation and runtime compatibility metadata."""
+
+        del config
+        return ProviderUiPolicy(menu_label=self.name)
+
+    def shows_claude_workflow_options(self, config: ProviderConfig) -> bool:
+        del config
+        return True
+
+    def intercepts_advisor_shortcut(self, config: ProviderConfig) -> bool:
+        """Whether the router should handle /advisor instead of the native runtime."""
+
+        del config
+        return True
+
+    def option_timeout_default(self) -> str:
+        return "default"
+
+    def model_configuration_profile(
+        self, config: ProviderConfig
+    ) -> tuple[Mapping[str, Any], str | None]:
+        """Return provider/model-specific configuration updates and an optional notice."""
+
+        del config
+        return {}, None
+
+    def propagates_inbound_beta_query(self, config: ProviderConfig) -> bool:
+        """Whether an inbound Claude beta query should be forwarded upstream."""
+
+        del config
+        return False
+
+    def api_key_display_name(self) -> str:
+        """Return the provider-owned name used in API-key status text."""
+
+        return self.name
+
+    def api_key_status(self, config: ProviderConfig, *, key_count: int, primary_detail: str) -> str:
+        """Format API-key readiness without central provider-name branching."""
+
+        scope = self.api_key_display_name()
+        round_robin = f"{key_count} keys, round-robin"
+        if key_count > 1:
+            detail = f"{scope}{primary_detail}" if scope else primary_detail.lstrip("; ")
+            return f"API keys: {round_robin} ({detail})"
+        if key_count:
+            detail = f"{scope}{primary_detail}" if scope else primary_detail.lstrip("; ")
+            return f"API key: set ({detail})"
+        if self.capabilities(config).requires_api_key:
+            return f"API key: missing ({scope} required)"
+        if self.capabilities(config).local:
+            return f"API key: not required for {scope}"
+        return "API key: optional or not configured"
+
+    def launch_api_key_error(self, config: ProviderConfig) -> str | None:
+        """Return a launch blocker when this provider requires an absent key."""
+
+        if self.capabilities(config).requires_api_key and not config.api_keys:
+            return f"Launch blocked: {self.api_key_display_name()} requires an API key."
+        return None
+
+    def model_panel_badge(self, config: ProviderConfig, model: str) -> str:
+        """Return an optional provider-owned model label for selection UIs."""
+
+        del config, model
+        return ""
+
+    def supports_server_advisor_tool(self, config: ProviderConfig) -> bool:
+        """Whether the upstream executes Claude's server-side advisor tool."""
+
+        del config
+        return False
+
+    def context_compaction_available(self, config: ProviderConfig) -> bool:
+        """Whether this configured provider can run an auxiliary summary request."""
+
+        del config
+        return True
+
+    def router_native_anthropic_enabled(self, config: ProviderConfig, model: str | None = None) -> bool:
+        """Whether the generic router may send Anthropic Messages directly upstream."""
+
+        del config, model
+        return False
+
+    def advisor_panel_notice(self, config: ProviderConfig) -> tuple[tuple[str, ...], tuple[str, ...]] | None:
+        """Return a provider-owned advisor panel replacement, when applicable."""
+
+        del config
+        return None
+
+    def advisor_model_badge(self, config: ProviderConfig, model: str) -> str:
+        """Return an optional provider-owned advisor model annotation."""
+
+        del config, model
+        return ""
+
+    def normalize_request_options(self, config: ProviderConfig, request: Mapping[str, Any]) -> Mapping[str, Any]:
+        del config
+        return request
+
+    def openai_reasoning_effort(
+        self, config: ProviderConfig, model: str, request: Mapping[str, Any]
+    ) -> str | None:
+        """Return a provider-normalized Chat Completions reasoning effort."""
+
+        del config, model, request
+        return None
+
+    def allows_sampling_overrides(self, config: ProviderConfig) -> bool:
+        """Whether user-provided sampling controls are valid for this provider."""
+
+        del config
+        return True
+
+    def normalize_tool_choice(self, config: ProviderConfig, model: str, tool_choice: Any) -> Any:
+        del config, model
+        return tool_choice
+
 
 class MessageProtocolAdapter(ABC):
     """Adapter for upstream request/response wire formats."""
@@ -191,6 +677,7 @@ __all__ = [
     "ModelInfo",
     "ProviderAdapter",
     "ProviderConfig",
+    "ProviderUiPolicy",
     "RateLimitState",
     "RuntimeAdapter",
     "RuntimeCommand",