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

ksadk/tui/stream_render.py

@@ -0,0 +1,68 @@
+"""TUI 流式渲染共享纯函数。
+
+从 RemoteRunner.stream 的归一化 chunk 提取 delta/usage/终止信号，格式化 usage 文本。
+被 loop.py（交互 TUI）和 cmd_invoke._invoke_once（-m 单次）共用，保证两路径渲染口径一致。
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+
+def clean_response(text: str) -> str:
+    """清理 LLM 响应中的内部调试伪影。
+
+    只删内部调试残留（Tool Result 标记、python repr 片段、tool_call_id），
+    不动正常的 XML/HTML 标签（用户可能需要 <tag> 输出）。
+    """
+    text = re.sub(r"\[Tool Result:.*?\]", "", text, flags=re.DOTALL)
+    text = re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL)
+    text = re.sub(r"name='[^']*'\s*tool_call_id='[^']*'", "", text)
+    return text.strip()
+
+
+def extract_stream_delta(chunk: dict) -> tuple[str, dict | None, bool]:
+    """从 RemoteRunner.stream 的 chunk 提取 (delta 文本, usage, 是否终止信号)。
+
+    - text/thinking 等普通 chunk：取 delta，非终止。
+    - final（chat 路径结束，output=完整文本）/ responses_output（responses 路径
+      response.completed，output=list）：只取 usage，不把 output 当 delta——
+      否则末尾会把完整文本或 list 再 append 一遍（重复/乱码）。
+    """
+    chunk_type = str(chunk.get("type") or "text")
+    if chunk_type in {"final", "responses_output"}:
+        usage = chunk.get("usage")
+        usage = dict(usage) if isinstance(usage, dict) else None
+        # terminal chunk 可能带 metadata.last_usage（上下文用量），合并进 usage
+        # 让 TUI 能显示 context 占比，不丢这条 metadata。
+        metadata = chunk.get("metadata")
+        if isinstance(metadata, dict) and isinstance(metadata.get("last_usage"), dict):
+            if usage is None:
+                usage = {}
+            usage.setdefault("last_usage", dict(metadata["last_usage"]))
+        return "", (usage or None), True
+    delta = chunk.get("delta") or ""
+    if not isinstance(delta, str):
+        delta = str(delta or "")
+    return delta, None, False
+
+
+def format_usage(usage: Optional[dict[str, Any]]) -> str:
+    """把 usage dict 格式成紧凑文本：↑输入 ↓输出 ⌀总计。
+
+    兼容 input_tokens/output_tokens（chat 路径）与 prompt_tokens/completion_tokens
+    （responses 路径）两种字段名。
+    """
+    if not isinstance(usage, dict) or not usage:
+        return ""
+    inp = usage.get("input_tokens") or usage.get("prompt_tokens")
+    out = usage.get("output_tokens") or usage.get("completion_tokens")
+    total = usage.get("total_tokens")
+    parts = []
+    if inp:
+        parts.append(f"↑{inp}")
+    if out:
+        parts.append(f"↓{out}")
+    if total:
+        parts.append(f"⌀{total}")
+    return " ".join(parts)

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.7.0"
+__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"]

ksadk_runtime_common/memory_backend/providers/lancedb.py

@@ -0,0 +1,151 @@
+"""LanceDB memory backend provider."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ksadk_runtime_common.memory_backend.manifest import MemoryBackendManifest
+from ksadk_runtime_common.memory_backend.registry import RenderResult
+
+
+class LanceDBProvider:
+    """Provider for the in-process LanceDB OpenClaw memory plugin."""
+
+    def render(self, manifest: MemoryBackendManifest) -> RenderResult:
+        """Render LanceDB plugin config for OpenClaw.
+
+        Maps the platform manifest config fields onto the memory-lancedb
+        plugin schema. This must stay in sync with the inline renderer in
+        ``deploy/openclaw/bootstrap.sh`` so both code paths produce the same
+        plugin entry.
+        """
+        entry: dict[str, Any] = {"enabled": True}
+        config = self._render_plugin_config(manifest.config or {})
+        if config:
+            entry["config"] = config
+
+        return RenderResult(
+            backend_type="lancedb",
+            config_patch={
+                "plugins": {
+                    "slots": {
+                        "memory": "memory-lancedb",
+                    },
+                    "entries": {
+                        "memory-lancedb": entry,
+                    },
+                },
+            },
+            plugin_ids=["memory-lancedb"],
+            disabled_plugin_ids=["openclaw-mem0"],
+        )
+
+    @staticmethod
+    def _first(config: dict[str, Any], *keys: str) -> Any:
+        for key in keys:
+            value = config.get(key)
+            if isinstance(value, str):
+                value = value.strip()
+                if value:
+                    return value
+            elif value is not None:
+                return value
+        return None
+
+    @classmethod
+    def _render_plugin_config(cls, config: dict[str, Any]) -> dict[str, Any]:
+        if not config:
+            return {}
+
+        output: dict[str, Any] = {}
+
+        embedding: dict[str, Any] = {}
+        for target_key, *source_keys in (
+            ("provider", "provider", "embedding_provider"),
+            ("model", "model", "embedding_model"),
+            ("apiKey", "apiKey", "api_key", "embedding_api_key"),
+            ("baseUrl", "baseUrl", "base_url", "embedding_base_url"),
+        ):
+            value = cls._first(config, *source_keys)
+            if value is not None:
+                embedding[target_key] = value
+        dimensions = cls._first(
+            config, "dimensions", "embedding_dimensions"
+        )
+        if isinstance(dimensions, int) or (
+            isinstance(dimensions, str) and dimensions.strip().isdigit()
+        ):
+            embedding["dimensions"] = int(dimensions)
+        if embedding:
+            output["embedding"] = embedding
+
+        db_path = cls._first(
+            config, "dbPath", "db_path", "data_path",
+            "database_uri", "databaseUri", "database_url",
+        )
+        if db_path is not None:
+            output["dbPath"] = db_path
+
+        for target_key, *source_keys in (
+            ("autoCapture", "autoCapture", "auto_capture"),
+            ("autoRecall", "autoRecall", "auto_recall"),
+        ):
+            value = cls._first(config, *source_keys)
+            if isinstance(value, bool):
+                output[target_key] = value
+            elif isinstance(value, str):
+                normalized = value.strip().lower()
+                if normalized in {"1", "true", "yes", "on"}:
+                    output[target_key] = True
+                elif normalized in {"0", "false", "no", "off"}:
+                    output[target_key] = False
+
+        for target_key, *source_keys in (
+            ("captureMaxChars", "captureMaxChars", "capture_max_chars"),
+            ("recallMaxChars", "recallMaxChars", "recall_max_chars"),
+        ):
+            value = cls._first(config, *source_keys)
+            if isinstance(value, int) and not isinstance(value, bool):
+                output[target_key] = value
+            elif isinstance(value, str) and value.strip().lstrip("-").isdigit():
+                output[target_key] = int(value)
+
+        custom_triggers = config.get("customTriggers", config.get("custom_triggers"))
+        if isinstance(custom_triggers, list):
+            output["customTriggers"] = custom_triggers
+
+        for target_key, *source_keys in (
+            ("dreaming", "dreaming"),
+            ("storageOptions", "storageOptions", "storage_options"),
+        ):
+            value = cls._first(config, *source_keys)
+            if isinstance(value, dict):
+                output[target_key] = value
+
+        storage_options = output.get("storageOptions")
+        if not isinstance(storage_options, dict):
+            storage_options = {}
+        for target_key, *source_keys in (
+            ("endpoint", "storage_endpoint", "storageEndpoint"),
+            ("region", "storage_region", "storageRegion"),
+            ("bucket", "storage_bucket", "storageBucket"),
+            ("prefix", "storage_prefix", "storagePrefix"),
+            ("accessKeyId", "storage_access_key_id", "storageAccessKeyId"),
+            ("secretAccessKey", "storage_secret_access_key", "storageSecretAccessKey"),
+        ):
+            value = cls._first(config, *source_keys)
+            if value is not None:
+                storage_options[target_key] = value
+        allow_http = cls._first(config, "storage_allow_http", "storageAllowHttp")
+        if isinstance(allow_http, bool):
+            storage_options["allowHttp"] = "true" if allow_http else "false"
+        elif isinstance(allow_http, str):
+            normalized = allow_http.strip().lower()
+            if normalized in {"1", "true", "yes", "on"}:
+                storage_options["allowHttp"] = "true"
+            elif normalized in {"0", "false", "no", "off"}:
+                storage_options["allowHttp"] = "false"
+        if storage_options:
+            output["storageOptions"] = storage_options
+
+        return output

ksadk_runtime_common/memory_backend/providers/mem0.py

@@ -0,0 +1,74 @@
+"""Mem0 memory backend provider."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ksadk_runtime_common.memory_backend.manifest import MemoryBackendManifest
+from ksadk_runtime_common.memory_backend.registry import RenderResult
+
+
+def _resolve_env_name(secrets_env: dict[str, str], key: str, default: str) -> str:
+    """Resolve an env var name from secrets_env, falling back to a default."""
+    return str(secrets_env.get(key) or default).strip() or default
+
+
+def _require_env(name: str) -> None:
+    """Require a non-empty environment variable in the current process."""
+    if not str(os.getenv(name) or "").strip():
+        raise ValueError(f"mem0 backend requires environment variable '{name}'")
+
+
+def _require_env_value(name: str) -> str:
+    """Return a required env var value after validating it is non-empty."""
+    _require_env(name)
+    return str(os.getenv(name) or "").strip()
+
+
+class Mem0Provider:
+    """Provider for the mem0 memory backend."""
+
+    def render(self, manifest: MemoryBackendManifest) -> RenderResult:
+        """Render mem0 config for OpenClaw."""
+        config = manifest.config
+        secrets_env = manifest.secrets_env
+
+        mem0_instance_id = config.get("mem0_instance_id")
+        if not mem0_instance_id:
+            raise ValueError("mem0 backend requires 'mem0_instance_id' in config")
+
+        api_key_env = _resolve_env_name(secrets_env, "api_key", "MEM0_API_KEY")
+        user_id_env = _resolve_env_name(secrets_env, "user_id", "MEM0_USER_ID")
+        base_url_env = _resolve_env_name(secrets_env, "base_url", "MEM0_BASE_URL")
+
+        required_env = [api_key_env, user_id_env, base_url_env]
+        api_key = _require_env_value(api_key_env)
+        user_id = _require_env_value(user_id_env)
+        base_url = _require_env_value(base_url_env)
+
+        config_patch: dict[str, Any] = {
+            "plugins": {
+                "slots": {
+                    "memory": "openclaw-mem0",
+                },
+                "entries": {
+                    "openclaw-mem0": {
+                        "enabled": True,
+                        "config": {
+                            "mode": "platform",
+                            "apiKey": api_key,
+                            "baseUrl": base_url,
+                            "userId": user_id,
+                        },
+                    },
+                },
+            },
+        }
+
+        return RenderResult(
+            backend_type="mem0",
+            config_patch=config_patch,
+            required_env=required_env,
+            plugin_ids=["openclaw-mem0"],
+        )

ksadk_runtime_common/memory_backend/registry.py

@@ -0,0 +1,56 @@
+"""Memory backend provider registry."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from pydantic import BaseModel, Field
+
+from ksadk_runtime_common.memory_backend.manifest import MemoryBackendManifest
+
+
+class RenderResult(BaseModel):
+    """Result from rendering a memory backend config."""
+
+    backend_type: str
+    config_patch: dict[str, Any] = Field(default_factory=dict)
+    required_env: list[str] = Field(default_factory=list)
+    plugin_ids: list[str] = Field(default_factory=list)
+    disabled_plugin_ids: list[str] = Field(default_factory=list)
+    clear_plugin_slots: list[str] = Field(default_factory=list)
+
+
+class ProviderProtocol(Protocol):
+    """Protocol for memory backend providers."""
+
+    def render(self, manifest: MemoryBackendManifest) -> RenderResult: ...
+
+
+_PROVIDERS: dict[str, ProviderProtocol] = {}
+
+
+def register_provider(backend_type: str, provider: ProviderProtocol) -> None:
+    """Register a memory backend provider."""
+    _PROVIDERS[backend_type] = provider
+
+
+def get_provider(backend_type: str) -> ProviderProtocol | None:
+    """Get a registered provider by backend type."""
+    return _PROVIDERS.get(backend_type)
+
+
+def list_providers() -> list[str]:
+    """List registered backend type identifiers."""
+    return list(_PROVIDERS.keys())
+
+
+def _register_builtin_providers() -> None:
+    """Register providers shipped in this repo copy."""
+    from ksadk_runtime_common.memory_backend.providers.mem0 import Mem0Provider
+    from ksadk_runtime_common.memory_backend.providers.lancedb import LanceDBProvider
+
+    register_provider("mem0", Mem0Provider())
+    register_provider("lancedb", LanceDBProvider())
+
+
+_register_builtin_providers()