hy-memory 1.0.0__py3-none-any.whl

hy_memory/__init__.py

@@ -0,0 +1,146 @@
+"""
+HY Memory - 核心 SDK
+
+工业级智能体记忆系统核心框架。
+
+快速开始:
+    export OPENAI_API_KEY="sk-your-key-here"
+
+    from hy_memory import HyMemoryClient
+
+    # 最简用法 — 只需设置 OPENAI_API_KEY 环境变量
+    client = HyMemoryClient(user_id="test_user")
+    client.add("用户喜欢科幻电影")
+    results = client.search("用户喜欢什么？")
+    client.close()
+
+默认配置:
+    - embedder: OpenAI text-embedding-3-small (1536 维)
+    - llm: OpenAI gpt-4.1-nano
+    - vector_store: Chroma 本地嵌入式 (零外部依赖)
+
+    只需设置 OPENAI_API_KEY 环境变量即可运行。
+
+    # 自定义配置
+    client = HyMemoryClient.from_config({
+        "vector_store": {"provider": "qdrant"},
+        "graph_store": {
+            "provider": "neo4j",
+            "url": "bolt://localhost:7687",
+            "username": "neo4j",
+            "password": "password",
+        },
+        "enable_graph": True,
+    }, user_id="test_user")
+
+数据隔离 (两级):
+    - user_id:  一级 key — 每个用户唯一的记忆库
+    - agent_id: 二级 key — 同一用户下不同 Agent 场景的隔离
+
+安装方式:
+    pip install hy-memory          # 核心依赖 (含 Chroma，开箱即用)
+    pip install hy-memory[qdrant]  # + Qdrant 向量库
+    pip install hy-memory[faiss]   # + FAISS 向量库
+    pip install hy-memory[all]     # 包含所有可选依赖
+"""
+
+try:
+    from importlib.metadata import version as _get_version
+    __version__ = _get_version("hy-memory")
+except Exception:
+    __version__ = "1.0.0"
+
+# ====== 用户级 API（推荐） ======
+from .client import HyMemoryClient
+from .inspector import MemoryInspector
+
+# ====== 配置 ======
+from .config import MemoryConfig
+
+# ====== 高级 API（按需使用） ======
+from .pipelines import (
+    ComponentFactory,
+    PipelineConfig,
+    WritePipeline,
+    ReadPipeline,
+    ChatMessage,
+    WriteRequest,
+    WriteResponse,
+    ReadRequest,
+    ReadResponse,
+)
+
+# ====== 数据模型 ======
+from .models import (
+    MemoryLayer,
+    MemoryNode,
+    MemoryEntry,
+    MemoryMetadata,
+    MemoryScore,
+    MemoryInputType,
+    AgentProcessMode,
+    TaskStatus,
+    DeleteScope,
+    QAPair,
+    AddRequest,
+    AddResponse,
+    AsyncAddResponse,
+    RecallRequest,
+    RecallResponse,
+    UpdateRequest,
+    UpdateResponse,
+    DeleteRequest,
+    DeleteResponse,
+    BatchDeleteRequest,
+    BatchDeleteResponse,
+    GetRequest,
+    GetResponse,
+    ListRequest,
+    ListResponse,
+)
+
+
+__all__ = [
+    "__version__",
+    # 用户级 API
+    "HyMemoryClient",
+    "MemoryInspector",
+    # 配置
+    "MemoryConfig",
+    # 高级 API
+    "ComponentFactory",
+    "PipelineConfig",
+    "WritePipeline",
+    "ReadPipeline",
+    "ChatMessage",
+    "WriteRequest",
+    "WriteResponse",
+    "ReadRequest",
+    "ReadResponse",
+    # 数据模型
+    "MemoryLayer",
+    "MemoryNode",
+    "MemoryEntry",
+    "MemoryMetadata",
+    "MemoryScore",
+    "MemoryInputType",
+    "AgentProcessMode",
+    "TaskStatus",
+    "DeleteScope",
+    "QAPair",
+    "AddRequest",
+    "AddResponse",
+    "AsyncAddResponse",
+    "RecallRequest",
+    "RecallResponse",
+    "UpdateRequest",
+    "UpdateResponse",
+    "DeleteRequest",
+    "DeleteResponse",
+    "BatchDeleteRequest",
+    "BatchDeleteResponse",
+    "GetRequest",
+    "GetResponse",
+    "ListRequest",
+    "ListResponse",
+]

hy_memory/agent/__init__.py

@@ -0,0 +1,99 @@
+"""
+Agent Memory - 智能层 (Agent Layer)
+
+基于 LLM 的智能处理能力，提供语义理解、信息提取、推理判断等功能。
+该层是可选的，关闭后系统仍能正常工作。
+
+包含模块：
+- MemAgent: 智能体协调器，统一入口
+- Summarizer: Lite+Agent pipeline 摘要生成器 (L3_SUMMARY)
+- Abstractor: System 2 全量摘要智能体 (Session摘要/Schema归纳/Profile摘要)
+- Extractor: 提取智能体，提取结构化信息 (V2: 轻量提取/深度提取双模式)
+- Reflector: 反思智能体，检测冲突和更新 (V2: UpdateType分类/冲突检测/隐式推断)
+- EmotionAnalyzer: 情绪分析智能体，valence + arousal 双维标注
+- IntentionDetector: 意图检测智能体，前瞻性记忆 + 主动关怀
+- LLMProvider: LLM 提供器，统一的模型调用接口
+"""
+
+# Lite+Agent pipeline
+from .mem_agent import MemAgent, AgentResult, ProcessMode
+from .summarizer import Summarizer, SummaryResult
+from .extractor import Extractor, ExtractResult
+from .reflector import Reflector, ReflectResult, ConflictType, ConflictAction
+from .llm_provider import LLMProvider, LLMResponse, LLMConfig, LLMBackend
+
+# V2 Extractor
+from .extractor import ExtractMode, V2ExtractResult
+
+# System 2 / Pro Pipeline Abstractor
+from .abstractor import Abstractor, SessionSummaryResult, SchemaAbstractResult, ProfileSummaryResult
+
+# V2 Reflector
+from .reflector import (
+    V2ConflictType,
+    UpdateTypeResult,
+    ConflictDetectionResult,
+    ImplicitSignal,
+    ImplicitInferenceResult,
+)
+
+# V2 Emotion Analyzer
+from .emotion_analyzer import EmotionAnalyzer, EmotionAnalysisConfig, EmotionResult
+
+# V2 Intention Detector
+from .intention_detector import (
+    IntentionDetector,
+    IntentionDetectorConfig,
+    DetectedIntention,
+    IntentionDetectResult,
+    TriggeredIntentionItem,
+    IntentionTriggerResult,
+)
+
+__all__ = [
+    # MemAgent
+    "MemAgent",
+    "AgentResult",
+    "ProcessMode",
+    # Summarizer (Lite+Agent)
+    "Summarizer",
+    "SummaryResult",
+    # Abstractor (System 2)
+    "Abstractor",
+    "SessionSummaryResult",
+    "SchemaAbstractResult",
+    "ProfileSummaryResult",
+    # Extractor (V1)
+    "Extractor",
+    "ExtractResult",
+    # Extractor (V2)
+    "ExtractMode",
+    "V2ExtractResult",
+    # Reflector (V1)
+    "Reflector",
+    "ReflectResult",
+    "ConflictType",
+    "ConflictAction",
+    # Reflector (V2)
+    "V2ConflictType",
+    "UpdateTypeResult",
+    "ConflictDetectionResult",
+    "ImplicitSignal",
+    "ImplicitInferenceResult",
+    # Emotion Analyzer (V2)
+    "EmotionAnalyzer",
+    "EmotionAnalysisConfig",
+    "EmotionResult",
+    # Intention Detector (V2)
+    "IntentionDetector",
+    "IntentionDetectorConfig",
+    "DetectedIntention",
+    "IntentionDetectResult",
+    "TriggeredIntentionItem",
+    "IntentionTriggerResult",
+    # LLMProvider
+    "LLMProvider",
+    "LLMResponse",
+    "LLMConfig",
+    "LLMBackend",
+]

hy_memory/agent/abstractor.py

@@ -0,0 +1,300 @@
+"""
+Agent Memory V2 - Abstractor 摘要智能体 (System 2 Pro Pipeline)
+
+负责 System 2 pro pipeline 的高阶摘要能力：
+  1. Session 摘要生成 (L3 层 — System 2 Sleep Replay 调用)
+  2. Schema 归纳 (L5 层 — System 2 Schema Miner 调用)
+  3. Profile 摘要生成 (Context Assembly 调用)
+
+注意：lite+agent pipeline 的 L3_SUMMARY 生成由 summarizer.py 的 Summarizer 负责。
+"""
+
+from typing import Dict, Any, Optional, List
+from dataclasses import dataclass, field
+import json
+import logging
+
+from .llm_provider import LLMProvider
+from ..config import LLMConfig as GlobalLLMConfig
+
+logger = logging.getLogger(__name__)
+
+
+# ================================================================
+# 数据结构
+# ================================================================@dataclass
+class SessionSummaryResult:
+    """Session 摘要结果 (V2)"""
+    success: bool
+    summary: str = ""
+    key_topics: List[str] = field(default_factory=list)
+    emotional_tone: str = ""
+    new_facts_count: int = 0
+    tokens_used: int = 0
+    error: Optional[str] = None
+
+
+@dataclass
+class SchemaAbstractResult:
+    """Schema 归纳结果 (V2)"""
+    success: bool
+    central_proposition: str = ""
+    supporting_summary: str = ""
+    expected_inferences: List[str] = field(default_factory=list)
+    confidence: float = 0.0
+    tokens_used: int = 0
+    error: Optional[str] = None
+
+
+@dataclass
+class ProfileSummaryResult:
+    """Profile 摘要结果 (V2)"""
+    success: bool
+    core: str = ""
+    personality: str = ""
+    active_schemas: List[str] = field(default_factory=list)
+    gotchas: List[str] = field(default_factory=list)
+    note: str = ""
+    tokens_used: int = 0
+    error: Optional[str] = None
+
+
+# ================================================================
+# Prompt 模板
+# ================================================================
+
+SESSION_SUMMARY_PROMPT = """Generate a summary of the following conversation session. The summary language MUST match the conversation language.
+
+Session content:
+---
+{session_content}
+---
+
+Existing user profile:
+{user_profile}
+
+Current time: {current_time}
+
+Output in JSON format:
+{{
+  "summary": "A brief session summary (max 200 words, in the same language as the conversation)",
+  "key_topics": ["key topic 1", "topic 2"],
+  "emotional_tone": "overall emotional tone (e.g., positive/neutral/anxious/happy)",
+  "new_facts_count": 0
+}}"""
+
+SCHEMA_ABSTRACT_PROMPT = """Below is a set of related facts mentioned by the user across multiple sessions. Induce an abstract "mental model" (Schema).
+
+Related facts:
+{facts}
+
+A good Schema should:
+- Describe a recurring behavioral pattern or thinking style of the user
+- Not be a simple enumeration of facts, but an abstract pattern
+- Help predict how the user would react in similar situations
+
+Output in JSON format:
+{{
+  "central_proposition": "core proposition (one sentence describing this pattern)",
+  "supporting_summary": "evidence overview (why you believe this pattern exists)",
+  "expected_inferences": ["expected inference based on this pattern 1", "inference 2"],
+  "confidence": 0.0-1.0
+}}"""
+
+PROFILE_SUMMARY_PROMPT = """Generate a structured user profile summary based on the following data. The summary language MUST match the profile data language.
+
+Profile data:
+{profile_data}
+
+Active mental models:
+{active_schemas}
+
+Known gotchas/notes:
+{gotchas}
+
+Output in JSON format:
+{{
+  "core": "core description (e.g., name, age, location, occupation)",
+  "personality": "personality/style description (e.g., pragmatic, tech-oriented)",
+  "active_schemas": ["active behavioral patterns"],
+  "gotchas": ["gotchas/safety notes to be aware of"],
+  "note": "other notes"
+}}"""
+
+
+# ================================================================
+# 核心实现
+# ================================================================
+
+class Abstractor:
+    """
+    摘要智能体 (System 2 Pro Pipeline)
+
+    负责 System 2 的高阶摘要：Session 摘要 / Schema 归纳 / Profile 摘要。
+    lite+agent pipeline 的 L3_SUMMARY 由 Summarizer（summarizer.py）负责。
+    """
+
+    def __init__(
+        self,
+        llm_provider: LLMProvider,
+        llm_config: Optional[GlobalLLMConfig] = None,
+    ):
+        self.llm = llm_provider
+        self._llm_config = llm_config or GlobalLLMConfig()
+        self._call_count = 0
+        self._total_tokens = 0
+        logger.debug("Abstractor initialized")
+
+    async def generate_session_summary(
+        self,
+        session_content: str,
+        user_profile: str = "",
+        current_time: str = "",  # 由调用方传入，不传则为空字符串
+    ) -> SessionSummaryResult:
+        """
+        生成 Session 摘要 (L3 层)。
+        由 System 2 Sleep Replay Worker 调用。
+        """
+        try:
+            prompt = SESSION_SUMMARY_PROMPT.format(
+                session_content=session_content,
+                user_profile=user_profile or "(暂无画像)",
+                current_time=current_time,  # 由调用方决定，不传则为空字符串
+            )
+            response = await self.llm.complete(
+                prompt=prompt,
+                max_tokens=self._llm_config.agent_max_tokens,
+                temperature=0.3,
+            )
+            self._call_count += 1
+            self._total_tokens += response.tokens_used
+
+            data = self._parse_json(response.content)
+
+            return SessionSummaryResult(
+                success=True,
+                summary=data.get("summary", response.content.strip()),
+                key_topics=data.get("key_topics", []),
+                emotional_tone=data.get("emotional_tone", "中性"),
+                new_facts_count=data.get("new_facts_count", 0),
+                tokens_used=response.tokens_used,
+            )
+        except Exception as e:
+            logger.error(f"generate_session_summary failed: {e}")
+            return SessionSummaryResult(success=False, error=str(e))
+
+    # ================================================================
+    # V2 Schema 归纳 (L4.5)
+    # ================================================================
+
+    async def abstract_schema(
+        self,
+        facts: List[str],
+    ) -> SchemaAbstractResult:
+        """
+        从一组关联事实中归纳 Schema (心智模型)。
+        由 System 2 Schema Miner 调用。
+        """
+        try:
+            facts_text = "\n".join(f"  - {f}" for f in facts)
+            prompt = SCHEMA_ABSTRACT_PROMPT.format(facts=facts_text)
+
+            response = await self.llm.complete(
+                prompt=prompt,
+                max_tokens=self._llm_config.agent_max_tokens,
+                temperature=0.4,
+            )
+            self._call_count += 1
+            self._total_tokens += response.tokens_used
+
+            data = self._parse_json(response.content)
+
+            return SchemaAbstractResult(
+                success=True,
+                central_proposition=data.get("central_proposition", ""),
+                supporting_summary=data.get("supporting_summary", ""),
+                expected_inferences=data.get("expected_inferences", []),
+                confidence=float(data.get("confidence", 0.5)),
+                tokens_used=response.tokens_used,
+            )
+        except Exception as e:
+            logger.error(f"abstract_schema failed: {e}")
+            return SchemaAbstractResult(success=False, error=str(e))
+
+    # ================================================================
+    # V2 Profile 摘要 (L5)
+    # ================================================================
+
+    async def generate_profile_summary(
+        self,
+        profile_data: str,
+        active_schemas: str = "",
+        gotchas: str = "",
+    ) -> ProfileSummaryResult:
+        """
+        生成 Profile 摘要，用于 Memory Context Package 的 Layer 0。
+        由 Context Assembly 调用。
+        """
+        try:
+            prompt = PROFILE_SUMMARY_PROMPT.format(
+                profile_data=profile_data or "(暂无画像数据)",
+                active_schemas=active_schemas or "(无)",
+                gotchas=gotchas or "(无)",
+            )
+            response = await self.llm.complete(
+                prompt=prompt,
+                max_tokens=self._llm_config.agent_max_tokens,
+                temperature=0.2,
+            )
+            self._call_count += 1
+            self._total_tokens += response.tokens_used
+
+            data = self._parse_json(response.content)
+
+            return ProfileSummaryResult(
+                success=True,
+                core=data.get("core", ""),
+                personality=data.get("personality", ""),
+                active_schemas=data.get("active_schemas", []),
+                gotchas=data.get("gotchas", []),
+                note=data.get("note", ""),
+                tokens_used=response.tokens_used,
+            )
+        except Exception as e:
+            logger.error(f"generate_profile_summary failed: {e}")
+            return ProfileSummaryResult(success=False, error=str(e))
+
+    # ================================================================
+    # 工具方法
+    # ================================================================
+
+    @staticmethod
+    def _parse_json(text: str) -> Dict[str, Any]:
+        """从 LLM 输出中解析 JSON"""
+        text = text.strip()
+        if "```json" in text:
+            text = text.split("```json")[1].split("```")[0].strip()
+        elif "```" in text:
+            text = text.split("```")[1].split("```")[0].strip()
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            import re
+            match = re.search(r'\{[\s\S]*\}', text)
+            if match:
+                try:
+                    return json.loads(match.group())
+                except json.JSONDecodeError:
+                    pass
+        return {}
+
+    def get_stats(self) -> Dict[str, Any]:
+        """获取统计信息"""
+        return {
+            "call_count": self._call_count,
+            "total_tokens": self._total_tokens,
+            "avg_tokens_per_call": (
+                self._total_tokens / self._call_count
+                if self._call_count > 0 else 0
+            ),
+        }