agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/memory/models.py

@@ -19,7 +19,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any, Literal
+from typing import Any, Literal, Mapping
 
 __all__ = [
     "LongTermMemoryRecord",
@@ -195,6 +195,50 @@ SensitiveLabel = Literal[
     "binary",
     "none",
 ]
+#: 敏感级别（长任务方案 §7.2）：none=可跨作用域；low=限同作用域；high=禁止入长期 Memory。
+SensitivityLevel = Literal["none", "low", "high"]
+#: 写策略（长任务方案 §7.2）：auto=管线自动提交；user_confirm=需用户确认；locked=只读。
+WritePolicy = Literal["auto", "user_confirm", "locked"]
+MemoryArtifactModality = Literal[
+    "text", "image", "audio", "video", "document", "binary"
+]
+
+
+@dataclass(frozen=True)
+class MemoryArtifactRef:
+    """长期记忆引用的多模态 Artifact 元数据。
+
+    这里只保存可审计的引用与内容指纹，绝不保存 base64、文件字节或签名下载
+    URL。真正的内容仍由 Artifact Store 按权限读取，默认不会进入 Prompt。
+    """
+
+    uri: str
+    mime_type: str
+    content_hash: str
+    size_bytes: int
+    modality: MemoryArtifactModality = "binary"
+
+    def __post_init__(self) -> None:
+        if not self.uri.startswith("artifact://"):
+            raise ValueError("Memory Artifact 必须使用 artifact:// 稳定引用")
+        if not self.mime_type or "/" not in self.mime_type:
+            raise ValueError("Memory Artifact 必须声明合法 MIME type")
+        if not self.content_hash or len(self.content_hash) < 16:
+            raise ValueError("Memory Artifact 必须携带内容哈希")
+        if self.size_bytes < 0:
+            raise ValueError("Memory Artifact size_bytes 不能为负数")
+
+    @classmethod
+    def from_value(cls, value: MemoryArtifactRef | Mapping[str, Any]) -> MemoryArtifactRef:
+        if isinstance(value, cls):
+            return value
+        return cls(
+            uri=str(value.get("uri") or ""),
+            mime_type=str(value.get("mime_type") or ""),
+            content_hash=str(value.get("content_hash") or ""),
+            size_bytes=int(value.get("size_bytes") or 0),
+            modality=str(value.get("modality") or "binary"),  # type: ignore[arg-type]
+        )
 
 
 @dataclass(frozen=True)
@@ -222,6 +266,21 @@ class MemoryRecord:
     metadata: dict[str, Any] = field(default_factory=dict)
     created_at: str = ""
     updated_at: str = ""
+    # ---- 长任务方案 §7.2 兼容扩展（全部带默认值，additive） ----
+    #: 来源 Artifact 引用（大 Tool Result / 摘要正文不进正文，只留引用）。
+    source_artifact_refs: tuple[str, ...] = field(default=())
+    #: 多模态来源的结构化元数据。只含稳定引用，不含媒体正文或临时下载 URL。
+    source_artifacts: tuple[MemoryArtifactRef, ...] = field(default=())
+    #: 敏感级别：high 禁止入长期 Memory（须先脱敏）；low 限同作用域。
+    sensitivity: SensitivityLevel = "none"
+    #: 写策略：locked 记录只能显式解锁后更新；user_confirm 需用户确认。
+    write_policy: WritePolicy = "auto"
+    #: 本记录 supersede 的旧记录（审计链）。
+    supersedes: tuple[str, ...] = field(default=())
+
+    def __post_init__(self) -> None:
+        normalized = tuple(MemoryArtifactRef.from_value(item) for item in self.source_artifacts)
+        object.__setattr__(self, "source_artifacts", normalized)
 
     def is_active_now(self, *, now_iso: str = "") -> bool:
         if self.status != "active":
@@ -248,6 +307,17 @@ class MemoryCandidate:
     sensitive_labels: list[SensitiveLabel] = field(default_factory=list)
     reason: str = ""
     slot_key: str = ""
+    # ---- 长任务方案 §7.2 兼容扩展（additive） ----
+    source_artifact_refs: tuple[str, ...] = field(default=())
+    source_artifacts: tuple[MemoryArtifactRef, ...] = field(default=())
+    sensitivity: SensitivityLevel = "none"
+    write_policy: WritePolicy = "auto"
+    #: TTL（ISO 日期字符串；空 = 不过期）。时效数据必须有来源和 TTL（§7.3）。
+    expires_at: str = ""
+
+    def __post_init__(self) -> None:
+        normalized = tuple(MemoryArtifactRef.from_value(item) for item in self.source_artifacts)
+        object.__setattr__(self, "source_artifacts", normalized)
 
     def is_hard_rejected(self) -> bool:
         return any(label != "none" for label in self.sensitive_labels)
@@ -274,6 +344,12 @@ class MemorySearchResult:
     latency_ms: int
     accounting_accuracy: str
     truncated_by_budget: bool = False
+    #: Harness-side retrieval projection. Additive fields keep Provider contracts
+    #: stable while making semantic fallback visible to Studio/observability.
+    retrieval_strategy: str = "provider"
+    reranker_status: str = "not_configured"
+    semantic_scorer_status: str = "not_configured"
+    dedicated_reranker_status: str = "not_configured"
 
 
 @dataclass(frozen=True)

ksadk/memory/provider_resolver.py

@@ -63,6 +63,11 @@ def resolve_memory_provider(provider_ref: str) -> MemoryProviderLike:
 
         return LongTermMemoryService.from_env()
 
+    if ref in ("local-postgres", "postgres"):
+        from ksadk.memory.providers.local_postgres import PostgresMemoryProvider
+
+        return PostgresMemoryProvider()
+
     # 默认：持久 SQLite（local-default / local-sqlite / 未知 ref）
     from ksadk.memory.providers.local_sqlite import (
         resolve_default_memory_provider,

ksadk/memory/providers/local_candidates.py

@@ -0,0 +1,183 @@
+"""Local candidate consumption under the owning Provider's writer transaction.
+
+No candidate body is retained while pending/rejected. Original source markers
+outlive a forget so replay cannot count old prose as new evidence or resurrect it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import replace
+
+from ksadk.memory.extraction import NATIVE_USER_EXTRACTION_POLICY, derive_profile_slot_key
+from ksadk.memory.models import MemoryRecord
+from ksadk.memory.policy import MemoryPolicy, content_hash
+
+from .local_sqlite import VersionConflict, _now_iso, _row_to_record
+
+
+def namespace(tenant_id, workspace_id, scope, scope_id, memory_type):
+    identity = (tenant_id, None if scope == "org" else workspace_id, scope, scope_id, memory_type)
+    return hashlib.sha256(json.dumps(identity, ensure_ascii=False).encode()).hexdigest()
+
+
+def discard_slot_observations(conn, record):
+    key = namespace(record.tenant_id, record.workspace_id, record.scope,
+                    record.scope_id, record.memory_type)
+    slot = str(record.metadata.get("slot_key") or derive_profile_slot_key(record.content))
+    conn.execute(
+        "DELETE FROM memory_candidate_observations WHERE namespace=? "
+        "AND (content_hash=? OR (slot_key<>'' AND slot_key=?))",
+        (key, record.content_hash, slot),
+    )
+
+
+def consume_explicit_write_horizon(conn, record, original, candidates):
+    """A confirmed write consumes earlier eligible inputs in its actual slot.
+
+This is part of the same writer transaction as the fact and receipt. Keep only
+original identities/digests, and preserve unrelated slots for later extraction.
+"""
+    targets = (original, record) if original is not None else (record,)
+    slots = {value for target in targets if (
+        value := target.metadata.get("slot_key") or derive_profile_slot_key(target.content)
+    )}
+    hashes = {target.content_hash for target in targets}
+    for candidate, source_digest in candidates:
+        if (candidate.scope, candidate.scope_id) != (record.scope, record.scope_id):
+            raise VersionConflict("candidate_write_horizon_scope_unbound")
+        if not (candidate.slot_key in slots or content_hash(candidate.content) in hashes):
+            continue
+        key = namespace(record.tenant_id, record.workspace_id, candidate.scope,
+                        candidate.scope_id, candidate.memory_type)
+        for target in targets:
+            conn.execute(
+                "DELETE FROM memory_candidate_observations WHERE namespace=? "
+                "AND (content_hash=? OR (slot_key<>'' AND slot_key=?))",
+                (key, target.content_hash,
+                 target.metadata.get("slot_key") or derive_profile_slot_key(target.content)),
+            )
+        source = candidate.source_event_ids[0]
+        previous = conn.execute(
+            "SELECT source_digest FROM memory_candidate_sources "
+            "WHERE namespace=? AND source_event_id=?", (key, source),
+        ).fetchone()
+        if previous is not None and previous["source_digest"] != source_digest:
+            raise VersionConflict("candidate_source_changed")
+        conn.execute("INSERT OR IGNORE INTO memory_candidate_sources VALUES (?,?,?)",
+                     (key, source, source_digest))
+
+
+def consume(provider, candidate, *, operation_key, request_digest, source_session_id,
+            source_digest, tenant_id, workspace_id):
+    # The caller holds the Provider lock and BEGIN IMMEDIATE. Fact, source,
+    # independent observations and receipt commit/roll back together.
+    prior = provider._mutation_receipt_locked(operation_key, request_digest)
+    if prior is not None:
+        return prior
+    if tenant_id != provider._tenant_id or len(candidate.source_event_ids) != 1:
+        raise VersionConflict("candidate_source_or_tenant_unbound")
+    conn, source = provider._conn, candidate.source_event_ids[0]
+    key = namespace(tenant_id, workspace_id, candidate.scope, candidate.scope_id,
+                    candidate.memory_type)
+    fact_hash = content_hash(candidate.content)
+    fingerprint = hashlib.sha256(json.dumps(
+        (NATIVE_USER_EXTRACTION_POLICY, candidate.slot_key, fact_hash),
+    ).encode()).hexdigest()
+
+    def seal(decision, *, reason, observations=0, record=None, action=None):
+        result = {"committed": decision == "committed", "decision": decision,
+                  "code": reason, "observations": observations}
+        if record is not None:
+            result.update(memory_id=record.memory_id, version=record.version,
+                          status=record.status, content_hash=record.content_hash,
+                          action=action)
+        conn.execute("INSERT INTO memory_operation_receipts VALUES (?,?,?)",
+                     (operation_key, request_digest, json.dumps(result, ensure_ascii=False)))
+        return result
+
+    policy = MemoryPolicy()
+    early = policy.evaluate(candidate)
+    if early.decision == "reject":
+        return seal("rejected", reason=early.reason)
+    if len(candidate.content) > provider.capabilities().max_record_chars:
+        return seal("rejected", reason="candidate_content_over_budget")
+    original = conn.execute(
+        "SELECT source_digest FROM memory_candidate_sources "
+        "WHERE namespace=? AND source_event_id=?",
+        (key, source),
+    ).fetchone()
+    if original is not None:
+        if original["source_digest"] != source_digest:
+            raise VersionConflict("candidate_source_changed")
+        count = conn.execute(
+            "SELECT COUNT(*) FROM memory_candidate_observations "
+            "WHERE namespace=? AND candidate_key=?",
+            (key, fingerprint),
+        ).fetchone()[0]
+        return seal("duplicate_source", reason="original_source_already_consumed",
+                    observations=count)
+
+    # Native writes have a slot key. For older records derive only the same
+    # deterministic slot inside the exact tenant/workspace/scope/type partition.
+    rows = conn.execute(
+        "SELECT * FROM memory_records WHERE tenant_id=? AND scope=? AND scope_id=? "
+        "AND memory_type=? AND status='active' "
+        "AND (scope='org' OR workspace_id=?)",
+        (tenant_id, candidate.scope, candidate.scope_id, candidate.memory_type, workspace_id),
+    ).fetchall()
+    matches = [record for row in rows if (
+        (record := _row_to_record(row)).content_hash == fact_hash
+        or bool(candidate.slot_key) and (
+            record.metadata.get("slot_key") or derive_profile_slot_key(record.content)
+        ) == candidate.slot_key
+    )]
+    if len(matches) > 1:
+        return seal("rejected", reason="candidate_slot_ambiguous")
+    existing = matches[0] if matches else None
+    if existing is not None and existing.write_policy == "locked":
+        return seal("rejected", reason="candidate_slot_locked")
+    if candidate.operation != "add" and existing is None:
+        return seal("rejected", reason="candidate_correction_target_missing")
+    conn.execute("INSERT INTO memory_candidate_sources VALUES (?,?,?)",
+                 (key, source, source_digest))
+    conn.execute("INSERT INTO memory_candidate_observations VALUES (?,?,?,?,?,?)",
+                 (key, fingerprint, source, fact_hash, candidate.slot_key, _now_iso()))
+    observed = conn.execute(
+        "SELECT source_event_id FROM memory_candidate_observations "
+        "WHERE namespace=? AND candidate_key=? ORDER BY source_event_id",
+        (key, fingerprint),
+    ).fetchall()
+    count = len(observed)
+    effective = replace(candidate, operation="update") if existing else candidate
+    evaluated = policy.evaluate(effective, existing=existing, observations=count)
+    if evaluated.decision != "commit":
+        return seal(evaluated.decision, reason=evaluated.reason, observations=count)
+    if existing is not None and existing.content_hash == fact_hash:
+        return seal("duplicate", reason="same_current_fact", observations=count, record=existing)
+    from uuid import uuid4
+
+    record = MemoryRecord(
+        memory_id=existing.memory_id if existing else "memory_" + uuid4().hex,
+        tenant_id=tenant_id, workspace_id=workspace_id, scope=candidate.scope,
+        scope_id=candidate.scope_id, memory_type=candidate.memory_type,
+        content=candidate.content, summary=candidate.content, status="active",
+        confidence=candidate.confidence, importance=candidate.importance,
+        valid_from=existing.valid_from if existing else _now_iso(), valid_to="",
+        expires_at=candidate.expires_at,
+        source_session_id=existing.source_session_id if existing else source_session_id,
+        source_event_ids=list(dict.fromkeys((
+            *(existing.source_event_ids if existing else ()),
+            *(row["source_event_id"] for row in observed),
+        ))), source_seq_range=None, content_hash=fact_hash, version=1,
+        metadata={**(existing.metadata if existing else {}),
+                  "slot_key": candidate.slot_key,
+                  "extraction_policy": NATIVE_USER_EXTRACTION_POLICY,
+                  "mutation_session_id": source_session_id, "source_input_digest": source_digest},
+        write_policy=existing.write_policy if existing else
+        "user_confirm" if candidate.reason.startswith("explicit_user") else "auto",
+    )
+    saved = provider._upsert_locked(record, expected_version=existing.version if existing else None)
+    return seal("committed", reason=evaluated.reason, observations=count, record=saved,
+                action="correct" if existing else "remember")

ksadk/memory/providers/local_postgres.py

@@ -0,0 +1,200 @@
+"""Postgres 长期记忆 Provider（分布式后端，plan §9 / 方案 P1）。
+
+实现与 :class:`SqliteMemoryProvider` 相同的 MemoryProvider Protocol，
+但用 psycopg 连接 Postgres，支持多副本共享。
+
+依赖：``ksadk[postgres]`` extra（psycopg[binary]）。缺依赖时显式报错。
+
+配置：``KSADK_MEMORY_PROVIDER=local-postgres`` + ``KSADK_MEMORY_POSTGRES_DSN``
+或 ``KSADK_CHECKPOINT_DSN``（复用同一连接串）。
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from typing import Any
+
+from ksadk.memory.models import (
+    CoreMemoryRequest,
+    MemoryCapabilities,
+    MemoryDeleteRequest,
+    MemoryDeleteResult,
+    MemoryRecord,
+    MemorySearchRequest,
+    MemorySearchResult,
+)
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS memory_records (
+    memory_id TEXT PRIMARY KEY,
+    tenant_id TEXT NOT NULL,
+    workspace_id TEXT NOT NULL,
+    scope TEXT NOT NULL,
+    scope_id TEXT NOT NULL,
+    memory_type TEXT NOT NULL DEFAULT 'fact',
+    content TEXT NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1,
+    status TEXT NOT NULL DEFAULT 'active',
+    source_event_ids TEXT NOT NULL DEFAULT '[]',
+    sensitive_labels TEXT NOT NULL DEFAULT '[]',
+    confidence REAL NOT NULL DEFAULT 0.8,
+    importance REAL NOT NULL DEFAULT 0.6,
+    created_at REAL NOT NULL,
+    updated_at REAL NOT NULL,
+    expires_at REAL
+);
+CREATE INDEX IF NOT EXISTS idx_memory_scope
+ON memory_records (tenant_id, workspace_id, scope, scope_id);
+CREATE INDEX IF NOT EXISTS idx_memory_status
+ON memory_records (tenant_id, workspace_id, status);
+"""
+
+
+class PostgresMemoryProvider:
+    """Postgres 长期记忆 Provider（多副本共享，实现 MemoryProviderLike Protocol）。
+
+    与 :class:`SqliteMemoryProvider` 接口一致，但用 Postgres 连接。
+    线程安全：单连接 + per-thread lock（与 SQLite 版相同策略）。
+    ``last_error`` 供 Coordinator 区分"吞错返空"与"真无记忆"。
+    """
+
+    capabilities_def = MemoryCapabilities(
+        semantic_search=False,
+        keyword_search=True,
+        metadata_filter=True,
+        versioned_update=True,
+        hard_delete=True,
+        ttl=True,
+        max_record_chars=8192,
+    )
+
+    def __init__(
+        self,
+        *,
+        dsn: str | None = None,
+        tenant_id: str = "local",
+        workspace_id: str = "local",
+    ) -> None:
+        self._dsn = (
+            dsn
+            or os.getenv("KSADK_MEMORY_POSTGRES_DSN")
+            or os.getenv("KSADK_CHECKPOINT_DSN", "")
+        )
+        if not self._dsn:
+            raise RuntimeError(
+                "PostgresMemoryProvider 需要 DSN"
+                "（KSADK_MEMORY_POSTGRES_DSN 或 KSADK_CHECKPOINT_DSN）"
+            )
+        try:
+            import psycopg  # type: ignore[import-not-found]
+        except ImportError as exc:
+            raise RuntimeError(
+                "PostgresMemoryProvider 需要"
+                " ksadk[postgres] extra（psycopg[binary]）"
+            ) from exc
+        self._psycopg = psycopg
+        self._tenant_id = tenant_id
+        self._workspace_id = workspace_id
+        self._lock = threading.Lock()
+        self._conn = psycopg.connect(self._dsn, autocommit=True)
+        self._conn.execute(_SCHEMA)
+        self.last_error: str = ""
+
+    # ---- MemoryProvider Protocol ----
+
+    def capabilities(self) -> MemoryCapabilities:
+        return self.capabilities_def
+
+    def search(self, request: MemorySearchRequest) -> MemorySearchResult:
+        start = time.monotonic()
+        try:
+            with self._lock:
+                query = request.query.strip()
+                if not query:
+                    return MemorySearchResult(
+                        records=[],
+                        elapsed_ms=int((time.monotonic() - start) * 1000),
+                    )
+                # keyword search (ILIKE, Postgres 大小写不敏感)
+                pattern = f"%{query}%"
+                rows = self._conn.execute(
+                    """SELECT * FROM memory_records
+                       WHERE tenant_id = %s AND workspace_id = %s
+                         AND status = 'active'
+                         AND (content ILIKE %s)
+                       ORDER BY importance DESC, updated_at DESC
+                       LIMIT %s""",
+                    (self._tenant_id, self._workspace_id, pattern, request.top_k),
+                ).fetchall()
+                records = [self._row_to_record(row) for row in rows]
+                return MemorySearchResult(
+                    records=records,
+                    elapsed_ms=int((time.monotonic() - start) * 1000),
+                )
+        except Exception as exc:  # noqa: BLE001 - 不阻断主对话
+            self.last_error = str(exc)
+            return MemorySearchResult(records=[], elapsed_ms=int((time.monotonic() - start) * 1000))
+
+    def list_core(self, request: CoreMemoryRequest) -> list[MemoryRecord]:
+        try:
+            with self._lock:
+                rows = self._conn.execute(
+                    """SELECT * FROM memory_records
+                       WHERE tenant_id = %s AND workspace_id = %s
+                         AND status = 'active'
+                       ORDER BY importance DESC, updated_at DESC
+                       LIMIT %s""",
+                    (self._tenant_id, self._workspace_id, request.max_blocks),
+                ).fetchall()
+                return [self._row_to_record(row) for row in rows]
+        except Exception as exc:  # noqa: BLE001
+            self.last_error = str(exc)
+            return []
+
+    def delete(self, request: MemoryDeleteRequest) -> MemoryDeleteResult:
+        try:
+            with self._lock:
+                self._conn.execute(
+                    "DELETE FROM memory_records WHERE memory_id = %s"
+                    " AND scope = %s AND scope_id = %s",
+                    (request.memory_id, request.scope, request.scope_id),
+                )
+            return MemoryDeleteResult(deleted=True)
+        except Exception as exc:  # noqa: BLE001
+            self.last_error = str(exc)
+            return MemoryDeleteResult(deleted=False)
+
+    def close(self) -> None:
+        with self._lock:
+            if self._conn:
+                self._conn.close()
+
+    # ---- helpers ----
+
+    def _row_to_record(self, row: Any) -> MemoryRecord:
+        # psycopg Row 可按列名访问
+        import json
+
+        return MemoryRecord(
+            memory_id=row["memory_id"],
+            tenant_id=row["tenant_id"],
+            workspace_id=row["workspace_id"],
+            scope=row["scope"],
+            scope_id=row["scope_id"],
+            memory_type=row["memory_type"],
+            content=row["content"],
+            version=row["version"],
+            status=row["status"],
+            source_event_ids=json.loads(row["source_event_ids"] or "[]"),
+            sensitive_labels=json.loads(row["sensitive_labels"] or "[]"),
+            confidence=row["confidence"],
+            importance=row["importance"],
+            created_at=row["created_at"],
+            updated_at=row["updated_at"],
+            expires_at=row["expires_at"],
+        )
+
+
+__all__ = ["PostgresMemoryProvider"]