agentengine-sdk-python 0.6.2__py3-none-any.whl → 0.6.9__py3-none-any.whl

ksadk/tui/widgets/thinking.py

@@ -0,0 +1,110 @@
+"""
+ThinkingMessage - 思考过程组件
+
+带 spinner 动画的思考过程展示
+"""
+
+from textual.widgets import Static
+from textual.reactive import reactive
+from textual.timer import Timer
+from typing import ClassVar, Any
+from time import time
+
+from .base import MessageWidget
+
+
+class ThinkingMessage(MessageWidget):
+    """思考过程组件
+    
+    显示 AI 思考过程，支持：
+    - spinner 动画
+    - 实时计时
+    - 流式内容追加
+    - 可折叠
+    """
+    
+    DEFAULT_CSS = """
+    ThinkingMessage {
+        height: auto;
+        padding: 0 1;
+        margin: 0 0 1 0;
+        border-left: wide #7777aa;
+        color: #ffffff;
+        background: $surface;
+    }
+    
+    ThinkingMessage .thinking-header {
+        color: #cccccc;
+        width: 100%;
+    }
+    
+    ThinkingMessage .thinking-content {
+        color: #ffffff;
+        margin-left: 2;
+        width: 100%;
+    }
+
+    /* 确保所有子组件都有正确的颜色 */
+    ThinkingMessage * {
+        color: #ffffff;
+    }
+    """
+    
+    # Spinner 动画帧
+    _SPINNER_FRAMES: ClassVar[tuple[str, ...]] = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏")
+    
+    is_active: reactive[bool] = reactive(True)
+    
+    def __init__(self, content: str = "", **kwargs: Any) -> None:
+        super().__init__(content=content, **kwargs)
+        self._thinking_content = content
+        self._spinner_position = 0
+        self._start_time: float = time()
+        self._animation_timer: Timer | None = None
+        self._header_widget: Static | None = None
+        self._content_widget: Static | None = None
+    
+    def compose(self):
+        """构建思考消息布局"""
+        self._header_widget = Static("🧠 Thinking...", classes="thinking-header")
+        yield self._header_widget
+        
+        self._content_widget = Static(self._thinking_content, classes="thinking-content")
+        yield self._content_widget
+    
+    def on_mount(self) -> None:
+        """启动动画"""
+        if self.is_active:
+            self._animation_timer = self.set_interval(0.1, self._update_animation)
+    
+    def _update_animation(self) -> None:
+        """更新 spinner 动画"""
+        if not self.is_active or self._header_widget is None:
+            return
+        
+        frame = self._SPINNER_FRAMES[self._spinner_position]
+        self._spinner_position = (self._spinner_position + 1) % len(self._SPINNER_FRAMES)
+        
+        elapsed = int(time() - self._start_time)
+        self._header_widget.update(f"[bold #ffffff]{frame}[/] [italic #dddddd]Thinking... ({elapsed}s)[/]")
+    
+    async def append_content(self, delta: str) -> None:
+        """追加思考内容"""
+        self._thinking_content += delta
+        if self._content_widget:
+            self._content_widget.update(self._thinking_content)
+    
+    def stop(self) -> None:
+        """停止思考动画"""
+        self.is_active = False
+        if self._animation_timer:
+            self._animation_timer.stop()
+            self._animation_timer = None
+        
+        if self._header_widget:
+            elapsed = int(time() - self._start_time)
+            self._header_widget.update(f"[bold #ffffff]💭[/] [italic #aaaaaa]Thought for {elapsed}s[/]")
+    
+    @property
+    def thinking_content(self) -> str:
+        return self._thinking_content

ksadk/tui/widgets/tool_call.py

@@ -0,0 +1,161 @@
+"""
+ToolCallMessage - 工具调用消息组件
+
+显示 Tool Call 状态和参数。
+"""
+
+from textual.widgets import Static
+from textual.reactive import reactive
+from textual.containers import Vertical
+from typing import Any, Dict, Optional
+import json
+
+from .base import MessageWidget
+
+
+class ToolStatus:
+    """Tool Call 状态"""
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCESS = "success"
+    ERROR = "error"
+    REJECTED = "rejected"
+
+
+class ToolCallMessage(MessageWidget):
+    """工具调用消息组件
+    
+    用于显示 Tool Call 的状态和参数：
+    - pending: 等待执行（黄色）
+    - running: 执行中（蓝色动画）
+    - success: 成功（绿色）
+    - error: 失败（红色）
+    - rejected: 被拒绝（灰色）
+    """
+    
+    DEFAULT_CSS = """
+    ToolCallMessage {
+        width: 100%;
+        padding: 1;
+        margin: 0 0 1 0;
+        border: round $secondary;
+        background: $surface;
+        color: #ffffff;
+    }
+    
+    ToolCallMessage.pending {
+        border: round $warning;
+    }
+    
+    ToolCallMessage.running {
+        border: round $primary;
+    }
+    
+    ToolCallMessage.success {
+        border: round $success;
+    }
+    
+    ToolCallMessage.error {
+        border: round $error;
+    }
+    
+    ToolCallMessage.rejected {
+        border: round $surface-darken-2;
+        opacity: 0.7;
+    }
+    
+    ToolCallMessage .tool-header {
+        text-style: bold;
+        color: #ffffff;
+    }
+    
+    ToolCallMessage .tool-args {
+        color: #aaaaaa;
+        margin-left: 2;
+    }
+    
+    ToolCallMessage .tool-output {
+        margin-top: 1;
+        padding: 1;
+        background: $surface-darken-1;
+        color: #ffffff;
+    }
+    """
+    
+    status: reactive[str] = reactive(ToolStatus.PENDING)
+    output: reactive[str] = reactive("")
+    
+    def __init__(
+        self,
+        tool_name: str,
+        args: Dict[str, Any],
+        tool_id: Optional[str] = None,
+        **kwargs
+    ) -> None:
+        super().__init__(**kwargs)
+        self._tool_name = tool_name
+        self._args = args
+        self._tool_id = tool_id
+        self.add_class("pending")
+    
+    def compose(self):
+        """构建组件"""
+        status_icon = self._get_status_icon()
+        yield Static(
+            f"{status_icon} {self._tool_name}",
+            classes="tool-header"
+        )
+        
+        # 显示参数（截断过长的值）
+        args_display = self._format_args(self._args)
+        yield Static(args_display, classes="tool-args")
+        
+        # 输出区域
+        if self.output:
+            yield Static(self.output, classes="tool-output")
+    
+    def _get_status_icon(self) -> str:
+        """获取状态图标"""
+        icons = {
+            ToolStatus.PENDING: "⏳",
+            ToolStatus.RUNNING: "🔄",
+            ToolStatus.SUCCESS: "✅",
+            ToolStatus.ERROR: "❌",
+            ToolStatus.REJECTED: "🚫",
+        }
+        return icons.get(self.status, "⏳")
+    
+    def _format_args(self, args: Dict[str, Any], max_len: int = 100) -> str:
+        """格式化参数显示"""
+        try:
+            args_str = json.dumps(args, ensure_ascii=False, indent=2)
+            if len(args_str) > max_len:
+                args_str = args_str[:max_len] + "..."
+            return args_str
+        except Exception:
+            return str(args)[:max_len]
+    
+    def _update_status(self, new_status: str) -> None:
+        """更新状态"""
+        self.remove_class(self.status)
+        self.status = new_status
+        self.add_class(new_status)
+        self.refresh()
+    
+    def set_running(self) -> None:
+        """设置为运行中"""
+        self._update_status(ToolStatus.RUNNING)
+    
+    def set_success(self, output: str = "") -> None:
+        """设置为成功"""
+        self.output = output
+        self._update_status(ToolStatus.SUCCESS)
+    
+    def set_error(self, error: str = "") -> None:
+        """设置为失败"""
+        self.output = f"Error: {error}"
+        self._update_status(ToolStatus.ERROR)
+    
+    def set_rejected(self) -> None:
+        """设置为被拒绝"""
+        self._update_status(ToolStatus.REJECTED)

ksadk/tui/widgets/user.py

@@ -0,0 +1,37 @@
+"""
+UserMessage - 用户消息组件
+"""
+
+from textual.widgets import Static
+from rich.text import Text
+from typing import Any
+
+from .base import MessageWidget
+
+
+class UserMessage(MessageWidget):
+    """用户消息组件
+    
+    显示用户输入，左边框绿色
+    """
+    
+    DEFAULT_CSS = """
+    UserMessage {
+        height: auto;
+        padding: 0 1;
+        margin: 1 0 0 0;
+        background: transparent;
+        border-left: wide #10b981;
+    }
+    """
+
+    def __init__(self, content: str, **kwargs: Any) -> None:
+        super().__init__(content=content, **kwargs)
+        self._content = content
+
+    def compose(self):
+        """构建用户消息布局"""
+        text = Text()
+        text.append("> ", style="bold #10b981")
+        text.append(self._content, style="#ffffff")
+        yield Static(text)

ksadk/ui_config.py

@@ -0,0 +1,168 @@
+"""UI configuration helpers shared by CLI, deployment, and runtime."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple
+from urllib.parse import urlsplit
+
+
+UI_PROFILE_AUTO = "auto"
+UI_PROFILE_ADK = "adk"
+UI_PROFILE_LANGCHAIN = "langchain"
+UI_PROFILE_OPENCLAW = "openclaw"
+UI_PROFILE_HERMES = "hermes"
+UI_PROFILE_CUSTOM = "custom"
+
+SUPPORTED_UI_PROFILES = (
+    UI_PROFILE_AUTO,
+    UI_PROFILE_ADK,
+    UI_PROFILE_LANGCHAIN,
+    UI_PROFILE_OPENCLAW,
+    UI_PROFILE_HERMES,
+    UI_PROFILE_CUSTOM,
+)
+
+
+_FRAMEWORK_TO_PROFILE = {
+    "adk": UI_PROFILE_ADK,
+    "langchain": UI_PROFILE_LANGCHAIN,
+    "langgraph": UI_PROFILE_LANGCHAIN,
+    "deepagents": UI_PROFILE_LANGCHAIN,
+    "openclaw": UI_PROFILE_OPENCLAW,
+    "hermes": UI_PROFILE_HERMES,
+}
+
+_DEFAULT_PATH_BY_PROFILE = {
+    UI_PROFILE_ADK: "/chat",
+    UI_PROFILE_LANGCHAIN: "/chat",
+    UI_PROFILE_OPENCLAW: "/chat",
+    UI_PROFILE_HERMES: "/chat",
+    UI_PROFILE_CUSTOM: "/",
+}
+
+
+@dataclass(frozen=True)
+class UIConfig:
+    """Resolved UI configuration."""
+
+    profile: str
+    path: str
+    url: Optional[str] = None
+
+
+def normalize_ui_profile(profile: Optional[str], *, default: str = UI_PROFILE_AUTO) -> str:
+    value = (profile or "").strip().lower()
+    if not value:
+        return default
+    if value not in SUPPORTED_UI_PROFILES:
+        raise ValueError(f"unsupported ui_profile: {profile}")
+    return value
+
+
+def normalize_ui_path(path: Optional[str]) -> Optional[str]:
+    if path is None:
+        return None
+
+    value = path.strip()
+    if not value:
+        return None
+
+    if not value.startswith("/"):
+        value = "/" + value
+    return value
+
+
+def normalize_ui_url(url: Optional[str]) -> Optional[str]:
+    if url is None:
+        return None
+    value = url.strip()
+    return value or None
+
+
+def infer_ui_profile_from_framework(framework: Optional[str]) -> str:
+    key = (framework or "").strip().lower()
+    return _FRAMEWORK_TO_PROFILE.get(key, UI_PROFILE_ADK)
+
+
+def default_ui_path(profile: str) -> str:
+    return _DEFAULT_PATH_BY_PROFILE.get(profile, "/")
+
+
+def extract_ui_state(state: Optional[Dict[str, Any]]) -> Tuple[Optional[str], Optional[str], Optional[str]]:
+    if not isinstance(state, dict):
+        return None, None, None
+
+    nested = state.get("ui") if isinstance(state.get("ui"), dict) else {}
+
+    profile = state.get("ui_profile") or nested.get("profile")
+    path = state.get("ui_path") or nested.get("path")
+    url = state.get("ui_url") or nested.get("url")
+
+    return profile, path, url
+
+
+def resolve_ui_config(
+    *,
+    framework: Optional[str],
+    state: Optional[Dict[str, Any]],
+    cli_profile: Optional[str],
+    cli_path: Optional[str],
+    cli_url: Optional[str],
+) -> UIConfig:
+    """Merge CLI + state + framework defaults into the final UI config.
+
+    Priority:
+    1) CLI arguments
+    2) .agentengine.state
+    3) framework default
+    4) global default
+    """
+
+    state_profile, state_path, state_url = extract_ui_state(state)
+
+    profile = normalize_ui_profile(cli_profile or state_profile or UI_PROFILE_AUTO)
+    if profile == UI_PROFILE_AUTO:
+        profile = infer_ui_profile_from_framework(framework)
+
+    path = normalize_ui_path(cli_path) if cli_path is not None else normalize_ui_path(state_path)
+    url = normalize_ui_url(cli_url) if cli_url is not None else normalize_ui_url(state_url)
+
+    if profile in {UI_PROFILE_ADK, UI_PROFILE_LANGCHAIN, UI_PROFILE_OPENCLAW, UI_PROFILE_HERMES}:
+        normalized_legacy_path = (path or "").rstrip("/") or "/"
+        legacy_paths = {"/langchain"}
+        if cli_path is None:
+            legacy_paths.add("/")
+        if normalized_legacy_path in legacy_paths:
+            path = "/chat"
+
+    if not path:
+        path = default_ui_path(profile)
+    if profile == UI_PROFILE_CUSTOM and path == "/chat":
+        path = "/"
+
+    return UIConfig(profile=profile, path=path, url=url)
+
+
+def ui_config_to_state_fields(config: UIConfig) -> Dict[str, Any]:
+    return {
+        "ui_profile": config.profile,
+        "ui_path": config.path,
+        "ui_url": config.url,
+    }
+
+
+def is_same_origin(url: str, endpoint: str) -> bool:
+    if not url or not endpoint:
+        return False
+
+    left = urlsplit(url)
+    right = urlsplit(endpoint)
+
+    if not left.scheme or not left.netloc or not right.scheme or not right.netloc:
+        return False
+
+    return (left.scheme.lower(), left.netloc.lower()) == (
+        right.scheme.lower(),
+        right.netloc.lower(),
+    )

ksadk/version.py

@@ -0,0 +1,4 @@
+"""KsADK 版本信息"""
+
+VERSION = "0.6.9"
+__version__ = VERSION

ksadk_runtime_common/__init__.py

@@ -0,0 +1,20 @@
+"""Shared runtime components bundled inside ksadk-python."""
+
+__version__ = "0.1.0"
+
+from ksadk_runtime_common.workspace_files.bootstrap import (
+    build_workspace_files_bootstrap,
+    workspace_files_enabled,
+    workspace_files_max_upload_bytes,
+    workspace_files_root_label,
+)
+from ksadk_runtime_common.workspace_files.router import create_workspace_files_router
+
+__all__ = [
+    "__version__",
+    "create_workspace_files_router",
+    "build_workspace_files_bootstrap",
+    "workspace_files_enabled",
+    "workspace_files_root_label",
+    "workspace_files_max_upload_bytes",
+]

ksadk_runtime_common/memory_backend/__init__.py

@@ -0,0 +1,29 @@
+"""Memory backend manifest parsing and config rendering helpers."""
+
+from ksadk_runtime_common.memory_backend.manifest import (
+    MemoryBackendManifest,
+    parse_manifest,
+)
+from ksadk_runtime_common.memory_backend.registry import (
+    RenderResult,
+    get_provider,
+    list_providers,
+    register_provider,
+)
+from ksadk_runtime_common.memory_backend.render import (
+    MANIFEST_ENV_VAR,
+    render_memory_backend_config,
+    render_to_json,
+)
+
+__all__ = [
+    "MemoryBackendManifest",
+    "parse_manifest",
+    "render_memory_backend_config",
+    "render_to_json",
+    "MANIFEST_ENV_VAR",
+    "RenderResult",
+    "register_provider",
+    "get_provider",
+    "list_providers",
+]

ksadk_runtime_common/memory_backend/manifest.py

@@ -0,0 +1,79 @@
+"""Memory backend manifest model validated against the bundled JSON Schema."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Literal
+
+from jsonschema import Draft202012Validator
+from jsonschema import ValidationError as JsonSchemaValidationError
+from pydantic import BaseModel, Field
+
+_SCHEMA_PATH = Path(__file__).parent.parent / "schemas" / "memory_backend_manifest.schema.json"
+
+
+class MemoryBackendManifest(BaseModel):
+    """Memory backend manifest for OpenClaw runtime."""
+
+    schema_version: Literal["v1"] = "v1"
+    backend_type: Literal["openclaw_default", "mem0", "lancedb"]
+    config: dict[str, Any] = Field(default_factory=dict)
+    secrets_env: dict[str, str] = Field(default_factory=dict)
+
+
+@lru_cache(maxsize=1)
+def _schema_validator() -> Draft202012Validator:
+    """Build and cache the canonical JSON Schema validator."""
+    schema = json.loads(_SCHEMA_PATH.read_text(encoding="utf-8"))
+    Draft202012Validator.check_schema(schema)
+    return Draft202012Validator(
+        schema,
+        format_checker=Draft202012Validator.FORMAT_CHECKER,
+    )
+
+
+def _format_schema_error(error: JsonSchemaValidationError) -> str:
+    """Format schema validation errors with a stable dotted path."""
+    location = ".".join(str(part) for part in error.absolute_path) or "<root>"
+    return f"Invalid manifest at '{location}': {error.message}"
+
+
+def _validate_against_schema(data: object) -> dict[str, Any]:
+    """Validate a raw manifest payload against the bundled JSON Schema."""
+    errors = sorted(
+        _schema_validator().iter_errors(data),
+        key=lambda error: error.json_path,
+    )
+    if errors:
+        first_error = errors[0]
+        raise ValueError(_format_schema_error(first_error)) from first_error
+    if not isinstance(data, Mapping):
+        raise ValueError("Invalid manifest at '<root>': manifest must be an object")
+    return dict(data)
+
+
+def parse_manifest(
+    raw: MemoryBackendManifest | str | Mapping[str, Any] | None,
+) -> MemoryBackendManifest | None:
+    """Parse a memory backend manifest from model, JSON string, or mapping."""
+    if raw is None:
+        return None
+
+    if isinstance(raw, MemoryBackendManifest):
+        data: object = raw.model_dump(mode="python")
+    elif isinstance(raw, str):
+        raw = raw.strip()
+        if not raw:
+            return None
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON: {e}") from e
+    else:
+        data = dict(raw)
+
+    validated = _validate_against_schema(data)
+    return MemoryBackendManifest.model_validate(validated)

ksadk_runtime_common/memory_backend/providers/__init__.py

@@ -0,0 +1,6 @@
+"""Memory backend providers package."""
+
+from ksadk_runtime_common.memory_backend.providers.lancedb import LanceDBProvider
+from ksadk_runtime_common.memory_backend.providers.mem0 import Mem0Provider
+
+__all__ = ["LanceDBProvider", "Mem0Provider"]