agentengine-sdk-python 0.6.4__py3-none-any.whl → 0.7.0__py3-none-any.whl

ksadk/model_policy.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import copy
+import json
+import os
+from typing import Any, Mapping
+
+from ksadk.configs.settings import DEFAULT_MODEL_NAME
+
+DEFAULT_MULTIMODAL_MODEL = "kimi-k2.7-code"
+DEFAULT_FALLBACK_MODEL = "deepseek-v4-pro"
+
+DEFAULT_MODEL_POLICY: dict[str, Any] = {
+    "version": "v1",
+    "primary": {"model": DEFAULT_MODEL_NAME},
+    "multimodal": {"model": DEFAULT_MULTIMODAL_MODEL},
+    "fallback": {
+        "model": DEFAULT_FALLBACK_MODEL,
+        "fallback_errors": [
+            "timeout",
+            "temporarily unavailable",
+            "temporary unavailable",
+            "model unavailable",
+            "rate limit",
+            "too many requests",
+            "503",
+            "504",
+        ],
+        "on_errors": [
+            "timeout",
+            "temporarily unavailable",
+            "temporary unavailable",
+            "model unavailable",
+            "rate limit",
+            "too many requests",
+            "503",
+            "504",
+        ],
+    },
+    "models": {
+        DEFAULT_MODEL_NAME: {
+            "reasoning": True,
+            "options": {},
+        },
+        DEFAULT_MULTIMODAL_MODEL: {
+            "input": ["text", "image"],
+            "reasoning": True,
+            "options": {"temperature": 1},
+        },
+        DEFAULT_FALLBACK_MODEL: {
+            "reasoning": True,
+            "options": {},
+        },
+    },
+}
+
+
+def _deep_merge(base: dict[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
+    merged = copy.deepcopy(base)
+    for key, value in override.items():
+        if (
+            isinstance(value, Mapping)
+            and isinstance(merged.get(key), dict)
+        ):
+            merged[key] = _deep_merge(merged[key], value)
+        else:
+            merged[key] = copy.deepcopy(value)
+    return merged
+
+
+def normalize_model_policy(raw: str | Mapping[str, Any] | None = None) -> dict[str, Any]:
+    if raw is None or raw == "":
+        return copy.deepcopy(DEFAULT_MODEL_POLICY)
+    if isinstance(raw, str):
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            return copy.deepcopy(DEFAULT_MODEL_POLICY)
+    else:
+        parsed = raw
+    if not isinstance(parsed, Mapping):
+        return copy.deepcopy(DEFAULT_MODEL_POLICY)
+    normalized = _deep_merge(DEFAULT_MODEL_POLICY, parsed)
+    fallback = normalized.get("fallback")
+    if isinstance(fallback, dict):
+        raw_errors = fallback.get("fallback_errors") or fallback.get("on_errors")
+        if isinstance(raw_errors, list):
+            fallback["fallback_errors"] = list(raw_errors)
+            fallback["on_errors"] = list(raw_errors)
+    return normalized
+
+
+def _unqualified_model_name(model: str) -> str:
+    return str(model or "").strip().rsplit("/", 1)[-1]
+
+
+def model_policy_options_for_model(
+    model: str,
+    policy: str | Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    normalized = normalize_model_policy(policy)
+    models = normalized.get("models")
+    if not isinstance(models, Mapping):
+        return {}
+
+    candidates = [str(model or "").strip(), _unqualified_model_name(model)]
+    for candidate in candidates:
+        config = models.get(candidate)
+        if isinstance(config, Mapping) and isinstance(config.get("options"), Mapping):
+            return dict(config["options"])
+    return {}
+
+
+def fallback_model_for_exception(
+    exc: BaseException,
+    *,
+    current_model: str,
+    policy: str | Mapping[str, Any] | None = None,
+) -> str | None:
+    normalized = normalize_model_policy(policy)
+    fallback = normalized.get("fallback")
+    if not isinstance(fallback, Mapping):
+        return None
+
+    fallback_model = str(fallback.get("model") or "").strip()
+    if not fallback_model or fallback_model == str(current_model or "").strip():
+        return None
+
+    message = str(exc or "").strip().lower()
+    if not message:
+        return None
+    if "400" in message or "invalid request" in message or "bad request" in message:
+        return None
+
+    transient_markers = fallback.get("fallback_errors") or fallback.get("on_errors")
+    if not isinstance(transient_markers, list):
+        transient_markers = DEFAULT_MODEL_POLICY["fallback"]["on_errors"]
+
+    if any(str(marker).lower() in message for marker in transient_markers):
+        return fallback_model
+    return None
+
+
+def _provider_ref(model: str, provider: str = "ksyun") -> str:
+    value = str(model or "").strip()
+    if not value or "/" in value:
+        return value
+    return f"{provider}/{value}"
+
+
+def _role_model(policy: Mapping[str, Any], role: str) -> str:
+    value = policy.get(role)
+    if isinstance(value, Mapping):
+        return str(value.get("model") or "").strip()
+    return str(value or "").strip()
+
+
+def _catalog_from_policy(policy: Mapping[str, Any]) -> list[dict[str, Any]]:
+    models = policy.get("models") if isinstance(policy.get("models"), Mapping) else {}
+    catalog: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for role in ("primary", "multimodal", "fallback"):
+        model = _role_model(policy, role)
+        if not model or model in seen:
+            continue
+        seen.add(model)
+        metadata = dict(models.get(model) or {}) if isinstance(models, Mapping) else {}
+        item = {
+            "id": model,
+            "name": model,
+            "api": metadata.get("api") or "openai-completions",
+            "input": metadata.get("input") or ["text"],
+        }
+        if isinstance(metadata.get("reasoning"), bool):
+            item["reasoning"] = metadata["reasoning"]
+        if isinstance(metadata.get("options"), Mapping) and metadata["options"]:
+            item["options"] = dict(metadata["options"])
+        catalog.append(item)
+    return catalog
+
+
+def build_runtime_model_policy_env(
+    env_vars: Mapping[str, str] | None,
+    *,
+    runtime: str,
+    policy: str | Mapping[str, Any] | None = None,
+) -> dict[str, str]:
+    env = dict(env_vars or {})
+    normalized = normalize_model_policy(policy or os.getenv("AGENTENGINE_MODEL_POLICY_JSON"))
+    env.setdefault(
+        "AGENTENGINE_MODEL_POLICY_JSON",
+        json.dumps(normalized, ensure_ascii=False, sort_keys=True, separators=(",", ":")),
+    )
+    primary = _role_model(normalized, "primary")
+    fallback = _role_model(normalized, "fallback")
+    multimodal = _role_model(normalized, "multimodal")
+    has_primary = any(
+        str(env.get(key) or "").strip()
+        for key in ("OPENCLAW_DEFAULT_MODEL", "HERMES_DEFAULT_MODEL", "OPENAI_MODEL_NAME", "MODEL_NAME")
+    )
+    runtime_name = str(runtime or "").strip().lower()
+    if runtime_name == "openclaw":
+        if primary and not has_primary:
+            env["OPENAI_MODEL_NAME"] = _provider_ref(primary)
+        if fallback:
+            env.setdefault("OPENCLAW_FALLBACK_MODEL", _provider_ref(fallback))
+        if multimodal:
+            env.setdefault("OPENCLAW_IMAGE_MODEL", _provider_ref(multimodal))
+        env.setdefault("OPENCLAW_MODEL_CATALOG_JSON", json.dumps(_catalog_from_policy(normalized), ensure_ascii=False))
+        return env
+    if runtime_name == "hermes":
+        if primary and not has_primary:
+            env["OPENAI_MODEL_NAME"] = primary
+            env["HERMES_DEFAULT_MODEL"] = primary
+        if fallback:
+            env.setdefault("HERMES_FALLBACK_MODEL", fallback)
+        env.setdefault("HERMES_MODEL_CATALOG_JSON", json.dumps(_catalog_from_policy(normalized), ensure_ascii=False))
+        return env
+    if primary and not has_primary:
+        env["OPENAI_MODEL_NAME"] = primary
+    if fallback:
+        env.setdefault("OPENAI_FALLBACK_MODEL_NAME", fallback)
+    return env

ksadk/openclaw_gateway.py

@@ -0,0 +1,378 @@
+"""Thin OpenClaw gateway client for Dashboard short-link sessions."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import platform
+import uuid
+from dataclasses import dataclass
+from typing import Any, Optional
+from urllib.parse import urlsplit, urlunsplit
+
+import requests
+
+from ksadk.api import AgentEngineClient
+from ksadk.version import VERSION as KSADK_VERSION
+
+
+DEFAULT_CLIENT_NAME = "openclaw-control-ui"
+DEFAULT_CLIENT_MODE = "webchat"
+DEFAULT_SCOPES = ("operator.admin",)
+GATEWAY_PROTOCOL_VERSION = 4
+
+
+class OpenClawGatewayError(RuntimeError):
+    """Gateway connection or protocol error."""
+
+
+class OpenClawGatewayRequestError(OpenClawGatewayError):
+    """Structured gateway RPC error."""
+
+    def __init__(self, message: str, *, code: Any = None, details: Any = None):
+        self.code = code
+        self.details = details
+        super().__init__(message)
+
+
+@dataclass
+class DashboardAccessInfo:
+    agent_id: str
+    agent_name: Optional[str]
+    access_url: str
+    ws_url: str
+    cookie_header: str
+    origin: str
+    link_id: Optional[str] = None
+    expires_at: Optional[str] = None
+
+
+def derive_gateway_ws_url(access_url: str) -> str:
+    """Derive the router websocket URL from a Dashboard short-link URL."""
+    parsed = urlsplit((access_url or "").strip())
+    if not parsed.scheme or not parsed.netloc:
+        raise OpenClawGatewayError("Dashboard access URL is invalid")
+
+    marker = "/s/"
+    path = parsed.path or "/"
+    marker_idx = path.find(marker)
+    base_path = path[:marker_idx] if marker_idx >= 0 else path
+    if not base_path:
+        base_path = "/"
+    if not base_path.endswith("/"):
+        base_path = f"{base_path}/"
+
+    ws_scheme = "wss" if parsed.scheme == "https" else "ws"
+    return urlunsplit((ws_scheme, parsed.netloc, base_path, "", ""))
+
+
+class OpenClawGatewayClient:
+    """Minimal cookie-session websocket client for a managed OpenClaw gateway."""
+
+    def __init__(
+        self,
+        *,
+        region: str,
+        agent_id: str,
+        agent_name: Optional[str] = None,
+        client_name: str = DEFAULT_CLIENT_NAME,
+        client_mode: str = DEFAULT_CLIENT_MODE,
+    ):
+        self.region = region
+        self.agent_id = agent_id
+        self.agent_name = agent_name
+        self.client_name = client_name
+        self.client_mode = client_mode
+        self.instance_id = str(uuid.uuid4())
+        self.session = requests.Session()
+        self._ws: Any = None
+        self.connection_info: Optional[DashboardAccessInfo] = None
+        self.hello: Optional[dict[str, Any]] = None
+        self.challenge_nonce: Optional[str] = None
+
+    async def __aenter__(self) -> "OpenClawGatewayClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> bool:
+        await self.close()
+        return False
+
+    async def close(self) -> None:
+        if self._ws is not None:
+            try:
+                await self._ws.close()
+            except Exception:
+                pass
+            self._ws = None
+        self.session.close()
+
+    @property
+    def methods(self) -> list[str]:
+        features = (self.hello or {}).get("features") or {}
+        methods = features.get("methods")
+        if isinstance(methods, list):
+            return [str(item) for item in methods]
+        return []
+
+    def has_method(self, method: str) -> bool:
+        return method in set(self.methods)
+
+    async def build_access_info(
+        self,
+        *,
+        path: Optional[str] = None,
+        expires_seconds: Optional[int] = None,
+        link_type: str = "private",
+        force_new: bool = False,
+    ) -> DashboardAccessInfo:
+        async with AgentEngineClient(region=self.region) as client:
+            link = await client.create_dashboard_access_link(
+                agent_id=self.agent_id,
+                name=self.agent_name,
+                link_type=link_type,
+                path=path,
+                expires_seconds=expires_seconds,
+                force_new=force_new,
+            )
+
+        access_url = str(link.get("access_url") or "").strip()
+        if not access_url:
+            raise OpenClawGatewayError("CreateDashboardAccessLink returned an empty access URL")
+
+        response = await asyncio.to_thread(
+            self.session.get,
+            access_url,
+            allow_redirects=False,
+            timeout=30,
+        )
+        if response.status_code >= 400 or response.status_code < 300:
+            raise OpenClawGatewayError(
+                f"Dashboard short-link bootstrap failed: HTTP {response.status_code}"
+            )
+
+        cookie_header = self._build_cookie_header()
+        if not cookie_header:
+            raise OpenClawGatewayError("Dashboard short-link bootstrap did not produce a session cookie")
+
+        parsed = urlsplit(access_url)
+        self.connection_info = DashboardAccessInfo(
+            agent_id=self.agent_id,
+            agent_name=self.agent_name,
+            access_url=access_url,
+            ws_url=derive_gateway_ws_url(access_url),
+            cookie_header=cookie_header,
+            origin=f"{parsed.scheme}://{parsed.netloc}",
+            link_id=str(link.get("link_id") or "").strip() or None,
+            expires_at=str(link.get("expires_at") or "").strip() or None,
+        )
+        return self.connection_info
+
+    async def connect(
+        self,
+        *,
+        path: Optional[str] = None,
+        expires_seconds: Optional[int] = None,
+        link_type: str = "private",
+    ) -> dict[str, Any]:
+        info = self.connection_info or await self.build_access_info(
+            path=path,
+            expires_seconds=expires_seconds,
+            link_type=link_type,
+        )
+
+        headers = {
+            "Cookie": info.cookie_header,
+            "User-Agent": f"ksadk/{KSADK_VERSION}",
+            "Origin": info.origin,
+        }
+        self._ws = await self._connect_ws(info.ws_url, headers)
+        self.challenge_nonce = await self._wait_for_connect_challenge()
+        self.hello = await self.request(
+            "connect",
+            {
+                "minProtocol": GATEWAY_PROTOCOL_VERSION,
+                "maxProtocol": GATEWAY_PROTOCOL_VERSION,
+                "client": {
+                    "id": self.client_name,
+                    "displayName": "ksadk openclaw channel",
+                    "version": KSADK_VERSION,
+                    "platform": platform.system().lower() or "unknown",
+                    "mode": self.client_mode,
+                    "instanceId": self.instance_id,
+                },
+                "caps": [],
+                "role": "operator",
+                "scopes": list(DEFAULT_SCOPES),
+            },
+            timeout_ms=10_000,
+        )
+        return self.hello
+
+    async def channels_status(self, *, probe: bool = False, timeout_ms: Optional[int] = None) -> dict[str, Any]:
+        params: dict[str, Any] = {"probe": bool(probe)}
+        if timeout_ms is not None:
+            params["timeoutMs"] = int(timeout_ms)
+        return await self.request("channels.status", params)
+
+    async def config_get(self) -> dict[str, Any]:
+        return await self.request("config.get", {})
+
+    async def config_apply(
+        self,
+        *,
+        config: dict[str, Any],
+        base_hash: str,
+        note: Optional[str] = None,
+        session_key: Optional[str] = None,
+        restart_delay_ms: Optional[int] = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {
+            "raw": json.dumps(config, ensure_ascii=False, indent=2),
+            "baseHash": base_hash,
+        }
+        if note:
+            params["note"] = note
+        if session_key:
+            params["sessionKey"] = session_key
+        if restart_delay_ms is not None:
+            params["restartDelayMs"] = int(restart_delay_ms)
+        return await self.request("config.apply", params, timeout_ms=20_000)
+
+    async def web_login_start(
+        self,
+        *,
+        force: bool = False,
+        timeout_ms: Optional[int] = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {"force": bool(force)}
+        if timeout_ms is not None:
+            params["timeoutMs"] = int(timeout_ms)
+        return await self.request("web.login.start", params, timeout_ms=(timeout_ms or 30_000) + 5_000)
+
+    async def web_login_wait(
+        self,
+        *,
+        account_id: Optional[str] = None,
+        session_key: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        effective_account_id = account_id or session_key
+        if effective_account_id:
+            params["accountId"] = effective_account_id
+        if timeout_ms is not None:
+            params["timeoutMs"] = int(timeout_ms)
+        return await self.request("web.login.wait", params, timeout_ms=(timeout_ms or 120_000) + 5_000)
+
+    async def request(
+        self,
+        method: str,
+        params: Optional[dict[str, Any]] = None,
+        *,
+        timeout_ms: int = 30_000,
+    ) -> dict[str, Any]:
+        if self._ws is None:
+            raise OpenClawGatewayError("Gateway websocket is not connected")
+
+        request_id = uuid.uuid4().hex
+        payload = {
+            "type": "req",
+            "id": request_id,
+            "method": method,
+            "params": params or {},
+        }
+        await self._ws.send(json.dumps(payload, ensure_ascii=False))
+        return await self._wait_for_response(request_id, timeout_ms=timeout_ms)
+
+    async def wait_for_disconnect(self, *, timeout_ms: int = 5_000) -> bool:
+        """Wait briefly for the current websocket to close, typically after config-triggered restart."""
+        if self._ws is None:
+            return True
+
+        deadline = asyncio.get_running_loop().time() + (timeout_ms / 1000)
+        while True:
+            remaining = deadline - asyncio.get_running_loop().time()
+            if remaining <= 0:
+                return False
+            try:
+                await self._recv_json(timeout=remaining)
+            except OpenClawGatewayError as exc:
+                return "timed out" not in str(exc).lower()
+
+    def _build_cookie_header(self) -> str:
+        cookies = self.session.cookies.get_dict()
+        return "; ".join(f"{name}={value}" for name, value in cookies.items())
+
+    async def _connect_ws(self, ws_url: str, headers: dict[str, str]):
+        try:
+            import websockets
+        except Exception as exc:  # pragma: no cover - exercised only when dependency missing
+            raise OpenClawGatewayError(
+                "Missing dependency `websockets`; reinstall ksadk with channel support enabled"
+            ) from exc
+
+        connect_kwargs = {
+            "open_timeout": 10,
+            "ping_interval": 20,
+            "ping_timeout": 20,
+            "max_size": 50 * 1024 * 1024,
+        }
+        try:
+            return await websockets.connect(ws_url, additional_headers=headers, **connect_kwargs)
+        except TypeError:
+            return await websockets.connect(ws_url, extra_headers=headers, **connect_kwargs)
+
+    async def _wait_for_connect_challenge(self, *, timeout_ms: int = 10_000) -> str:
+        deadline = timeout_ms / 1000
+        while True:
+            frame = await self._recv_json(timeout=deadline)
+            if frame.get("type") != "event":
+                continue
+            if frame.get("event") != "connect.challenge":
+                continue
+            payload = frame.get("payload") or {}
+            nonce = str(payload.get("nonce") or "").strip()
+            if nonce:
+                return nonce
+            raise OpenClawGatewayError("Gateway connect challenge missing nonce")
+
+    async def _wait_for_response(self, request_id: str, *, timeout_ms: int) -> dict[str, Any]:
+        deadline = timeout_ms / 1000
+        while True:
+            frame = await self._recv_json(timeout=deadline)
+            if frame.get("type") != "res":
+                continue
+            if frame.get("id") != request_id:
+                continue
+            if frame.get("ok"):
+                payload = frame.get("payload")
+                if isinstance(payload, dict):
+                    return payload
+                return {"value": payload}
+            error = frame.get("error") or {}
+            raise OpenClawGatewayRequestError(
+                str(error.get("message") or "Gateway request failed"),
+                code=error.get("code"),
+                details=error.get("details"),
+            )
+
+    async def _recv_json(self, *, timeout: float) -> dict[str, Any]:
+        if self._ws is None:
+            raise OpenClawGatewayError("Gateway websocket is not connected")
+
+        try:
+            raw = await asyncio.wait_for(self._ws.recv(), timeout=timeout)
+        except asyncio.TimeoutError as exc:
+            raise OpenClawGatewayError("Gateway websocket timed out") from exc
+        except Exception as exc:
+            raise OpenClawGatewayError(f"Gateway websocket receive failed: {exc}") from exc
+
+        if isinstance(raw, bytes):
+            raw = raw.decode("utf-8", errors="replace")
+        try:
+            parsed = json.loads(raw)
+        except Exception as exc:
+            raise OpenClawGatewayError("Gateway websocket returned invalid JSON") from exc
+        if not isinstance(parsed, dict):
+            raise OpenClawGatewayError("Gateway websocket returned an unexpected frame")
+        return parsed

ksadk/runners/__init__.py

@@ -0,0 +1,8 @@
+"""
+KsADK Runners - 统一运行时模块
+"""
+
+from ksadk.runners.base_runner import BaseRunner
+from ksadk.runners.factory import create_runner
+
+__all__ = ["BaseRunner", "create_runner"]