realtimex-deeptutor 0.5.0.post1__py3-none-any.whl

src/agents/guide/prompts/zh/locate_agent.yaml

@@ -0,0 +1,68 @@
+system: |
+  # 角色定位
+  你是一位资深的**学习规划师 (Learning Planner)**。你的核心职责是分析用户笔记本中的学习记录，理解其涵盖的知识范围，并设计一套循序渐进的学习计划。
+
+  # 核心原则
+  1. **内容驱动**：基于笔记本中实际存在的内容（用户提问和系统回答）来分析知识点
+  2. **递进设计**：知识点必须按照从基础到进阶的逻辑顺序排列
+  3. **聚焦难点**：识别用户在理解过程中可能存在的困难和障碍
+  4. **动态粒度**：根据内容复杂度灵活确定知识点数量
+
+  # 知识点数量决策规则
+  根据笔记本内容的广度和深度，灵活决定知识点数量：
+  | 内容特征 | 知识点数量 | 适用场景 |
+  |---------|-----------|---------|
+  | 单一主题，内容简单 | 1-2个 | 笔记本只涉及一个简单概念或问题 |
+  | 单一主题，内容深入 | 2-3个 | 一个主题但有多个层次（基础→应用→拓展） |
+  | 多主题，相互独立 | 3-5个 | 笔记本涉及多个独立的知识点 |
+  | 多主题，高度关联 | 4-6个 | 复杂系统或框架，需要系统性学习 |
+  | 大量记录，内容丰富 | 5-8个 | 笔记本记录数量多，涵盖完整知识体系 |
+
+  **决策流程**：
+  1. 首先评估笔记本的记录数量和内容广度
+  2. 识别主要知识领域（可能是1个或多个）
+  3. 对每个领域判断是否需要拆分（是否有基础/进阶之分）
+  4. 合并过于细碎的点，拆分过于笼统的点
+  5. 确保每个知识点都是有意义的学习单元
+
+  # 分析维度
+  1. **知识点标题 (knowledge_title)**：用简洁的标题概括这一知识点
+  2. **知识点摘要 (knowledge_summary)**：基于笔记本内容，完整阐述这个知识点的核心内容，包括定义、原理、公式、应用等，不限字数，说清楚为止
+  3. **用户难点 (user_difficulty)**：分析用户的提问方式和问题内容，推测用户在理解这个知识点时可能遇到的困难
+
+  # 输出格式
+  直接输出JSON数组（无Markdown格式）：
+  ```json
+  [
+    {
+      "knowledge_title": "知识点标题",
+      "knowledge_summary": "详细的知识点内容阐述...",
+      "user_difficulty": "用户可能存在的理解困难..."
+    },
+    ...
+  ]
+  ```
+
+  # 注意事项
+  - 每个知识点应该是独立且完整的学习单元
+  - knowledge_summary 需要足够详细，包含所有必要的背景知识
+  - user_difficulty 应该具体、可操作，便于后续教学时针对性解决
+  - **数量灵活**：不强制要求固定数量，根据实际内容决定（1-8个都可以）
+  - 确保知识点之间有清晰的递进关系
+  - 宁可少而精，不要多而泛
+
+user_template: |
+  ## 笔记本信息
+  笔记本ID: {notebook_id}
+  笔记本名称: {notebook_name}
+  记录数量: {record_count}
+
+  ## 笔记本内容记录
+  {records_content}
+
+  ## 任务
+  请仔细分析以上笔记本中的所有内容，理解用户的学习主题和范围，然后：
+  1. 识别出涉及的所有核心知识点
+  2. 按照从基础到进阶的顺序组织这些知识点
+  3. 为每个知识点生成详细的摘要和用户可能的困难点
+  4. 输出3-5个知识点的JSON数组

src/agents/guide/prompts/zh/summary_agent.yaml

@@ -0,0 +1,157 @@
+system: |
+  # 角色定位
+  你是一位**学习总结专家 (Learning Summary Expert)**。你的职责是在用户完成一轮引导式学习后，生成一份全面、具体、个性化的学习总结报告。
+
+  # 核心原则
+  1. **具体化优先**：所有分析必须基于实际的学习数据，引用具体的知识点、具体的问题、具体的互动内容
+  2. **数据驱动**：基于用户的实际提问和互动情况进行分析，不要泛泛而谈
+  3. **个性化**：针对用户的学习特点、困难点、互动模式提供个性化分析
+  4. **可操作性**：所有建议必须具体、可执行，不要使用空泛的表述
+
+  # 总结维度（必须具体化）
+  1. **学习内容回顾**：
+     - 必须列出每个知识点的具体标题
+     - 简要说明每个知识点的核心内容（1-2句话）
+     - 说明知识点之间的递进关系
+     - 不要只说"学习了X个知识点"，要具体列出每个知识点
+
+  2. **学习过程分析**：
+     - 必须引用用户的具体问题（如果用户有提问）
+     - 分析用户提问的频率、深度、关注点
+     - 识别用户的学习模式（主动提问型/被动接受型/深入探索型等）
+     - 如果用户没有提问，说明用户的学习方式，并分析可能的原因
+     - 不要使用"用户提出了几个问题"这样的泛泛表述，要具体说明问题内容
+
+  3. **掌握程度评估**：
+     - 基于用户的具体问题内容，评估对每个知识点的理解程度
+     - 如果用户针对某个知识点提问，说明提问的类型（概念理解/应用实践/深入探索等）
+     - 识别用户可能存在的薄弱环节（基于提问内容或没有提问的知识点）
+     - 不要使用"掌握良好"这样的空泛评价，要具体说明掌握的证据
+
+  4. **改进建议**：
+     - 针对用户的具体薄弱环节提供建议
+     - 建议必须具体、可操作，不要使用"多练习"、"多思考"这样的空泛建议
+     - 可以建议具体的复习重点、拓展方向、实践方法
+     - 如果用户提问较少，可以建议如何更主动地学习
+
+  # 报告风格
+  - 以导师的身份撰写，语气亲切专业
+  - 使用鼓励性的语言，肯定用户的学习努力
+  - 提供具体、可操作的建议
+  - 使用Markdown格式，结构清晰
+  - **重要**：直接输出Markdown内容，不要用代码块（```markdown）包裹
+  - **重要**：输出纯Markdown文本，不要添加任何markdown标记或解释
+  - **重要**：所有分析必须具体，引用实际的学习数据，避免空泛的表述
+
+  # 报告结构（必须包含具体内容）
+  ```markdown
+  # 📊 学习总结报告
+
+  ## 🎯 学习概览
+  [具体说明：学习了哪些知识点，学习时长/互动次数，整体学习特点]
+
+  例如：
+  - 本次学习共涵盖3个知识点：XXX、XXX、XXX
+  - 在学习过程中，你提出了X个问题，主要集中在XXX方面
+  - 你的学习方式表现出XXX特点
+
+  ## 📚 知识点回顾
+  [逐一回顾，每个知识点都要具体说明]
+
+  ### 知识点1：XXX
+  - 核心内容：[具体说明这个知识点的核心内容]
+  - 学习情况：[基于互动情况，说明你在这个知识点上的学习表现]
+
+  ### 知识点2：XXX
+  - 核心内容：[具体说明]
+  - 学习情况：[具体分析]
+
+  ## 💬 学习互动分析
+  [必须引用具体的提问内容，具体分析]
+
+  - 提问频率：[具体数字和分布]
+  - 提问特点：[基于具体问题内容分析，例如"你关注的是概念理解还是实际应用"]
+  - 具体问题回顾：[列出1-2个典型问题，说明这些问题反映了什么]
+  - 学习模式：[基于互动情况，判断用户的学习模式]
+
+  ## 📈 掌握程度评估
+  [基于具体数据，对每个知识点进行具体评估]
+
+  - 知识点1：XXX
+    - 掌握证据：[具体说明，例如"你提出了关于XXX的问题，说明你理解了..."]
+    - 薄弱环节：[如果有，具体说明]
+
+  - 知识点2：XXX
+    - 掌握证据：[具体说明]
+    - 薄弱环节：[如果有，具体说明]
+
+  ## 🚀 后续学习建议
+  [必须具体、可操作]
+
+  - 复习重点：[具体列出需要重点复习的知识点或概念]
+  - 拓展方向：[具体建议可以学习哪些相关内容]
+  - 实践建议：[具体建议如何实践应用]
+  - 学习方法：[基于你的学习特点，给出具体的学习方法建议]
+
+  ## 🌟 结语
+  [鼓励性的结束语，可以总结本次学习的亮点]
+  ```
+
+  # 输出要求
+  - 所有分析必须基于提供的实际数据（知识点、对话历史）
+  - 必须引用具体的知识点标题、具体的问题内容
+  - 避免使用"很好"、"不错"、"需要加强"这样的空泛评价
+  - 使用具体的数据、具体的例子、具体的建议
+  - 如果用户没有提问，要分析原因并给出具体建议
+  - 直接输出Markdown格式的文本内容，不要用代码块包裹
+
+user_template: |
+  ## 学习计划概览
+  笔记本名称: {notebook_name}
+  知识点数量: {total_points}
+
+  ## 所有知识点
+  {all_knowledge_points}
+
+  ## 完整对话历史
+  {full_chat_history}
+
+  ## 任务
+  请基于以上**实际的学习数据**，生成一份**具体、详细**的学习总结报告。
+
+  ### 要求（必须严格遵守）：
+
+  1. **具体化所有内容**：
+     - 必须列出每个知识点的具体标题和核心内容
+     - 必须引用用户的具体问题（如果有）
+     - 必须基于实际互动情况进行分析
+     - 不要使用"学习了几个知识点"这样的泛泛表述
+
+  2. **数据驱动分析**：
+     - 统计用户提问的次数、分布（哪个知识点提问多）
+     - 分析用户问题的类型（概念理解/应用/深入探索）
+     - 基于问题内容判断用户的理解程度
+     - 如果用户没有提问，分析可能的原因（快速理解/需要引导等）
+
+  3. **个性化评估**：
+     - 对每个知识点，基于实际互动情况给出具体评估
+     - 识别用户的具体薄弱环节（如果有）
+     - 说明评估的依据（例如"你提出了关于XXX的问题，说明你理解了..."）
+
+  4. **可操作建议**：
+     - 建议必须具体，不要使用"多练习"、"多思考"这样的空泛表述
+     - 可以建议具体的复习重点、拓展方向、实践方法
+     - 基于用户的学习特点给出个性化的学习方法建议
+
+  5. **引用实际数据**：
+     - 在报告中引用具体的知识点标题
+     - 引用用户的具体问题（如果有）
+     - 使用具体数字（提问次数、知识点数量等）
+     - 避免空泛的表述
+
+  **输出格式要求**：
+  - 直接输出Markdown格式的文本内容
+  - 不要用 ```markdown 或 ``` 代码块包裹
+  - 不要添加任何解释或说明文字
+  - 直接输出可渲染的Markdown内容
+  - 确保所有内容都是具体的、基于实际数据的

src/agents/ideagen/__init__.py

@@ -0,0 +1,12 @@
+"""
+Idea Generation Agents
+Agent system for generating research ideas based on notebook content
+"""
+
+from .idea_generation_workflow import IdeaGenerationWorkflow
+from .material_organizer_agent import MaterialOrganizerAgent
+
+__all__ = [
+    "IdeaGenerationWorkflow",
+    "MaterialOrganizerAgent",
+]

src/agents/ideagen/idea_generation_workflow.py

@@ -0,0 +1,426 @@
+"""
+Idea Generation Workflow.
+Uses unified PromptManager for prompt loading.
+"""
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from datetime import datetime
+import json
+from pathlib import Path
+import sys
+from typing import Any
+
+# Add project root to path
+_project_root = Path(__file__).parent.parent.parent.parent
+if str(_project_root) not in sys.path:
+    sys.path.insert(0, str(_project_root))
+
+from src.agents.base_agent import BaseAgent
+from src.services.prompt import get_prompt_manager
+
+
+class IdeaGenerationWorkflow(BaseAgent):
+    """Idea generation workflow"""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        api_version: str | None = None,
+        model: str | None = None,
+        progress_callback: Callable[[str, Any], None | Awaitable[None]] | None = None,
+        output_dir: Path | None = None,
+        language: str = "en",
+    ):
+        """
+        Initialize workflow
+
+        Args:
+            api_key: API key
+            base_url: API endpoint
+            api_version: API version (for Azure OpenAI)
+            model: Model name
+            progress_callback: Progress callback function for streaming output
+            output_dir: Output directory for saving intermediate results
+            language: Language for prompts ("en" or "zh")
+        """
+        super().__init__(
+            module_name="ideagen",
+            agent_name="idea_generation",
+            api_key=api_key,
+            base_url=base_url,
+            api_version=api_version,
+            model=model,
+            language=language,
+        )
+        self.progress_callback = progress_callback
+        self.output_dir = output_dir
+        self._prompts = get_prompt_manager().load_prompts(
+            module_name="ideagen",
+            agent_name="idea_generation",
+            language=language,
+        )
+
+    async def _emit_progress(self, stage: str, data: Any):
+        """Emit progress update"""
+        if self.progress_callback:
+            result = self.progress_callback(stage, data)
+            if result is not None and asyncio.iscoroutine(result):
+                await result
+
+    async def loose_filter(self, knowledge_points: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """
+        Loose filtering - filter out unsuitable knowledge points
+
+        Args:
+            knowledge_points: Knowledge point list
+
+        Returns:
+            Filtered knowledge point list
+        """
+        await self._emit_progress(
+            "loose_filter", {"status": "start", "total": len(knowledge_points)}
+        )
+
+        system_prompt = self._prompts.get("loose_filter_system", "")
+        user_template = self._prompts.get("loose_filter_user_template", "")
+
+        points_text = ""
+        for i, point in enumerate(knowledge_points, 1):
+            points_text += (
+                f"\n{i}. {point['knowledge_point']}\n   Description: {point['description']}\n"
+            )
+
+        user_prompt = user_template.format(points_text=points_text)
+
+        self.logger.info(f"Calling LLM to filter {len(knowledge_points)} knowledge points...")
+
+        response = await self.call_llm(
+            user_prompt=user_prompt,
+            system_prompt=system_prompt,
+            response_format={"type": "json_object"},
+        )
+
+        self.logger.debug(f"LLM response length: {len(response)} chars")
+
+        try:
+            result = json.loads(response)
+            filtered = result.get("filtered_points", [])
+
+            self.logger.info(
+                f"Parsed result: {len(filtered)} filtered points from {len(knowledge_points)} original"
+            )
+
+            # If filtered is empty but original list is not, filter is too strict, return original list
+            if not filtered and knowledge_points:
+                self.logger.warning("All points filtered out! Returning original list.")
+                filtered = knowledge_points
+
+            # Save filtered results
+            if self.output_dir:
+                with open(
+                    self.output_dir / "02_filtered_knowledge_points.json", "w", encoding="utf-8"
+                ) as f:
+                    json.dump(
+                        {
+                            "stage": "loose_filter",
+                            "original_count": len(knowledge_points),
+                            "filtered_count": len(filtered),
+                            "filtered_points": filtered,
+                            "timestamp": datetime.now().isoformat(),
+                        },
+                        f,
+                        ensure_ascii=False,
+                        indent=2,
+                    )
+
+            await self._emit_progress(
+                "loose_filter", {"status": "complete", "filtered": len(filtered)}
+            )
+            return filtered
+        except json.JSONDecodeError as e:
+            self.logger.error(f"JSON decode error: {e}")
+            self.logger.debug(f"Raw response: {response[:500]}...")
+            await self._emit_progress("loose_filter", {"status": "error"})
+            return knowledge_points  # If parsing fails, return original list
+
+    async def explore_ideas(self, knowledge_point: dict[str, Any]) -> list[str]:
+        """
+        3.2 Explore knowledge points - Generate at least 5 research ideas for each knowledge point
+
+        Args:
+            knowledge_point: Knowledge point dictionary
+
+        Returns:
+            List of research ideas (at least 5)
+        """
+        system_prompt = self._prompts.get("explore_ideas_system", "")
+        user_template = self._prompts.get("explore_ideas_user_template", "")
+
+        user_prompt = user_template.format(
+            knowledge_point=knowledge_point["knowledge_point"],
+            description=knowledge_point["description"],
+        )
+
+        self.logger.info(
+            f"Generating ideas for: {knowledge_point.get('knowledge_point', 'unknown')}"
+        )
+
+        response = await self.call_llm(
+            user_prompt=user_prompt,
+            system_prompt=system_prompt,
+            response_format={"type": "json_object"},
+        )
+
+        self.logger.debug(f"LLM response length: {len(response)} chars")
+
+        try:
+            result = json.loads(response)
+            ideas = result.get("research_ideas", [])
+            self.logger.info(f"Generated {len(ideas)} research ideas")
+            # Ensure at least 5
+            if len(ideas) < 5:
+                # If less than 5, can call again or supplement
+                self.logger.warning(f"Only {len(ideas)} ideas generated (expected at least 5)")
+
+            # Save generated research ideas
+            if self.output_dir:
+                safe_name = (
+                    "".join(
+                        c
+                        for c in knowledge_point["knowledge_point"]
+                        if c.isalnum() or c in (" ", "-", "_")
+                    )
+                    .strip()[:50]
+                    .replace(" ", "_")
+                )
+                with open(
+                    self.output_dir / f"03_ideas_{safe_name}.json", "w", encoding="utf-8"
+                ) as f:
+                    json.dump(
+                        {
+                            "stage": "explore_ideas",
+                            "knowledge_point": knowledge_point,
+                            "research_ideas": ideas,
+                            "count": len(ideas),
+                            "timestamp": datetime.now().isoformat(),
+                        },
+                        f,
+                        ensure_ascii=False,
+                        indent=2,
+                    )
+
+            return ideas[:10]  # Return at most 10
+        except json.JSONDecodeError as e:
+            self.logger.error(f"JSON decode error: {e}")
+            self.logger.debug(f"Raw response: {response[:500]}...")
+            return []
+
+    async def strict_filter(
+        self, knowledge_point: dict[str, Any], research_ideas: list[str]
+    ) -> list[str]:
+        """
+        3.3 Strict filtering - Evaluate research ideas with strict standards
+
+        Args:
+            knowledge_point: Knowledge point dictionary
+            research_ideas: Research ideas list
+
+        Returns:
+            Retained research ideas list (at least keep 1, at least filter out 2)
+        """
+        if len(research_ideas) <= 1:
+            return research_ideas  # If only 1 or less, return directly
+
+        system_prompt = self._prompts.get("strict_filter_system", "")
+        user_template = self._prompts.get("strict_filter_user_template", "")
+
+        ideas_text = ""
+        for i, idea in enumerate(research_ideas, 1):
+            ideas_text += f"{i}. {idea}\n"
+
+        user_prompt = user_template.format(
+            knowledge_point=knowledge_point["knowledge_point"],
+            description=knowledge_point["description"],
+            ideas_text=ideas_text,
+        )
+
+        self.logger.info(
+            f"Filtering {len(research_ideas)} ideas for: {knowledge_point.get('knowledge_point', 'unknown')}"
+        )
+
+        response = await self.call_llm(
+            user_prompt=user_prompt,
+            system_prompt=system_prompt,
+            response_format={"type": "json_object"},
+        )
+
+        self.logger.debug(f"LLM response length: {len(response)} chars")
+
+        try:
+            result = json.loads(response)
+            kept = result.get("kept_ideas", [])
+            rejected = result.get("rejected_ideas", [])
+            reasons = result.get("reasons", {})
+            self.logger.info(f"Kept {len(kept)}, rejected {len(rejected)}")
+
+            # Validation: at least keep 1, at least filter out 2
+            if len(kept) == 0:
+                # If all filtered out, at least keep the first one
+                kept = [research_ideas[0]]
+                rejected = research_ideas[1:]
+            elif len(rejected) < 2 and len(research_ideas) >= 3:
+                # If less than 2 filtered out, force filter out the least suitable
+                # Can add smarter logic here
+                if len(kept) > 1:
+                    rejected.extend(kept[1:])
+                    kept = [kept[0]]
+
+            # Save filtering results
+            if self.output_dir:
+                safe_name = (
+                    "".join(
+                        c
+                        for c in knowledge_point["knowledge_point"]
+                        if c.isalnum() or c in (" ", "-", "_")
+                    )
+                    .strip()[:50]
+                    .replace(" ", "_")
+                )
+                with open(
+                    self.output_dir / f"04_filtered_ideas_{safe_name}.json", "w", encoding="utf-8"
+                ) as f:
+                    json.dump(
+                        {
+                            "stage": "strict_filter",
+                            "knowledge_point": knowledge_point,
+                            "original_ideas": research_ideas,
+                            "kept_ideas": kept,
+                            "rejected_ideas": rejected,
+                            "reasons": reasons,
+                            "kept_count": len(kept),
+                            "rejected_count": len(rejected),
+                            "timestamp": datetime.now().isoformat(),
+                        },
+                        f,
+                        ensure_ascii=False,
+                        indent=2,
+                    )
+
+            return kept
+        except json.JSONDecodeError as e:
+            self.logger.error(f"JSON decode error: {e}")
+            self.logger.debug(f"Raw response: {response[:500]}...")
+            # If parsing fails, at least keep the first one
+            return research_ideas[:1] if research_ideas else []
+
+    async def generate_statement(
+        self, knowledge_point: dict[str, Any], research_ideas: list[str]
+    ) -> str:
+        """
+        3.4 Generate statement - Generate markdown-formatted statement for knowledge points and research ideas
+
+        Args:
+            knowledge_point: Knowledge point dictionary
+            research_ideas: Retained research ideas list
+
+        Returns:
+            Markdown-formatted statement
+        """
+        system_prompt = self._prompts.get("generate_statement_system", "")
+        user_template = self._prompts.get("generate_statement_user_template", "")
+
+        ideas_text = ""
+        for i, idea in enumerate(research_ideas, 1):
+            ideas_text += f"{i}. {idea}\n"
+
+        user_prompt = user_template.format(
+            knowledge_point=knowledge_point["knowledge_point"],
+            description=knowledge_point["description"],
+            ideas_text=ideas_text,
+        )
+
+        response = await self.call_llm(user_prompt=user_prompt, system_prompt=system_prompt)
+
+        return response
+
+    async def process(self, knowledge_points: list[dict[str, Any]]) -> str:
+        """
+        Execute complete workflow
+
+        Args:
+            knowledge_points: Knowledge points list
+
+        Returns:
+            Final markdown document
+        """
+        # 3.1 Loose filtering
+        filtered_points = await self.loose_filter(knowledge_points)
+
+        if not filtered_points:
+            return "# Research Ideas Generation Result\n\nNo suitable knowledge points found."
+
+        # 3.2 and 3.3 Process each knowledge point
+        final_statements = []
+
+        for idx, point in enumerate(filtered_points):
+            await self._emit_progress(
+                "explore", {"status": "processing", "index": idx + 1, "total": len(filtered_points)}
+            )
+
+            # 3.2 Explore knowledge points
+            research_ideas = await self.explore_ideas(point)
+            await self._emit_progress(
+                "explore",
+                {"status": "complete", "index": idx + 1, "ideas_count": len(research_ideas)},
+            )
+
+            if not research_ideas:
+                continue
+
+            # 3.3 Strict filtering
+            kept_ideas = await self.strict_filter(point, research_ideas)
+            await self._emit_progress(
+                "filter", {"status": "complete", "index": idx + 1, "kept": len(kept_ideas)}
+            )
+
+            if not kept_ideas:
+                continue
+
+            # 3.4 Generate statement
+            statement = await self.generate_statement(point, kept_ideas)
+            final_statements.append(statement)
+
+        # Join all statements
+        final_markdown = "# Research Ideas Generation Result\n\n"
+        final_markdown += "\n\n---\n\n".join(final_statements)
+
+        # Save workflow summary
+        if self.output_dir:
+            workflow_summary = {
+                "stage": "workflow_summary",
+                "original_knowledge_points_count": len(knowledge_points),
+                "filtered_knowledge_points_count": len(filtered_points),
+                "processed_points": [
+                    {
+                        "knowledge_point": point["knowledge_point"],
+                        "description": point["description"],
+                        "statement": statement,
+                    }
+                    for point, statement in zip(
+                        [
+                            p
+                            for p in filtered_points
+                            if any(p["knowledge_point"] in s for s in final_statements)
+                        ],
+                        final_statements,
+                    )
+                ],
+                "final_statements_count": len(final_statements),
+                "timestamp": datetime.now().isoformat(),
+            }
+            with open(self.output_dir / "06_workflow_summary.json", "w", encoding="utf-8") as f:
+                json.dump(workflow_summary, f, ensure_ascii=False, indent=2)
+
+        return final_markdown