iflow-mcp_hanw39_reasoning-bank-mcp 0.2.0__py3-none-any.whl

src/__init__.py

@@ -0,0 +1,16 @@
+"""ReasoningBank MCP 服务器包"""
+__version__ = "0.1.0"
+__author__ = "Your Name"
+__description__ = "Memory-augmented reasoning for AI agents via MCP"
+
+from .config import load_config, get_config
+# 注意：为了避免循环导入和RuntimeWarning，不从server模块导入ReasoningBankServer和main
+
+# 为了脚本入口点，我们需要导入run_server函数
+from .server import run_server
+
+__all__ = [
+    "load_config",
+    "get_config",
+    "run_server",  # 为脚本入口点导出
+]

src/__main__.py

@@ -0,0 +1,6 @@
+"""MCP 服务器入口点"""
+import asyncio
+from .server import main
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/config.py

@@ -0,0 +1,266 @@
+"""配置管理模块"""
+import os
+import yaml
+import logging
+from pathlib import Path
+from typing import Dict, Any, Optional
+from dotenv import load_dotenv
+
+# 配置日志
+logger = logging.getLogger(__name__)
+
+
+# def _find_dotenv_file() -> Optional[Path]:
+#     """
+#     智能查找 .env 文件
+#
+#     查找顺序：
+#     1. 当前工作目录
+#     2. 项目根目录（从 src/config.py 向上查找 pyproject.toml）
+#
+#     Returns:
+#         Path 对象或 None
+#     """
+#     # 1. 当前工作目录
+#     cwd_env = Path.cwd() / ".env"
+#     if cwd_env.exists():
+#         logger.debug(f"找到 .env 文件: {cwd_env}")
+#         return cwd_env
+#
+#     # 2. 项目根目录
+#     current_file = Path(__file__).resolve()  # src/config.py
+#     src_dir = current_file.parent            # src/
+#     project_root = src_dir.parent            # 项目根目录
+#
+#     if (project_root / "pyproject.toml").exists():
+#         project_env = project_root / ".env"
+#         if project_env.exists():
+#             logger.debug(f"找到 .env 文件: {project_env}")
+#             return project_env
+#
+#     logger.debug(".env 文件未找到")
+#     return None
+#
+#
+# # 加载环境变量（优先使用已存在的环境变量，如 MCP 传递的）
+# dotenv_path = _find_dotenv_file()
+# if dotenv_path:
+#     # override=False 确保不覆盖已存在的环境变量（如 MCP 传递的）
+#     load_dotenv(dotenv_path, override=False)
+#     logger.debug(f"已加载 .env 文件: {dotenv_path}")
+# else:
+#     logger.debug("未找到 .env 文件，将仅使用系统环境变量")
+load_dotenv()
+
+
+class Config:
+    """配置管理类"""
+
+    def __init__(self, config_path: str = "config.yaml"):
+        """
+        初始化配置
+
+        Args:
+            config_path: 配置文件路径，支持：
+                - 绝对路径：如 "/path/to/config.yaml"
+                - 相对路径：会依次在以下位置查找
+                  1. 当前工作目录
+                  2. 项目根目录（pyproject.toml 所在目录）
+                  3. ~/.reasoningbank/config.yaml
+        """
+        self.config_path = self._resolve_config_path(config_path)
+        self._config: Dict[str, Any] = {}
+        self._load_config()
+
+    def _resolve_config_path(self, config_path: str) -> Path:
+        """
+        智能解析配置文件路径
+
+        查找顺序：
+        1. 如果是绝对路径且存在，直接使用
+        2. 当前工作目录
+        3. 项目根目录（从 src/config.py 向上查找 pyproject.toml）
+        4. 用户主目录 ~/.reasoningbank/
+        5. src 目录下的 default_config.yaml（随包安装的默认配置）
+        """
+        path = Path(config_path)
+
+        # 1. 绝对路径直接使用
+        if path.is_absolute():
+            return path
+
+        # 2. 当前工作目录
+        cwd_path = Path.cwd() / config_path
+        if cwd_path.exists():
+            return cwd_path
+
+        # 3. 项目根目录（向上查找 pyproject.toml）
+        # 从当前文件所在目录（src/）开始向上查找
+        current_file = Path(__file__).resolve()  # src/config.py
+        src_dir = current_file.parent              # src/
+        project_root = src_dir.parent              # 项目根目录
+
+        # 验证是否找到项目根目录（检查 pyproject.toml）
+        if (project_root / "pyproject.toml").exists():
+            project_config = project_root / config_path
+            if project_config.exists():
+                return project_config
+
+        # 4. 用户主目录
+        home_path = Path.home() / ".reasoningbank" / config_path
+        if home_path.exists():
+            return home_path
+
+        # 5. 回退到 src 目录下的默认配置（随包安装）
+        default_config = src_dir / "default_config.yaml"
+        if default_config.exists():
+            logger.info(f"使用默认配置文件: {default_config}")
+            logger.info(f"建议在以下位置创建自定义配置: {home_path}")
+            return default_config
+
+        # 如果都没找到，优先使用用户主目录路径（引导用户创建配置）
+        return home_path
+
+    def _load_config(self):
+        """加载配置文件"""
+        if not self.config_path.exists():
+            raise FileNotFoundError(f"配置文件不存在: {self.config_path}")
+
+        with open(self.config_path, 'r', encoding='utf-8') as f:
+            self._config = yaml.safe_load(f)
+
+        # 替换环境变量
+        self._replace_env_variables(self._config)
+
+    def _replace_env_variables(self, config: Any) -> Any:
+        """
+        递归替换配置中的环境变量
+
+        支持的格式:
+        - ${VAR_NAME}           : 必需的环境变量，不存在时抛出异常
+        - ${VAR_NAME?}          : 可选的环境变量，不存在时返回空字符串
+        - ${VAR_NAME:default}   : 带默认值的环境变量，不存在时使用默认值
+        """
+        if isinstance(config, dict):
+            for key, value in config.items():
+                config[key] = self._replace_env_variables(value)
+        elif isinstance(config, list):
+            return [self._replace_env_variables(item) for item in config]
+        elif isinstance(config, str):
+            # 替换 ${VAR_NAME} 格式的环境变量
+            if config.startswith("${") and config.endswith("}"):
+                var_spec = config[2:-1]
+
+                # 支持带默认值: ${VAR_NAME:default_value}
+                if ':' in var_spec:
+                    var_name, default_value = var_spec.split(':', 1)
+                    return os.getenv(var_name, default_value)
+
+                # 支持可选环境变量: ${VAR_NAME?}
+                if var_spec.endswith('?'):
+                    var_name = var_spec[:-1]
+                    return os.getenv(var_name, "")
+
+                # 必需的环境变量
+                env_value = os.getenv(var_spec)
+                if env_value is None:
+                    # 提供详细的错误信息
+                    error_msg = f"环境变量未设置: {var_spec}\n\n"
+                    error_msg += "解决方案：\n"
+                    error_msg += "1. 如果使用 MCP，请在配置中添加：\n"
+                    error_msg += '   {\n'
+                    error_msg += '     "env": {\n'
+                    error_msg += f'       "{var_spec}": "your-api-key-here"\n'
+                    error_msg += '     }\n'
+                    error_msg += '   }\n\n'
+                    error_msg += "2. 或在项目根目录创建 .env 文件：\n"
+                    error_msg += f'   {var_spec}=your-api-key-here\n\n'
+
+                    # 显示 .env 文件的查找路径
+                    # dotenv_file = _find_dotenv_file()
+                    # if dotenv_file:
+                    #     error_msg += f"3. 当前加载的 .env 文件: {dotenv_file}\n"
+                    #     error_msg += f"   请确认该文件包含 {var_spec} 配置"
+                    # else:
+                    #     error_msg += f"3. 未找到 .env 文件"
+
+                    raise ValueError(error_msg)
+                return env_value
+
+        return config
+
+    def get(self, *keys, default=None) -> Any:
+        """
+        获取配置值
+
+        例如: config.get('llm', 'provider') -> 'dashscope'
+        """
+        value = self._config
+        for key in keys:
+            if isinstance(value, dict):
+                value = value.get(key, default)
+            else:
+                return default
+        return value
+
+    def get_llm_config(self) -> Dict[str, Any]:
+        """获取 LLM 配置"""
+        provider = self.get('llm', 'provider')
+        return {
+            'provider': provider,
+            **self.get('llm', provider, default={})
+        }
+
+    def get_embedding_config(self) -> Dict[str, Any]:
+        """获取 Embedding 配置"""
+        provider = self.get('embedding', 'provider')
+        return {
+            'provider': provider,
+            **self.get('embedding', provider, default={})
+        }
+
+    def get_retrieval_config(self) -> Dict[str, Any]:
+        """获取检索配置"""
+        strategy = self.get('retrieval', 'strategy')
+        return {
+            'strategy': strategy,
+            'default_top_k': self.get('retrieval', 'default_top_k', default=1),
+            'max_top_k': self.get('retrieval', 'max_top_k', default=10),
+            'strategy_config': self.get('retrieval', strategy, default={})
+        }
+
+    def get_storage_config(self) -> Dict[str, Any]:
+        """获取存储配置"""
+        backend = self.get('storage', 'backend')
+        return {
+            'backend': backend,
+            **self.get('storage', backend, default={})
+        }
+
+    def get_extraction_config(self) -> Dict[str, Any]:
+        """获取记忆提取配置"""
+        return self.get('extraction', default={})
+
+    @property
+    def all(self) -> Dict[str, Any]:
+        """返回完整配置"""
+        return self._config
+
+
+# 全局配置实例
+_global_config: Config = None
+
+
+def load_config(config_path: str = "config.yaml") -> Config:
+    """加载全局配置"""
+    global _global_config
+    _global_config = Config(config_path)
+    return _global_config
+
+
+def get_config() -> Config:
+    """获取全局配置实例"""
+    global _global_config
+    if _global_config is None:
+        _global_config = Config()
+    return _global_config

src/deduplication/__init__.py

@@ -0,0 +1,19 @@
+"""
+Deduplication module initialization
+
+Registers all built-in deduplication strategies.
+"""
+
+from .base import DeduplicationStrategy, DeduplicationResult
+from .factory import DeduplicationFactory
+from .strategies.semantic_dedup import SemanticDeduplicationStrategy
+
+# Register built-in strategies
+DeduplicationFactory.register("semantic", SemanticDeduplicationStrategy)
+
+__all__ = [
+    "DeduplicationStrategy",
+    "DeduplicationResult",
+    "DeduplicationFactory",
+    "SemanticDeduplicationStrategy",
+]

src/deduplication/base.py

@@ -0,0 +1,88 @@
+"""
+Deduplication Strategy Base Interface
+
+Provides pluggable deduplication strategies for memory management.
+All operations MUST respect agent_id isolation.
+"""
+
+from abc import ABC, abstractmethod
+from typing import List, Optional, Dict, Any
+from dataclasses import dataclass, field
+import numpy as np
+
+
+@dataclass
+class DeduplicationResult:
+    """Result of deduplication check"""
+    is_duplicate: bool
+    duplicate_of: Optional[str] = None  # memory_id of existing memory
+    similarity_score: float = 0.0
+    reason: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class DeduplicationStrategy(ABC):
+    """
+    Abstract base class for deduplication strategies.
+
+    Key principle: All operations are scoped to a specific agent_id.
+    Different agents should have isolated memory spaces.
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        """
+        Initialize strategy with configuration.
+
+        Args:
+            config: Strategy-specific configuration dictionary
+        """
+        self.config = config
+
+    @abstractmethod
+    async def check_duplicate(
+        self,
+        memory: Dict[str, Any],
+        embedding: Optional[np.ndarray] = None,
+        storage_backend: Any = None,
+        agent_id: Optional[str] = None
+    ) -> DeduplicationResult:
+        """
+        Check if a memory is duplicate of existing memories within the same agent_id.
+
+        Args:
+            memory: Memory object to check (dict with keys: title, content, query, etc.)
+            embedding: Optional pre-computed embedding vector
+            storage_backend: Storage backend for querying existing memories
+            agent_id: Agent ID for isolation (REQUIRED for multi-tenant safety)
+
+        Returns:
+            DeduplicationResult with is_duplicate flag and details
+        """
+        pass
+
+    @abstractmethod
+    async def find_duplicate_groups(
+        self,
+        storage_backend: Any,
+        agent_id: Optional[str] = None,
+        limit: Optional[int] = None
+    ) -> List[List[str]]:
+        """
+        Find groups of duplicate memories within the same agent_id.
+
+        Args:
+            storage_backend: Storage backend for querying memories
+            agent_id: Agent ID for isolation (only search within this agent's memories)
+            limit: Maximum number of groups to return
+
+        Returns:
+            List of groups, where each group is a list of memory_ids that are duplicates
+            Example: [["mem_1", "mem_2"], ["mem_3", "mem_4", "mem_5"]]
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return strategy name for logging and config"""
+        pass

src/deduplication/factory.py

@@ -0,0 +1,60 @@
+"""
+Deduplication Strategy Factory
+
+Provides plugin mechanism for registering and creating deduplication strategies.
+"""
+
+from typing import Dict, Type, Any
+from .base import DeduplicationStrategy
+
+
+class DeduplicationFactory:
+    """Factory for creating deduplication strategy instances"""
+
+    _strategies: Dict[str, Type[DeduplicationStrategy]] = {}
+
+    @classmethod
+    def register(cls, name: str, strategy_class: Type[DeduplicationStrategy]):
+        """
+        Register a deduplication strategy.
+
+        Args:
+            name: Strategy name (e.g., "hash", "semantic", "hybrid")
+            strategy_class: Strategy class (must inherit from DeduplicationStrategy)
+        """
+        cls._strategies[name] = strategy_class
+
+    @classmethod
+    def create(cls, config: Any) -> DeduplicationStrategy:
+        """
+        Create a deduplication strategy instance based on config.
+
+        Args:
+            config: Config object with get() method
+
+        Returns:
+            DeduplicationStrategy instance
+
+        Raises:
+            ValueError: If strategy name is not registered
+        """
+        # 使用统一的配置访问方式
+        strategy_name = config.get('memory_manager', 'deduplication', 'strategy', default='semantic')
+
+        if strategy_name not in cls._strategies:
+            raise ValueError(
+                f"Unknown deduplication strategy: {strategy_name}. "
+                f"Available: {list(cls._strategies.keys())}"
+            )
+
+        strategy_class = cls._strategies[strategy_name]
+
+        # 获取去重配置
+        dedup_config = config.get('memory_manager', 'deduplication', default={})
+
+        return strategy_class(dedup_config)
+
+    @classmethod
+    def list_strategies(cls) -> list:
+        """Return list of registered strategy names"""
+        return list(cls._strategies.keys())

src/deduplication/strategies/__init__.py

@@ -0,0 +1 @@
+"""Strategies submodule"""

src/deduplication/strategies/semantic_dedup.py

@@ -0,0 +1,187 @@
+"""
+Semantic Deduplication Strategy
+
+Detects semantically similar memories using embedding similarity.
+"""
+
+from typing import List, Optional, Dict, Any
+import numpy as np
+from ..base import DeduplicationStrategy, DeduplicationResult
+from ...utils.similarity import cosine_similarity
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class SemanticDeduplicationStrategy(DeduplicationStrategy):
+    """
+    Semantic deduplication using embedding cosine similarity.
+
+    Use case: Find memories that describe similar experiences,
+    even if the exact wording is different.
+    """
+
+    @property
+    def name(self) -> str:
+        return "semantic"
+
+    def __init__(self, config: Dict[str, Any]):
+        super().__init__(config)
+        self.threshold = config.get("semantic", {}).get("threshold", 0.90)
+        self.top_k = config.get("semantic", {}).get("top_k_check", 1)
+
+    async def check_duplicate(
+        self,
+        memory: Dict[str, Any],
+        embedding: Optional[np.ndarray] = None,
+        storage_backend: Any = None,
+        agent_id: Optional[str] = None
+    ) -> DeduplicationResult:
+        """
+        Check if semantically similar memories exist for this agent.
+
+        Args:
+            memory: Memory dict
+            embedding: Pre-computed embedding of memory query (REQUIRED)
+            storage_backend: Storage backend
+            agent_id: Agent ID for isolation (CRITICAL)
+        """
+        if embedding is None:
+            logger.warning("No embedding provided for semantic dedup check")
+            return DeduplicationResult(
+                is_duplicate=False,
+                reason="No embedding provided"
+            )
+
+        if not storage_backend:
+            logger.warning("No storage_backend provided")
+            return DeduplicationResult(is_duplicate=False)
+
+        # Retrieve similar memories within agent_id scope
+        try:
+            # Use existing retrieval mechanism with agent_id filter
+            from ...retrieval.factory import RetrievalFactory
+
+            # Get retrieval strategy from storage
+            retrieval_strategy = storage_backend.retrieval_strategy
+            if not retrieval_strategy:
+                logger.warning("No retrieval strategy available")
+                return DeduplicationResult(is_duplicate=False)
+
+            # Retrieve top-k similar memories
+            # Note: query text is not used by retrieval (only embedding),
+            # but required by interface
+            query_text = memory.get("query", "")
+            similar_results = await retrieval_strategy.retrieve(
+                query=query_text,
+                query_embedding=embedding,
+                top_k=self.top_k,
+                agent_id=agent_id,  # CRITICAL: Only search within this agent
+                storage_backend=storage_backend
+            )
+
+            # Check if any exceed threshold
+            for mem_id, score in similar_results:
+                if score >= self.threshold:
+                    existing_mem = await storage_backend.get_memory(mem_id)
+                    logger.info(
+                        f"Found semantically similar memory: {mem_id} "
+                        f"(score={score:.3f}, threshold={self.threshold}) "
+                        f"for agent_id={agent_id}"
+                    )
+                    return DeduplicationResult(
+                        is_duplicate=True,
+                        duplicate_of=mem_id,
+                        similarity_score=score,
+                        reason=f"Semantically similar to existing memory (score={score:.3f})",
+                        metadata={
+                            "existing_title": existing_mem.get("title", ""),
+                            "threshold": self.threshold
+                        }
+                    )
+
+            return DeduplicationResult(
+                is_duplicate=False,
+                reason=f"No similar memories above threshold {self.threshold}"
+            )
+
+        except Exception as e:
+            logger.error(f"Error in semantic dedup check: {e}", exc_info=True)
+            return DeduplicationResult(
+                is_duplicate=False,
+                reason=f"Error during check: {str(e)}"
+            )
+
+    async def find_duplicate_groups(
+        self,
+        storage_backend: Any,
+        agent_id: Optional[str] = None,
+        limit: Optional[int] = None
+    ) -> List[List[str]]:
+        """
+        Find clusters of semantically similar memories within agent_id scope.
+
+        Uses a greedy clustering approach:
+        1. For each memory, find all memories above similarity threshold
+        2. Group connected memories together
+        """
+        if not storage_backend:
+            return []
+
+        # Get all memories for this agent
+        all_memories = await storage_backend.get_all_memories(agent_id=agent_id)
+        all_embeddings = await storage_backend.get_embeddings(
+            [m["memory_id"] for m in all_memories]
+        )
+
+        if len(all_memories) < 2:
+            return []
+
+        # Build similarity matrix
+        n = len(all_memories)
+        visited = set()
+        groups = []
+
+        for i in range(n):
+            mem_id_i = all_memories[i]["memory_id"]
+
+            if mem_id_i in visited:
+                continue
+
+            # Start a new group
+            current_group = [mem_id_i]
+            visited.add(mem_id_i)
+
+            emb_i = all_embeddings.get(mem_id_i)
+            if emb_i is None:
+                continue
+
+            # Find all similar memories
+            for j in range(i + 1, n):
+                mem_id_j = all_memories[j]["memory_id"]
+
+                if mem_id_j in visited:
+                    continue
+
+                emb_j = all_embeddings.get(mem_id_j)
+                if emb_j is None:
+                    continue
+
+                similarity = cosine_similarity(emb_i, emb_j)
+
+                if similarity >= self.threshold:
+                    current_group.append(mem_id_j)
+                    visited.add(mem_id_j)
+
+            # Only keep groups with 2+ members
+            if len(current_group) >= 2:
+                groups.append(current_group)
+
+        if limit:
+            groups = groups[:limit]
+
+        logger.info(
+            f"Found {len(groups)} semantic duplicate groups for agent_id={agent_id}"
+        )
+
+        return groups