@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/response_collection.py

@@ -0,0 +1,209 @@
+"""Protocol strategies for collecting one message for a Responses API projection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class ChatCollectionStrategy:
+    operation: str
+    build_request: Callable[..., dict[str, Any]]
+    decode_response: Callable[..., dict[str, Any]]
+    request_timeout_seconds: Callable[..., float]
+    normalize_upstream_model: Callable[..., str]
+    skip_rate_limit_during_compatibility_test: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class ResponseCollectionRequest:
+    normalize_thinking: Callable[..., dict[str, Any]]
+    resolve_model: Callable[..., str]
+    body_with_advisor_tool: Callable[..., dict[str, Any]]
+    advisor_provider_supported: Callable[..., bool]
+    provider_endpoint: Callable[..., str]
+    provider_headers: Callable[..., dict[str, str]]
+
+
+@dataclass(frozen=True, slots=True)
+class ResponseCollectionRateLimit:
+    apply: Callable[..., tuple[float, int, int]]
+    effective_rpm: Callable[..., int]
+    notice: Callable[..., str]
+
+
+@dataclass(frozen=True, slots=True)
+class ResponseCollectionProjection:
+    refine_with_advisor: Callable[..., dict[str, Any]]
+    remember_tool_uses: Callable[..., Any]
+    prepend_text: Callable[..., dict[str, Any]]
+
+
+@dataclass(frozen=True, slots=True)
+class ResponseCollectionServices:
+    compatibility_test_header: str
+    request: ResponseCollectionRequest
+    rate_limit: ResponseCollectionRateLimit
+    projection: ResponseCollectionProjection
+    post_json_with_retry: Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class AnthropicCollectionRequest:
+    normalize_thinking: Callable[..., dict[str, Any]]
+    normalize_system_roles: Callable[..., dict[str, Any]]
+    cap_body: Callable[..., dict[str, Any]]
+    apply_options: Callable[..., dict[str, Any]]
+    rehydrate_thinking: Callable[..., dict[str, Any]]
+    resolve_model: Callable[..., str]
+    normalize_upstream_model: Callable[..., str]
+    resolve_tool_models: Callable[..., dict[str, Any]]
+    normalize_model_options: Callable[..., dict[str, Any]]
+    strip_internal_metadata: Callable[..., dict[str, Any]]
+
+
+@dataclass(frozen=True, slots=True)
+class AnthropicCollectionTransport:
+    native_compat_enabled: Callable[..., bool]
+    native_base_url: Callable[..., str]
+    upstream_request_base: Callable[..., str]
+    join_url: Callable[..., str]
+    messages_query: Callable[..., str]
+    provider_headers: Callable[..., dict[str, str]]
+    apply_rate_limit: Callable[..., tuple[float, int, int]]
+    open_request_with_retry: Callable[..., Any]
+    request_timeout_seconds: Callable[..., float]
+
+
+@dataclass(frozen=True, slots=True)
+class AnthropicCollectionProjection:
+    normalize_response_thinking: Callable[..., dict[str, Any]]
+    append_synthetic_tasklist: Callable[..., dict[str, Any]]
+    prepend_text: Callable[..., dict[str, Any]]
+    rate_limit_notice: Callable[..., str]
+
+
+@dataclass(frozen=True, slots=True)
+class AnthropicCollectionServices:
+    request: AnthropicCollectionRequest
+    transport: AnthropicCollectionTransport
+    projection: AnthropicCollectionProjection
+    forwarded_headers: tuple[str, ...]
+
+
+def collect_chat_message_for_responses(
+    handler: Any,
+    provider: str,
+    pcfg: dict[str, Any],
+    body: dict[str, Any],
+    *,
+    strategy: ChatCollectionStrategy,
+    services: ResponseCollectionServices,
+) -> dict[str, Any]:
+    """Collect a provider chat response using a protocol-specific strategy."""
+
+    request = services.request
+    rate_limit = services.rate_limit
+    projection = services.projection
+    body = request.normalize_thinking(provider, pcfg, body)
+    model = request.resolve_model(provider, pcfg, body.get("model"))
+    model = strategy.normalize_upstream_model(provider, pcfg, model)
+    original_body = body
+    upstream_body = request.body_with_advisor_tool(body, pcfg) if request.advisor_provider_supported(provider) else body
+    req_body = strategy.build_request(provider, model, upstream_body, pcfg, stream=False)
+    url = request.provider_endpoint(provider, pcfg, strategy.operation)
+    compatibility_test = str(handler.headers.get(services.compatibility_test_header) or "").strip().lower() in ("1", "true", "yes", "on")
+    if compatibility_test and strategy.skip_rate_limit_during_compatibility_test:
+        waited, rpm_used, rpm_limit = 0.0, 0, rate_limit.effective_rpm(provider, pcfg, model)
+    else:
+        waited, rpm_used, rpm_limit = rate_limit.apply(provider, pcfg, model)
+    data = services.post_json_with_retry(
+        url,
+        req_body,
+        request.provider_headers(
+            provider, pcfg, handler.headers, strategy.operation
+        ),
+        strategy.request_timeout_seconds(pcfg),
+        provider,
+        pcfg,
+        model,
+        None,
+        retry_rate_limits=not compatibility_test,
+    )
+    message = strategy.decode_response(data, model, source_body=original_body)
+    message = projection.refine_with_advisor(provider, pcfg, original_body, message, model)
+    projection.remember_tool_uses(original_body, message)
+    notice = rate_limit.notice(waited, rpm_used, rpm_limit, bool(pcfg.get("rate_limit_status", False)))
+    return projection.prepend_text(message, notice)
+
+
+def collect_anthropic_message_for_responses(
+    handler: Any,
+    provider: str,
+    pcfg: dict[str, Any],
+    body: dict[str, Any],
+    *,
+    services: AnthropicCollectionServices,
+) -> dict[str, Any]:
+    """Collect one native Anthropic message for a Responses API projection."""
+
+    request = services.request
+    transport = services.transport
+    projection = services.projection
+    body = request.normalize_thinking(provider, pcfg, body)
+    body = request.normalize_system_roles(body)
+    body = request.cap_body(provider, pcfg, body)
+    body = request.apply_options(provider, pcfg, body)
+    body = request.rehydrate_thinking(provider, pcfg, body)
+    upstream_model = request.resolve_model(provider, pcfg, body.get("model"))
+    upstream_model = request.normalize_upstream_model(provider, pcfg, upstream_model)
+    body["model"] = upstream_model
+    body = request.resolve_tool_models(provider, pcfg, body)
+    body = request.normalize_model_options(provider, pcfg, body, upstream_model)
+    upstream_body = request.strip_internal_metadata({**body, "stream": False})
+    if transport.native_compat_enabled(provider, pcfg):
+        base = transport.native_base_url(provider, pcfg)
+    else:
+        base = transport.upstream_request_base(provider, pcfg)
+    url = transport.join_url(base, "/v1/messages")
+    upstream_query = transport.messages_query(pcfg, handler.path, provider)
+    if upstream_query:
+        url = f"{url}?{upstream_query}"
+    headers = transport.provider_headers(
+        provider, pcfg, handler.headers, "anthropic_messages"
+    )
+    for header in services.forwarded_headers:
+        if handler.headers.get(header):
+            headers[header] = handler.headers[header]
+    waited, rpm_used, rpm_limit = transport.apply_rate_limit(provider, pcfg, upstream_model)
+    upstream_response = transport.open_request_with_retry(
+        url,
+        upstream_body,
+        headers,
+        transport.request_timeout_seconds(pcfg),
+        provider,
+        pcfg,
+        upstream_model,
+        stream=False,
+    )
+    try:
+        raw_response = upstream_response.read()
+        payload = json.loads(raw_response.decode("utf-8", errors="replace"))
+        if not isinstance(payload, dict):
+            raise RuntimeError("upstream returned non-object JSON")
+        payload = projection.normalize_response_thinking(provider, pcfg, payload, upstream_model)
+        payload = projection.append_synthetic_tasklist(payload, upstream_model, body, "native_json", provider=provider)
+        notice = projection.rate_limit_notice(
+            waited,
+            rpm_used,
+            rpm_limit,
+            bool(pcfg.get("rate_limit_status", False)),
+        )
+        return projection.prepend_text(payload, notice)
+    finally:
+        try:
+            upstream_response.close()
+        except Exception:
+            pass

package/ciel_runtime_support/router_access.py

@@ -0,0 +1,238 @@
+"""Router bind, authentication, token persistence, and configuration policy."""
+
+from __future__ import annotations
+
+import hmac
+import json
+import os
+import secrets
+import time
+from collections.abc import Callable, Mapping, MutableMapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol
+
+
+class RouterRequest(Protocol):
+    client_address: tuple[Any, ...]
+    headers: Any
+
+
+class RouterResponse(RouterRequest, Protocol):
+    wfile: Any
+
+    def send_response(self, status: int) -> Any: ...
+
+    def send_header(self, name: str, value: str) -> Any: ...
+
+    def end_headers(self) -> Any: ...
+
+
+def is_loopback_address(host: str | None) -> bool:
+    normalized = (host or "").strip().lower()
+    return normalized in {"127.0.0.1", "::1", "localhost"} or normalized.startswith(
+        "127."
+    )
+
+
+def router_request_bearer_token(handler: RouterRequest) -> str:
+    try:
+        authorization = str(
+            handler.headers.get("authorization")
+            or handler.headers.get("Authorization")
+            or ""
+        )
+        if authorization.lower().startswith("bearer "):
+            return authorization[7:].strip()
+        return str(handler.headers.get("x-ciel-runtime-token") or "").strip()
+    except Exception:
+        return ""
+
+
+@dataclass(frozen=True, slots=True)
+class RouterAccessPolicy:
+    environ: Mapping[str, str]
+    parse_bool: Callable[[Any, bool], bool]
+    parse_env_bool: Callable[[str | None, bool | None], bool | None]
+    load_config: Callable[[], dict[str, Any]]
+
+    def external_access_enabled(self, config: dict[str, Any] | None = None) -> bool:
+        configured = self.parse_env_bool(
+            self.environ.get("CIEL_RUNTIME_ROUTER_DEBUG_EXTERNAL"), None
+        )
+        if configured is not None:
+            return configured
+        current = self.load_config() if config is None else config
+        return self.parse_bool(
+            current.get("router_debug_external_access"), False
+        ) and self.parse_bool(
+            current.get("router_debug_external_access_confirmed"), False
+        )
+
+    def bind_host(self, config: dict[str, Any] | None = None) -> str:
+        override = (
+            self.environ.get("CIEL_RUNTIME_ROUTER_BIND_HOST")
+            or self.environ.get("CIEL_RUNTIME_ROUTER_HOST")
+            or ""
+        ).strip()
+        if override:
+            return override
+        current = self.load_config() if config is None else config
+        web_backend = current.get("web_backend") if isinstance(current, dict) else {}
+        saved_host = (
+            str(web_backend.get("host") or "").strip()
+            if isinstance(web_backend, dict)
+            else ""
+        )
+        external = self.external_access_enabled(current)
+        if saved_host and (not external or not is_loopback_address(saved_host)):
+            return saved_host
+        return "0.0.0.0" if external else "127.0.0.1"
+
+    def request_allowed(
+        self,
+        handler: RouterRequest,
+        config: dict[str, Any] | None,
+        token_provider: Callable[[], str],
+    ) -> bool:
+        try:
+            if is_loopback_address(str(handler.client_address[0])):
+                return True
+        except Exception:
+            return False
+        if not self.external_access_enabled(config):
+            return False
+        expected = token_provider()
+        supplied = router_request_bearer_token(handler)
+        return bool(expected and supplied and hmac.compare_digest(expected, supplied))
+
+
+@dataclass(frozen=True, slots=True)
+class RouterExternalTokenRepository:
+    path: Path
+    config_dir: Path
+    environ: MutableMapping[str, str]
+
+    def get(self) -> str:
+        configured = str(self.environ.get("CIEL_RUNTIME_ROUTER_EXTERNAL_TOKEN") or "").strip()
+        if configured:
+            return configured
+        try:
+            return self.path.read_text(encoding="utf-8").strip()
+        except OSError:
+            return ""
+
+    def ensure(self) -> str:
+        existing = self.get()
+        if existing:
+            return existing
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+        token = secrets.token_urlsafe(32)
+        temporary = self.path.with_name(
+            f"{self.path.name}.{os.getpid()}.{time.time_ns()}.tmp"
+        )
+        temporary.write_text(token + "\n", encoding="utf-8")
+        os.chmod(temporary, 0o600)
+        temporary.replace(self.path)
+        return token
+
+
+@dataclass(frozen=True, slots=True)
+class RouterAccessMutationPorts:
+    load_config: Callable[[], dict[str, Any]]
+    save_config: Callable[[dict[str, Any]], Any]
+    clear_model_cache: Callable[[], Any]
+    ensure_token: Callable[[], str]
+
+
+@dataclass(frozen=True, slots=True)
+class RouterAccessConfigService:
+    policy: RouterAccessPolicy
+    ports: RouterAccessMutationPorts
+
+    def set_external_access(self, value: Any) -> list[str]:
+        config = self.ports.load_config()
+        enabled = self.policy.parse_bool(value, False)
+        config["router_debug_external_access"] = enabled
+        config["router_debug_external_access_confirmed"] = enabled
+        self.ports.save_config(config)
+        self.ports.clear_model_cache()
+        bind = self.policy.bind_host(config)
+        if enabled:
+            token = self.ports.ensure_token()
+            return [
+                "Router debug external access: on.",
+                f"Router bind host for next launch: {bind}.",
+                "External clients must authenticate with Authorization: Bearer <token>.",
+                f"External access token: {token}",
+            ]
+        return [
+            "Router debug external access: off.",
+            "External clients are denied immediately; next launch binds to 127.0.0.1 unless overridden by environment.",
+        ]
+
+
+@dataclass(frozen=True, slots=True)
+class RouterAccessHttpController:
+    request_allowed: Callable[
+        [RouterRequest, dict[str, Any] | None],
+        bool,
+    ]
+    external_access_enabled: Callable[
+        [dict[str, Any] | None],
+        bool,
+    ]
+
+    def reject_external_request(
+        self,
+        handler: RouterResponse,
+        config: dict[str, Any] | None = None,
+    ) -> bool:
+        if self.request_allowed(handler, config):
+            return False
+        external_enabled = self.external_access_enabled(config)
+        status = 401 if external_enabled else 403
+        message = (
+            "ciel-runtime router external authentication is required."
+            if external_enabled
+            else "ciel-runtime router external debug access is off."
+        )
+        payload = json.dumps(
+            {
+                "type": "error",
+                "error": {
+                    "type": (
+                        "unauthorized"
+                        if status == 401
+                        else "forbidden"
+                    ),
+                    "message": message,
+                },
+            },
+            ensure_ascii=False,
+        ).encode("utf-8")
+        handler.send_response(status)
+        handler.send_header(
+            "content-type",
+            "application/json; charset=utf-8",
+        )
+        handler.send_header("content-length", str(len(payload)))
+        if status == 401:
+            handler.send_header(
+                "www-authenticate",
+                'Bearer realm="ciel-runtime"',
+            )
+        handler.end_headers()
+        handler.wfile.write(payload)
+        return True
+
+
+__all__ = [
+    "RouterAccessConfigService",
+    "RouterAccessHttpController",
+    "RouterAccessMutationPorts",
+    "RouterAccessPolicy",
+    "RouterExternalTokenRepository",
+    "is_loopback_address",
+    "router_request_bearer_token",
+]