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

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()

ksadk_runtime_common/memory_backend/render.py

@@ -0,0 +1,71 @@
+"""Memory backend config renderer for runtime bootstrap integration."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from typing import Any
+
+from ksadk_runtime_common.memory_backend.manifest import (
+    MemoryBackendManifest,
+    parse_manifest,
+)
+from ksadk_runtime_common.memory_backend.registry import (
+    RenderResult,
+    get_provider,
+)
+
+MANIFEST_ENV_VAR = "MEMORY_BACKEND_MANIFEST"
+MEMORY_BACKEND_PLUGIN_IDS = ["openclaw-mem0", "memory-lancedb"]
+MEMORY_BACKEND_PLUGIN_SLOTS = ["memory"]
+
+
+def render_memory_backend_config(
+    manifest: MemoryBackendManifest | str | Mapping[str, Any] | None = None,
+) -> RenderResult:
+    """Render memory backend config from a manifest."""
+    if manifest is None:
+        manifest_raw = os.getenv(MANIFEST_ENV_VAR)
+        if not manifest_raw:
+            return RenderResult(
+                backend_type="openclaw_default",
+                config_patch={},
+                required_env=[],
+                plugin_ids=[],
+            )
+        manifest = manifest_raw
+
+    parsed = parse_manifest(manifest)
+    if parsed is None:
+        return RenderResult(
+            backend_type="openclaw_default",
+            config_patch={},
+            required_env=[],
+            plugin_ids=[],
+        )
+
+    if parsed.backend_type == "openclaw_default":
+        return RenderResult(
+            backend_type="openclaw_default",
+            config_patch={},
+            required_env=[],
+            disabled_plugin_ids=MEMORY_BACKEND_PLUGIN_IDS,
+            clear_plugin_slots=MEMORY_BACKEND_PLUGIN_SLOTS,
+        )
+
+    provider = get_provider(parsed.backend_type)
+    if provider is None:
+        raise ValueError(f"Unknown backend_type: {parsed.backend_type}")
+
+    return provider.render(parsed)
+
+
+def render_to_json(manifest: MemoryBackendManifest | str | dict[str, Any] | None = None) -> str:
+    """Render memory backend config to a JSON string."""
+    result = render_memory_backend_config(manifest)
+    return json.dumps(result.model_dump())
+
+
+if __name__ == "__main__":
+    print(render_to_json())

ksadk_runtime_common/schemas/memory_backend_manifest.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kingsoftcloud.github.io/ksadk-python/schemas/memory_backend_manifest/v1",
+  "title": "MemoryBackendManifest",
+  "description": "Memory backend manifest for OpenClaw runtime configuration.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "backend_type"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "v1",
+      "description": "Schema version identifier. Must be 'v1'."
+    },
+    "backend_type": {
+      "type": "string",
+      "enum": [
+        "openclaw_default",
+        "mem0",
+        "lancedb"
+      ],
+      "description": "Memory backend type. Supports 'openclaw_default', 'mem0', and 'lancedb'."
+    },
+    "config": {
+      "type": "object",
+      "description": "Backend-specific configuration.",
+      "additionalProperties": true,
+      "properties": {
+        "mem0_instance_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Mem0 instance UUID (required when backend_type is 'mem0')."
+        },
+        "mem0_instance_name": {
+          "type": "string",
+          "description": "Mem0 instance display name."
+        },
+        "mem0_region": {
+          "type": "string",
+          "description": "Mem0 instance region."
+        },
+        "dbPath": {
+          "type": "string",
+          "description": "Optional LanceDB plugin dbPath override."
+        },
+        "database_uri": {
+          "type": "string",
+          "description": "Database URI for LanceDB storage (e.g. s3://bucket/prefix). Mapped to dbPath when dbPath is absent."
+        },
+        "embedding": {
+          "type": "object",
+          "description": "Optional LanceDB plugin embedding configuration.",
+          "additionalProperties": true
+        },
+        "embedding_provider": {
+          "type": "string",
+          "description": "Embedding provider for LanceDB (e.g. openai)."
+        },
+        "embedding_model": {
+          "type": "string",
+          "description": "Embedding model name for LanceDB."
+        },
+        "embedding_dimensions": {
+          "type": "integer",
+          "description": "Embedding vector dimensions for LanceDB."
+        },
+        "embedding_base_url": {
+          "type": "string",
+          "description": "Embedding provider base URL for LanceDB."
+        },
+        "storageOptions": {
+          "type": "object",
+          "description": "Optional LanceDB plugin storage options.",
+          "additionalProperties": true
+        },
+        "storage_endpoint": {
+          "type": "string",
+          "description": "S3-compatible storage endpoint URL. Mapped into storageOptions.endpoint."
+        },
+        "storage_region": {
+          "type": "string",
+          "description": "S3-compatible storage region. Mapped into storageOptions.region."
+        },
+        "storage_bucket": {
+          "type": "string",
+          "description": "S3-compatible storage bucket. Mapped into storageOptions.bucket."
+        },
+        "storage_prefix": {
+          "type": "string",
+          "description": "S3-compatible storage key prefix. Mapped into storageOptions.prefix."
+        },
+        "storage_access_key_id": {
+          "type": "string",
+          "description": "S3-compatible storage access key id. Mapped into storageOptions.accessKeyId."
+        },
+        "storage_secret_access_key": {
+          "type": "string",
+          "description": "S3-compatible storage secret access key. Mapped into storageOptions.secretAccessKey."
+        },
+        "storage_allow_http": {
+          "type": ["boolean", "string"],
+          "description": "Allow plain HTTP for S3-compatible storage. Mapped into storageOptions.allowHttp as a string (\"true\"/\"false\")."
+        }
+      }
+    },
+    "secrets_env": {
+      "type": "object",
+      "description": "Environment variable names for secrets. Values are env var names, not actual secrets.",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "properties": {
+        "api_key": {
+          "type": "string",
+          "description": "Environment variable name for API key (e.g., 'MEM0_API_KEY')."
+        },
+        "memory_id": {
+          "type": "string",
+          "description": "Environment variable name for memory ID (e.g., 'MEM0_MEMORY_ID')."
+        },
+        "embedding_api_key": {
+          "type": "string",
+          "description": "Reserved for future LanceDB embedding secrets."
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "backend_type": { "const": "mem0" }
+        }
+      },
+      "then": {
+        "required": ["config"],
+        "properties": {
+          "config": {
+            "required": ["mem0_instance_id"]
+          }
+        }
+      }
+    }
+  ]
+}

ksadk_runtime_common/workspace_files/__init__.py

@@ -0,0 +1,29 @@
+"""Workspace files module shared across bundled runtimes."""
+
+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.constants import (
+    DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES,
+    WORKSPACE_CONTENT_PATH,
+    WORKSPACE_ENTRY_ACTION,
+    WORKSPACE_PATH_ESCAPE_DETAIL,
+    WORKSPACE_UPLOAD_ACTION,
+)
+from ksadk_runtime_common.workspace_files.router import create_workspace_files_router
+
+__all__ = [
+    "create_workspace_files_router",
+    "build_workspace_files_bootstrap",
+    "workspace_files_enabled",
+    "workspace_files_root_label",
+    "workspace_files_max_upload_bytes",
+    "DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES",
+    "WORKSPACE_PATH_ESCAPE_DETAIL",
+    "WORKSPACE_ENTRY_ACTION",
+    "WORKSPACE_UPLOAD_ACTION",
+    "WORKSPACE_CONTENT_PATH",
+]

ksadk_runtime_common/workspace_files/bootstrap.py

@@ -0,0 +1,56 @@
+"""Workspace files bootstrap configuration builder."""
+
+from __future__ import annotations
+
+import os
+
+from ksadk_runtime_common.workspace_files.constants import (
+    DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES,
+    WORKSPACE_CONTENT_PATH,
+    WORKSPACE_ENTRY_ACTION,
+    WORKSPACE_UPLOAD_ACTION,
+)
+
+
+def _env_flag(name: str, default: bool) -> bool:
+    """Parse boolean environment variable."""
+    raw = str(os.getenv(name, "")).strip().lower()
+    if not raw:
+        return default
+    return raw in {"1", "true", "yes", "on"}
+
+
+def workspace_files_enabled(*, default: bool = True) -> bool:
+    """Check if workspace files feature is enabled."""
+    return _env_flag("KSADK_WORKSPACE_FILES_ENABLED", default)
+
+
+def workspace_files_root_label() -> str:
+    """Get workspace root label for UI display."""
+    return str(os.getenv("KSADK_WORKSPACE_ROOT_LABEL") or "workspace").strip() or "workspace"
+
+
+def workspace_files_max_upload_bytes() -> int:
+    """Get max upload size in bytes."""
+    raw = str(os.getenv("KSADK_WORKSPACE_MAX_UPLOAD_BYTES") or "").strip()
+    if not raw:
+        return DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES
+    try:
+        return max(int(raw), 1)
+    except ValueError:
+        return DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES
+
+
+def build_workspace_files_bootstrap(*, enabled: bool) -> dict[str, bool | int | str] | None:
+    """Build bootstrap configuration for workspace files."""
+    if not enabled:
+        return None
+    return {
+        "Enabled": True,
+        "MaxUploadBytes": workspace_files_max_upload_bytes(),
+        "SupportsDelete": True,
+        "RootLabel": workspace_files_root_label(),
+        "EntryAction": WORKSPACE_ENTRY_ACTION,
+        "UploadAction": WORKSPACE_UPLOAD_ACTION,
+        "ContentPath": WORKSPACE_CONTENT_PATH,
+    }

ksadk_runtime_common/workspace_files/constants.py

@@ -0,0 +1,9 @@
+"""Workspace files constants - preserves the existing contract exactly."""
+
+DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES = 100 * 1024 * 1024
+
+WORKSPACE_PATH_ESCAPE_DETAIL = "workspace path escapes the workspace root"
+
+WORKSPACE_ENTRY_ACTION = "ListWorkspaceFiles"
+WORKSPACE_UPLOAD_ACTION = "AddWorkspaceFile"
+WORKSPACE_CONTENT_PATH = "/agentengine/api/v1/GetWorkspaceFileContent"

ksadk_runtime_common/workspace_files/path_utils.py

@@ -0,0 +1,71 @@
+"""Workspace files path utilities and security helpers."""
+
+from __future__ import annotations
+
+import os
+import posixpath
+import re
+from collections.abc import Callable
+from pathlib import Path
+
+from fastapi import HTTPException
+
+from ksadk_runtime_common.workspace_files.constants import WORKSPACE_PATH_ESCAPE_DETAIL
+
+_SAFE_WORKSPACE_SEGMENT_RE = re.compile(r"^[^/\x00]+$")
+
+
+def _env_flag(name: str, default: bool) -> bool:
+    """Parse boolean environment variable."""
+    raw = str(os.getenv(name, "")).strip().lower()
+    if not raw:
+        return default
+    return raw in {"1", "true", "yes", "on"}
+
+
+def _normalize_workspace_path(raw_path: str | None, *, allow_root: bool) -> str:
+    """Normalize and validate a workspace path."""
+    raw = str(raw_path or ".").strip().replace("\\", "/")
+    if raw in {"", "."}:
+        if allow_root:
+            return "."
+        raise HTTPException(status_code=400, detail="workspace file path must not be empty")
+    if raw.startswith("/"):
+        raise HTTPException(status_code=400, detail=WORKSPACE_PATH_ESCAPE_DETAIL)
+
+    normalized = posixpath.normpath(raw)
+    if normalized in {"", "."}:
+        if allow_root:
+            return "."
+        raise HTTPException(status_code=400, detail="workspace file path must not be empty")
+    if normalized == ".." or normalized.startswith("../"):
+        raise HTTPException(status_code=400, detail=WORKSPACE_PATH_ESCAPE_DETAIL)
+    return normalized
+
+
+def _resolve_workspace_root(root_getter: Callable[[], Path]) -> Path:
+    """Resolve and create the workspace root directory."""
+    root = Path(root_getter()).expanduser().resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def _resolve_workspace_target(
+    root: Path, raw_path: str | None, *, allow_root: bool
+) -> tuple[str, Path]:
+    """Resolve a path within the workspace root with an escape check."""
+    normalized = _normalize_workspace_path(raw_path, allow_root=allow_root)
+    if normalized == ".":
+        target = root
+    else:
+        segments = tuple(part for part in normalized.split("/") if part)
+        if not segments or any(
+            part in {".", ".."} or not _SAFE_WORKSPACE_SEGMENT_RE.fullmatch(part)
+            for part in segments
+        ):
+            raise HTTPException(status_code=400, detail=WORKSPACE_PATH_ESCAPE_DETAIL)
+        target = root.joinpath(*segments)
+    resolved_target = target.resolve(strict=False)
+    if resolved_target != root and root not in resolved_target.parents:
+        raise HTTPException(status_code=400, detail=WORKSPACE_PATH_ESCAPE_DETAIL)
+    return normalized, resolved_target