recallweaver 1.2.0__py3-none-any.whl

plugins/dsh_adapter.py

@@ -0,0 +1,87 @@
+"""RecallWeaver 的 DSH（DeepSeek Harness）桌宠适配器。
+
+给刚接触 Python 的 DSH 用户：
+1. 先在运行 DSH 的同一个 Python 环境中安装 RecallWeaver：
+   ``python -m pip install recallweaver``。如果使用尚未发布的源码版本，
+   请在 RecallWeaver 项目根目录运行 ``python -m pip install -e .``。
+2. 将本文件复制到 DSH 文档指定的插件目录。若 DSH 要求插件有特定入口
+   名称，请在其插件入口中导入 ``DSHMemoryAdapter``，并保留下面的调用：
+   ``adapter.process_message(user_id, message)``。
+3. DSH 插件调用该方法后，会先将本轮消息写入对应用户的记忆空间，再检索
+   相关事实；返回的字符串可直接作为本轮对话的 System Prompt。
+4. 默认数据库路径取 RecallWeaver 的 ``RECALLWEAVER_DB_PATH`` 配置；
+   未配置时使用当前工作目录下的 ``recallweaver.db``。如需指定其他路径，
+   可在创建适配器时传入 ``db_path``。
+
+本文件是一个轻量的 Python 桥接示例，并不依赖或假设 DSH 的特定插件 SDK。
+"""
+
+import os
+
+from recallweaver.api import RecallWeaverAPI
+from recallweaver.config import settings
+from recallweaver.models import MemoryOut
+
+
+class DSHMemoryAdapter:
+    """将 RecallWeaver 的记忆读写能力桥接到 DSH 的 System Prompt。"""
+
+    def __init__(
+        self,
+        db_path: str | None = None,
+        api: RecallWeaverAPI | None = None,
+    ) -> None:
+        """创建适配器；通常无需参数，测试或自定义部署可注入数据库/API。"""
+        configured_db_path = (
+            db_path
+            or os.environ.get("RECALLWEAVER_DB_PATH")
+            or settings.db_path
+        )
+        self.api = api or RecallWeaverAPI(configured_db_path)
+
+    @staticmethod
+    def _fact_text(memory: MemoryOut) -> str:
+        """把文本记忆或图谱事实转换成可放入提示词的一行文字。"""
+        if memory.content:
+            return memory.content
+
+        # 图谱结果没有 content，使用关系的主语、关系和宾语组成自然语言片段。
+        parts = (
+            memory.subject or memory.start_name,
+            memory.predicate or memory.relation,
+            memory.object or memory.entity_name,
+        )
+        return " ".join(part for part in parts if part)
+
+    def process_message(self, user_id: str, message: str) -> str:
+        """写入并召回该用户的记忆，返回 DSH 可用的 System Prompt。
+
+        DSH 侧只需提供用户标识和本轮消息；``user_id`` 同时作为 RecallWeaver
+        的租户标识，确保不同桌宠用户之间的记忆互相隔离。
+        """
+        self.api.add_memory(message, tenant_id=user_id)
+        recalled = self.api.recall(message, limit=5, tenant_id=user_id)
+
+        # 保持事实顺序并去重，避免相同内容重复占用模型上下文。
+        facts = list(
+            dict.fromkeys(
+                fact
+                for memory in recalled
+                if (fact := self._fact_text(memory))
+            )
+        )
+        memory_context = (
+            "\n".join(f"- {fact}" for fact in facts)
+            if facts
+            else "（暂无相关记忆）"
+        )
+        return (
+            "你是一个拥有长期记忆的私人助手。\n"
+            "以下是你记得关于用户的事实：\n"
+            f"{memory_context}\n"
+            "请结合上述记忆回答用户；若无相关记忆，请直接回答。"
+        )
+
+    def on_message(self, user_id: str, message: str) -> str:
+        """提供 DSH 常见事件入口名称，返回与 process_message 相同的提示词。"""
+        return self.process_message(user_id, message)

recallweaver/__init__.py

@@ -0,0 +1,25 @@
+"""RecallWeaver 的公共包接口。
+
+通过在包初始化时重新导出常用对象，外部代码可以直接从
+``recallweaver`` 导入配置、异常类型和数据库管理器，而不必记住内部模块路径。
+"""
+
+# 暴露全局配置实例，使调用方可以使用 ``recallweaver.settings`` 读取项目配置。
+from .config import settings
+# 暴露项目异常体系的基类，便于调用方统一捕获 RecallWeaver 相关错误。
+from .errors import RecallWeaverError
+from .errors import DatabaseError, ValidationError
+# 暴露数据库管理类和默认管理器，分别用于创建自定义实例或直接操作默认数据库。
+from .db import Database, db_manager
+from .api import RecallWeaverAPI
+
+# 显式声明包的公共接口，避免内部实现细节被误认为稳定的公开 API。
+__all__ = [
+    "Database",
+    "DatabaseError",
+    "RecallWeaverAPI",
+    "RecallWeaverError",
+    "ValidationError",
+    "db_manager",
+    "settings",
+]

recallweaver/api.py

@@ -0,0 +1,513 @@
+"""依赖注入式 RecallWeaver API 与 Pydantic 契约模型。"""
+
+import time
+from typing import Any, NoReturn, TypeVar
+
+from pydantic import BaseModel, ValidationError as PydanticValidationError
+
+from recallweaver.config import settings
+from recallweaver.db import Database
+from recallweaver.decay_engine import DecayEngine
+from recallweaver.errors import DatabaseError, ValidationError
+from recallweaver.graph import GraphManager
+from recallweaver.memory_manager import MemoryManager
+from recallweaver.models import (
+    DatabasePathIn,
+    HistoryIn,
+    HistoryOut,
+    MemoryIdOut,
+    MemoryOut,
+    RecallIn,
+    SuccessOut,
+    TextMemoryIn,
+    TripleIn,
+)
+from recallweaver.observability.logging import get_logger, trace_context
+from recallweaver.observability.metrics import MetricsCollector
+from recallweaver.retrieval import Retriever
+
+ModelT = TypeVar("ModelT", bound=BaseModel)
+
+
+def _validate_input(model_type: type[ModelT], **values: Any) -> ModelT:
+    """Validate an input model and translate Pydantic errors to API errors.
+
+    Args:
+        model_type: Pydantic model class used to validate the input.
+        **values: Input fields passed to the model.
+
+    Returns:
+        A validated instance of ``model_type``.
+
+    Raises:
+        ValidationError: If any input value violates the API contract.
+    """
+    try:
+        return model_type.model_validate(values)
+    except PydanticValidationError as exc:
+        raise ValidationError(str(exc)) from exc
+
+
+def _raise_database_error(operation: str, exc: Exception) -> NoReturn:
+    """Translate lower-level storage exceptions at the public API boundary.
+
+    Args:
+        operation: Human-readable operation name for the error message.
+        exc: The exception raised by an injected component.
+
+    Raises:
+        DatabaseError: Always, with the original exception chained.
+    """
+    if isinstance(exc, DatabaseError):
+        raise exc
+    raise DatabaseError(f"{operation} failed: {exc}") from exc
+
+
+class RecallWeaverAPI:
+    """Expose validated memory, graph, hybrid-recall, and history operations.
+
+    Args:
+        db_path: Filesystem path of the SQLite database to use.
+
+    All engines share the injected database manager so a single API instance
+    never reads from or writes to the process-global database by accident.
+    """
+
+    def __init__(self, db_path: str) -> None:
+        """Create and initialize all engines for one SQLite database.
+
+        Args:
+            db_path: Path to the database file.
+
+        Raises:
+            DatabaseError: If the database cannot be initialized.
+            ValidationError: If ``db_path`` is empty.
+        """
+        database_path = _validate_input(DatabasePathIn, db_path=db_path)
+        self.database_manager = Database(database_path.db_path)
+        self.decay_engine = DecayEngine()
+        self.memory_manager = MemoryManager(database=self.database_manager)
+        self.graph_manager = GraphManager(database=self.database_manager)
+        self.retriever = Retriever(
+            database=self.database_manager,
+            decay_engine=self.decay_engine,
+        )
+        self.metrics = MetricsCollector()
+        self.logger = get_logger(__name__)
+        try:
+            self.database_manager.init_db(verbose=False)
+        except Exception as exc:
+            _raise_database_error("database initialization", exc)
+
+    def remember_triple(
+        self,
+        subject: str,
+        predicate: str,
+        object_: str,
+        tenant_id: str = "default",
+    ) -> bool:
+        """Insert a fact and record request count plus safe error events."""
+        started_at = time.perf_counter()
+        self.logger.info(
+            "收到写入请求: %s-%s-%s",
+            subject,
+            predicate,
+            object_,
+            extra={
+                "action": "remember_triple",
+                "details": {
+                    "event": "收到写入请求",
+                    "subject": subject,
+                    "predicate": predicate,
+                    "object": object_,
+                },
+            },
+        )
+        try:
+            return self._remember_triple(
+                subject,
+                predicate,
+                object_,
+                tenant_id=tenant_id,
+            )
+        except Exception as exc:
+            self.logger.error(
+                "remember_triple failed: %s",
+                type(exc).__name__,
+                exc_info=True,
+            )
+            raise
+        finally:
+            duration_ms = (time.perf_counter() - started_at) * 1_000
+            self.metrics.record_remember(duration_ms)
+
+    def _remember_triple(
+        self,
+        subject: str,
+        predicate: str,
+        object_: str,
+        tenant_id: str = "default",
+    ) -> bool:
+        """Insert or resolve a time-versioned graph fact.
+
+        Args:
+            subject: Entity that owns the fact.
+            predicate: Relationship name.
+            object_: Related entity or value.
+            tenant_id: Tenant namespace for all created records.
+
+        Returns:
+            ``True`` when the fact is stored or is already current.
+
+        Raises:
+            ValidationError: If a fact field or tenant ID is empty or invalid.
+            DatabaseError: If persistence or conflict resolution fails.
+        """
+        request = _validate_input(
+            TripleIn,
+            subject=subject,
+            predicate=predicate,
+            object_=object_,
+            tenant_id=tenant_id,
+        )
+        try:
+            result = self.memory_manager.remember_with_conflict_resolution(
+                subject=request.subject,
+                predicate=request.predicate,
+                object_=request.object_,
+                tenant_id=request.tenant_id,
+            )
+            return SuccessOut(success=result).success
+        except PydanticValidationError as exc:
+            raise ValidationError(str(exc)) from exc
+        except Exception as exc:
+            _raise_database_error("remember triple", exc)
+
+    def add_memory(
+        self,
+        content: str,
+        tenant_id: str = "default",
+    ) -> str:
+        """Persist validated plain text without creating graph edges.
+
+        Args:
+            content: Text content to store.
+            tenant_id: Tenant namespace for the memory.
+
+        Returns:
+            The unique ID assigned to the new memory.
+
+        Raises:
+            ValidationError: If content or tenant ID is empty or invalid.
+            DatabaseError: If the memory cannot be persisted.
+        """
+        request = _validate_input(
+            TextMemoryIn,
+            content=content,
+            tenant_id=tenant_id,
+        )
+        try:
+            memory_id = self.memory_manager.remember(
+                request.content,
+                tenant_id=request.tenant_id,
+            )
+            return MemoryIdOut(memory_id=memory_id).memory_id
+        except PydanticValidationError as exc:
+            raise ValidationError(str(exc)) from exc
+        except Exception as exc:
+            _raise_database_error("add memory", exc)
+
+    def recall(
+        self,
+        query: str,
+        limit: int = 5,
+        tenant_id: str = "default",
+    ) -> list[MemoryOut]:
+        """Recall memories while recording duration and safe error events."""
+        with trace_context() as trace_id:
+            started_at = time.perf_counter()
+            self.logger.info(
+                '🚀 收到检索 | query="%s"',
+                query,
+                extra={
+                    "action": "recall_start",
+                    "details": {"query": query},
+                },
+            )
+            try:
+                results = self._recall(
+                    query,
+                    limit=limit,
+                    tenant_id=tenant_id,
+                    trace_id=trace_id,
+                )
+                duration_ms = (time.perf_counter() - started_at) * 1_000
+                self.logger.info(
+                    "检索完成，耗时 %.3f ms，召回 %d 条记录",
+                    duration_ms,
+                    len(results),
+                    extra={
+                        "action": "recall_complete",
+                        "details": {
+                            "duration_ms": round(duration_ms, 3),
+                            "result_count": len(results),
+                        },
+                    },
+                )
+                return results
+            except Exception as exc:
+                self.logger.error(
+                    "recall failed: %s",
+                    type(exc).__name__,
+                    exc_info=True,
+                    extra={
+                        "action": "recall_error",
+                        "details": {"error_type": type(exc).__name__},
+                    },
+                )
+                raise
+            finally:
+                duration_ms = (time.perf_counter() - started_at) * 1_000
+                self.metrics.record_recall(duration_ms)
+
+    def _recall(
+        self,
+        query: str,
+        limit: int = 5,
+        tenant_id: str = "default",
+        trace_id: str | None = None,
+    ) -> list[MemoryOut]:
+        """Merge text and graph recall, validate, deduplicate, and rank results.
+
+        Args:
+            query: Text query or exact graph entity name.
+            limit: Maximum number of returned results; must be non-negative.
+            tenant_id: Tenant namespace to search.
+
+        Returns:
+            Results as validated ``MemoryOut`` Pydantic models, sorted by
+            current decay score in descending order.
+
+        Raises:
+            ValidationError: If query, limit, or tenant ID is invalid.
+            DatabaseError: If any retrieval or scoring operation fails.
+        """
+        request = _validate_input(
+            RecallIn,
+            query=query,
+            limit=limit,
+            tenant_id=tenant_id,
+        )
+        if request.limit == 0:
+            return []
+
+        try:
+            text_rows = self.retriever.search(
+                request.query,
+                request.limit,
+                tenant_id=request.tenant_id,
+            )
+            graph_rows = self.graph_manager.query_multi_hop(
+                request.query,
+                tenant_id=request.tenant_id,
+            )
+
+            results: list[MemoryOut] = []
+            seen_memory_ids: set[str] = set()
+            seen_graph_paths: set[tuple[Any, ...]] = set()
+
+            for row in text_rows:
+                memory_id = str(row["id"])
+                if memory_id in seen_memory_ids:
+                    continue
+                seen_memory_ids.add(memory_id)
+                score = self.decay_engine.calculate_score(
+                    base_weight=float(row["base_weight"]),
+                    decay_lambda=float(row["decay_lambda"]),
+                    last_decay_at=int(row["last_decay_at"]),
+                    retrieval_count=int(row["retrieval_count"]),
+                    usefulness_weight=float(
+                        row.get("usefulness_weight", row["base_weight"])
+                    ),
+                )
+                results.append(
+                    MemoryOut(
+                        memory_id=memory_id,
+                        result_type="memory",
+                        content=str(row["content"]),
+                        tenant_id=request.tenant_id,
+                        score=score,
+                        trace_id=trace_id,
+                        valid_from=row["valid_from"],
+                        valid_to=row["valid_to"],
+                        created_at=int(row["created_at"]),
+                    )
+                )
+
+            for row in graph_rows:
+                memory_id_value = row.get("memory_id")
+                memory_id = str(memory_id_value) if memory_id_value else None
+                if memory_id is not None:
+                    if memory_id in seen_memory_ids:
+                        continue
+                    seen_memory_ids.add(memory_id)
+                    memory = self.memory_manager.get_memory(memory_id)
+                    score = self.decay_engine.calculate_score(
+                        base_weight=float(memory["base_weight"]),
+                        decay_lambda=float(memory["decay_lambda"]),
+                        last_decay_at=int(memory["last_decay_at"]),
+                        retrieval_count=int(memory["retrieval_count"]),
+                        usefulness_weight=float(
+                            memory.get("usefulness_weight", memory["base_weight"])
+                        ),
+                    )
+                    created_at = int(memory["created_at"])
+                else:
+                    graph_key = (
+                        row.get("start_id"),
+                        row.get("entity_id"),
+                        row.get("relation"),
+                        row.get("depth"),
+                    )
+                    if graph_key in seen_graph_paths:
+                        continue
+                    seen_graph_paths.add(graph_key)
+                    score = 0.0
+                    created_at = None
+
+                results.append(
+                    MemoryOut(
+                        memory_id=memory_id,
+                        result_type="graph",
+                        subject=row.get("start_name"),
+                        predicate=row.get("relation"),
+                        object=row.get("entity_name"),
+                        entity_name=row.get("entity_name"),
+                        relation=row.get("relation"),
+                        depth=row.get("depth"),
+                        tenant_id=request.tenant_id,
+                        trace_id=trace_id,
+                        score=score,
+                        valid_from=row.get("valid_from"),
+                        created_at=created_at,
+                    )
+                )
+
+            results.sort(key=lambda result: result.score, reverse=True)
+            return results[: request.limit]
+        except PydanticValidationError as exc:
+            raise ValidationError(str(exc)) from exc
+        except Exception as exc:
+            _raise_database_error("recall", exc)
+
+    def get_history(self, subject: str, predicate: str) -> list[dict[str, Any]]:
+        """Return all current and expired versions of a subject-predicate fact.
+
+        Args:
+            subject: Subject entity name.
+            predicate: Relationship name.
+
+        Returns:
+            Dictionaries containing the object and both validity timestamps.
+
+        Raises:
+            ValidationError: If subject or predicate is empty.
+            DatabaseError: If the history query fails.
+        """
+        request = _validate_input(
+            HistoryIn,
+            subject=subject,
+            predicate=predicate,
+        )
+        try:
+            with self.database_manager.get_connection() as conn:
+                rows = conn.execute(
+                    """
+                    SELECT edge.id, edge.tenant_id, edge.subject_id,
+                           subject.name AS subject, edge.predicate,
+                           edge.object_id, object.name AS object,
+                           edge.valid_from, edge.valid_to, edge.confidence,
+                           edge.memory_id, edge.created_at
+                    FROM edges AS edge
+                    JOIN entities AS subject
+                      ON subject.id = edge.subject_id
+                     AND subject.tenant_id = edge.tenant_id
+                    JOIN entities AS object
+                      ON object.id = edge.object_id
+                     AND object.tenant_id = edge.tenant_id
+                    WHERE edge.tenant_id = ?
+                      AND subject.name = ?
+                      AND edge.predicate = ?
+                    ORDER BY edge.valid_from, edge.created_at, edge.id
+                    """,
+                    ("default", request.subject, request.predicate),
+                ).fetchall()
+            history = [
+                HistoryOut.model_validate(dict(row)).model_dump()
+                for row in rows
+            ]
+            return history
+        except PydanticValidationError as exc:
+            raise ValidationError(str(exc)) from exc
+        except Exception as exc:
+            _raise_database_error("get history", exc)
+
+
+RecallWeaver = RecallWeaverAPI
+
+_default_instance: RecallWeaverAPI | None = None
+
+
+def _get_default_instance() -> RecallWeaverAPI:
+    """Return the lazily initialized default API for legacy function callers.
+
+    Returns:
+        The singleton API connected to the configured default database.
+    """
+    global _default_instance
+    if _default_instance is None:
+        _default_instance = RecallWeaverAPI(settings.db_path)
+    return _default_instance
+
+
+def remember(content: str, base_weight: float = 1.0) -> str:
+    """Persist plain text through the legacy module-level function.
+
+    Args:
+        content: Text memory to persist.
+        base_weight: Base importance weight.
+
+    Returns:
+        The generated memory identifier.
+    """
+    try:
+        request = TextMemoryIn(content=content)
+        return _get_default_instance().memory_manager.remember(
+            request.content,
+            base_weight=base_weight,
+        )
+    except PydanticValidationError as exc:
+        raise ValidationError(str(exc)) from exc
+    except (ValidationError, DatabaseError):
+        raise
+    except Exception as exc:
+        _raise_database_error("remember", exc)
+
+
+def recall(
+    query: str,
+    limit: int = 5,
+) -> list[MemoryOut]:
+    """Search the configured default database through the legacy function.
+
+    Args:
+        query: Search term or entity name.
+        limit: Maximum number of results.
+
+    Returns:
+        Validated, ranked memory and graph results.
+    """
+    return _get_default_instance().recall(query, limit)
+
+
+__all__ = ["MemoryOut", "RecallWeaver", "RecallWeaverAPI", "recall", "remember"]