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

ksadk/memory/policy.py

@@ -0,0 +1,215 @@
+"""Memory 写入策略、敏感信息拒绝与冲突解决（方案 §10.4 / §19）。
+
+策略与阈值必须属于 ``MemoryPolicy``，不能硬编码在 Runner（方案 §10.4 末）。Candidate 进入
+Provider 前必须执行 Secret/PII 检查；硬拒绝标签（api_key/secret_key/access_key/cookie/
+auth_header/signed_url/dsn/token/binary）一律 ``reject``，不写入长期记忆（方案 §19）。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from typing import Literal
+
+from ksadk.memory.models import MemoryCandidate, MemoryOperation, MemoryRecord, SensitiveLabel
+
+# 硬拒绝敏感标签：出现任一即 reject，绝不写入（方案 §19）。
+HARD_REJECT_LABELS: frozenset[SensitiveLabel] = frozenset(
+    {
+        "api_key",
+        "secret_key",
+        "access_key",
+        "cookie",
+        "auth_header",
+        "signed_url",
+        "dsn",
+        "token",
+        "binary",
+    }
+)
+
+PolicyDecision = Literal["commit", "pending", "reject"]
+
+
+@dataclass(frozen=True)
+class MemoryPolicyThresholds:
+    """候选写入阈值（方案 §10.4 初始值）。
+
+    阈值属于 Policy，不硬编码在 Runner。可由部署/配置覆盖。
+    """
+
+    explicit_user_request: float = 0.60
+    verified_tool_fact: float = 0.80
+    implicit_preference: float = 0.85
+    implicit_preference_min_observations: int = 2
+    episode_importance: float = 0.70
+
+
+@dataclass(frozen=True)
+class MemoryEvaluation:
+    """对单个 Candidate 的策略判定结果。"""
+
+    decision: PolicyDecision
+    operation: MemoryOperation
+    reason: str
+    new_version: int | None = None
+    conflicts_with: list[str] = field(default_factory=list)
+
+
+# 敏感信息正则（best-effort，方案 §19）。只做写入前拦截，不做完整 DLP。
+_SECRET_PATTERNS: tuple[tuple[re.Pattern[str], SensitiveLabel], ...] = (
+    (re.compile(r"(?i)api[_-]?key\s*[:=]\s*\S+"), "api_key"),
+    (re.compile(r"(?i)secret[_-]?key\s*[:=]\s*\S+"), "secret_key"),
+    (re.compile(r"(?i)access[_-]?key\s*[:=]\s*\S+"), "access_key"),
+    (re.compile(r"(?i)AKIA[0-9A-Z]{16}"), "access_key"),
+    (re.compile(r"(?i)cookie\s*[:=]\s*\S+"), "cookie"),
+    (re.compile(r"(?i)authorization\s*[:=]\s*bearer\s+\S+"), "auth_header"),
+    (
+        re.compile(r"https?://\S+?(?:X-Amz-Signature|X-Amz-Security-Token|signed)=", re.I),
+        "signed_url",
+    ),
+    (re.compile(r"(?i)(postgres|mysql|mongodb|redis)://\S+:\S+@\S+"), "dsn"),
+    (re.compile(r"(?i)sk-[A-Za-z0-9]{20,}"), "token"),
+)
+
+
+def detect_sensitive_labels(
+    content: str, candidate_labels: list[SensitiveLabel]
+) -> list[SensitiveLabel]:
+    """对 Candidate 正文做敏感信息检测（方案 §19）。
+
+    先采纳 Candidate 自带的 ``sensitive_labels``，再用正则做 best-effort 补检。任一硬拒绝
+    标签命中即整体拒绝。
+    """
+    labels: set[SensitiveLabel] = set()
+    for label in candidate_labels:
+        if label and label != "none":
+            labels.add(label)
+    text = str(content or "")
+    for pattern, label in _SECRET_PATTERNS:
+        if pattern.search(text):
+            labels.add(label)
+    # 二进制特征：大量非文本/重复字节不做完整检测，仅按显式标签处理。
+    return sorted(labels)
+
+
+def _content_hash(content: str) -> str:
+    return "sha256:" + hashlib.sha256(str(content or "").encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class MemoryPolicy:
+    """写入策略与冲突解决（方案 §10.4）。
+
+    无状态、可复用。``evaluate`` 不接触 Provider；commit 由 Coordinator 执行。
+    """
+
+    thresholds: MemoryPolicyThresholds = field(default_factory=MemoryPolicyThresholds)
+
+    def evaluate(
+        self,
+        candidate: MemoryCandidate,
+        *,
+        existing: MemoryRecord | None = None,
+        observations: int = 1,
+    ) -> MemoryEvaluation:
+        """评估单个 Candidate（方案 §10.4 决策表）。
+
+        - 硬拒绝敏感标签 → ``reject``（绝不写入）。
+        - 用户明确"记住"（reason 含 explicit）→ 同步 propose，达阈值 commit。
+        - 用户明确"忘掉"（operation=delete）→ 解析目标删除；歧义时不猜测 → reject。
+        - 一次性当前任务状态 / 模型猜测 → 留 Session，不写 → ``reject``
+          （reason 标 ``not_durable``）。
+        - 与旧事实冲突 → ``update``/``supersede``，不覆盖历史来源。
+        """
+        labels = detect_sensitive_labels(candidate.content, list(candidate.sensitive_labels))
+        hard_hit = any(label in HARD_REJECT_LABELS for label in labels)
+        if hard_hit or candidate.is_hard_rejected():
+            return MemoryEvaluation(
+                decision="reject",
+                operation="ignore",
+                reason=f"sensitive_label_rejected:{','.join(labels) or 'explicit'}",
+                conflicts_with=list(candidate.conflicts_with),
+            )
+
+        if candidate.operation == "delete":
+            # 删除需明确目标；reason 为空或含 "ambiguous" 时不猜测（方案 §10.4）。
+            if not candidate.conflicts_with and not candidate.reason.strip():
+                return MemoryEvaluation(
+                    decision="reject",
+                    operation="ignore",
+                    reason="delete_without_target",
+                )
+            return MemoryEvaluation(
+                decision="commit",
+                operation="delete",
+                reason="explicit_delete",
+                conflicts_with=list(candidate.conflicts_with),
+            )
+
+        # 一次性当前任务状态 / 模型猜测不写长期记忆（方案 §10.4）。
+        reason_lc = candidate.reason.lower()
+        if "model_guess" in reason_lc or "transient" in reason_lc or "current_plan" in reason_lc:
+            return MemoryEvaluation(
+                decision="reject",
+                operation="ignore",
+                reason="not_durable",
+            )
+
+        # 阈值判定（方案 §10.4 初始阈值）。
+        threshold = self._threshold_for(candidate, observations)
+        if candidate.confidence < threshold:
+            return MemoryEvaluation(
+                decision="pending",
+                operation=candidate.operation,
+                reason=f"below_threshold:{candidate.confidence:.2f}<{threshold:.2f}",
+            )
+
+        # 冲突：update/supersede，不覆盖历史来源（方案 §10.4）。
+        if existing is not None and candidate.operation != "add":
+            return MemoryEvaluation(
+                decision="commit",
+                operation="update",
+                reason="conflict_supersede",
+                new_version=existing.version + 1,
+                conflicts_with=[existing.memory_id],
+            )
+
+        return MemoryEvaluation(
+            decision="commit",
+            operation=candidate.operation,
+            reason="threshold_met",
+            new_version=1,
+        )
+
+    def _threshold_for(self, candidate: MemoryCandidate, observations: int) -> float:
+        t = self.thresholds
+        reason_lc = candidate.reason.lower()
+        if "explicit" in reason_lc or "user_request" in reason_lc:
+            return t.explicit_user_request
+        if "tool_fact" in reason_lc or "verified" in reason_lc:
+            return t.verified_tool_fact
+        if candidate.memory_type == "episode":
+            return t.episode_importance
+        # implicit preference
+        if observations < t.implicit_preference_min_observations:
+            # 观察次数不足，抬高到 implicit 阈值且要求更多观察 → pending。
+            return float("inf")
+        return t.implicit_preference
+
+
+def content_hash(content: str) -> str:
+    """暴露给 Coordinator/Provider 的稳定 content hash。"""
+    return _content_hash(content)
+
+
+__all__ = [
+    "HARD_REJECT_LABELS",
+    "MemoryEvaluation",
+    "MemoryPolicy",
+    "MemoryPolicyThresholds",
+    "PolicyDecision",
+    "content_hash",
+    "detect_sensitive_labels",
+]

ksadk/memory/provider.py

@@ -0,0 +1,47 @@
+"""MemoryProvider Protocol 与能力声明（方案 §10.5）。
+
+Provider 合同是本地与云端一致性的运行时边界：本地用 SQLite Provider，云端用 HTTP/SDK
+Provider，二者共用同一套契约测试（方案 §17.4）。``expected_version`` 用于并发更新乐观锁，
+避免多个 Run 并发更新同一偏好时静默覆盖。
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from ksadk.memory.models import (
+    CoreMemoryRequest,
+    MemoryCapabilities,
+    MemoryDeleteRequest,
+    MemoryDeleteResult,
+    MemoryRecord,
+    MemorySearchRequest,
+    MemorySearchResult,
+)
+
+
+class MemoryProvider(Protocol):
+    """平台长期记忆 Provider 合同（方案 §10.5）。
+
+    实现必须按 ``scope`` 隔离；``scope_id`` 由可信 Principal/Runtime Projection 决定，
+    不能信任用户自行提交的 scope_id（方案 §19）。异常路径不得把错误文本塞进检索结果正文。
+    """
+
+    def capabilities(self) -> MemoryCapabilities: ...
+
+    def search(self, request: MemorySearchRequest) -> MemorySearchResult: ...
+
+    def get(self, memory_id: str) -> MemoryRecord | None: ...
+
+    def upsert(
+        self, record: MemoryRecord, *, expected_version: int | None
+    ) -> MemoryRecord: ...
+
+    def delete(self, request: MemoryDeleteRequest) -> MemoryDeleteResult: ...
+
+    def list_core(self, request: CoreMemoryRequest) -> list[MemoryRecord]: ...
+
+
+__all__ = [
+    "MemoryProvider",
+]

ksadk/memory/provider_adapter.py

@@ -0,0 +1,159 @@
+"""Memory Provider Adapter —— 统一不同 Provider 接口为 MemoryProvider Protocol（方案 §2）。
+
+不同后端接口不统一：
+- SqliteMemoryProvider: upsert/search/delete（MemoryProvider Protocol）
+- BaseLongTermMemoryBackend: save_memory/search_memory
+- LongTermMemoryService: save_event_strings/search_entries
+
+本模块把它们统一适配为 MemoryCoordinator 可消费的接口。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ksadk.memory.models import (
+    MemoryDeleteRequest,
+    MemoryDeleteResult,
+    MemoryRecord,
+    MemorySearchRequest,
+    MemorySearchResult,
+)
+
+
+class LegacyMemoryAdapter:
+    """把 BaseLongTermMemoryBackend / LongTermMemoryService 适配为 MemoryProvider Protocol。
+
+    save_memory → upsert（每条 event_string 构造 MemoryRecord）
+    search_memory → search（返回 MemorySearchResult）
+    """
+
+    def __init__(self, backend: Any) -> None:
+        self._backend = backend
+        self.last_error = getattr(backend, "last_error", "")
+
+    def capabilities(self):
+        from ksadk.memory.models import MemoryCapabilities
+
+        return MemoryCapabilities(
+            semantic_search=False,
+            keyword_search=True,
+            metadata_filter=False,
+            versioned_update=False,
+            hard_delete=False,
+            ttl=False,
+            max_record_chars=8192,
+        )
+
+    def search(self, request: MemorySearchRequest) -> MemorySearchResult:
+        """统一 search：用 search_memory/search_entries 取原始字符串列表。"""
+        import time
+
+        start = time.monotonic()
+        try:
+            # BaseLongTermMemoryBackend.search_memory
+            if hasattr(self._backend, "search_memory"):
+                entries = self._backend.search_memory(
+                    user_id=request.scopes[0][1] if request.scopes else "",
+                    query=request.query,
+                    top_k=request.top_k,
+                )
+            # LongTermMemoryService.search_entries
+            elif hasattr(self._backend, "search_entries"):
+                entries = self._backend.search_entries(
+                    user_id=request.scopes[0][1] if request.scopes else "",
+                    query=request.query,
+                    top_k=request.top_k,
+                )
+            else:
+                entries = []
+        except Exception:  # noqa: BLE001
+            return MemorySearchResult(
+                status="failed",
+                records=[],
+                error_code="provider_error",
+                provider=type(self._backend).__name__,
+                latency_ms=int((time.monotonic() - start) * 1000),
+                accounting_accuracy="opaque",
+            )
+
+        # 转为 MemoryRecord 列表
+        records: list[MemoryRecord] = []
+        for i, entry in enumerate(entries):
+            records.append(
+                MemoryRecord(
+                    memory_id=f"legacy_{i}",
+                    tenant_id="local",
+                    workspace_id="local",
+                    scope="user",
+                    scope_id=request.scopes[0][1] if request.scopes else "",
+                    memory_type="fact",
+                    content=entry,
+                    summary=entry[:200],
+                    status="active",
+                    confidence=0.8,
+                    importance=0.5,
+                    valid_from="",
+                    valid_to="",
+                    expires_at="",
+                    source_session_id="",
+                    source_event_ids=[],
+                    source_seq_range=None,
+                    content_hash=f"sha256:{hash(entry) & 0xFFFFFFFFFFFFFFFF:016x}",
+                    version=1,
+                )
+            )
+        return MemorySearchResult(
+            status="ok",
+            records=records,
+            error_code=None,
+            provider=type(self._backend).__name__,
+            latency_ms=int((time.monotonic() - start) * 1000),
+            accounting_accuracy="estimated",
+        )
+
+    def upsert(self, record: MemoryRecord, *, expected_version: int | None) -> MemoryRecord:
+        """统一 upsert：用 save_memory/save_event_strings。"""
+        import json
+
+        event_str = json.dumps(
+            {"parts": [{"text": record.content}], "metadata": record.metadata},
+            ensure_ascii=False,
+        )
+        success = True
+        if hasattr(self._backend, "save_memory"):
+            success = bool(
+                self._backend.save_memory(user_id=record.scope_id, event_strings=[event_str])
+            )
+        elif hasattr(self._backend, "save_event_strings"):
+            success = bool(
+                self._backend.save_event_strings(user_id=record.scope_id, event_strings=[event_str])
+            )
+        if not success:
+            raise RuntimeError(
+                f"Memory Provider save returned False: {type(self._backend).__name__}"
+            )
+        return record
+
+    def delete(self, request: MemoryDeleteRequest) -> MemoryDeleteResult:
+        return MemoryDeleteResult(status="ok", deleted=False, error_code="not_supported")
+
+    def list_core(self, request) -> list[MemoryRecord]:
+        return []
+
+
+def adapt_as_memory_provider(obj: Any) -> Any:
+    """把任意后端适配为 MemoryProvider Protocol 兼容对象。
+
+    - 已经是 MemoryProvider Protocol（有 upsert/search）→ 原样返回
+    - BaseLongTermMemoryBackend / LongTermMemoryService → LegacyMemoryAdapter
+    """
+    # 已经兼容 MemoryProvider Protocol
+    if hasattr(obj, "upsert") and hasattr(obj, "search"):
+        return obj
+
+    # 需要适配
+    return LegacyMemoryAdapter(obj)
+
+
+__all__ = ["LegacyMemoryAdapter", "adapt_as_memory_provider"]

ksadk/memory/provider_resolver.py

@@ -0,0 +1,71 @@
+"""MemoryProviderResolver —— 根据 providerRef 解析真实 Memory Provider（方案 §2）。
+
+providerRef 值映射：
+  "local-default" → 持久 SQLite（resolve_default_memory_provider）
+  "local-sqlite"  → 同上
+  "local-inmemory" → InMemoryLTMBackend（测试用）
+  "http"          → HttpLTMBackend（需 KSADK_LTM_HTTP_URL/TOKEN）
+  "sdk"           → SdkLTMBackend（需 AK/SK + namespace）
+  "longterm-service" → LongTermMemoryService.from_env()
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class MemoryProviderLike(Protocol):
+    def search_memory(self, user_id: str, query: str, top_k: int = 5, **kwargs) -> list[str]: ...
+    def save_memory(self, user_id: str, event_strings: list[str], **kwargs) -> bool: ...
+
+
+def resolve_memory_provider(provider_ref: str) -> MemoryProviderLike:
+    """根据 providerRef 解析真实 Memory Provider。
+
+    providerRef 值映射：
+      "local-default" / "local-sqlite" → 持久 SQLite
+      "local-inmemory" → InMemoryLTMBackend（测试用）
+      "http" → HttpLTMBackend（需 KSADK_LTM_HTTP_URL/TOKEN）
+      "sdk" → SdkLTMBackend（需 AK/SK + namespace）
+      "longterm-service" → LongTermMemoryService.from_env()
+      其他 → fallback 到持久 SQLite（兼容旧 AgentVersion）
+    """
+    ref = str(provider_ref or "").strip().lower()
+
+    if ref in ("local-inmemory", "inmemory"):
+        from ksadk.memory.adk.backends.inmemory_ltm_backend import (
+            InMemoryLTMBackend,
+        )
+
+        return InMemoryLTMBackend()
+
+    if ref in ("http",):
+        import os
+
+        from ksadk.memory.adk.backends.http_ltm_backend import HttpLTMBackend
+
+        return HttpLTMBackend(
+            index="ksadk",
+            base_url=os.environ.get("KSADK_LTM_HTTP_URL", ""),
+            token=os.environ.get("KSADK_LTM_HTTP_TOKEN", ""),
+        )
+
+    if ref in ("sdk",):
+        from ksadk.memory.adk.backends.sdk_ltm_backend import SdkLTMBackend
+
+        return SdkLTMBackend(index="ksadk")
+
+    if ref in ("longterm-service",):
+        from ksadk.memory.service import LongTermMemoryService
+
+        return LongTermMemoryService.from_env()
+
+    # 默认：持久 SQLite（local-default / local-sqlite / 未知 ref）
+    from ksadk.memory.providers.local_sqlite import (
+        resolve_default_memory_provider,
+    )
+
+    return resolve_default_memory_provider()
+
+
+__all__ = ["MemoryProviderLike", "resolve_memory_provider"]

ksadk/memory/providers/__init__.py

@@ -0,0 +1,5 @@
+"""Memory Provider 实现入口。"""
+
+from ksadk.memory.providers.local_sqlite import SqliteMemoryProvider
+
+__all__ = ["SqliteMemoryProvider"]