@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/providers/openrouter.py

@@ -0,0 +1,57 @@
+"""OpenRouter provider adapter."""
+
+from dataclasses import dataclass, field
+
+from ..architecture import ProviderCapabilities, ProviderConfig, ProviderContextPolicy
+from .base import OpenAICompatibleProviderAdapter, provider_configuration
+from .constants import DEFAULT_REQUEST_TIMEOUT_MS, PROVIDER_DEFAULT_BASE_URLS
+
+
+@dataclass(frozen=True)
+class OpenRouterProviderAdapter(OpenAICompatibleProviderAdapter):
+    name: str = "OpenRouter"
+    base_url: str = PROVIDER_DEFAULT_BASE_URLS["openrouter"]
+    configuration_defaults_value: dict = field(
+        default_factory=lambda: provider_configuration(
+            "nvidia/nemotron-3-ultra-550b-a55b:free",
+            native_compat=False,
+            rate_limit_rpm=0,
+            rate_limit_status=False,
+            context_window=262144,
+            max_output_tokens=8192,
+            temperature=0.7,
+            top_p=0.8,
+            context_reserve_tokens=1024,
+            request_timeout_ms=DEFAULT_REQUEST_TIMEOUT_MS,
+            stream_enabled=True,
+            stream_word_chunking=False,
+        )
+    )
+    authorization_header: str = "Authorization"
+    require_api_key: bool = True
+    api_key_display_name_value: str = "OpenRouter"
+    api_key_launch_error_value: str = (
+        "Launch blocked: OpenRouter requires an OpenRouter API key."
+    )
+    capabilities_value: ProviderCapabilities = field(
+        default_factory=lambda: ProviderCapabilities(
+            upstream_protocol="openai_chat", requires_api_key=True
+        )
+    )
+
+    def context_policy(self, config: ProviderConfig) -> ProviderContextPolicy:
+        del config
+        return ProviderContextPolicy(
+            capacity_strategy="configured_first",
+            settings_strategy="standard",
+            hosted_timeout=True,
+        )
+
+    def router_native_anthropic_enabled(
+        self, config: ProviderConfig, model: str | None = None
+    ) -> bool:
+        del config, model
+        return False
+
+
+__all__ = ["OpenRouterProviderAdapter"]

package/ciel_runtime_support/providers/vllm.py

@@ -0,0 +1,65 @@
+"""vLLM provider adapter."""
+
+from dataclasses import dataclass, field, replace
+
+from ..architecture import (
+    ProviderCapabilities,
+    ProviderConfig,
+    ProviderContextPolicy,
+    ProviderStatusPolicy,
+)
+from .base import OpenAICompatibleProviderAdapter, provider_configuration
+from .constants import DEFAULT_REQUEST_TIMEOUT_MS, PROVIDER_DEFAULT_BASE_URLS
+
+
+@dataclass(frozen=True)
+class VllmProviderAdapter(OpenAICompatibleProviderAdapter):
+    name: str = "vllm"
+    base_url: str = PROVIDER_DEFAULT_BASE_URLS["vllm"]
+    configuration_defaults_value: dict = field(
+        default_factory=lambda: provider_configuration(
+            "my-model",
+            api_key="dummy",
+            custom_models=("my-model",),
+            native_compat=True,
+            supports_tool_choice=False,
+            context_window=32768,
+            max_output_tokens=4096,
+            temperature=0.7,
+            top_p=0.8,
+            context_reserve_tokens=1024,
+            request_timeout_ms=DEFAULT_REQUEST_TIMEOUT_MS,
+            stream_enabled=True,
+            stream_word_chunking=False,
+        )
+    )
+    send_placeholder_key: bool = True
+    capabilities_value: ProviderCapabilities = field(
+        default_factory=lambda: ProviderCapabilities(
+            upstream_protocol="openai_chat", supports_tool_choice=False, local=True
+        )
+    )
+
+    def requires_catalog_model_selection(self, config: ProviderConfig) -> bool:
+        del config
+        return True
+
+    def placeholder_model_ids(self) -> frozenset[str]:
+        return super().placeholder_model_ids() | {"my-model"}
+
+    def context_policy(self, config: ProviderConfig) -> ProviderContextPolicy:
+        del config
+        return ProviderContextPolicy(
+            capacity_strategy="remote_first",
+            settings_strategy="standard",
+            status_capacity_strategy="openai_budget",
+        )
+
+    def status_policy(self, config: ProviderConfig) -> ProviderStatusPolicy:
+        return replace(
+            super().status_policy(config),
+            unreachable_hint="vLLM must be reachable from this machine and expose Anthropic-compatible /v1/messages.",
+        )
+
+
+__all__ = ["VllmProviderAdapter"]

package/ciel_runtime_support/providers/zai.py

@@ -0,0 +1,119 @@
+"""Z.AI provider adapter."""
+
+from dataclasses import dataclass, field
+
+from ..architecture import (
+    ProviderCapabilities,
+    ProviderConfig,
+    ProviderContextPolicy,
+    ProviderModelCatalogPolicy,
+    ProviderOptionPresentationPolicy,
+    ProviderRequestPolicy,
+    ProviderStatusPolicy,
+)
+from .base import HttpBearerProviderAdapter, provider_configuration
+from .constants import PROVIDER_DEFAULT_BASE_URLS, ZAI_MODEL_FALLBACK_IDS
+
+
+@dataclass(frozen=True)
+class ZaiProviderAdapter(HttpBearerProviderAdapter):
+    name: str = "zai"
+    base_url: str = PROVIDER_DEFAULT_BASE_URLS["zai"]
+    configuration_defaults_value: dict = field(
+        default_factory=lambda: provider_configuration(
+            "glm-5.2[1m]",
+            custom_models=ZAI_MODEL_FALLBACK_IDS,
+            native_compat=True,
+            preserve_anthropic_thinking=True,
+            claude_code_supported_capabilities=["effort", "thinking"],
+            context_window=1000000,
+            auto_compact_window=1000000,
+            max_output_tokens=8192,
+            context_reserve_tokens=8192,
+            request_timeout_ms=3000000,
+            stream_enabled=True,
+            stream_word_chunking=False,
+            effort_level="max",
+            opus_model="glm-5.2[1m]",
+            sonnet_model="glm-5.2[1m]",
+            haiku_model="glm-4.7",
+            subagent_model="glm-5.2[1m]",
+            managed_mcp=True,
+        )
+    )
+    send_placeholder_key: bool = True
+    api_key_display_name_value: str = "Z.AI GLM"
+    api_key_launch_error_value: str = (
+        "Launch blocked: Z.AI GLM requires a Z.AI API key."
+    )
+    capabilities_value: ProviderCapabilities = field(
+        default_factory=lambda: ProviderCapabilities(
+            upstream_protocol="anthropic_messages",
+            supports_thinking=True,
+            requires_api_key=True,
+        )
+    )
+    request_policy_value: ProviderRequestPolicy = field(
+        default_factory=lambda: ProviderRequestPolicy(
+            chat_path="/v1/messages", models_path="/v1/models"
+        )
+    )
+    model_catalog_policy_value: ProviderModelCatalogPolicy = field(
+        default_factory=lambda: ProviderModelCatalogPolicy(
+            kind="openai", fallback_models=ZAI_MODEL_FALLBACK_IDS
+        )
+    )
+
+    def normalize_model_id(self, model_id: str) -> str:
+        return str(model_id or "").strip()
+
+    def upstream_api_model_id(self, model_id: str) -> str:
+        return super().normalize_model_id(model_id)
+
+    def model_selection_config_updates(
+        self, config: ProviderConfig, model_id: str
+    ) -> dict[str, str]:
+        del config
+        return {
+            "haiku_model": model_id,
+            "opus_model": model_id,
+            "sonnet_model": model_id,
+        }
+
+    def context_policy(self, config: ProviderConfig) -> ProviderContextPolicy:
+        del config
+        return ProviderContextPolicy(
+            capacity_strategy="hint_first",
+            settings_strategy="standard",
+            hosted_timeout=True,
+            context_family_before_size_markers=True,
+            status_capacity_strategy="provider",
+        )
+
+    def router_native_anthropic_enabled(
+        self, config: ProviderConfig, model: str | None = None
+    ) -> bool:
+        del model
+        return bool(config.options.get("native_compat", True))
+
+    def option_presentation_policy(
+        self, config: ProviderConfig
+    ) -> ProviderOptionPresentationPolicy:
+        del config
+        return ProviderOptionPresentationPolicy(
+            show_native=True,
+            show_tool_choice=True,
+            show_stream=True,
+            show_rate_limit_controls=True,
+            show_sampling_controls=True,
+            show_ip_family_control=True,
+        )
+
+    def status_policy(self, config: ProviderConfig) -> ProviderStatusPolicy:
+        del config
+        return ProviderStatusPolicy(
+            kind="configured", configured_description="Z.AI Anthropic API configured"
+        )
+
+
+__all__ = ["ZaiProviderAdapter"]

package/ciel_runtime_support/pseudo_tool_parser.py

@@ -0,0 +1,115 @@
+"""Parser strategy for provider-emitted pseudo tool-call envelopes."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+PSEUDO_TOOL_START = "<|tool_calls_section_begin|>"
+PSEUDO_TOOL_END = "<|tool_calls_section_end|>"
+PSEUDO_CALL_BEGIN = "<|tool_call_begin|>"
+PSEUDO_ARG_BEGIN = "<|tool_call_argument_begin|>"
+PSEUDO_CALL_END = "<|tool_call_end|>"
+
+
+def normalize_tool_arguments(tool_name: str, arguments: Any) -> dict[str, Any]:
+    if isinstance(arguments, dict):
+        return arguments
+    if isinstance(arguments, str):
+        text = arguments.strip()
+        if not text:
+            return {}
+        try:
+            parsed = json.loads(text)
+            if isinstance(parsed, dict):
+                return parsed
+        except (TypeError, ValueError):
+            pass
+        if tool_name == "Bash":
+            return {"command": text}
+    return {}
+
+
+def infer_tool_name_from_args(arguments: dict[str, Any]) -> str:
+    keys = set(arguments)
+    if "command" in keys:
+        return "Bash"
+    if {"file_path", "content"}.issubset(keys):
+        return "Write"
+    if {"file_path", "old_string", "new_string"}.issubset(keys):
+        return "Edit"
+    if "file_path" in keys:
+        return "Read"
+    if keys & {"taskId", "task_id", "addBlocks", "addBlockedBy"}:
+        return "TaskUpdate"
+    return "TaskList" if not arguments else "Write"
+
+
+@dataclass(frozen=True, slots=True)
+class PseudoToolParserServices:
+    parse_xml: Callable[..., tuple[str, list[dict[str, Any]]]]
+    fuzzy_tool_name: Callable[[str], str]
+
+
+def parse_pseudo_tool_calls(
+    text: str,
+    source_body: dict[str, Any] | None,
+    services: PseudoToolParserServices,
+) -> tuple[str, list[dict[str, Any]]]:
+    if PSEUDO_TOOL_START not in text:
+        return services.parse_xml(text, source_body)
+    visible_parts: list[str] = []
+    calls: list[dict[str, Any]] = []
+    position = 0
+    while True:
+        start = text.find(PSEUDO_TOOL_START, position)
+        if start < 0:
+            visible_parts.append(text[position:])
+            break
+        visible_parts.append(text[position:start])
+        end = text.find(PSEUDO_TOOL_END, start)
+        if end < 0:
+            section = text[start + len(PSEUDO_TOOL_START) :]
+            position = len(text)
+        else:
+            section = text[start + len(PSEUDO_TOOL_START) : end]
+            position = end + len(PSEUDO_TOOL_END)
+        pattern = (
+            re.escape(PSEUDO_CALL_BEGIN)
+            + r"(.*?)"
+            + re.escape(PSEUDO_ARG_BEGIN)
+            + r"(.*?)"
+            + re.escape(PSEUDO_CALL_END)
+        )
+        for match in re.finditer(pattern, section, flags=re.DOTALL):
+            raw_header = match.group(1).strip()
+            try:
+                arguments = json.loads(match.group(2).strip())
+            except (TypeError, ValueError):
+                continue
+            if not isinstance(arguments, dict):
+                continue
+            name = next(
+                (
+                    candidate
+                    for part in re.split(r"[\s:|,]+", raw_header)
+                    if (candidate := services.fuzzy_tool_name(part))
+                ),
+                "",
+            )
+            if not name:
+                name = infer_tool_name_from_args(arguments)
+            calls.append(
+                {
+                    "function": {"name": name, "arguments": arguments},
+                    "id": raw_header,
+                }
+            )
+        if end < 0:
+            break
+    visible_text, xml_calls = services.parse_xml("".join(visible_parts), source_body)
+    return visible_text, calls + xml_calls

package/ciel_runtime_support/rate_limit_policy.py

@@ -0,0 +1,117 @@
+"""Pure rate-limit configuration, window, and HTTP header policy."""
+
+from __future__ import annotations
+
+import math
+import re
+import time
+from email.utils import parsedate_to_datetime
+from typing import Any, Callable
+
+
+def configured_rpm(config: dict[str, Any], positive_int: Callable[[Any], int | None]) -> int | None:
+    raw = config.get("rate_limit_rpm")
+    if raw is None:
+        return None
+    if isinstance(raw, str) and raw.strip().lower() in (
+        "0", "false", "off", "disable", "disabled", "none", "unset",
+    ):
+        return 0
+    try:
+        if int(raw) == 0:
+            return 0
+    except Exception:
+        pass
+    rpm = positive_int(raw)
+    return rpm if rpm and rpm > 0 else None
+
+
+def capacity(rpm: int) -> int:
+    if rpm <= 1:
+        return 1
+    reserve = 1 if rpm <= 20 else max(1, math.ceil(rpm * 0.05))
+    return max(1, rpm - reserve)
+
+
+def recent_timestamps(
+    timestamps: Any,
+    now: float,
+    window: float,
+    *,
+    include_future: bool,
+) -> list[float]:
+    result: list[float] = []
+    for timestamp in timestamps or []:
+        if not isinstance(timestamp, (int, float)):
+            continue
+        value = float(timestamp)
+        age = now - value
+        if age < window and (include_future or age >= 0.0):
+            result.append(value)
+    return sorted(result)
+
+
+def retry_after_seconds(value: str | None, now: Callable[[], float] = time.time) -> float | None:
+    if not value:
+        return None
+    text = value.strip()
+    try:
+        return max(0.0, float(text))
+    except Exception:
+        pass
+    try:
+        return max(0.0, parsedate_to_datetime(text).timestamp() - now())
+    except Exception:
+        return None
+
+
+def format_duration(seconds: float) -> str:
+    total = max(0, int(round(seconds)))
+    days, remainder = divmod(total, 86400)
+    hours, remainder = divmod(remainder, 3600)
+    minutes, secs = divmod(remainder, 60)
+    parts: list[str] = []
+    if days:
+        parts.append(f"{days}d")
+    if hours:
+        parts.append(f"{hours}h")
+    if minutes:
+        parts.append(f"{minutes}m")
+    if secs or not parts:
+        parts.append(f"{secs}s")
+    return " ".join(parts)
+
+
+def first_header(headers: Any, names: list[str]) -> str | None:
+    for name in names:
+        try:
+            value = headers.get(name)
+        except Exception:
+            value = None
+        if value:
+            return str(value)
+    return None
+
+
+def first_integer(value: str | None) -> int | None:
+    match = re.search(r"\d+", value) if value else None
+    try:
+        return int(match.group(0)) if match else None
+    except Exception:
+        return None
+
+
+def reset_seconds(value: str | None, now: Callable[[], float] = time.time) -> float | None:
+    if not value:
+        return None
+    text = value.strip()
+    try:
+        numeric = float(text)
+        current = now()
+        if numeric > 1e12:
+            return max(0.0, numeric / 1000.0 - current)
+        if numeric > current + 60.0:
+            return max(0.0, numeric - current)
+        return max(0.0, numeric)
+    except Exception:
+        return retry_after_seconds(text, now)

package/ciel_runtime_support/rate_limit_repository.py

@@ -0,0 +1,154 @@
+"""Persistent repository for provider rate usage and API-key cooldown state."""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable
+from pathlib import Path
+from threading import Lock, RLock
+from typing import Any
+
+
+class RateLimitRepository:
+    def __init__(
+        self,
+        config_dir: Path,
+        state_path: Path,
+        lock: Lock | RLock,
+        log: Callable[[str, str], None],
+    ) -> None:
+        self.config_dir = config_dir
+        self.state_path = state_path
+        self.lock = lock
+        self.log = log
+
+    def entry(self, key: str, legacy_key: str) -> dict[str, Any]:
+        state = self._read()
+        entry = state.get(key)
+        if not isinstance(entry, dict):
+            entry = state.get(legacy_key)
+        return entry if isinstance(entry, dict) else {}
+
+    def effective_rpm(self, key: str, legacy_key: str, configured: int | None) -> int | None:
+        if configured == 0:
+            return 0
+        entry = self.entry(key, legacy_key)
+        try:
+            server_rpm = int(entry.get("server_rpm") or 0)
+            updated_at = float(entry.get("server_rpm_updated_at") or 0.0)
+            if server_rpm > 0 and 0.0 <= time.time() - updated_at < 3600.0:
+                return server_rpm
+        except Exception:
+            pass
+        return configured
+
+    def usage(
+        self,
+        key: str,
+        legacy_key: str,
+        rpm: int | None,
+        recent: Callable[..., list[float]],
+    ) -> tuple[int, int | None]:
+        if rpm is None:
+            return 0, None
+        if rpm == 0:
+            return 0, 0
+        state = self._read()
+        entry = state.get(key)
+        if not isinstance(entry, dict):
+            entry = state.get(legacy_key)
+        timestamps = (
+            entry.get("timestamps")
+            if isinstance(entry, dict)
+            else [float(entry)]
+            if isinstance(entry, (int, float))
+            else []
+        )
+        used = len(recent(timestamps, time.time(), 60.0, include_future=False))
+        return used, rpm
+
+    def record_usage(
+        self,
+        key: str,
+        legacy_key: str,
+        rpm: int | None,
+        recent: Callable[..., list[float]],
+    ) -> tuple[int, int | None]:
+        if rpm is None:
+            return 0, None
+        with self.lock:
+            state = self._read()
+            now = time.time()
+            entry = state.get(key)
+            if not isinstance(entry, dict):
+                entry = state.get(legacy_key)
+            timestamps = (
+                entry.get("timestamps")
+                if isinstance(entry, dict)
+                else [float(entry)]
+                if isinstance(entry, (int, float))
+                else []
+            )
+            values = recent(timestamps, now, 60.0, include_future=True)
+            values.append(now)
+            new_entry: dict[str, Any] = {
+                "timestamps": values[-max(int(rpm or 0), 240) :],
+                "rpm": int(rpm or 0),
+                "updated_at": now,
+                "last_wait": 0.0,
+            }
+            existing_penalty = (
+                float(entry.get("penalty_until") or 0.0)
+                if isinstance(entry, dict)
+                else 0.0
+            )
+            if existing_penalty > now:
+                new_entry["penalty_until"] = existing_penalty
+            state[key] = new_entry
+            self._write(state)
+            return len(values), rpm
+
+    def register_cooldown(self, state_key: str, seconds: float) -> None:
+        with self.lock:
+            state = self._read()
+            now = time.time()
+            state[state_key] = {"cooldown_until": now + seconds, "last_429_at": now}
+            self._write(state)
+
+    def cooldown_until(self, state_key: str) -> float:
+        with self.lock:
+            entry = self._read().get(state_key)
+        if not isinstance(entry, dict):
+            return 0.0
+        try:
+            until = float(entry.get("cooldown_until") or 0.0)
+        except Exception:
+            return 0.0
+        return until if until > time.time() else 0.0
+
+    def reset_key_cooldowns(self) -> int:
+        with self.lock:
+            state = self._read()
+            kept = {key: value for key, value in state.items() if ":__key__:" not in str(key)}
+            removed = len(state) - len(kept)
+            if removed > 0:
+                self._write(kept)
+        return removed
+
+    def _read(self) -> dict[str, Any]:
+        try:
+            value = (
+                json.loads(self.state_path.read_text(encoding="utf-8"))
+                if self.state_path.exists()
+                else {}
+            )
+            return value if isinstance(value, dict) else {}
+        except Exception:
+            return {}
+
+    def _write(self, state: dict[str, Any]) -> None:
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+        self.state_path.write_text(
+            json.dumps(state, ensure_ascii=False) + "\n", encoding="utf-8"
+        )

package/ciel_runtime_support/registry.py

@@ -0,0 +1,46 @@
+"""Small typed registries used by runtime architecture extension points."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any, Generic, TypeVar
+
+
+T = TypeVar("T")
+
+
+class AdapterRegistry(Generic[T]):
+    """Map stable names and aliases to adapter factories."""
+
+    def __init__(self) -> None:
+        self._factories: dict[str, Callable[..., T]] = {}
+
+    def register(self, name: str, factory: Callable[..., T], *, aliases: Iterable[str] = ()) -> None:
+        keys = tuple(dict.fromkeys(self._normalize(key) for key in (name, *aliases)))
+        for normalized in keys:
+            if not normalized:
+                raise ValueError("adapter name cannot be empty")
+            if normalized in self._factories:
+                raise ValueError(f"adapter already registered: {normalized}")
+            self._factories[normalized] = factory
+
+    def create(self, name: str, /, **kwargs: Any) -> T:
+        normalized = self._normalize(name)
+        try:
+            factory = self._factories[normalized]
+        except KeyError as exc:
+            raise KeyError(f"unknown adapter: {name}") from exc
+        return factory(**kwargs)
+
+    def contains(self, name: str) -> bool:
+        return self._normalize(name) in self._factories
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(sorted(self._factories))
+
+    @staticmethod
+    def _normalize(name: str) -> str:
+        return str(name or "").strip().lower().replace("_", "-")
+
+
+__all__ = ["AdapterRegistry"]