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

ksadk/memory/service.py

@@ -0,0 +1,172 @@
+"""Platform-level long-term memory service helpers."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+from ksadk.common.aicp_env import resolve_aicp_connection
+from ksadk.memory.adk.backends.base_ltm_backend import BaseLongTermMemoryBackend
+from ksadk.memory.ltm_backend_factory import get_long_term_memory_backend_cls
+
+logger = logging.getLogger(__name__)
+
+
+def format_memory_entries(entries: list[str]) -> str:
+    if not entries:
+        return "未找到相关长期记忆。"
+
+    formatted_entries: list[str] = []
+    for index, entry in enumerate(entries, 1):
+        text = entry
+        try:
+            payload = json.loads(entry)
+        except (json.JSONDecodeError, TypeError):
+            payload = None
+
+        if isinstance(payload, dict):
+            parts = payload.get("parts") or []
+            if parts and isinstance(parts[0], dict):
+                text = str(parts[0].get("text") or text)
+        formatted_entries.append(f"[{index}] {text}")
+
+    return "\n\n".join(formatted_entries)
+
+
+class LongTermMemoryService:
+    def __init__(
+        self,
+        *,
+        backend: str | BaseLongTermMemoryBackend = "local",
+        backend_config: dict[str, Any] | None = None,
+        top_k: int = 5,
+        index: str = "",
+        app_name: str = "",
+    ):
+        self.backend = backend
+        self.backend_config = dict(backend_config or {})
+        self.top_k = top_k
+        self.app_name = app_name
+        backend_index = getattr(backend, "index", "") if isinstance(backend, BaseLongTermMemoryBackend) else ""
+        self.index = index or backend_index or app_name or "default_app"
+        self._backend = self._resolve_backend()
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        app_name: str = "",
+        backend: str | None = None,
+    ) -> "LongTermMemoryService":
+        resolved_backend = backend or os.environ.get("KSADK_LTM_BACKEND", "local")
+        top_k = int(os.environ.get("KSADK_LTM_TOP_K", "5"))
+        index = os.environ.get("KSADK_LTM_INDEX", "")
+        app_name = os.environ.get("KSADK_LTM_APP_NAME", "") or app_name
+
+        backend_config: dict[str, Any] = {}
+        if resolved_backend == "http":
+            backend_config = {
+                "base_url": os.environ.get("KSADK_LTM_HTTP_URL", ""),
+                "token": os.environ.get("KSADK_LTM_HTTP_TOKEN", ""),
+            }
+        elif resolved_backend == "sdk":
+            connection = resolve_aicp_connection("KSADK_LTM")
+            backend_config = {
+                "access_key": (
+                    os.environ.get("KSADK_LTM_ACCESS_KEY")
+                    or os.environ.get("KSYUN_ACCESS_KEY", "")
+                ),
+                "secret_key": (
+                    os.environ.get("KSADK_LTM_SECRET_KEY")
+                    or os.environ.get("KSYUN_SECRET_KEY", "")
+                ),
+                "region": connection["region"],
+                "endpoint": connection["endpoint"],
+                "scheme": connection["scheme"],
+                "namespace": os.environ.get("KSADK_LTM_NAMESPACE", ""),
+                "agent_id": os.environ.get("KSADK_LTM_AGENT_ID", ""),
+                "scene_id": os.environ.get("KSADK_LTM_SCENE_ID", "_sys_general"),
+            }
+
+        return cls(
+            backend=resolved_backend,
+            backend_config=backend_config,
+            top_k=top_k,
+            index=index,
+            app_name=app_name,
+        )
+
+    @staticmethod
+    def is_configured() -> bool:
+        return bool(str(os.environ.get("KSADK_LTM_BACKEND", "")).strip())
+
+    def _resolve_backend(self) -> BaseLongTermMemoryBackend:
+        if isinstance(self.backend, BaseLongTermMemoryBackend):
+            return self.backend
+
+        backend_cls = get_long_term_memory_backend_cls(str(self.backend))
+        config = dict(self.backend_config)
+        config.setdefault("index", self.index)
+        return backend_cls(**config)
+
+    def search_entries(self, *, user_id: str, query: str, top_k: int | None = None) -> list[str]:
+        return self._backend.search_memory(
+            user_id=user_id,
+            query=query,
+            top_k=top_k if top_k is not None else self.top_k,
+        )
+
+    def search_text(self, *, user_id: str, query: str, top_k: int | None = None) -> str:
+        try:
+            return format_memory_entries(
+                self.search_entries(user_id=user_id, query=query, top_k=top_k)
+            )
+        except Exception as exc:
+            logger.error("load_memory failed: %s", exc)
+            return f"长期记忆检索失败: {exc}"
+
+    def save_event_strings(
+        self,
+        *,
+        user_id: str,
+        event_strings: list[str],
+        metadata: dict[str, Any] | None = None,
+    ) -> bool:
+        return bool(
+            self._backend.save_memory(
+                user_id=user_id,
+                event_strings=event_strings,
+                metadata=metadata or {},
+            )
+        )
+
+    def save_text(self, *, user_id: str, content: str, metadata: dict[str, Any] | None = None) -> bool:
+        payload = {
+            "role": "user",
+            "parts": [{"text": content}],
+            "metadata": metadata or {},
+        }
+        return self.save_event_strings(
+            user_id=user_id,
+            event_strings=[json.dumps(payload, ensure_ascii=False)],
+            metadata=metadata,
+        )
+
+    def build_context(
+        self,
+        *,
+        user_id: str,
+        query: str,
+        top_k: int | None = None,
+    ) -> dict[str, str] | None:
+        normalized = str(query or "").strip()
+        if not normalized:
+            return None
+        if not self.is_configured():
+            return None
+        return {
+            "query": normalized,
+            "formatted_text": self.search_text(user_id=user_id, query=normalized, top_k=top_k),
+        }

ksadk/memory/tool.py

@@ -0,0 +1,96 @@
+"""Cross-framework long-term memory tools."""
+
+from __future__ import annotations
+
+import logging
+
+from ksadk.memory.service import LongTermMemoryService
+from ksadk.runtime_context import get_current_invocation_context
+
+logger = logging.getLogger(__name__)
+
+_service: LongTermMemoryService | None = None
+
+
+def _get_or_create_service() -> LongTermMemoryService:
+    global _service
+    if _service is None:
+        _service = LongTermMemoryService.from_env()
+    return _service
+
+
+def load_memory(query: str) -> str:
+    context = get_current_invocation_context()
+    if context is None:
+        return "长期记忆检索失败: 缺少运行时上下文。"
+
+    try:
+        service = _get_or_create_service()
+        return service.search_text(user_id=context.user_id, query=query)
+    except Exception as exc:
+        logger.error("load_memory failed: %s", exc)
+        return f"长期记忆检索失败: {exc}"
+
+
+def _is_sdk_backend(service: LongTermMemoryService) -> bool:
+    backend = getattr(service, "_backend", None)
+    return backend.__class__.__name__ == "SdkLTMBackend"
+
+
+def _sdk_pending_result(service: LongTermMemoryService, context) -> dict:
+    backend = getattr(service, "_backend", None)
+    session_status = None
+    get_session_status = getattr(backend, "get_session_status", None)
+    if callable(get_session_status):
+        session_status = get_session_status(
+            user_id=context.user_id,
+            session_id=context.session_id,
+        )
+
+    result = {
+        "ok": False,
+        "status": "accepted_not_extracted",
+        "message": "记忆保存请求已被后端受理，但尚未抽取成可检索记忆。",
+    }
+    if isinstance(session_status, dict):
+        result["session_state"] = session_status.get("State")
+        result["session_id"] = session_status.get("SessionId") or context.session_id
+    elif context.session_id:
+        result["session_id"] = context.session_id
+    return result
+
+
+def save_memory(content: str) -> dict:
+    context = get_current_invocation_context()
+    if context is None:
+        return {
+            "ok": False,
+            "status": "failed",
+            "message": "记忆保存失败: 缺少运行时上下文。",
+        }
+
+    try:
+        service = _get_or_create_service()
+        ok = service.save_text(
+            user_id=context.user_id,
+            content=content,
+            metadata={
+                "agent_id": context.agent_id,
+                "session_id": context.session_id,
+                "runner_type": context.runner_type,
+            },
+        )
+        if ok:
+            if _is_sdk_backend(service):
+                entries = service.search_entries(user_id=context.user_id, query=content, top_k=1)
+                if not entries:
+                    return _sdk_pending_result(service, context)
+            return {"ok": True, "status": "persisted", "message": "记忆已保存。"}
+
+        backend = getattr(service, "_backend", None)
+        last_error = str(getattr(backend, "last_error", "") or "").strip()
+        message = f"记忆保存失败: {last_error}" if last_error else "记忆保存失败。"
+        return {"ok": False, "status": "failed", "message": message}
+    except Exception as exc:
+        logger.error("save_memory failed: %s", exc)
+        return {"ok": False, "status": "failed", "message": f"记忆保存失败: {exc}"}

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