agentengine-sdk-python 0.8.1__py3-none-any.whl → 0.8.2__py3-none-any.whl

ksadk/knowledge_base/client.py

@@ -82,6 +82,10 @@ class KnowledgeBaseClient(BaseModel):
     score_threshold: float = 0.0
     score_threshold_enabled: bool = False
     reranking_enable: bool = False
+    # 最近一次检索失败原因（成功调用前置空，失败时填充）。供
+    # KnowledgeBaseService.build_context 区分"后端吞错返空"与"真无结果"，
+    # 避免错误伪装成"未找到"注入模型上下文。
+    last_error: str = ""
 
     _aicp_client: Any = None
 
@@ -188,6 +192,7 @@ class KnowledgeBaseClient(BaseModel):
         try:
             data = json.loads(response) if isinstance(response, str) else response
         except (json.JSONDecodeError, TypeError):
+            self.last_error = f"Failed to parse response: {str(response)[:200]}"
             logger.error(f"Failed to parse response: {str(response)[:200]}")
             return []
 
@@ -230,6 +235,7 @@ class KnowledgeBaseClient(BaseModel):
             f"Searching knowledge base: dataset_id={self.dataset_id}, " f"query='{query[:50]}'"
         )
 
+        self.last_error = ""
         try:
             response = client.call("RetrieveKnowledge", params, options={"IsPostJson": True})
             results = self._parse_response(response)
@@ -238,6 +244,7 @@ class KnowledgeBaseClient(BaseModel):
             )
             return results
         except Exception as e:
+            self.last_error = str(e)
             logger.error(f"Knowledge base search failed: {e}")
             raise
 

ksadk/knowledge_base/service.py

@@ -44,6 +44,15 @@ class KnowledgeBaseService:
             self._client = KnowledgeBaseClient.from_env()
         return self._client
 
+    @property
+    def last_error(self) -> str:
+        """最近一次检索失败原因（成功前置空，失败填充；含响应解析失败）。
+
+        供 ``build_context`` 区分"后端吞错/解析失败返空"与"真无结果"。
+        客户端尚未懒加载时视为无错误。
+        """
+        return str(getattr(self._client, "last_error", "") or "")
+
     def search(self, query: str, top_k: Optional[int] = None) -> list[KnowledgeBaseResult]:
         return self._get_client().search(query, top_k)
 
@@ -54,13 +63,31 @@ class KnowledgeBaseService:
             logger.error("search_knowledge failed: %s", exc)
             return f"知识库检索失败: {exc}"
 
-    def build_context(self, query: str, top_k: Optional[int] = None) -> dict[str, str] | None:
+    def build_context(
+        self,
+        query: str,
+        top_k: Optional[int] = None,
+    ) -> dict[str, str] | None:
+        """构造环境知识库上下文。失败时返回 ``formatted_text=""`` + 独立 ``error`` 字段，
+        不把错误字符串塞进 ``formatted_text``（避免错误伪装成知识库正文注入模型）。
+
+        - 检索抛错（网络/鉴权失败）→ except 捕获，返 ``error`` 字段。
+        - 响应解析失败返空列表（``_parse_response``）→ client ``last_error`` 非空，
+          返回 ``error`` 字段。
+        - 真无结果（检索正常返空）→ ``formatted_text`` 为"未找到…"（语义真实，可注入）。
+        """
         normalized = str(query or "").strip()
-        if not normalized:
-            return None
-        if not self.is_configured():
+        if not normalized or not self.is_configured():
             return None
+        try:
+            results = self.search(normalized, top_k)
+        except Exception as exc:
+            logger.error("search_knowledge failed: %s", exc)
+            return {"query": normalized, "formatted_text": "", "error": str(exc)}
+        client_error = self.last_error
+        if not results and client_error:
+            return {"query": normalized, "formatted_text": "", "error": client_error}
         return {
             "query": normalized,
-            "formatted_text": self.search_text(normalized, top_k),
+            "formatted_text": format_knowledge_results(results),
         }

ksadk/memory/__init__.py

@@ -54,4 +54,65 @@ def __getattr__(name):
         from ksadk.memory.service import LongTermMemoryService
 
         return LongTermMemoryService
+    # Memory v2（方案 §10）：lazy import，避免在仅用旧 API 时强制加载 SQLite/tiktoken 依赖。
+    _v2_names = {
+        "MemoryRecord",
+        "MemoryCandidate",
+        "MemorySearchRequest",
+        "MemorySearchResult",
+        "MemoryCapabilities",
+        "CoreMemoryBlock",
+        "MemoryDeleteRequest",
+        "MemoryDeleteResult",
+        "MemoryProvider",
+        "MemoryPolicy",
+        "MemoryCoordinator",
+        "MemoryExtractor",
+        "SqliteMemoryProvider",
+        "build_search_request",
+        "recall_to_context_item",
+        "propose_memory_candidates",
+    }
+    if name in _v2_names:
+        if name in {
+            "MemoryRecord",
+            "MemoryCandidate",
+            "MemorySearchRequest",
+            "MemorySearchResult",
+            "MemoryCapabilities",
+            "CoreMemoryBlock",
+            "MemoryDeleteRequest",
+            "MemoryDeleteResult",
+        }:
+            from ksadk.memory import models as _models
+
+            return getattr(_models, name)
+        if name == "MemoryProvider":
+            from ksadk.memory.provider import MemoryProvider
+
+            return MemoryProvider
+        if name == "MemoryPolicy":
+            from ksadk.memory.policy import MemoryPolicy
+
+            return MemoryPolicy
+        if name == "MemoryCoordinator":
+            from ksadk.memory.coordinator import MemoryCoordinator
+
+            return MemoryCoordinator
+        if name in {"build_search_request", "recall_to_context_item"}:
+            from ksadk.memory import coordinator as _coord
+
+            return getattr(_coord, name)
+        if name == "MemoryExtractor":
+            from ksadk.memory.extraction import MemoryExtractor
+
+            return MemoryExtractor
+        if name == "propose_memory_candidates":
+            from ksadk.memory.extraction import propose_memory_candidates
+
+            return propose_memory_candidates
+        if name == "SqliteMemoryProvider":
+            from ksadk.memory.providers.local_sqlite import SqliteMemoryProvider
+
+            return SqliteMemoryProvider
     raise AttributeError(f"module 'ksadk.memory' has no attribute {name!r}")

ksadk/memory/adk/backends/base_ltm_backend.py

@@ -3,22 +3,48 @@
 所有长期记忆后端必须继承此类并实现 save_memory / search_memory 方法。
 
 参考 VeADK: veadk/memory/long_term_memory_backends/base_backend.py
+
+扩展协议（技术改造方案 §7.3）：
+    - search_records: 结构化检索，返回带 memory_id 的 LongTermMemoryRecord
+    - update_memory / delete_memory: 按 ID 原地更新/软删除
+    - capabilities: 声明 backend 支持的能力集合
+    基类对扩展方法提供默认实现：抛出 UnsupportedMemoryOperation 并在
+    capabilities 中不声明对应能力，旧 backend 无需改动即保持兼容。
 """
 
 from abc import ABC, abstractmethod
-from typing import List
+from typing import List, Set
 
 from pydantic import BaseModel
 
+from ksadk.memory.models import (
+    LongTermMemoryRecord,
+    MemoryExtractionStatus,
+    MemoryMutationResult,
+    UnsupportedMemoryOperation,
+)
+
+# 能力常量（§7.3）
+CAP_SEARCH = "search"
+CAP_ADD = "add"
+CAP_FLUSH = "flush"
+CAP_STRUCTURED_SEARCH = "structured_search"
+CAP_UPDATE = "update"
+CAP_DELETE = "delete"
+CAP_SESSION_STATUS = "session_status"
+
 
 class BaseLongTermMemoryBackend(ABC, BaseModel):
     """长期记忆存储后端抽象基类
 
     Attributes:
         index: 索引/集合名称，用于隔离不同应用的记忆数据
+        last_error: 最近一次 search/save 失败的原因。成功调用前置空，失败时填充。
+            上层（LongTermMemoryService.build_context）据此区分"后端吞错返空"与"真无记忆"。
     """
 
     index: str = ""
+    last_error: str = ""
 
     @abstractmethod
     def save_memory(self, user_id: str, event_strings: List[str], **kwargs) -> bool:
@@ -46,3 +72,72 @@ class BaseLongTermMemoryBackend(ABC, BaseModel):
             匹配的记忆字符串列表
         """
         pass
+
+    # ---- 扩展协议（可选能力，默认 unsupported） ----
+
+    def search_records(
+        self,
+        user_id: str,
+        query: str,
+        top_k: int = 5,
+        **kwargs,
+    ) -> List[LongTermMemoryRecord]:
+        """结构化检索：返回带服务端 memory_id 的记录列表。
+
+        不支持的 backend 抛出 UnsupportedMemoryOperation，
+        不得降级为返回正文 hash 伪造的 ID。
+        """
+        raise UnsupportedMemoryOperation(
+            f"{type(self).__name__} does not support structured search"
+        )
+
+    def update_memory(
+        self,
+        *,
+        user_id: str,
+        memory_id: str,
+        content: str,
+        **kwargs,
+    ) -> MemoryMutationResult:
+        """按 memory_id 原地更新记忆正文。
+
+        不支持的 backend 抛出 UnsupportedMemoryOperation，
+        不得静默追加一条新记忆来模拟 update。
+        """
+        raise UnsupportedMemoryOperation(f"{type(self).__name__} does not support update")
+
+    def delete_memory(
+        self,
+        *,
+        user_id: str,
+        memory_id: str,
+        **kwargs,
+    ) -> MemoryMutationResult:
+        """按 memory_id 软删除指定记忆。
+
+        不支持的 backend 抛出 UnsupportedMemoryOperation。
+        """
+        raise UnsupportedMemoryOperation(f"{type(self).__name__} does not support delete")
+
+    def get_extraction_status(
+        self,
+        *,
+        user_id: str,
+        session_id: str,
+    ) -> MemoryExtractionStatus:
+        """查询 Session 后台提取状态（写后确认，§7.7）。
+
+        不支持的 backend 抛出 UnsupportedMemoryOperation。
+        """
+        raise UnsupportedMemoryOperation(f"{type(self).__name__} does not support session status")
+
+    def capabilities(self) -> Set[str]:
+        """声明本 backend 支持的能力集合。
+
+        基类默认只声明基础读写能力；子类按真实实现覆写，
+        声明必须与实际可用方法一致（§11.1）。
+        """
+        return {CAP_SEARCH, CAP_ADD}
+
+    def has_capability(self, capability: str) -> bool:
+        return capability in self.capabilities()

ksadk/memory/adk/backends/http_ltm_backend.py

@@ -52,10 +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]}... index={self.index}"
         )
 
     @property
@@ -101,13 +101,13 @@ 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 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} {e.response.text[:200]}"
             )
             return False
         except Exception as e:
@@ -133,6 +133,7 @@ class HttpLTMBackend(BaseLongTermMemoryBackend):
         """
         if not self.base_url:
             logger.warning("HttpLTMBackend: base_url not configured, return empty results.")
+            self.last_error = "base_url not configured"
             return []
 
         try:
@@ -161,7 +162,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} {e.response.text[:200]}"
             )
             return []
         except Exception as e:
@@ -173,3 +174,11 @@ class HttpLTMBackend(BaseLongTermMemoryBackend):
         if self._client:
             self._client.close()
             self._client = None
+
+    # ------------------------------------------------------------------
+    # 扩展协议（方案 §7.3）：HTTP backend 为框架预留，结构化能力未定。
+    # 远程 API 对接细节待提供（见 save_memory TODO），因此不声明
+    # structured/update/delete/session_status 能力；search_records 也不降级
+    # 伪造 ID，保持 base 的 UnsupportedMemoryOperation 默认行为。
+    # 远端 schema 确认后，在此接入对应端点并覆写 capabilities()。
+    # ------------------------------------------------------------------

ksadk/memory/adk/backends/inmemory_ltm_backend.py

@@ -2,15 +2,35 @@
 
 使用简单的内存字典存储和文本匹配检索。
 数据在进程退出后丢失，仅适用于开发和测试场景。
+
+扩展协议（技术改造方案 §7.3）：内存实现结构化检索与 update/delete，
+用于本地开发和 fake 场景下的契约验证；不声明 flush/session_status 能力
+（没有后台提取过程，写入即"可见"）。
+
+兼容设计：_storage 保存原始事件字符串不改写，search_memory 返回原始
+字符串列表（保留旧契约，§7.5）；结构化能力通过平行 ID 索引提供。
 """
 
+import json
 import logging
+import uuid
 from collections import defaultdict
-from typing import List
+from typing import List, Set
 
 from pydantic import PrivateAttr
 
-from ksadk.memory.adk.backends.base_ltm_backend import BaseLongTermMemoryBackend
+from ksadk.memory.adk.backends.base_ltm_backend import (
+    CAP_ADD,
+    CAP_DELETE,
+    CAP_SEARCH,
+    CAP_STRUCTURED_SEARCH,
+    CAP_UPDATE,
+    BaseLongTermMemoryBackend,
+)
+from ksadk.memory.models import (
+    LongTermMemoryRecord,
+    MemoryMutationResult,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -30,6 +50,12 @@ class InMemoryLTMBackend(BaseLongTermMemoryBackend):
     """
 
     _storage: defaultdict[str, list[str]] = PrivateAttr(default_factory=lambda: defaultdict(list))
+    # memory_id -> 原始事件字符串（不改写 _storage，保留旧 search_memory 契约）。
+    _entry_ids: dict[str, str] = PrivateAttr(default_factory=dict)
+    # (user_id) -> {memory_id -> 原始事件字符串}，用于快速定位与更新/删除。
+    _user_entry_index: defaultdict[str, dict[str, str]] = PrivateAttr(
+        default_factory=lambda: defaultdict(dict)
+    )
 
     def model_post_init(self, __context) -> None:
         # {user_id: [event_string, ...]}
@@ -40,7 +66,11 @@ class InMemoryLTMBackend(BaseLongTermMemoryBackend):
         if not event_strings:
             return True
 
-        self._storage[user_id].extend(event_strings)
+        for entry in event_strings:
+            memory_id = f"mem-{uuid.uuid4().hex[:12]}"
+            self._entry_ids[memory_id] = entry
+            self._user_entry_index[user_id][memory_id] = entry
+            self._storage[user_id].append(entry)
         logger.debug(
             f"Saved {len(event_strings)} events for user={user_id}, "
             f"total={len(self._storage[user_id])}"
@@ -88,3 +118,106 @@ class InMemoryLTMBackend(BaseLongTermMemoryBackend):
             f"found {len(results)} results from {len(user_memories)} total"
         )
         return results
+
+    # ---- 扩展协议实现（§7.3） ----
+
+    def capabilities(self) -> Set[str]:
+        return {
+            CAP_SEARCH,
+            CAP_ADD,
+            CAP_STRUCTURED_SEARCH,
+            CAP_UPDATE,
+            CAP_DELETE,
+        }
+
+    def search_records(
+        self, user_id: str, query: str, top_k: int = 5, **kwargs
+    ) -> List[LongTermMemoryRecord]:
+        """结构化检索：复用关键词匹配，返回稳定生成的本地 ID。"""
+        entries = self.search_memory(user_id, query, top_k=top_k)
+        records: List[LongTermMemoryRecord] = []
+        for entry in entries:
+            memory_id = self._find_entry_id(user_id, entry)
+            if memory_id is None:
+                continue
+            records.append(
+                LongTermMemoryRecord(
+                    memory_id=memory_id,
+                    content=self._entry_text(entry),
+                    score=None,
+                    user_id=user_id,
+                )
+            )
+        return records
+
+    def update_memory(
+        self,
+        *,
+        user_id: str,
+        memory_id: str,
+        content: str,
+        **kwargs,
+    ) -> MemoryMutationResult:
+        user_index = self._user_entry_index.get(user_id, {})
+        old_entry = user_index.get(memory_id)
+        if old_entry is None:
+            return MemoryMutationResult(ok=False, memory_id=memory_id, status="not_found")
+        new_entry = json.dumps(
+            {"role": "user", "parts": [{"text": content}]}, ensure_ascii=False
+        )
+        memories = self._storage[user_id]
+        for i, entry in enumerate(memories):
+            if entry is old_entry:
+                memories[i] = new_entry
+                break
+        self._entry_ids[memory_id] = new_entry
+        user_index[memory_id] = new_entry
+        return MemoryMutationResult(
+            ok=True,
+            memory_id=memory_id,
+            new_memory_id=memory_id,
+            status="updated",
+        )
+
+    def delete_memory(
+        self,
+        *,
+        user_id: str,
+        memory_id: str,
+        **kwargs,
+    ) -> MemoryMutationResult:
+        user_index = self._user_entry_index.get(user_id, {})
+        entry = user_index.pop(memory_id, None)
+        if entry is None:
+            return MemoryMutationResult(
+                ok=True, memory_id=memory_id, status="already_absent", message="目标记忆已不存在"
+            )
+        self._entry_ids.pop(memory_id, None)
+        memories = self._storage.get(user_id, [])
+        try:
+            memories.remove(entry)
+        except ValueError:
+            pass
+        return MemoryMutationResult(ok=True, memory_id=memory_id, status="deleted")
+
+    def _find_entry_id(self, user_id: str, entry: str) -> str | None:
+        """根据原始条目定位 memory_id（反向查表）。"""
+        for memory_id, stored in self._user_entry_index.get(user_id, {}).items():
+            if stored is entry or stored == entry:
+                return memory_id
+        return None
+
+    # ---- 内部工具 ----
+
+    @staticmethod
+    def _entry_text(entry: str) -> str:
+        """提取事件字符串里的正文（兼容 JSON 事件与纯文本）。"""
+        try:
+            payload = json.loads(entry)
+        except (json.JSONDecodeError, TypeError):
+            return entry
+        if isinstance(payload, dict):
+            parts = payload.get("parts")
+            if isinstance(parts, list) and parts and isinstance(parts[0], dict):
+                return str(parts[0].get("text", entry))
+        return entry