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

ksadk/memory/backends/memory.py

@@ -1,49 +1,48 @@
 """In-Memory Backend - 内存存储 (开发/测试用)"""
 
-import json
-from datetime import datetime, timedelta
-from typing import Any, Optional, List, Dict
 from collections import defaultdict
+from datetime import datetime, timedelta
+from typing import Any, Dict, List, Optional
 
 from ksadk.memory.backends.base import BaseMemoryBackend
 
 
 class InMemoryBackend(BaseMemoryBackend):
     """内存存储后端
-    
+
     适用于开发和测试，数据在进程退出后丢失。
     """
-    
+
     def __init__(self):
         # {session_id: {key: (value, expires_at)}}
         self._data: Dict[str, Dict[str, tuple]] = defaultdict(dict)
         # {session_id: [messages]}
         self._messages: Dict[str, List[Dict]] = defaultdict(list)
-    
+
     def _make_key(self, key: str, session_id: Optional[str]) -> tuple:
         """生成复合键"""
         sid = session_id or "__global__"
         return sid, key
-    
+
     def _is_expired(self, expires_at: Optional[datetime]) -> bool:
         if expires_at is None:
             return False
         return datetime.utcnow() > expires_at
-    
+
     def get(self, key: str, session_id: Optional[str] = None) -> Optional[Any]:
         sid, k = self._make_key(key, session_id)
-        
+
         if sid not in self._data or k not in self._data[sid]:
             return None
-        
+
         value, expires_at = self._data[sid][k]
-        
+
         if self._is_expired(expires_at):
             del self._data[sid][k]
             return None
-        
+
         return value
-    
+
     def set(
         self,
         key: str,
@@ -52,32 +51,32 @@ class InMemoryBackend(BaseMemoryBackend):
         ttl: Optional[timedelta] = None,
     ) -> bool:
         sid, k = self._make_key(key, session_id)
-        
+
         expires_at = None
         if ttl:
             expires_at = datetime.utcnow() + ttl
-        
+
         self._data[sid][k] = (value, expires_at)
         return True
-    
+
     def delete(self, key: str, session_id: Optional[str] = None) -> bool:
         sid, k = self._make_key(key, session_id)
-        
+
         if sid in self._data and k in self._data[sid]:
             del self._data[sid][k]
             return True
         return False
-    
+
     def exists(self, key: str, session_id: Optional[str] = None) -> bool:
         return self.get(key, session_id) is not None
-    
+
     def clear_session(self, session_id: str) -> bool:
         if session_id in self._data:
             del self._data[session_id]
         if session_id in self._messages:
             del self._messages[session_id]
         return True
-    
+
     def add_message(
         self,
         session_id: str,
@@ -85,28 +84,28 @@ class InMemoryBackend(BaseMemoryBackend):
         content: str,
         metadata: Optional[Dict] = None,
     ) -> bool:
-        msg = {
+        msg: Dict[str, Any] = {
             "role": role,
             "content": content,
             "timestamp": datetime.utcnow().isoformat() + "Z",
         }
         if metadata:
             msg["metadata"] = metadata
-        
+
         self._messages[session_id].append(msg)
         return True
-    
+
     def get_messages(
         self,
         session_id: str,
         limit: Optional[int] = None,
     ) -> List[Dict]:
         messages = self._messages.get(session_id, [])
-        
+
         if limit:
             return messages[-limit:]
         return messages.copy()
-    
+
     def close(self) -> None:
         self._data.clear()
         self._messages.clear()

ksadk/memory/backends/redis.py

@@ -2,20 +2,20 @@
 
 import json
 from datetime import datetime, timedelta
-from typing import Any, Optional, List, Dict
+from typing import Any, Dict, List, Optional
 
 from ksadk.memory.backends.base import BaseMemoryBackend
 
 
 class RedisBackend(BaseMemoryBackend):
     """Redis 存储后端
-    
+
     适用于短期记忆和会话状态存储。
-    
+
     使用示例:
         backend = RedisBackend(url="redis://localhost:6379/0")
     """
-    
+
     def __init__(
         self,
         url: str = "redis://localhost:6379/0",
@@ -26,39 +26,40 @@ class RedisBackend(BaseMemoryBackend):
         self.prefix = prefix
         self.default_ttl = default_ttl
         self._client = None
-    
+
     @property
     def client(self):
         """懒加载 Redis 客户端"""
         if self._client is None:
             try:
                 import redis
+
                 self._client = redis.from_url(self.url, decode_responses=True)
             except ImportError:
                 raise ImportError("redis package required. Install with: pip install redis")
         return self._client
-    
+
     def _make_key(self, key: str, session_id: Optional[str]) -> str:
         """生成 Redis 键"""
         if session_id:
             return f"{self.prefix}session:{session_id}:{key}"
         return f"{self.prefix}global:{key}"
-    
+
     def _messages_key(self, session_id: str) -> str:
         return f"{self.prefix}messages:{session_id}"
-    
+
     def get(self, key: str, session_id: Optional[str] = None) -> Optional[Any]:
         redis_key = self._make_key(key, session_id)
         value = self.client.get(redis_key)
-        
+
         if value is None:
             return None
-        
+
         try:
             return json.loads(value)
         except json.JSONDecodeError:
             return value
-    
+
     def set(
         self,
         key: str,
@@ -67,40 +68,40 @@ class RedisBackend(BaseMemoryBackend):
         ttl: Optional[timedelta] = None,
     ) -> bool:
         redis_key = self._make_key(key, session_id)
-        
+
         # 序列化
         if not isinstance(value, str):
             value = json.dumps(value, ensure_ascii=False)
-        
+
         # 设置过期时间
         ex = None
         if ttl:
             ex = int(ttl.total_seconds())
         elif self.default_ttl:
             ex = int(self.default_ttl.total_seconds())
-        
+
         self.client.set(redis_key, value, ex=ex)
         return True
-    
+
     def delete(self, key: str, session_id: Optional[str] = None) -> bool:
         redis_key = self._make_key(key, session_id)
-        return self.client.delete(redis_key) > 0
-    
+        return bool(self.client.delete(redis_key) > 0)
+
     def exists(self, key: str, session_id: Optional[str] = None) -> bool:
         redis_key = self._make_key(key, session_id)
-        return self.client.exists(redis_key) > 0
-    
+        return bool(self.client.exists(redis_key) > 0)
+
     def clear_session(self, session_id: str) -> bool:
         pattern = f"{self.prefix}session:{session_id}:*"
         keys = list(self.client.scan_iter(match=pattern))
-        
+
         # 也删除消息
         keys.append(self._messages_key(session_id))
-        
+
         if keys:
             self.client.delete(*keys)
         return True
-    
+
     def add_message(
         self,
         session_id: str,
@@ -108,38 +109,38 @@ class RedisBackend(BaseMemoryBackend):
         content: str,
         metadata: Optional[Dict] = None,
     ) -> bool:
-        msg = {
+        msg: dict[str, Any] = {
             "role": role,
             "content": content,
             "timestamp": datetime.utcnow().isoformat() + "Z",
         }
         if metadata:
             msg["metadata"] = metadata
-        
+
         redis_key = self._messages_key(session_id)
         self.client.rpush(redis_key, json.dumps(msg, ensure_ascii=False))
-        
+
         # 可以设置消息历史的过期时间
         if self.default_ttl:
             self.client.expire(redis_key, int(self.default_ttl.total_seconds()))
-        
+
         return True
-    
+
     def get_messages(
         self,
         session_id: str,
         limit: Optional[int] = None,
     ) -> List[Dict]:
         redis_key = self._messages_key(session_id)
-        
+
         if limit:
             # 获取最后 N 条
             raw = self.client.lrange(redis_key, -limit, -1)
         else:
             raw = self.client.lrange(redis_key, 0, -1)
-        
+
         return [json.loads(m) for m in raw]
-    
+
     def close(self) -> None:
         if self._client:
             self._client.close()

ksadk/memory/langchain_tool.py

@@ -31,7 +31,8 @@ def create_langchain_tools():
         return load_memory_tool, save_memory_tool
     except ImportError:
         logger.warning(
-            "langchain-core not installed, returning raw functions. Install with: pip install langchain-core"
+            "langchain-core not installed, returning raw functions. "
+            "Install with: pip install langchain-core"
         )
         return _load_memory, _save_memory
 

ksadk/memory/manager.py

@@ -1,9 +1,9 @@
 """Memory Manager - 统一记忆管理接口"""
 
-import os
 import logging
+import os
 from datetime import timedelta
-from typing import Any, Optional, List, Dict, Type
+from typing import Any, Dict, List, Optional, Type, cast
 
 from ksadk.memory.backends.base import BaseMemoryBackend
 from ksadk.memory.backends.memory import InMemoryBackend
@@ -24,26 +24,26 @@ def register_backend(name: str, backend_class: Type[BaseMemoryBackend]):
 
 class MemoryManager:
     """统一记忆管理器
-    
+
     支持可插拔后端，自动从环境变量读取配置。
-    
+
     使用示例:
         # 从环境变量自动配置
         memory = MemoryManager.from_env()
-        
+
         # 手动配置
         memory = MemoryManager(backend="redis", url="redis://localhost:6379")
-        
+
         # 存取数据
         memory.set("key", {"data": "value"}, session_id="sess-123")
         data = memory.get("key", session_id="sess-123")
-        
+
         # 消息历史
         memory.add_message("sess-123", "user", "你好")
         memory.add_message("sess-123", "assistant", "你好！有什么可以帮助你的？")
         messages = memory.get_messages("sess-123")
     """
-    
+
     def __init__(
         self,
         backend: str = "memory",
@@ -53,7 +53,7 @@ class MemoryManager:
         **kwargs,
     ):
         """初始化 Memory Manager
-        
+
         Args:
             backend: 后端类型 ("memory", "redis")
             url: 后端连接 URL
@@ -63,7 +63,7 @@ class MemoryManager:
         """
         self.backend_name = backend
         self._backend = self._create_backend(backend, url, prefix, default_ttl, **kwargs)
-    
+
     def _create_backend(
         self,
         backend: str,
@@ -76,25 +76,29 @@ class MemoryManager:
         # 延迟导入 Redis backend
         if backend == "redis":
             from ksadk.memory.backends.redis import RedisBackend
+
             _BACKENDS["redis"] = RedisBackend
-        
+
         if backend not in _BACKENDS:
             raise ValueError(f"Unknown backend: {backend}. Available: {list(_BACKENDS.keys())}")
-        
-        backend_class = _BACKENDS[backend]
-        
+
+        backend_class: Any = _BACKENDS[backend]
+
         # 根据后端类型传递参数
         if backend == "memory":
-            return backend_class()
+            return cast(BaseMemoryBackend, backend_class())
         elif backend == "redis":
-            return backend_class(url=url, prefix=prefix, default_ttl=default_ttl, **kwargs)
+            return cast(
+                BaseMemoryBackend,
+                backend_class(url=url, prefix=prefix, default_ttl=default_ttl, **kwargs),
+            )
         else:
-            return backend_class(**kwargs)
-    
+            return cast(BaseMemoryBackend, backend_class(**kwargs))
+
     @classmethod
     def from_env(cls) -> "MemoryManager":
         """从环境变量创建 MemoryManager
-        
+
         环境变量:
             KSADK_MEMORY_BACKEND: 后端类型 (默认 "memory")
             KSADK_MEMORY_URL: 连接 URL (如 redis://localhost:6379)
@@ -104,27 +108,27 @@ class MemoryManager:
         backend = os.environ.get("KSADK_MEMORY_BACKEND", "memory")
         url = os.environ.get("KSADK_MEMORY_URL", "")
         prefix = os.environ.get("KSADK_MEMORY_PREFIX", "ksadk:memory:")
-        
+
         ttl = None
         ttl_str = os.environ.get("KSADK_MEMORY_TTL", "")
         if ttl_str:
             ttl = timedelta(seconds=int(ttl_str))
-        
+
         logger.debug(f"MemoryManager.from_env: backend={backend}, url={url[:20]}...")
-        
+
         return cls(
             backend=backend,
             url=url or None,
             prefix=prefix,
             default_ttl=ttl,
         )
-    
+
     # ===== 键值操作 =====
-    
+
     def get(self, key: str, session_id: Optional[str] = None) -> Optional[Any]:
         """获取值"""
         return self._backend.get(key, session_id)
-    
+
     def set(
         self,
         key: str,
@@ -133,24 +137,24 @@ class MemoryManager:
         ttl: Optional[timedelta] = None,
     ) -> bool:
         """设置值"""
-        return self._backend.set(key, value, session_id, ttl)
-    
+        return bool(self._backend.set(key, value, session_id, ttl))
+
     def delete(self, key: str, session_id: Optional[str] = None) -> bool:
         """删除键"""
-        return self._backend.delete(key, session_id)
-    
+        return bool(self._backend.delete(key, session_id))
+
     def exists(self, key: str, session_id: Optional[str] = None) -> bool:
         """检查键是否存在"""
-        return self._backend.exists(key, session_id)
-    
+        return bool(self._backend.exists(key, session_id))
+
     # ===== 会话操作 =====
-    
+
     def clear_session(self, session_id: str) -> bool:
         """清除会话所有数据"""
-        return self._backend.clear_session(session_id)
-    
+        return bool(self._backend.clear_session(session_id))
+
     # ===== 消息历史 =====
-    
+
     def add_message(
         self,
         session_id: str,
@@ -159,39 +163,40 @@ class MemoryManager:
         metadata: Optional[Dict] = None,
     ) -> bool:
         """添加消息"""
-        return self._backend.add_message(session_id, role, content, metadata)
-    
+        return bool(self._backend.add_message(session_id, role, content, metadata))
+
     def get_messages(
         self,
         session_id: str,
         limit: Optional[int] = None,
     ) -> List[Dict]:
         """获取消息历史"""
-        return self._backend.get_messages(session_id, limit)
-    
+        messages = self._backend.get_messages(session_id, limit)
+        return list(messages)
+
     # ===== 便捷方法 =====
-    
+
     def get_state(self, session_id: str) -> Dict:
         """获取会话状态 (短期记忆)"""
         return self.get("__state__", session_id) or {}
-    
+
     def set_state(self, session_id: str, state: Dict, ttl: Optional[timedelta] = None) -> bool:
         """设置会话状态"""
         return self.set("__state__", state, session_id, ttl)
-    
+
     def update_state(self, session_id: str, updates: Dict) -> bool:
         """更新会话状态 (合并)"""
         current = self.get_state(session_id)
         current.update(updates)
         return self.set_state(session_id, current)
-    
+
     def close(self) -> None:
         """关闭连接"""
         self._backend.close()
-    
+
     def __enter__(self):
         return self
-    
+
     def __exit__(self, exc_type, exc_val, exc_tb):
         self.close()
 
@@ -202,10 +207,10 @@ _global_manager: Optional[MemoryManager] = None
 
 def get_memory_manager() -> MemoryManager:
     """获取全局 MemoryManager 单例
-    
+
     在 Agent 代码中使用:
         from ksadk.memory import get_memory_manager
-        
+
         memory = get_memory_manager()
         memory.set("key", "value")
     """

ksadk/memory/service.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 import logging
 import os
-from typing import Any
+from typing import Any, cast
 
 from ksadk.common.aicp_env import resolve_aicp_connection
 from ksadk.memory.adk.backends.base_ltm_backend import BaseLongTermMemoryBackend
@@ -49,7 +49,9 @@ class LongTermMemoryService:
         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 ""
+        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()
 
@@ -75,12 +77,10 @@ class LongTermMemoryService:
             connection = resolve_aicp_connection("KSADK_LTM")
             backend_config = {
                 "access_key": (
-                    os.environ.get("KSADK_LTM_ACCESS_KEY")
-                    or os.environ.get("KSYUN_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", "")
+                    os.environ.get("KSADK_LTM_SECRET_KEY") or os.environ.get("KSYUN_SECRET_KEY", "")
                 ),
                 "region": connection["region"],
                 "endpoint": connection["endpoint"],
@@ -109,7 +109,7 @@ class LongTermMemoryService:
         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)
+        return cast(BaseLongTermMemoryBackend, backend_cls(**config))
 
     def search_entries(self, *, user_id: str, query: str, top_k: int | None = None) -> list[str]:
         return self._backend.search_memory(
@@ -142,7 +142,9 @@ class LongTermMemoryService:
             )
         )
 
-    def save_text(self, *, user_id: str, content: str, metadata: dict[str, Any] | None = None) -> bool:
+    def save_text(
+        self, *, user_id: str, content: str, metadata: dict[str, Any] | None = None
+    ) -> bool:
         payload = {
             "role": "user",
             "parts": [{"text": content}],

ksadk/model_policy.py

@@ -58,10 +58,7 @@ DEFAULT_MODEL_POLICY: dict[str, Any] = {
 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)
-        ):
+        if isinstance(value, Mapping) and isinstance(merged.get(key), dict):
             merged[key] = _deep_merge(merged[key], value)
         else:
             merged[key] = copy.deepcopy(value)
@@ -196,7 +193,12 @@ def build_runtime_model_policy_env(
     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")
+        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":
@@ -206,7 +208,10 @@ def build_runtime_model_policy_env(
             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))
+        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:
@@ -214,7 +219,10 @@ def build_runtime_model_policy_env(
             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))
+        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