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

ksadk/memory/models.py

@@ -0,0 +1,316 @@
+"""长期记忆结构化模型、操作结果与稳定异常类型。
+
+按《Hermes × KsADK 长期记忆实时性与纠错能力技术改造方案》§7.1/§7.2/§7.8 设计：
+
+- LongTermMemoryRecord: 结构化记忆记录（memory_id 来自服务端返回值）
+- MemoryWriteResult: 写入受理结果（accepted + queued/failed）
+- MemoryMutationResult: update/delete 结果（updated/deleted/already_absent/not_found/failed）
+- MemoryExtractionStatus: 后台提取状态
+  （queued/extracting/extracted/duplicate_skipped/failed/unknown）
+- MemoryOperationError 族: 稳定异常类型，供上层归一化处理
+
+设计要点：
+- memory_id 不能由正文 hash 临时生成；大部分情况稳定，但融合/人工编辑可能变化，
+  不能作为永久业务主键长期缓存。
+- 写入受理（accepted）与提取状态（extraction status）使用不同类型，
+  避免布尔值同时表示"请求成功"和"已经可检索"。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+__all__ = [
+    "LongTermMemoryRecord",
+    "MemoryWriteResult",
+    "MemoryMutationResult",
+    "MemoryExtractionStatus",
+    "MemoryOperationError",
+    "MemoryNotFoundError",
+    "UnsupportedMemoryOperation",
+    "MemoryPermissionError",
+    "MemoryConflictError",
+    "SESSION_STATE_PENDING",
+    "SESSION_STATE_EXTRACTING",
+    "SESSION_STATE_EXTRACTED",
+    "SESSION_STATE_DUPLICATE_SKIPPED",
+    "SESSION_STATE_EXTRACT_FAILED",
+    "map_session_state",
+]
+
+# ---- AICP ListSessions State 枚举（服务端已确认） ----
+SESSION_STATE_PENDING = 0  # 待提取
+SESSION_STATE_EXTRACTING = 50  # 提取中
+SESSION_STATE_EXTRACTED = 100  # 提取成功
+SESSION_STATE_DUPLICATE_SKIPPED = -50  # 重复跳过
+SESSION_STATE_EXTRACT_FAILED = -100  # 提取失败
+
+
+@dataclass(frozen=True)
+class LongTermMemoryRecord:
+    """结构化长期记忆记录。
+
+    Attributes:
+        memory_id: 服务端返回的记忆 ID。大部分情况稳定，但系统融合或
+            人工编辑可能改变 ID，不能作为永久业务主键长期缓存。
+        content: 记忆正文。
+        score: 相关度得分；后端没有 score 时为 None。
+        user_id: 归属用户 ID。
+        session_id: 来源 Session ID（后端能提供时）。
+        created_at: 创建时间（后端原始字符串，通常为 ISO 时间或毫秒时间戳）。
+        updated_at: 更新时间（后端原始字符串）。
+        metadata: 其他必要元数据。禁止放入 AK/SK、token、内部 endpoint 等敏感信息。
+    """
+
+    memory_id: str
+    content: str
+    score: float | None = None
+    user_id: str = ""
+    session_id: str = ""
+    created_at: str | None = None
+    updated_at: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class MemoryWriteResult:
+    """写入受理结果。
+
+    status 只表达受理层状态：queued（已入队）/ failed（受理失败）。
+    后续提取进展用 MemoryExtractionStatus 查询，不在写入热路径等待。
+    """
+
+    accepted: bool
+    status: str  # queued | failed
+    session_id: str = ""
+    message: str = ""
+
+
+@dataclass(frozen=True)
+class MemoryMutationResult:
+    """update/delete 操作结果。
+
+    status:
+        updated          - 原地更新成功；new_memory_id 为服务端返回的新句柄
+        deleted          - 软删除成功
+        already_absent   - 目标已不存在（如重复删除），与 deleted 分开审计
+        not_found        - 目标记录不存在
+        failed           - 操作失败
+    """
+
+    ok: bool
+    memory_id: str
+    new_memory_id: str = ""
+    status: str = ""  # updated | deleted | already_absent | not_found | failed
+    message: str = ""
+
+
+@dataclass(frozen=True)
+class MemoryExtractionStatus:
+    """后台提取状态查询结果。
+
+    status:
+        queued           - 写请求已被服务端接受，等待后台处理
+        extracting       - 后台已经开始提取
+        extracted        - ListSessions.State=100，提取完成
+        duplicate_skipped- State=-50，本次内容因重复被跳过（不是系统失败）
+        failed           - State=-100 或查询过程失败
+        unknown          - 状态未知（如 Session 未在 ListSessions 返回中）
+
+    searchable 单独用布尔标志表达：State=100 后通过 ListMemories 确认目标
+    记录可见时才为 True（见方案 §7.2：状态与 searchable 分离建模）。
+    """
+
+    session_id: str
+    state: int | None
+    status: str
+    searchable: bool = False
+    message: str = ""
+
+
+def map_session_state(state: int | None) -> str:
+    """将 AICP Session State 映射为统一提取状态字符串。"""
+    mapping = {
+        SESSION_STATE_PENDING: "queued",
+        SESSION_STATE_EXTRACTING: "extracting",
+        SESSION_STATE_EXTRACTED: "extracted",
+        SESSION_STATE_DUPLICATE_SKIPPED: "duplicate_skipped",
+        SESSION_STATE_EXTRACT_FAILED: "failed",
+    }
+    if state is None:
+        return "unknown"
+    return mapping.get(int(state), "unknown")
+
+
+# ---- 稳定异常类型（§7.8） ----
+
+
+class MemoryOperationError(RuntimeError):
+    """长期记忆操作基础异常。子类供上层按类型归一化处理。"""
+
+
+class MemoryNotFoundError(MemoryOperationError):
+    """目标记忆记录不存在。"""
+
+
+class UnsupportedMemoryOperation(MemoryOperationError):
+    """当前 backend 不支持该操作。
+
+    不支持某能力的 backend 必须显式抛出本异常（或返回 unsupported 结果），
+    不能静默追加一条新记忆来模拟 update。
+    """
+
+
+class MemoryPermissionError(MemoryOperationError):
+    """跨用户或越权访问记忆资源。"""
+
+
+class MemoryConflictError(MemoryOperationError):
+    """并发修改冲突（如记录已被融合导致 ID 变化）。"""
+
+
+# ---- PCM v2 数据模型（feature-prompt-context-optimize 分支）----
+# 与 master 的 LongTermMemoryRecord 共存；PCM 模块用这些类型
+
+MEMORY_MODEL_VERSION = "v1"
+
+MemoryScope = Literal["user", "agent", "workspace", "org"]
+MemoryType = Literal["profile", "fact", "episode"]
+MemoryStatus = Literal["active", "superseded", "deleted", "expired"]
+MemoryOperation = Literal["add", "update", "delete", "ignore"]
+MemorySearchStatus = Literal["ok", "not_configured", "timeout", "unauthorized", "failed"]
+SensitiveLabel = Literal[
+    "api_key",
+    "secret_key",
+    "access_key",
+    "cookie",
+    "auth_header",
+    "signed_url",
+    "dsn",
+    "pii",
+    "token",
+    "binary",
+    "none",
+]
+
+
+@dataclass(frozen=True)
+class MemoryRecord:
+    memory_id: str
+    tenant_id: str
+    workspace_id: str
+    scope: MemoryScope
+    scope_id: str
+    memory_type: MemoryType
+    content: str
+    summary: str
+    status: MemoryStatus
+    confidence: float
+    importance: float
+    valid_from: str
+    valid_to: str
+    expires_at: str
+    source_session_id: str
+    source_event_ids: list[str]
+    source_seq_range: tuple[int, int] | None
+    content_hash: str
+    version: int
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_at: str = ""
+    updated_at: str = ""
+
+    def is_active_now(self, *, now_iso: str = "") -> bool:
+        if self.status != "active":
+            return False
+        if self.expires_at and now_iso and self.expires_at < now_iso:
+            return False
+        if self.valid_to and now_iso and self.valid_to < now_iso:
+            return False
+        return True
+
+
+@dataclass(frozen=True)
+class MemoryCandidate:
+    candidate_id: str
+    operation: MemoryOperation
+    memory_type: MemoryType
+    scope: MemoryScope
+    scope_id: str
+    content: str
+    confidence: float
+    importance: float
+    source_event_ids: list[str]
+    conflicts_with: list[str] = field(default_factory=list)
+    sensitive_labels: list[SensitiveLabel] = field(default_factory=list)
+    reason: str = ""
+    slot_key: str = ""
+
+    def is_hard_rejected(self) -> bool:
+        return any(label != "none" for label in self.sensitive_labels)
+
+
+@dataclass(frozen=True)
+class MemorySearchRequest:
+    query: str
+    scopes: list[tuple[MemoryScope, str]]
+    memory_types: list[MemoryType]
+    top_k: int = 8
+    max_tokens: int = 4000
+    min_score: float = 0.45
+    as_of: str = ""
+    filters: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class MemorySearchResult:
+    status: MemorySearchStatus
+    records: list[MemoryRecord]
+    error_code: str | None
+    provider: str
+    latency_ms: int
+    accounting_accuracy: str
+    truncated_by_budget: bool = False
+
+
+@dataclass(frozen=True)
+class MemoryCapabilities:
+    semantic_search: bool
+    keyword_search: bool
+    metadata_filter: bool
+    versioned_update: bool
+    hard_delete: bool
+    ttl: bool
+    max_record_chars: int
+
+
+@dataclass(frozen=True)
+class CoreMemoryBlock:
+    name: str
+    description: str
+    content: str
+    max_tokens: int
+    writable: bool
+    source_memory_ids: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class MemoryDeleteRequest:
+    memory_id: str
+    scope: MemoryScope
+    scope_id: str
+    hard: bool = False
+
+
+@dataclass(frozen=True)
+class MemoryDeleteResult:
+    status: MemorySearchStatus
+    deleted: bool
+    error_code: str | None = None
+
+
+@dataclass(frozen=True)
+class CoreMemoryRequest:
+    scopes: list[tuple[MemoryScope, str]]
+    max_blocks: int = 8
+    max_tokens: int = 4096

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",
+]