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

src/agents/research/agents/manager_agent.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+ManagerAgent - Queue management Agent
+Responsible for managing DynamicTopicQueue state and task distribution
+"""
+
+import asyncio
+from pathlib import Path
+import sys
+from typing import Any
+
+project_root = Path(__file__).parent.parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+from src.agents.base_agent import BaseAgent
+from src.agents.research.data_structures import DynamicTopicQueue, TopicBlock
+
+
+class ManagerAgent(BaseAgent):
+    """Queue management Agent"""
+
+    def __init__(
+        self,
+        config: dict[str, Any],
+        api_key: str | None = None,
+        base_url: str | None = None,
+        api_version: str | None = None,
+    ):
+        language = config.get("system", {}).get("language", "zh")
+        super().__init__(
+            module_name="research",
+            agent_name="manager_agent",
+            api_key=api_key,
+            base_url=base_url,
+            api_version=api_version,
+            language=language,
+            config=config,
+        )
+        self.queue: DynamicTopicQueue | None = None
+        self.primary_topic: str | None = None
+        self._lock = asyncio.Lock()  # Lock for thread-safe operations in parallel mode
+
+    def set_queue(self, queue: DynamicTopicQueue) -> None:
+        """Set queue to manage"""
+        self.queue = queue
+
+    def set_primary_topic(self, topic: str | None) -> None:
+        """Update primary research topic for subsequent topic consistency judgment"""
+        self.primary_topic = (topic or "").strip() or None
+
+    def get_next_task(self) -> TopicBlock | None:
+        """
+        Get next task to research
+
+        Returns:
+            Next TopicBlock with PENDING status, returns None if none available
+        """
+        if not self.queue:
+            return None
+
+        block = self.queue.get_pending_block()
+        if block:
+            # Mark as researching
+            self.queue.mark_researching(block.block_id)
+            print(f"\n📋 ManagerAgent: Assigned task {block.block_id}")
+            print(f"   Topic: {block.sub_topic}")
+
+        return block
+
+    def complete_task(self, block_id: str) -> bool:
+        """
+        Mark task as completed
+
+        Args:
+            block_id: Topic block ID
+
+        Returns:
+            Whether successfully marked
+        """
+        if not self.queue:
+            return False
+
+        success = self.queue.mark_completed(block_id)
+        if success:
+            print(f"✓ ManagerAgent: Task {block_id} completed")
+
+        return success
+
+    async def get_next_task_async(self) -> TopicBlock | None:
+        """
+        Thread-safe async version of get_next_task for parallel mode
+
+        Returns:
+            Next TopicBlock with PENDING status, returns None if none available
+        """
+        async with self._lock:
+            return self.get_next_task()
+
+    async def complete_task_async(self, block_id: str) -> bool:
+        """
+        Thread-safe async version of complete_task for parallel mode
+
+        Args:
+            block_id: Topic block ID
+
+        Returns:
+            Whether successfully marked
+        """
+        async with self._lock:
+            return self.complete_task(block_id)
+
+    async def fail_task_async(self, block_id: str, reason: str = "") -> bool:
+        """
+        Thread-safe async version of fail_task for parallel mode
+
+        Args:
+            block_id: Topic block ID
+            reason: Failure reason
+
+        Returns:
+            Whether successfully marked
+        """
+        async with self._lock:
+            return self.fail_task(block_id, reason)
+
+    async def add_new_topic_async(self, sub_topic: str, overview: str) -> TopicBlock:
+        """
+        Thread-safe async version of add_new_topic for parallel mode
+
+        Args:
+            sub_topic: Sub-topic name
+            overview: Topic overview
+
+        Returns:
+            Newly created TopicBlock
+        """
+        async with self._lock:
+            return self.add_new_topic(sub_topic, overview)
+
+    def fail_task(self, block_id: str, reason: str = "") -> bool:
+        """
+        Mark task as failed
+
+        Args:
+            block_id: Topic block ID
+            reason: Failure reason
+
+        Returns:
+            Whether successfully marked
+        """
+        if not self.queue:
+            return False
+
+        success = self.queue.mark_failed(block_id)
+        if success:
+            print(f"✗ ManagerAgent: Task {block_id} failed")
+            if reason:
+                print(f"   Reason: {reason}")
+
+        return success
+
+    def add_new_topic(self, sub_topic: str, overview: str) -> TopicBlock:
+        """
+        Add new topic to queue
+
+        Args:
+            sub_topic: Sub-topic name
+            overview: Topic overview
+
+        Returns:
+            Newly created TopicBlock
+        """
+        if not self.queue:
+            raise RuntimeError("Queue not initialized")
+
+        normalized = (sub_topic or "").strip()
+        if not normalized:
+            raise ValueError("New topic title cannot be empty")
+        if self.queue.has_topic(normalized):
+            print(f"⚠️ ManagerAgent: Topic《{normalized}》already exists, skipping addition")
+            return None
+
+        block = self.queue.add_block(normalized, overview)
+        print(f"✓ ManagerAgent: Added new topic {block.block_id}")
+        print(f"   Topic: {sub_topic}")
+
+        return block
+
+    def is_research_complete(self) -> bool:
+        """
+        Check if research is complete (all tasks are completed)
+
+        Returns:
+            Whether all tasks are completed
+        """
+        if not self.queue:
+            return False
+
+        return self.queue.is_all_completed()
+
+    def get_queue_status(self) -> dict[str, Any]:
+        """
+        Get queue status
+
+        Returns:
+            Queue statistics
+        """
+        if not self.queue:
+            return {}
+
+        stats = self.queue.get_statistics()
+        print("\n📊 Queue Status:")
+        print(f"   Total Topics: {stats['total_blocks']}")
+        print(f"   Pending: {stats['pending']}")
+        print(f"   Researching: {stats['researching']}")
+        print(f"   Completed: {stats['completed']}")
+        print(f"   Failed: {stats['failed']}")
+        print(f"   Total Tool Calls: {stats['total_tool_calls']}")
+
+        return stats
+
+    async def process(self, *args, **kwargs) -> Any:
+        """Main processing logic of Manager Agent"""
+        # Manager Agent is mainly called through other methods, no independent process method needed
+
+
+__all__ = ["ManagerAgent"]

src/agents/research/agents/note_agent.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+NoteAgent - Recording Agent
+Responsible for information compression and summary generation, converting raw data returned by tools into usable knowledge summaries
+"""
+
+from pathlib import Path
+from string import Template
+import sys
+from typing import Any, Optional
+
+project_root = Path(__file__).parent.parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+from src.agents.base_agent import BaseAgent
+from src.agents.research.data_structures import ToolTrace
+
+from ..utils.json_utils import extract_json_from_text
+
+
+class NoteAgent(BaseAgent):
+    """Recording Agent"""
+
+    def __init__(
+        self,
+        config: dict[str, Any],
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        api_version: Optional[str] = None,
+    ):
+        language = config.get("system", {}).get("language", "zh")
+        super().__init__(
+            module_name="research",
+            agent_name="note_agent",
+            api_key=api_key,
+            base_url=base_url,
+            api_version=api_version,
+            language=language,
+            config=config,
+        )
+
+    async def process(
+        self,
+        tool_type: str,
+        query: str,
+        raw_answer: str,
+        citation_id: str,
+        topic: str = "",
+        context: str = "",
+    ) -> ToolTrace:
+        """
+        Process raw data returned by tool, generate summary and create ToolTrace
+
+        Args:
+            tool_type: Tool type
+            query: Query statement
+            raw_answer: Raw answer returned by tool
+            citation_id: Citation ID (REQUIRED, must be obtained from CitationManager)
+            topic: Topic (for context)
+            context: Additional context
+
+        Returns:
+            ToolTrace object
+
+        Note:
+            citation_id must be obtained from CitationManager before calling this method.
+            Use CitationManager.get_next_citation_id() or its async variant.
+        """
+        print(f"\n{'=' * 70}")
+        print("📝 NoteAgent - Information Recording and Summary")
+        print(f"{'=' * 70}")
+        print(f"Tool: {tool_type}")
+        print(f"Query: {query}")
+        print(f"Citation ID: {citation_id}")
+        print(f"Raw Answer Length: {len(raw_answer)} characters\n")
+
+        # Generate summary
+        summary = await self._generate_summary(
+            tool_type=tool_type, query=query, raw_answer=raw_answer, topic=topic, context=context
+        )
+
+        print(f"✓ Summary generation completed ({len(summary)} characters)")
+
+        # Create ToolTrace with the provided citation ID
+        tool_id = self._generate_tool_id()
+        trace = ToolTrace(
+            tool_id=tool_id,
+            citation_id=citation_id,
+            tool_type=tool_type,
+            query=query,
+            raw_answer=raw_answer,
+            summary=summary,
+        )
+
+        return trace
+
+    @staticmethod
+    def _convert_to_template_format(template_str: str) -> str:
+        """
+        Convert {var} style placeholders to $var style for string.Template.
+        This avoids conflicts with LaTeX braces like {\rho}.
+        """
+        import re
+
+        # Only convert simple {var_name} patterns, not nested or complex ones
+        return re.sub(r"\{(\w+)\}", r"$\1", template_str)
+
+    async def _generate_summary(
+        self, tool_type: str, query: str, raw_answer: str, topic: str = "", context: str = ""
+    ) -> str:
+        """
+        Generate summary
+
+        Args:
+            tool_type: Tool type
+            query: Query statement
+            raw_answer: Raw answer
+            topic: Topic
+            context: Additional context
+
+        Returns:
+            Generated summary
+        """
+        system_prompt = self.get_prompt("system", "role")
+        if not system_prompt:
+            raise ValueError(
+                "NoteAgent missing system prompt, please configure system.role in prompts/{lang}/note_agent.yaml"
+            )
+
+        user_prompt_template = self.get_prompt("process", "generate_summary")
+        if not user_prompt_template:
+            raise ValueError(
+                "NoteAgent missing generate_summary prompt, please configure process.generate_summary in prompts/{lang}/note_agent.yaml"
+            )
+
+        # Use string.Template to avoid conflicts with LaTeX braces like {\rho}
+        # Convert {var} to $var format, then use safe_substitute
+        template_str = self._convert_to_template_format(user_prompt_template)
+        template = Template(template_str)
+        user_prompt = template.safe_substitute(
+            tool_type=tool_type,
+            query=query,
+            raw_answer=raw_answer,
+            topic=topic,
+            context=context,
+        )
+
+        response = await self.call_llm(
+            user_prompt=user_prompt,
+            system_prompt=system_prompt,
+            stage="generate_summary",
+            verbose=False,
+        )
+
+        # Parse JSON output (strict validation)
+        from ..utils.json_utils import ensure_json_dict, ensure_keys
+
+        data = extract_json_from_text(response)
+        try:
+            obj = ensure_json_dict(data)
+            ensure_keys(obj, ["summary"])
+            summary = obj.get("summary", "")
+            # Ensure summary is string type
+            if not isinstance(summary, str):
+                summary = str(summary) if summary else ""
+            return summary
+        except Exception:
+            # Fallback: directly use text prefix
+            return (response or "")[:1000]
+
+    def _generate_tool_id(self) -> str:
+        """Generate tool ID"""
+        import time
+
+        timestamp = int(time.time() * 1000)
+        return f"tool_{timestamp}"
+
+
+__all__ = ["NoteAgent"]

src/agents/research/agents/rephrase_agent.py

@@ -0,0 +1,263 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+RephraseAgent - Topic rephrasing Agent
+Responsible for rephrasing and optimizing user input
+"""
+
+from pathlib import Path
+import sys
+from typing import Any
+
+project_root = Path(__file__).parent.parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+from src.agents.base_agent import BaseAgent
+
+from ..utils.json_utils import extract_json_from_text
+
+
+class RephraseAgent(BaseAgent):
+    """Topic rephrasing Agent"""
+
+    def __init__(
+        self,
+        config: dict[str, Any],
+        api_key: str | None = None,
+        base_url: str | None = None,
+        api_version: str | None = None,
+    ):
+        language = config.get("system", {}).get("language", "zh")
+        super().__init__(
+            module_name="research",
+            agent_name="rephrase_agent",
+            api_key=api_key,
+            base_url=base_url,
+            api_version=api_version,
+            language=language,
+            config=config,
+        )
+        # Store complete conversation history for multi-turn optimization
+        self.conversation_history: list[dict[str, Any]] = []
+
+    def reset_history(self):
+        """Reset conversation history for a new research session"""
+        self.conversation_history = []
+
+    def _format_conversation_history(self) -> str:
+        """Format conversation history for prompt"""
+        if not self.conversation_history:
+            return ""
+
+        history_parts = []
+        for entry in self.conversation_history:
+            role = entry.get("role", "unknown")
+            iteration = entry.get("iteration", 0)
+            content = entry.get("content", "")
+
+            if role == "user":
+                if iteration == 0:
+                    history_parts.append(f"[User - Initial Input]\n{content}")
+                else:
+                    history_parts.append(f"[User - Feedback (Round {iteration})]\n{content}")
+            elif role == "assistant":
+                topic = content.get("topic", "") if isinstance(content, dict) else str(content)
+                history_parts.append(f"[Assistant - Rephrased Topic (Round {iteration})]\n{topic}")
+
+        return "\n\n".join(history_parts)
+
+    async def process(
+        self, user_input: str, iteration: int = 0, previous_result: dict[str, Any] = None
+    ) -> dict[str, Any]:
+        """
+        Rephrase and optimize user input, supports user interaction confirmation
+        Uses complete conversation history for better context understanding
+
+        Args:
+            user_input: User's original input (first time) or feedback (subsequent iterations)
+            iteration: Iteration count (for tracking rephrasing rounds)
+            previous_result: Previous rephrasing result (for backward compatibility)
+
+        Returns:
+            Dictionary containing rephrasing results
+            {
+                "topic": str,                  # Optimized research topic (a clear, explicit statement)
+                "iteration": int,              # Iteration count
+            }
+        """
+        print(f"\n{'=' * 70}")
+        print(f"🔄 RephraseAgent - Topic Rephrasing (Iteration {iteration})")
+        print(f"{'=' * 70}")
+
+        # Reset history for new session (iteration 0)
+        if iteration == 0:
+            self.reset_history()
+            print(f"Original Input: {user_input}\n")
+        else:
+            print(f"User Feedback: {user_input}\n")
+            print(f"Conversation History: {len(self.conversation_history)} entries\n")
+
+        # Add current user input to history
+        self.conversation_history.append(
+            {
+                "role": "user",
+                "content": user_input,
+                "iteration": iteration,
+            }
+        )
+
+        # Get system prompt
+        system_prompt = self.get_prompt("system", "role")
+        if not system_prompt:
+            raise ValueError(
+                "RephraseAgent missing system prompt, please configure system.role in prompts/{lang}/rephrase_agent.yaml"
+            )
+
+        # Get user prompt template
+        user_prompt_template = self.get_prompt("process", "rephrase")
+        if not user_prompt_template:
+            raise ValueError(
+                "RephraseAgent missing rephrase prompt, please configure process.rephrase in prompts/{lang}/rephrase_agent.yaml"
+            )
+
+        # Format conversation history for prompt
+        history_text = self._format_conversation_history()
+
+        # Format user prompt with full history
+        user_prompt = user_prompt_template.format(
+            user_input=user_input,
+            iteration=iteration,
+            conversation_history=history_text,
+            previous_result=history_text,  # For backward compatibility with old templates
+        )
+
+        # Call LLM
+        response = await self.call_llm(
+            user_prompt=user_prompt, system_prompt=system_prompt, stage="rephrase"
+        )
+
+        # Parse JSON output
+        data = extract_json_from_text(response)
+        from ..utils.json_utils import ensure_json_dict, ensure_keys
+
+        try:
+            result = ensure_json_dict(data)
+            ensure_keys(result, ["topic"])
+        except Exception:
+            # Fallback: use user input or last assistant topic
+            fallback_topic = user_input
+            for entry in reversed(self.conversation_history):
+                if entry.get("role") == "assistant":
+                    content = entry.get("content", {})
+                    if isinstance(content, dict) and content.get("topic"):
+                        fallback_topic = content["topic"]
+                        break
+            result = {"topic": fallback_topic}
+
+        result["iteration"] = iteration
+
+        # Add assistant response to history
+        self.conversation_history.append(
+            {
+                "role": "assistant",
+                "content": result,
+                "iteration": iteration,
+            }
+        )
+
+        print("\n✓ Rephrasing Completed:")
+        print(f"  Optimized Research Topic: {result.get('topic', '')}")
+
+        return result
+
+    async def check_user_satisfaction(
+        self, rephrase_result: dict[str, Any], user_feedback: str
+    ) -> dict[str, Any]:
+        """
+        Determine user satisfaction with rephrasing result
+
+        Args:
+            rephrase_result: Current rephrasing result
+            user_feedback: User feedback
+
+        Returns:
+            Dictionary containing judgment results
+            {
+                "user_satisfied": bool,        # Whether user is satisfied
+                "should_continue": bool,       # Whether to continue rephrasing
+                "interpretation": str,         # Interpretation of user intent
+                "suggested_action": str        # Suggested next action
+            }
+        """
+        print(f"\n{'=' * 70}")
+        print("🤔 RephraseAgent - Judging User Intent")
+        print(f"{'=' * 70}")
+        print(f"User Feedback: {user_feedback}\n")
+
+        system_prompt = self.get_prompt("system", "role")
+        if not system_prompt:
+            raise ValueError(
+                "RephraseAgent missing system prompt, please configure system.role in prompts/{lang}/rephrase_agent.yaml"
+            )
+
+        user_prompt_template = self.get_prompt("process", "check_satisfaction")
+        if not user_prompt_template:
+            raise ValueError(
+                "RephraseAgent missing check_satisfaction prompt, please configure process.check_satisfaction in prompts/{lang}/rephrase_agent.yaml"
+            )
+
+        user_prompt = user_prompt_template.format(
+            topic=rephrase_result.get("topic", ""), user_feedback=user_feedback
+        )
+
+        response = await self.call_llm(
+            user_prompt=user_prompt,
+            system_prompt=system_prompt,
+            stage="check_satisfaction",
+            verbose=False,
+        )
+
+        # Parse JSON output
+        data = extract_json_from_text(response)
+        from ..utils.json_utils import ensure_json_dict, ensure_keys
+
+        try:
+            result = ensure_json_dict(data)
+            ensure_keys(result, ["user_satisfied", "should_continue", "interpretation"])
+        except Exception:
+            # Fallback: judge based on keywords
+            feedback_lower = user_feedback.lower()
+            satisfied_keywords = ["ok", "yes", "satisfied", "good", "fine", "agree", "approved"]
+            continue_keywords = [
+                "modify",
+                "change",
+                "adjust",
+                "no",
+                "need",
+                "want",
+                "should",
+                "hope",
+            ]
+
+            user_satisfied = any(kw in feedback_lower for kw in satisfied_keywords) and not any(
+                kw in feedback_lower for kw in continue_keywords
+            )
+
+            result = {
+                "user_satisfied": user_satisfied,
+                "should_continue": not user_satisfied,
+                "interpretation": "Judged based on keywords",
+                "suggested_action": (
+                    "Continue rephrasing" if not user_satisfied else "Proceed to next stage"
+                ),
+            }
+
+        print("\n📊 Judgment Result:")
+        print(f"  User Satisfied: {'Yes' if result.get('user_satisfied') else 'No'}")
+        print(f"  Continue Rephrasing: {'Yes' if result.get('should_continue') else 'No'}")
+        print(f"  Intent Interpretation: {result.get('interpretation', '')}")
+
+        return result
+
+
+__all__ = ["RephraseAgent"]