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

src/agents/co_writer/narrator_agent.py

@@ -0,0 +1,423 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+NarratorAgent - Note narration agent.
+Inherits from unified BaseAgent with special TTS configuration.
+"""
+
+from datetime import datetime
+import json
+import os
+from pathlib import Path
+import re
+from typing import Any, Optional
+from urllib.parse import urlparse
+import uuid
+
+from openai import AsyncAzureOpenAI, AsyncOpenAI
+
+from src.agents.base_agent import BaseAgent
+from src.services.tts import get_tts_config
+
+# Import shared stats from edit_agent for legacy compatibility
+
+# Define storage path (unified under user/co-writer/ directory)
+USER_DIR = Path(__file__).parent.parent.parent.parent / "data" / "user" / "co-writer" / "audio"
+
+
+def ensure_dirs():
+    """Ensure directories exist"""
+    USER_DIR.mkdir(parents=True, exist_ok=True)
+
+
+class NarratorAgent(BaseAgent):
+    """Note Narration Agent - Generate narration script and convert to audio"""
+
+    def __init__(self, language: str = "en"):
+        """
+        Initialize NarratorAgent.
+
+        Args:
+            language: Language setting ('en' | 'zh'), default 'en'
+
+        Note: LLM configuration (api_key, base_url, model, etc.) is loaded
+        automatically from the unified config service. Use refresh_config()
+        to pick up configuration changes made in Settings.
+        """
+        # Use "narrator" as module_name to get independent temperature/max_tokens config
+        super().__init__(
+            module_name="narrator",
+            agent_name="narrator_agent",
+            language=language,
+        )
+
+        # Override prompts to load from co_writer module
+        # (narrator_agent prompts are stored under co_writer/prompts/)
+        from src.services.prompt import get_prompt_manager
+
+        self.prompts = get_prompt_manager().load_prompts(
+            module_name="co_writer",
+            agent_name="narrator_agent",
+            language=language,
+        )
+
+        # Load TTS-specific configuration
+        self._load_tts_config()
+
+    def _load_tts_config(self):
+        """Load TTS-specific configuration from unified config service."""
+        try:
+            self.tts_config = get_tts_config()
+            # Get voice from unified config (defaults to "alloy")
+            self.default_voice = self.tts_config.get("voice", "alloy")
+            self.logger.info(f"TTS settings loaded: voice={self.default_voice}")
+            # Validate TTS configuration
+            self._validate_tts_config()
+        except Exception as e:
+            self.logger.error(f"Failed to load TTS config: {e}", exc_info=True)
+            self.tts_config = None
+            self.default_voice = "alloy"
+
+    def _validate_tts_config(self):
+        """Validate TTS configuration completeness and format"""
+        if not self.tts_config:
+            raise ValueError("TTS config is None")
+
+        # Check required keys
+        required_keys = ["model", "api_key", "base_url"]
+        missing_keys = [key for key in required_keys if key not in self.tts_config]
+        if missing_keys:
+            raise ValueError(f"TTS config missing required keys: {missing_keys}")
+
+        # Validate base_url format
+        base_url = self.tts_config["base_url"]
+        if not base_url:
+            raise ValueError("TTS config 'base_url' is empty")
+
+        if not isinstance(base_url, str):
+            raise ValueError(f"TTS config 'base_url' must be a string, got {type(base_url)}")
+
+        # Validate URL format
+        if not base_url.startswith(("http://", "https://")):
+            raise ValueError(
+                f"TTS config 'base_url' must start with http:// or https://, got: {base_url}"
+            )
+
+        try:
+            parsed = urlparse(base_url)
+            if not parsed.netloc:
+                raise ValueError(f"TTS config 'base_url' has invalid format: {base_url}")
+        except Exception as e:
+            raise ValueError(f"TTS config 'base_url' parsing error: {e}")
+
+        # Validate api_key
+        api_key = self.tts_config.get("api_key")
+        if not api_key:
+            raise ValueError("TTS config 'api_key' is empty")
+
+        if not isinstance(api_key, str) or len(api_key.strip()) == 0:
+            raise ValueError("TTS config 'api_key' must be a non-empty string")
+
+        # Validate model
+        model = self.tts_config.get("model")
+        if not model:
+            raise ValueError("TTS config 'model' is empty")
+
+        # Log configuration info (hide sensitive information)
+        api_key_preview = f"{api_key[:8]}...{api_key[-4:]}" if len(api_key) > 12 else "*" * 10
+        self.logger.info("TTS Configuration Loaded (OpenAI API):")
+        self.logger.info(f"  Model: {model}")
+        self.logger.info(f"  Base URL: {base_url}")
+        self.logger.info(f"  API Key: {api_key_preview}")
+        self.logger.info(f"  Default Voice: {self.default_voice}")
+
+    async def process(
+        self,
+        content: str,
+        style: str = "friendly",
+        voice: Optional[str] = None,
+        skip_audio: bool = False,
+    ) -> dict[str, Any]:
+        """
+        Main processing method - alias for narrate().
+
+        Args:
+            content: Note content
+            style: Narration style
+            voice: Voice role
+            skip_audio: Whether to skip audio generation
+
+        Returns:
+            Dict containing script info and optionally audio info
+        """
+        return await self.narrate(content, style, voice, skip_audio)
+
+    async def generate_script(self, content: str, style: str = "friendly") -> dict[str, Any]:
+        """
+        Generate narration script
+
+        Args:
+            content: Note content (Markdown format)
+            style: Narration style (friendly, academic, concise)
+
+        Returns:
+            Dict containing:
+                - script: Narration script text
+                - key_points: List of extracted key points
+        """
+        # Estimate target length: OpenAI TTS supports up to 4096 characters
+        is_long_content = len(content) > 5000
+
+        style_prompts = {
+            "friendly": self.get_prompt("style_friendly", ""),
+            "academic": self.get_prompt("style_academic", ""),
+            "concise": self.get_prompt("style_concise", ""),
+        }
+
+        length_instruction = (
+            self.get_prompt("length_instruction_long", "")
+            if is_long_content
+            else self.get_prompt("length_instruction_short", "")
+        )
+
+        system_template = self.get_prompt("generate_script_system_template", "")
+        system_prompt = system_template.format(
+            style_prompt=style_prompts.get(style, style_prompts["friendly"]),
+            length_instruction=length_instruction,
+        )
+
+        if is_long_content:
+            user_template = self.get_prompt("generate_script_user_long", "")
+            user_prompt = user_template.format(content=content[:8000] + "...")
+        else:
+            user_template = self.get_prompt("generate_script_user_short", "")
+            user_prompt = user_template.format(content=content)
+
+        self.logger.info(f"Generating narration script with style: {style}")
+
+        # Use inherited call_llm method
+        response = await self.call_llm(
+            user_prompt=user_prompt,
+            system_prompt=system_prompt,
+            stage="generate_script",
+        )
+
+        # Clean and truncate response, ensure it doesn't exceed 4000 characters
+        script = response.strip()
+        if len(script) > 4000:
+            self.logger.warning(
+                f"Generated script length {len(script)} exceeds 4000 limit. Truncating..."
+            )
+            truncated = script[:3997]
+            last_period = max(
+                truncated.rfind("。"),
+                truncated.rfind("！"),
+                truncated.rfind("？"),
+                truncated.rfind("."),
+                truncated.rfind("!"),
+                truncated.rfind("?"),
+            )
+            if last_period > 3500:
+                script = truncated[: last_period + 1]
+            else:
+                script = truncated + "..."
+
+        key_points = await self._extract_key_points(content)
+
+        return {
+            "script": script,
+            "key_points": key_points,
+            "style": style,
+            "original_length": len(content),
+            "script_length": len(script),
+        }
+
+    async def _extract_key_points(self, content: str) -> list:
+        """Extract key points from notes"""
+        system_prompt = self.get_prompt("extract_key_points_system", "")
+        user_template = self.get_prompt(
+            "extract_key_points_user",
+            "Please extract key points from the following notes:\n\n{content}",
+        )
+        user_prompt = user_template.format(content=content[:4000])
+
+        try:
+            response = await self.call_llm(
+                user_prompt=user_prompt,
+                system_prompt=system_prompt,
+                stage="extract_key_points",
+            )
+
+            # Try to parse JSON
+            json_match = re.search(r"\[.*\]", response, re.DOTALL)
+            if json_match:
+                return json.loads(json_match.group())
+            return []
+        except Exception as e:
+            self.logger.warning(f"Failed to extract key points: {e}")
+            return []
+
+    async def generate_audio(self, script: str, voice: str = None) -> dict[str, Any]:
+        """
+        Convert narration script to audio using OpenAI TTS API
+
+        Args:
+            script: Narration script text
+            voice: Voice role (alloy, echo, fable, onyx, nova, shimmer)
+
+        Returns:
+            Dict containing:
+                - audio_path: Audio file path
+                - audio_url: Audio access URL
+                - audio_id: Unique audio identifier
+                - voice: Voice used
+        """
+        if not self.tts_config:
+            raise ValueError(
+                "TTS configuration not available. Please configure TTS_MODEL, TTS_API_KEY, and TTS_URL in .env"
+            )
+
+        # Use default voice if not specified
+        if voice is None:
+            voice = self.default_voice
+
+        # Validate input parameters
+        if not script or not script.strip():
+            raise ValueError("Script cannot be empty")
+
+        ensure_dirs()
+
+        # Truncate overly long scripts (OpenAI TTS supports up to 4096 characters)
+        original_script_length = len(script)
+        if len(script) > 4096:
+            self.logger.warning(f"Script length {len(script)} exceeds 4096 limit. Truncating...")
+            truncated = script[:4093]
+            last_period = max(
+                truncated.rfind("。"),
+                truncated.rfind("！"),
+                truncated.rfind("？"),
+                truncated.rfind("."),
+                truncated.rfind("!"),
+                truncated.rfind("?"),
+            )
+            if last_period > 3500:
+                script = truncated[: last_period + 1]
+            else:
+                script = truncated + "..."
+            self.logger.info(
+                f"Script truncated from {original_script_length} to {len(script)} characters"
+            )
+
+        audio_id = datetime.now().strftime("%Y%m%d_%H%M%S") + "_" + uuid.uuid4().hex[:6]
+        audio_filename = f"narration_{audio_id}.mp3"
+        audio_path = USER_DIR / audio_filename
+
+        self.logger.info(f"Starting TTS audio generation - ID: {audio_id}, Voice: {voice}")
+
+        try:
+            binding = os.getenv("TTS_BINDING", "openai")
+            api_version = self.tts_config.get("api_version")
+
+            # Only use Azure client if binding is explicitly Azure,
+            # OR if binding is generic 'openai' but an Azure-specific api_version is present.
+            if binding == "azure_openai" or (binding == "openai" and api_version):
+                client = AsyncAzureOpenAI(
+                    api_key=self.tts_config["api_key"],
+                    azure_endpoint=self.tts_config["base_url"],
+                    api_version=api_version,
+                )
+            else:
+                # Create OpenAI client with custom base_url
+                client = AsyncOpenAI(
+                    base_url=self.tts_config["base_url"], api_key=self.tts_config["api_key"]
+                )
+
+            # Call OpenAI TTS API
+            response = await client.audio.speech.create(
+                model=self.tts_config["model"], voice=voice, input=script
+            )
+
+            # Save audio to file
+            await response.stream_to_file(audio_path)
+
+            self.logger.info(f"Audio saved to: {audio_path}")
+
+            # Use correct path: co-writer/audio (matching the actual storage directory)
+            relative_path = f"co-writer/audio/{audio_filename}"
+            audio_access_url = f"/api/outputs/{relative_path}"
+
+            return {
+                "audio_path": str(audio_path),
+                "audio_url": audio_access_url,
+                "audio_id": audio_id,
+                "voice": voice,
+            }
+
+        except Exception as e:
+            self.logger.error(f"TTS generation failed: {type(e).__name__}: {e}", exc_info=True)
+            raise ValueError(f"TTS generation failed: {type(e).__name__}: {e}")
+
+    async def narrate(
+        self,
+        content: str,
+        style: str = "friendly",
+        voice: str = None,
+        skip_audio: bool = False,
+    ) -> dict[str, Any]:
+        """
+        Complete narration flow: generate script + generate audio
+
+        Args:
+            content: Note content
+            style: Narration style
+            voice: Voice role (alloy, echo, fable, onyx, nova, shimmer)
+            skip_audio: Whether to skip audio generation (only return script)
+
+        Returns:
+            Dict containing script info and optionally audio info
+        """
+        # Refresh TTS config before starting to avoid stale credentials
+        try:
+            self.tts_config = get_tts_config()
+        except Exception as e:
+            self.logger.error(f"Failed to refresh TTS config: {e}")
+
+        script_result = await self.generate_script(content, style)
+
+        # Use default voice if not specified
+        if voice is None:
+            voice = self.default_voice
+
+        result = {
+            "script": script_result["script"],
+            "key_points": script_result["key_points"],
+            "style": style,
+            "original_length": script_result["original_length"],
+            "script_length": script_result["script_length"],
+        }
+
+        if not skip_audio and self.tts_config:
+            try:
+                audio_result = await self.generate_audio(script_result["script"], voice=voice)
+                result.update(
+                    {
+                        "audio_url": audio_result["audio_url"],
+                        "audio_path": audio_result["audio_path"],
+                        "audio_id": audio_result["audio_id"],
+                        "voice": voice,
+                        "has_audio": True,
+                    }
+                )
+            except Exception as e:
+                self.logger.error(f"Audio generation failed: {e}")
+                result["has_audio"] = False
+                result["audio_error"] = str(e)
+        else:
+            result["has_audio"] = False
+            if not self.tts_config:
+                result["audio_error"] = "TTS not configured"
+
+        return result
+
+
+__all__ = ["NarratorAgent"]

src/agents/co_writer/prompts/en/edit_agent.yaml

@@ -0,0 +1,113 @@
+system: |
+  You are an expert editor and writing assistant.
+
+action_template: |
+  {action_verb} the following text based on the user's instruction.
+
+  User Instruction: {instruction}
+
+context_template: |
+  Reference Context:
+  {context}
+
+user_template: |
+  Target Text to Edit:
+  {text}
+
+  Output only the edited text, without quotes or explanations.
+
+auto_mark_system: |
+  You are a professional academic reading annotation assistant, helping readers quickly grasp the core points of text.
+
+  ## Task
+  Read the input text and **carefully select** the most critical information for annotation. Annotations should help readers quickly locate key points without interfering with reading.
+
+  ## Available Tags and Precise Usage Scenarios
+
+  ### 1. Circle - Use Sparingly
+  ```html
+  <span data-rough-notation="circle">content</span>
+  ```
+  **Applicable Scenarios**:
+  - Core topic words of articles/paragraphs (e.g., key concepts in paper titles)
+  - Unique proper nouns, model names (e.g., GPT-4, BERT)
+  - Key numerical values/metrics (e.g., 95.7%, p<0.05)
+
+  **Limitation**: Maximum 1 per 100 characters, content should not exceed 5 characters
+
+  ### 2. Highlight - Moderate Use
+  ```html
+  <span data-rough-notation="highlight">content</span>
+  ```
+  **Applicable Scenarios**:
+  - Definitional statements (e.g., "XX refers to...")
+  - First appearance of core concepts and their explanations
+  - Important methodological descriptions
+
+  **Limitation**: Maximum 2 per paragraph, content 2-15 characters
+
+  ### 3. Box - Minimal Use
+  ```html
+  <span data-rough-notation="box">content</span>
+  ```
+  **Applicable Scenarios**:
+  - Mathematical formulas, equations
+  - Specific data points or statistical values
+  - Code snippets, commands
+  - Version numbers, dates, and other precise information
+
+  **Limitation**: Maximum 1 per paragraph, content should not exceed 20 characters
+
+  ### 4. Underline - Moderate Use
+  ```html
+  <span data-rough-notation="underline">content</span>
+  ```
+  **Applicable Scenarios**:
+  - Conclusive statements
+  - Key expressions of causal relationships
+  - Core viewpoints in comparisons or contrasts
+  - Author's main arguments
+
+  **Limitation**: Maximum 1 per paragraph, content 5-30 characters
+
+  ### 5. Bracket - Use Sparingly
+  ```html
+  <span data-rough-notation="bracket">content</span>
+  ```
+  **Applicable Scenarios**:
+  - Entire paragraphs that are core summaries or conclusions
+  - Important quotations or theorem statements
+  - Critical warnings or notes
+
+  **Limitation**: Maximum 1-2 per entire article, for truly indispensable complete sentences
+
+  ## Core Rules
+
+  1. **Exercise Restraint**: Better to annotate less than to over-annotate. Annotation density should not exceed 10% of total text per paragraph.
+  2. **No Modifications**: Absolutely must not modify, delete, or add any text from the original, only insert HTML tags.
+  3. **Tag Placement**: Tags must be placed inside Markdown symbols (e.g., `**`, `*`, `` ` ``).
+  4. **When No Annotation Needed**: If the text has no information worth annotating, return it as-is.
+
+  ## Examples
+
+  **Input**:
+  Deep learning is a subfield of machine learning, and its core is using neural networks to learn data representations.
+
+  **Output**:
+  <span data-rough-notation="highlight">Deep learning is a subfield of machine learning</span>, and its core is using <span data-rough-notation="circle">neural networks</span> to learn data representations.
+
+  **Input**:
+  The weather is nice today, perfect for going out for a walk.
+
+  **Output**:
+  The weather is nice today, perfect for going out for a walk.
+
+  **Input**:
+  Experimental results show that our proposed method achieved 99.2% accuracy on the MNIST dataset, significantly exceeding the baseline method's 95.1%.
+
+  **Output**:
+  <span data-rough-notation="underline">Experimental results show that our proposed method achieved <span data-rough-notation="box">99.2%</span> accuracy on the MNIST dataset</span>, significantly exceeding the baseline method's 95.1%.
+
+auto_mark_user_template: |
+  Process the following text:
+  {text}

src/agents/co_writer/prompts/en/narrator_agent.yaml

@@ -0,0 +1,88 @@
+style_friendly: |
+  You are a friendly and approachable tutor, explaining note content face-to-face to students.
+
+  **Narration Requirements**:
+  1. **Person**: Use "we", "us", "you" to create closeness
+  2. **Tone**: Relaxed but professional, like chatting with a friend
+  3. **Pacing**: Appropriate pauses, use words like "well", "next", "so" for transitions
+  4. **Emphasis**: Use phrases like "this is important", "note here" to highlight key information
+  5. **Interaction**: Appropriately include phrases like "what do you think", "think about it" to guide thinking
+  6. **Length Control**: The script should be controlled within 4000 characters. If the original content is long, please generate a refined summary version, highlighting main points and key information.
+
+style_academic: |
+  You are a senior scholar giving an academic lecture.
+
+  **Narration Requirements**:
+  1. **Person**: Use "we", "this paper" and other academic language
+  2. **Tone**: Rigorous and professional, with clear logic
+  3. **Structure**: Clear introduction-body-conclusion structure
+  4. **Terminology**: Retain professional terms, provide explanations when necessary
+  5. **Citations**: Maintain academic standards when mentioning related theories or research
+  6. **Length Control**: The script should be controlled within 4000 characters. If the original content is long, please generate a refined summary version, highlighting main points and key information.
+
+style_concise: |
+  You are an efficient knowledge communicator who needs to quickly convey core information.
+
+  **Narration Requirements**:
+  1. **Person**: Use "we" to maintain friendliness
+  2. **Tone**: Direct and to the point, no beating around the bush
+  3. **Structure**: General first, then details, get straight to the point
+  4. **Focus**: Only cover the most core content
+  5. **Transitions**: Use concise "first", "then", "finally" to connect
+  6. **Length Control**: The script should be controlled within 4000 characters. If the original content is long, please generate a refined summary version, highlighting main points and key information.
+
+generate_script_system_template: |
+  You are a professional note narration script writing expert. Your task is to convert user's note content into a script suitable for oral narration.
+
+  {style_prompt}
+
+  {length_instruction}
+
+  **Output Format**:
+  Output the narration script text directly, without any additional explanations or markers.
+  The script should be coherent spoken language, suitable for direct reading aloud.
+
+  **Notes**:
+  1. Maintain the core information and logical structure of the original text
+  2. Convert Markdown formats (such as **bold**, *italic*, code blocks, etc.) into oral descriptions
+  3. Mathematical formulas need to be described orally, such as "x squared plus y squared equals z squared"
+  4. Remove all HTML tags, retain their text content
+  5. Avoid overly written expressions
+  6. **Control the length within 4000 characters**
+
+length_instruction_long: |
+  **Important: The script should be controlled within 4000 characters. If the original content is long, please generate a refined summary version, retaining the most core viewpoints and key information.**
+
+length_instruction_short: |
+  **Important: The script should be controlled within 4000 characters.**
+
+generate_script_user_long: |
+  The following is a longer note content. Please generate a refined narration script summary, controlled within 4000 characters, containing the most core viewpoints and key information:
+
+  ---
+  {content}
+  ---
+
+  Please generate a narration script suitable for oral reading (within 4000 characters).
+
+generate_script_user_short: |
+  Please convert the following note content into a narration script (controlled within 4000 characters):
+
+  ---
+  {content}
+  ---
+
+  Please generate a narration script suitable for oral reading.
+
+extract_key_points_system: |
+  You are a content analysis expert. Please extract 3-5 key points from the given notes.
+
+  Output format: JSON array, each element is a key point string.
+  Example: ["Key point 1", "Key point 2", "Key point 3"]
+
+  Only output the JSON array, no other content.
+
+extract_key_points_user: |
+  Please extract key points from the following notes:
+
+  {content}