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

src/llm/factory.py

@@ -0,0 +1,75 @@
+"""LLM 和 Embedding Provider 工厂"""
+from typing import Dict
+from .base import LLMProvider, EmbeddingProvider
+from .providers import (
+    DashScopeLLMProvider,
+    DashScopeEmbeddingProvider,
+    OpenAILLMProvider,
+    OpenAIEmbeddingProvider,
+    AnthropicLLMProvider,
+)
+
+
+class LLMFactory:
+    """LLM Provider 工厂"""
+
+    _providers = {
+        "dashscope": DashScopeLLMProvider,
+        "openai": OpenAILLMProvider,
+        "anthropic": AnthropicLLMProvider,
+    }
+
+    @classmethod
+    def create(cls, config: Dict) -> LLMProvider:
+        """
+        创建 LLM Provider 实例
+
+        Args:
+            config: 配置字典，包含 'provider' 键和对应配置
+
+        Returns:
+            LLMProvider 实例
+        """
+        provider_name = config.get("provider")
+        if provider_name not in cls._providers:
+            raise ValueError(f"Unknown LLM provider: {provider_name}")
+
+        provider_class = cls._providers[provider_name]
+        return provider_class(config)
+
+    @classmethod
+    def register_provider(cls, name: str, provider_class: type):
+        """注册新的 LLM Provider（插件机制）"""
+        cls._providers[name] = provider_class
+
+
+class EmbeddingFactory:
+    """Embedding Provider 工厂"""
+
+    _providers = {
+        "dashscope": DashScopeEmbeddingProvider,
+        "openai": OpenAIEmbeddingProvider,
+    }
+
+    @classmethod
+    def create(cls, config: Dict) -> EmbeddingProvider:
+        """
+        创建 Embedding Provider 实例
+
+        Args:
+            config: 配置字典，包含 'provider' 键和对应配置
+
+        Returns:
+            EmbeddingProvider 实例
+        """
+        provider_name = config.get("provider")
+        if provider_name not in cls._providers:
+            raise ValueError(f"Unknown embedding provider: {provider_name}")
+
+        provider_class = cls._providers[provider_name]
+        return provider_class(config)
+
+    @classmethod
+    def register_provider(cls, name: str, provider_class: type):
+        """注册新的 Embedding Provider（插件机制）"""
+        cls._providers[name] = provider_class

src/llm/providers/__init__.py

@@ -0,0 +1,12 @@
+"""Provider 包"""
+from .dashscope import DashScopeLLMProvider, DashScopeEmbeddingProvider
+from .openai import OpenAILLMProvider, OpenAIEmbeddingProvider
+from .anthropic import AnthropicLLMProvider
+
+__all__ = [
+    "DashScopeLLMProvider",
+    "DashScopeEmbeddingProvider",
+    "OpenAILLMProvider",
+    "OpenAIEmbeddingProvider",
+    "AnthropicLLMProvider",
+]

src/llm/providers/anthropic.py

@@ -0,0 +1,62 @@
+"""Anthropic (Claude) Provider 实现"""
+from typing import List, Dict
+try:
+    from anthropic import AsyncAnthropic
+    ANTHROPIC_AVAILABLE = True
+except ImportError:
+    ANTHROPIC_AVAILABLE = False
+
+from ..base import LLMProvider
+
+
+class AnthropicLLMProvider(LLMProvider):
+    """Anthropic Claude LLM Provider"""
+
+    def __init__(self, config: Dict):
+        if not ANTHROPIC_AVAILABLE:
+            raise ImportError(
+                "Anthropic provider requires 'anthropic' package. "
+                "Install it with: pip install anthropic"
+            )
+
+        self.api_key = config.get("api_key")
+        self.model = config.get("chat_model", "claude-3-5-sonnet-20241022")
+        self.default_temperature = config.get("temperature", 0.7)
+        self.default_max_tokens = config.get("max_tokens", 4096)
+
+        self.client = AsyncAnthropic(api_key=self.api_key)
+
+    async def chat(
+        self,
+        messages: List[Dict[str, str]],
+        temperature: float = None,
+        max_tokens: int = None,
+        **kwargs
+    ) -> str:
+        """调用 Anthropic Chat API"""
+        temperature = temperature if temperature is not None else self.default_temperature
+        max_tokens = max_tokens if max_tokens is not None else self.default_max_tokens
+
+        # Anthropic API 需要分离 system 和 messages
+        system_message = None
+        user_messages = []
+
+        for msg in messages:
+            if msg["role"] == "system":
+                system_message = msg["content"]
+            else:
+                user_messages.append(msg)
+
+        response = await self.client.messages.create(
+            model=self.model,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            system=system_message,
+            messages=user_messages,
+            **kwargs
+        )
+
+        return response.content[0].text
+
+    def get_provider_name(self) -> str:
+        return f"anthropic:{self.model}"

src/llm/providers/dashscope.py

@@ -0,0 +1,76 @@
+"""DashScope (通义千问) Provider 实现"""
+from typing import List, Dict
+from openai import AsyncOpenAI
+from ..base import LLMProvider, EmbeddingProvider
+
+
+class DashScopeLLMProvider(LLMProvider):
+    """DashScope LLM Provider（使用 OpenAI 兼容接口）"""
+
+    def __init__(self, config: Dict):
+        self.api_key = config.get("api_key")
+        self.base_url = config.get("base_url", "https://dashscope.aliyuncs.com/compatible-mode/v1")
+        self.model = config.get("chat_model", "qwen-plus")
+        self.default_temperature = config.get("temperature", 0.7)
+        self.default_max_tokens = config.get("max_tokens", 4096)
+
+        self.client = AsyncOpenAI(
+            api_key=self.api_key,
+            base_url=self.base_url
+        )
+
+    async def chat(
+        self,
+        messages: List[Dict[str, str]],
+        temperature: float = None,
+        max_tokens: int = None,
+        **kwargs
+    ) -> str:
+        """调用 DashScope Chat API"""
+        temperature = temperature if temperature is not None else self.default_temperature
+        max_tokens = max_tokens if max_tokens is not None else self.default_max_tokens
+
+        response = await self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            **kwargs
+        )
+
+        return response.choices[0].message.content
+
+    def get_provider_name(self) -> str:
+        return f"dashscope:{self.model}"
+
+
+class DashScopeEmbeddingProvider(EmbeddingProvider):
+    """DashScope Embedding Provider"""
+
+    def __init__(self, config: Dict):
+        self.api_key = config.get("api_key")
+        self.base_url = config.get("base_url", "https://dashscope.aliyuncs.com/compatible-mode/v1")
+        self.model = config.get("model", "text-embedding-v3")
+
+        self.client = AsyncOpenAI(
+            api_key=self.api_key,
+            base_url=self.base_url
+        )
+
+        # text-embedding-v3 是 1024 维
+        self._embedding_dim = 1024
+
+    async def embed(self, text: str) -> List[float]:
+        """调用 DashScope Embedding API"""
+        response = await self.client.embeddings.create(
+            model=self.model,
+            input=text
+        )
+
+        return response.data[0].embedding
+
+    def get_provider_name(self) -> str:
+        return f"dashscope:{self.model}"
+
+    def get_embedding_dim(self) -> int:
+        return self._embedding_dim

src/llm/providers/openai.py

@@ -0,0 +1,76 @@
+"""OpenAI Provider 实现"""
+from typing import List, Dict
+from openai import AsyncOpenAI
+from ..base import LLMProvider, EmbeddingProvider
+
+
+class OpenAILLMProvider(LLMProvider):
+    """OpenAI LLM Provider"""
+
+    def __init__(self, config: Dict):
+        self.api_key = config.get("api_key")
+        self.base_url = config.get("base_url", "https://api.openai.com/v1")
+        self.model = config.get("chat_model", "gpt-4o-mini")
+        self.default_temperature = config.get("temperature", 0.7)
+        self.default_max_tokens = config.get("max_tokens", 4096)
+
+        self.client = AsyncOpenAI(
+            api_key=self.api_key,
+            base_url=self.base_url
+        )
+
+    async def chat(
+        self,
+        messages: List[Dict[str, str]],
+        temperature: float = None,
+        max_tokens: int = None,
+        **kwargs
+    ) -> str:
+        """调用 OpenAI Chat API"""
+        temperature = temperature if temperature is not None else self.default_temperature
+        max_tokens = max_tokens if max_tokens is not None else self.default_max_tokens
+
+        response = await self.client.chat.completions.create(
+            model=self.model,
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            **kwargs
+        )
+
+        return response.choices[0].message.content
+
+    def get_provider_name(self) -> str:
+        return f"openai:{self.model}"
+
+
+class OpenAIEmbeddingProvider(EmbeddingProvider):
+    """OpenAI Embedding Provider"""
+
+    def __init__(self, config: Dict):
+        self.api_key = config.get("api_key")
+        self.base_url = config.get("base_url", "https://api.openai.com/v1")
+        self.model = config.get("model", "text-embedding-3-small")
+
+        self.client = AsyncOpenAI(
+            api_key=self.api_key,
+            base_url=self.base_url
+        )
+
+        # text-embedding-3-small 是 1536 维
+        self._embedding_dim = 1536 if "small" in self.model else 3072
+
+    async def embed(self, text: str) -> List[float]:
+        """调用 OpenAI Embedding API"""
+        response = await self.client.embeddings.create(
+            model=self.model,
+            input=text
+        )
+
+        return response.data[0].embedding
+
+    def get_provider_name(self) -> str:
+        return f"openai:{self.model}"
+
+    def get_embedding_dim(self) -> int:
+        return self._embedding_dim

src/merge/__init__.py

@@ -0,0 +1,22 @@
+"""
+Merge module initialization
+
+Registers all built-in merge strategies.
+"""
+
+from .base import MergeStrategy, MergeResult
+from .factory import MergeFactory
+from .strategies.voting_merge import VotingMergeStrategy
+from .strategies.llm_merge import LLMMergeStrategy
+
+# Register built-in strategies
+MergeFactory.register("voting", VotingMergeStrategy)
+MergeFactory.register("llm", LLMMergeStrategy)
+
+__all__ = [
+    "MergeStrategy",
+    "MergeResult",
+    "MergeFactory",
+    "VotingMergeStrategy",
+    "LLMMergeStrategy",
+]

src/merge/base.py

@@ -0,0 +1,89 @@
+"""
+Merge Strategy Base Interface
+
+Provides pluggable merge strategies for combining similar memories.
+All operations MUST respect agent_id isolation.
+"""
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, Optional
+from dataclasses import dataclass, field
+
+
+@dataclass
+class MergeResult:
+    """Result of a merge operation"""
+    success: bool
+    merged_memory_id: Optional[str] = None
+    merged_from: List[str] = field(default_factory=list)
+    abstraction_level: int = 1  # 0=specific case, 1=pattern, 2=principle
+    reason: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class MergeStrategy(ABC):
+    """
+    Abstract base class for merge strategies.
+
+    Different strategies can implement different merge algorithms:
+    - LLM-based (extract common patterns)
+    - Template-based (rule-based merging)
+    - Voting-based (keep best, remove rest)
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        """
+        Initialize strategy with configuration.
+
+        Args:
+            config: Strategy-specific configuration
+        """
+        self.config = config
+
+    @abstractmethod
+    async def should_merge(
+        self,
+        memories: List[Dict[str, Any]],
+        agent_id: Optional[str] = None
+    ) -> bool:
+        """
+        Determine if a group of memories should be merged.
+
+        Args:
+            memories: List of memory dicts to evaluate
+            agent_id: Agent ID (all memories must belong to same agent)
+
+        Returns:
+            True if memories should be merged, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    async def merge(
+        self,
+        memories: List[Dict[str, Any]],
+        agent_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Merge multiple memories into a single, more general memory.
+
+        Args:
+            memories: List of memory dicts to merge (all from same agent_id)
+            agent_id: Agent ID for validation
+
+        Returns:
+            New merged memory dict with keys:
+                - title: str
+                - content: str
+                - description: str
+                - query: str (generalized)
+                - abstraction_level: int
+                - merged_from: List[str] (memory_ids)
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return strategy name for logging and config"""
+        pass

src/merge/factory.py

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

src/merge/strategies/__init__.py

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

src/merge/strategies/llm_merge.py

@@ -0,0 +1,170 @@
+"""
+LLM-based Merge Strategy
+
+Uses LLM to extract common patterns and create a generalized memory.
+"""
+
+from typing import List, Dict, Any, Optional
+from ..base import MergeStrategy
+import logging
+import json
+
+logger = logging.getLogger(__name__)
+
+
+class LLMMergeStrategy(MergeStrategy):
+    """
+    LLM-driven merge: Extract common patterns from similar memories.
+
+    Creates a new, more abstract memory that captures the essence
+    of multiple specific experiences.
+    """
+
+    @property
+    def name(self) -> str:
+        return "llm"
+
+    def __init__(self, config: Dict[str, Any]):
+        super().__init__(config)
+        self.min_group_size = config.get("trigger", {}).get("min_similar_count", 3)
+        self.llm_config = config.get("llm", {})
+        self.temperature = self.llm_config.get("temperature", 0.7)
+        self.llm_provider = None  # Will be injected by MemoryManager
+
+    def set_llm_provider(self, llm_provider):
+        """Inject LLM provider dependency"""
+        self.llm_provider = llm_provider
+
+    async def should_merge(
+        self,
+        memories: List[Dict[str, Any]],
+        agent_id: Optional[str] = None
+    ) -> bool:
+        """
+        Check if group meets criteria for LLM merge.
+
+        Requirements:
+        1. At least min_group_size memories
+        2. All from same agent_id
+        3. Majority should be successful experiences
+        """
+        if len(memories) < self.min_group_size:
+            return False
+
+        # Validate agent_id consistency
+        if agent_id:
+            for mem in memories:
+                if mem.get("agent_id") != agent_id:
+                    logger.warning(
+                        f"Memory {mem.get('memory_id')} has different agent_id"
+                    )
+                    return False
+
+        # Check success rate
+        success_count = sum(1 for m in memories if m.get("success", False))
+        success_rate = success_count / len(memories)
+
+        # Only merge if majority are successful (avoid mixing success/failure)
+        if success_rate < 0.6:
+            logger.info(
+                f"Success rate too low ({success_rate:.2f}) for merge, "
+                f"agent_id={agent_id}"
+            )
+            return False
+
+        return True
+
+    async def merge(
+        self,
+        memories: List[Dict[str, Any]],
+        agent_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Use LLM to extract common patterns and create generalized memory.
+
+        Args:
+            memories: List of similar memories (all from same agent_id)
+            agent_id: Agent ID for validation
+
+        Returns:
+            New merged memory dict
+        """
+        if not self.llm_provider:
+            raise RuntimeError("LLM provider not set. Call set_llm_provider() first.")
+
+        if not memories:
+            raise ValueError("Cannot merge empty memory list")
+
+        # Validate agent_id
+        if agent_id:
+            for mem in memories:
+                if mem.get("agent_id") != agent_id:
+                    raise ValueError(
+                        f"Memory {mem.get('memory_id')} belongs to different agent"
+                    )
+
+        # Build prompt for LLM
+        prompt = self._build_merge_prompt(memories)
+
+        # Call LLM
+        try:
+            response = await self.llm_provider.chat(
+                messages=[{"role": "user", "content": prompt}],
+                temperature=self.temperature
+            )
+
+            # Parse JSON response
+            merged_data = json.loads(response)
+
+            # Validate response
+            required_fields = ["title", "content", "description", "abstraction_level"]
+            for field in required_fields:
+                if field not in merged_data:
+                    raise ValueError(f"LLM response missing required field: {field}")
+
+            # Build merged memory
+            merged_memory = {
+                "title": merged_data["title"],
+                "content": merged_data["content"],
+                "description": merged_data["description"],
+                "query": merged_data.get("query", "<通用场景>"),
+                "success": True,  # Merged memories are positive learnings
+                "agent_id": agent_id,
+                "is_merged": True,
+                "merged_from": [m["memory_id"] for m in memories],
+                "merge_metadata": {
+                    "merge_strategy": self.name,
+                    "original_count": len(memories),
+                    "abstraction_level": merged_data.get("abstraction_level", 1),
+                    "llm_model": self.llm_config.get("model", "unknown")
+                }
+            }
+
+            logger.info(
+                f"LLM merge successful: {len(memories)} memories -> "
+                f"'{merged_memory['title']}' (agent_id={agent_id})"
+            )
+
+            return merged_memory
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse LLM response as JSON: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Error during LLM merge: {e}", exc_info=True)
+            raise
+
+    def _build_merge_prompt(self, memories: List[Dict[str, Any]]) -> str:
+        """Build prompt for LLM to merge memories"""
+
+        # Format memories for LLM
+        memories_text = ""
+        for i, mem in enumerate(memories, 1):
+            memories_text += f"\n### 经验 {i}\n"
+            memories_text += f"**标题**: {mem.get('title', 'N/A')}\n"
+            memories_text += f"**描述**: {mem.get('description', 'N/A')}\n"
+            memories_text += f"**内容**: {mem.get('content', 'N/A')}\n"
+            memories_text += f"**原始场景**: {mem.get('query', 'N/A')}\n"
+        from ...prompts.templates import get_merge_prompt
+
+        return get_merge_prompt(memories_text)