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

ksadk/managed_runtime.py

@@ -0,0 +1,188 @@
+"""Managed runtime configuration and version resolution."""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as package_version
+from typing import Any
+
+
+class ManagedRuntimeError(ValueError):
+    """Raised when a managed runtime contract cannot be resolved safely."""
+
+
+@dataclass(frozen=True)
+class ResolvedRuntime:
+    name: str
+    version: str
+    source: str
+    package_requirement: str = ""
+
+
+def runtime_config(config: dict[str, Any]) -> tuple[str, str]:
+    value = config.get("runtime")
+    if not isinstance(value, dict):
+        raise ManagedRuntimeError("ManagedRuntime 项目缺少 runtime 配置")
+    name = str(value.get("name") or "").strip().lower()
+    requested_version = str(value.get("version") or "").strip()
+    if not name:
+        raise ManagedRuntimeError("ManagedRuntime 项目缺少 runtime.name")
+    return name, requested_version
+
+
+def extract_bootstrap_runtime(
+    bootstrap: dict[str, Any] | None,
+    runtime_name: str,
+) -> ResolvedRuntime | None:
+    if not isinstance(bootstrap, dict):
+        return None
+    configs = bootstrap.get("configs") or bootstrap.get("Configs")
+    if not isinstance(configs, dict):
+        return None
+    version = str(
+        configs.get("runtime.default_version")
+        or configs.get(f"runtime.{runtime_name}.default_version")
+        or ""
+    ).strip()
+    if not version:
+        return None
+    package = str(
+        configs.get("runtime.package")
+        or configs.get(f"runtime.{runtime_name}.package")
+        or ""
+    ).strip()
+    return ResolvedRuntime(
+        name=runtime_name,
+        version=version,
+        source="server",
+        package_requirement=package,
+    )
+
+
+async def resolve_managed_runtime(
+    config: dict[str, Any],
+    *,
+    region: str,
+    bootstrap: dict[str, Any] | None = None,
+) -> ResolvedRuntime:
+    name, requested_version = runtime_config(config)
+    if requested_version:
+        return ResolvedRuntime(name=name, version=requested_version, source="manifest")
+
+    resolved = extract_bootstrap_runtime(bootstrap, name)
+    if resolved is not None:
+        return resolved
+
+    if bootstrap is None:
+        from ksadk.api.client import AgentEngineClient
+        from ksadk.version import VERSION as CLI_VERSION
+
+        try:
+            async with AgentEngineClient(region=region) as client:
+                payload = await client.get_client_bootstrap_config(
+                    product="agentengine",
+                    framework=name,
+                    region=region,
+                    client_type="cli",
+                    client_version=CLI_VERSION,
+                    ignore_dry_run=True,
+                )
+        except Exception as exc:
+            raise ManagedRuntimeError(
+                "无法从 AgentEngine 获取 ManagedRuntime 默认版本；"
+                "请连接服务端或在 agentengine.yaml 中显式配置 runtime.version"
+            ) from exc
+        resolved = extract_bootstrap_runtime(payload, name)
+        if resolved is not None:
+            return resolved
+
+    raise ManagedRuntimeError(
+        f"AgentEngine 未下发 {name} 的默认 Runtime 版本；"
+        "请配置服务端 Runtime catalog 或显式设置 runtime.version"
+    )
+
+
+def installed_runtime_version(runtime_name: str) -> str:
+    package_name = {"codex": "openai-codex"}.get(runtime_name, runtime_name)
+    try:
+        return package_version(package_name)
+    except PackageNotFoundError:
+        return ""
+
+
+def validate_installed_runtime(resolved: ResolvedRuntime) -> str:
+    installed = installed_runtime_version(resolved.name)
+    if not installed:
+        raise ManagedRuntimeError(
+            f"本地缺少 {resolved.name} runtime；请安装 `pip install 'ksadk[{resolved.name}]'`"
+        )
+    if resolved.version and installed != resolved.version:
+        raise ManagedRuntimeError(
+            f"本地 {resolved.name} runtime 版本为 {installed}，"
+            f"配置要求 {resolved.version}；请安装匹配版本后重试"
+        )
+    validate_runtime_binary(resolved)
+    return installed
+
+
+def validate_runtime_binary(resolved: ResolvedRuntime) -> str:
+    if resolved.name != "codex":
+        return ""
+    try:
+        from codex_cli_bin import bundled_codex_path
+
+        codex_bin = bundled_codex_path()
+        completed = subprocess.run(
+            [str(codex_bin), "--version"],
+            check=True,
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+    except (ImportError, OSError, subprocess.SubprocessError) as exc:
+        raise ManagedRuntimeError(
+            "本地 Codex 平台二进制不可用；请重新安装 `pip install --force-reinstall "
+            "'ksadk[codex]'`"
+        ) from exc
+    output = f"{completed.stdout}\n{completed.stderr}".strip()
+    if resolved.version and resolved.version not in output:
+        raise ManagedRuntimeError(
+            f"Codex CLI 版本输出为 {output or '(empty)'}，配置要求 {resolved.version}"
+        )
+    return output
+
+
+async def resolve_local_managed_runtime(
+    config: dict[str, Any],
+    *,
+    region: str,
+) -> ResolvedRuntime:
+    """Resolve and verify the native runtime used by ``ksadk web``."""
+    name, requested_version = runtime_config(config)
+    if requested_version:
+        resolved = ResolvedRuntime(name=name, version=requested_version, source="manifest")
+        validate_installed_runtime(resolved)
+        return resolved
+
+    try:
+        resolved = await resolve_managed_runtime(config, region=region)
+    except ManagedRuntimeError:
+        resolved = None
+    if resolved is not None:
+        validate_installed_runtime(resolved)
+        return resolved
+
+    installed = installed_runtime_version(name)
+    if not installed:
+        raise ManagedRuntimeError(
+            f"本地缺少 {name} runtime；请安装 `pip install 'ksadk[{name}]'`"
+        )
+    resolved = ResolvedRuntime(
+        name=name,
+        version=installed,
+        source="installed-unlocked",
+    )
+    validate_runtime_binary(resolved)
+    return resolved

ksadk/markdown.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 from typing import Any
 
-
 _FENCE_MARKER_CHARS = ("`", "~")
 _LIST_PREFIXES = ("- ", "* ", "+ ")
 
@@ -157,7 +156,11 @@ def _is_closing_fence(candidate: str, open_marker: str) -> bool:
 
 
 def _is_table_line(stripped_line: str) -> bool:
-    return stripped_line.startswith("|") and stripped_line.endswith("|") and stripped_line.count("|") >= 2
+    return (
+        stripped_line.startswith("|")
+        and stripped_line.endswith("|")
+        and stripped_line.count("|") >= 2
+    )
 
 
 def _is_list_line(stripped_line: str) -> bool:

ksadk/mcp_runtime/__init__.py

@@ -1,18 +1,19 @@
 from __future__ import annotations
 
+import inspect
 import json
 import os
-import inspect
 from dataclasses import dataclass
-from typing import Any, Sequence
+from typing import Any, Coroutine, Sequence, cast
 from urllib.parse import urlparse
 
 import httpx
-from google.adk.tools.mcp_tool.mcp_session_manager import (
+
+from ksadk.compat.adk_compat import (
     CheckableMcpHttpClientFactory,
+    McpToolset,
     StreamableHTTPConnectionParams,
 )
-from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
 
 MCP_TOOLSET_KEY_ATTR = "_ksadk_mcp_toolset_key"
 
@@ -64,7 +65,9 @@ def build_connection_params(
     httpx_client_factory: CheckableMcpHttpClientFactory | None = None,
 ) -> StreamableHTTPConnectionParams:
     kwargs: dict[str, Any] = {"url": config.url, "headers": config.headers}
-    kwargs["httpx_client_factory"] = httpx_client_factory or _default_httpx_client_factory(config.url)
+    kwargs["httpx_client_factory"] = httpx_client_factory or _default_httpx_client_factory(
+        config.url
+    )
     return StreamableHTTPConnectionParams(**kwargs)
 
 
@@ -146,7 +149,7 @@ def _mcp_toolset_tools_sync(toolset: Any) -> list[Any]:
             try:
                 asyncio.get_running_loop()
             except RuntimeError:
-                result = asyncio.run(result)
+                result = asyncio.run(cast(Coroutine[Any, Any, Any], result))
             else:
                 close = getattr(result, "close", None)
                 if callable(close):

ksadk/memory/__init__.py

@@ -13,9 +13,9 @@
 
 from typing import TYPE_CHECKING
 
-from ksadk.memory.manager import MemoryManager, get_memory_manager
 from ksadk.memory.backends.base import BaseMemoryBackend
 from ksadk.memory.backends.memory import InMemoryBackend
+from ksadk.memory.manager import MemoryManager, get_memory_manager
 
 if TYPE_CHECKING:
     from ksadk.memory.service import LongTermMemoryService

ksadk/memory/adk/__init__.py

@@ -39,10 +39,12 @@ if TYPE_CHECKING:
 def __getattr__(name):
     if name == "ShortTermMemory":
         from ksadk.memory.adk.short_term_memory import ShortTermMemory
+
         return ShortTermMemory
 
     if name == "LongTermMemory":
         from ksadk.memory.adk.long_term_memory import LongTermMemory
+
         return LongTermMemory
 
     raise AttributeError(f"module 'ksadk.memory.adk' has no attribute '{name}'")

ksadk/memory/adk/backends/base_ltm_backend.py

@@ -21,9 +21,7 @@ class BaseLongTermMemoryBackend(ABC, BaseModel):
     index: str = ""
 
     @abstractmethod
-    def save_memory(
-        self, user_id: str, event_strings: List[str], **kwargs
-    ) -> bool:
+    def save_memory(self, user_id: str, event_strings: List[str], **kwargs) -> bool:
         """保存记忆
 
         Args:
@@ -36,9 +34,7 @@ class BaseLongTermMemoryBackend(ABC, BaseModel):
         pass
 
     @abstractmethod
-    def search_memory(
-        self, user_id: str, query: str, top_k: int = 5, **kwargs
-    ) -> List[str]:
+    def search_memory(self, user_id: str, query: str, top_k: int = 5, **kwargs) -> List[str]:
         """检索记忆
 
         Args:

ksadk/memory/adk/backends/http_ltm_backend.py

@@ -12,7 +12,7 @@ import logging
 from typing import List, Optional
 
 import httpx
-from pydantic import ConfigDict, Field
+from pydantic import ConfigDict
 
 from ksadk.memory.adk.backends.base_ltm_backend import BaseLongTermMemoryBackend
 
@@ -52,12 +52,10 @@ class HttpLTMBackend(BaseLongTermMemoryBackend):
     def model_post_init(self, __context) -> None:
         if not self.base_url:
             logger.warning(
-                "HttpLTMBackend: base_url is empty. "
-                "Set KSADK_LTM_HTTP_URL environment variable."
+                "HttpLTMBackend: base_url is empty. " "Set KSADK_LTM_HTTP_URL environment variable."
             )
         logger.info(
-            f"HttpLTMBackend initialized: base_url={self.base_url[:50]}... "
-            f"index={self.index}"
+            f"HttpLTMBackend initialized: base_url={self.base_url[:50]}... " f"index={self.index}"
         )
 
     @property
@@ -75,9 +73,7 @@ class HttpLTMBackend(BaseLongTermMemoryBackend):
             )
         return self._client
 
-    def save_memory(
-        self, user_id: str, event_strings: List[str], **kwargs
-    ) -> bool:
+    def save_memory(self, user_id: str, event_strings: List[str], **kwargs) -> bool:
         """保存记忆到远程服务
 
         TODO: 对接金山云记忆服务 API
@@ -105,24 +101,20 @@ class HttpLTMBackend(BaseLongTermMemoryBackend):
             response.raise_for_status()
 
             logger.info(
-                f"Saved {len(event_strings)} events to remote memory service "
-                f"for user={user_id}"
+                f"Saved {len(event_strings)} events to remote memory service " f"for user={user_id}"
             )
             return True
 
         except httpx.HTTPStatusError as e:
             logger.error(
-                f"HTTP error saving memory: {e.response.status_code} "
-                f"{e.response.text[:200]}"
+                f"HTTP error saving memory: {e.response.status_code} " f"{e.response.text[:200]}"
             )
             return False
         except Exception as e:
             logger.error(f"Error saving memory to remote service: {e}")
             return False
 
-    def search_memory(
-        self, user_id: str, query: str, top_k: int = 5, **kwargs
-    ) -> List[str]:
+    def search_memory(self, user_id: str, query: str, top_k: int = 5, **kwargs) -> List[str]:
         """从远程服务检索记忆
 
         TODO: 对接金山云记忆服务 API
@@ -140,9 +132,7 @@ class HttpLTMBackend(BaseLongTermMemoryBackend):
             }
         """
         if not self.base_url:
-            logger.warning(
-                "HttpLTMBackend: base_url not configured, return empty results."
-            )
+            logger.warning("HttpLTMBackend: base_url not configured, return empty results.")
             return []
 
         try:
@@ -158,7 +148,10 @@ class HttpLTMBackend(BaseLongTermMemoryBackend):
             response.raise_for_status()
 
             data = response.json()
-            memories = data.get("memories", [])
+            raw_memories = data.get("memories", [])
+            memories = (
+                [str(memory) for memory in raw_memories] if isinstance(raw_memories, list) else []
+            )
 
             logger.info(
                 f"Retrieved {len(memories)} memories from remote service "
@@ -168,8 +161,7 @@ class HttpLTMBackend(BaseLongTermMemoryBackend):
 
         except httpx.HTTPStatusError as e:
             logger.error(
-                f"HTTP error searching memory: {e.response.status_code} "
-                f"{e.response.text[:200]}"
+                f"HTTP error searching memory: {e.response.status_code} " f"{e.response.text[:200]}"
             )
             return []
         except Exception as e:

ksadk/memory/adk/backends/inmemory_ltm_backend.py

@@ -8,6 +8,8 @@ import logging
 from collections import defaultdict
 from typing import List
 
+from pydantic import PrivateAttr
+
 from ksadk.memory.adk.backends.base_ltm_backend import BaseLongTermMemoryBackend
 
 logger = logging.getLogger(__name__)
@@ -27,19 +29,13 @@ class InMemoryLTMBackend(BaseLongTermMemoryBackend):
         ```
     """
 
-    # Pydantic v2 不允许直接声明 mutable default，使用 model_post_init
-    _storage: dict = None
+    _storage: defaultdict[str, list[str]] = PrivateAttr(default_factory=lambda: defaultdict(list))
 
     def model_post_init(self, __context) -> None:
         # {user_id: [event_string, ...]}
-        self._storage = defaultdict(list)
-        logger.info(
-            f"InMemoryLTMBackend initialized: index={self.index}"
-        )
+        logger.info(f"InMemoryLTMBackend initialized: index={self.index}")
 
-    def save_memory(
-        self, user_id: str, event_strings: List[str], **kwargs
-    ) -> bool:
+    def save_memory(self, user_id: str, event_strings: List[str], **kwargs) -> bool:
         """保存记忆到内存"""
         if not event_strings:
             return True
@@ -51,9 +47,7 @@ class InMemoryLTMBackend(BaseLongTermMemoryBackend):
         )
         return True
 
-    def search_memory(
-        self, user_id: str, query: str, top_k: int = 5, **kwargs
-    ) -> List[str]:
+    def search_memory(self, user_id: str, query: str, top_k: int = 5, **kwargs) -> List[str]:
         """基于关键词匹配检索记忆
 
         简单实现：对 query 分词后，按匹配关键词数量排序。
@@ -68,7 +62,7 @@ class InMemoryLTMBackend(BaseLongTermMemoryBackend):
         # 按字符分词（支持中英文混合）
         query_terms = query_lower.split()
 
-        scored = []
+        scored: list[tuple[int, str]] = []
         for memory in user_memories:
             memory_lower = memory.lower()
             # 计算匹配分数：完整 query 匹配得高分，部分关键词匹配得低分

ksadk/memory/adk/backends/sdk_ltm_backend.py

@@ -105,9 +105,13 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             return self._aicp_client
 
         try:
-            from ksyun.common import credential
-            from ksyun.common.profile.client_profile import ClientProfile
-            from ksyun.common.profile.http_profile import HttpProfile
+            from ksyun.common import credential  # type: ignore[import-untyped]
+            from ksyun.common.profile.client_profile import (  # type: ignore[import-untyped]
+                ClientProfile,
+            )
+            from ksyun.common.profile.http_profile import (  # type: ignore[import-untyped]
+                HttpProfile,
+            )
         except ImportError:
             raise ImportError(
                 "kingsoftcloud-sdk-python is required for SDK memory backend. "
@@ -144,9 +148,7 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
         client_profile = ClientProfile()
         client_profile.httpProfile = http_profile
 
-        self._aicp_client = aicp_module.AicpClient(
-            cred, self.region, profile=client_profile
-        )
+        self._aicp_client = aicp_module.AicpClient(cred, self.region, profile=client_profile)
 
         # 强制覆写 API 版本为记忆库 API 所需的 2025-11-14
         self._aicp_client._apiVersion = "2025-11-14"
@@ -181,12 +183,14 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             if not text:
                 continue
 
-            conversation.append({
-                "Role": role,
-                "CreatedAt": int(time.time() * 1000),
-                "MessageId": str(uuid.uuid4()),
-                "Content": [{"Type": "input_text", "Text": text}],
-            })
+            conversation.append(
+                {
+                    "Role": role,
+                    "CreatedAt": int(time.time() * 1000),
+                    "MessageId": str(uuid.uuid4()),
+                    "Content": [{"Type": "input_text", "Text": text}],
+                }
+            )
         return conversation
 
     def _effective_memory_collection_id(self) -> str:
@@ -195,9 +199,7 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
     def _effective_scene_id(self) -> str:
         return self.scene_id or DEFAULT_SCENE_ID
 
-    def save_memory(
-        self, user_id: str, event_strings: list[str], **kwargs
-    ) -> bool:
+    def save_memory(self, user_id: str, event_strings: list[str], **kwargs) -> bool:
         """调用 CreateMemorySdk 写入记忆
 
         Args:
@@ -221,7 +223,10 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
                 logger.info("No valid conversation items to save")
                 return True
 
-            metadata = kwargs.get("metadata") if isinstance(kwargs.get("metadata"), dict) else {}
+            metadata_value = kwargs.get("metadata")
+            metadata: dict[str, Any] = (
+                dict(metadata_value) if isinstance(metadata_value, dict) else {}
+            )
             agent_id = metadata.get("agent_id") or self.agent_id
             session_id = metadata.get("session_id") or kwargs.get("session_id")
             params = {
@@ -241,9 +246,7 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
                 f"user_id={user_id}, messages={len(conversation)}"
             )
 
-            response = client.call(
-                "CreateMemorySdk", params, options={"IsPostJson": True}
-            )
+            response = client.call("CreateMemorySdk", params, options={"IsPostJson": True})
             self.last_create_response = self._parse_json_response(response) or {}
             self.last_session_status = {
                 "SessionId": session_id,
@@ -252,8 +255,7 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             }
 
             logger.info(
-                f"Saved {len(conversation)} messages to AICP memory service "
-                f"for user={user_id}"
+                f"Saved {len(conversation)} messages to AICP memory service " f"for user={user_id}"
             )
             return True
 
@@ -262,9 +264,7 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
             logger.error(f"CreateMemorySdk failed: {e}")
             return False
 
-    def search_memory(
-        self, user_id: str, query: str, top_k: int = 5, **kwargs
-    ) -> list[str]:
+    def search_memory(self, user_id: str, query: str, top_k: int = 5, **kwargs) -> list[str]:
         """调用 QueryMemorySdk 检索记忆
 
         Args:
@@ -306,9 +306,7 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
                 f"user_id={user_id}, query='{query[:50]}'"
             )
 
-            response = client.call(
-                "QueryMemorySdk", params, options={"IsPostJson": True}
-            )
+            response = client.call("QueryMemorySdk", params, options={"IsPostJson": True})
 
             # 解析响应
             memories = self._parse_query_response(response)
@@ -443,12 +441,7 @@ class SdkLTMBackend(BaseLongTermMemoryBackend):
                 parsed.extend(self._parse_memory_item(memory))
             return parsed
 
-        text = (
-            item.get("Content")
-            or item.get("Text")
-            or item.get("Memory")
-            or item.get("Data")
-        )
+        text = item.get("Content") or item.get("Text") or item.get("Memory") or item.get("Data")
         if text is None:
             return []
         if isinstance(text, (dict, list)):