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

scripts/sync_prompts_from_en.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+Semi-automatic sync of prompt structure from prompts/en to prompts/zh|prompts/cn.
+
+Behavior (safe by default):
+- Dry-run: prints what would be added
+- With --write: adds missing keys to zh/cn files without overwriting existing values
+- With --create-missing-files: creates missing zh/cn files using the en structure
+
+NOTE: This tool does NOT translate. It inserts TODO markers to be manually rewritten in Chinese.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+from typing import Any
+
+import yaml
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+AGENTS_DIR = PROJECT_ROOT / "src" / "agents"
+
+
+def _load_yaml(path: Path) -> Any:
+    with open(path, encoding="utf-8") as f:
+        return yaml.safe_load(f) or {}
+
+
+def _dump_yaml(path: Path, obj: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        yaml.safe_dump(obj, f, allow_unicode=True, sort_keys=False)
+
+
+def _merge_missing(en_obj: Any, zh_obj: Any) -> tuple[Any, int]:
+    """
+    Add missing keys from en_obj into zh_obj without overwriting existing zh content.
+    Returns (new_obj, added_count).
+    """
+    added = 0
+
+    if isinstance(en_obj, dict):
+        if not isinstance(zh_obj, dict):
+            zh_obj = {}
+        for k, v in en_obj.items():
+            if k not in zh_obj:
+                added += 1
+                if isinstance(v, str):
+                    zh_obj[k] = f"<<TODO_TRANSLATE>> {v}"
+                else:
+                    # For non-string nodes, insert scaffold recursively
+                    zh_obj[k], inc = _merge_missing(
+                        v, {} if isinstance(v, dict) else [] if isinstance(v, list) else None
+                    )
+                    added += inc
+            else:
+                zh_obj[k], inc = _merge_missing(v, zh_obj[k])
+                added += inc
+        return zh_obj, added
+
+    if isinstance(en_obj, list):
+        # Do not attempt to merge list structures; keep existing zh list.
+        return zh_obj, 0
+
+    # Primitive leaf: nothing to do
+    return zh_obj, 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--write", action="store_true", help="write changes to disk")
+    parser.add_argument(
+        "--create-missing-files",
+        action="store_true",
+        help="create missing zh/cn files from en structure with TODO markers",
+    )
+    parser.add_argument(
+        "--target",
+        choices=["zh", "cn", "both"],
+        default="both",
+        help="which target language directory to sync",
+    )
+    args = parser.parse_args()
+
+    if not AGENTS_DIR.exists():
+        print(f"Agents directory not found: {AGENTS_DIR}", file=sys.stderr)
+        return 2
+
+    total_added = 0
+    total_files = 0
+
+    for module_dir in sorted([p for p in AGENTS_DIR.iterdir() if p.is_dir()]):
+        prompts_dir = module_dir / "prompts"
+        en_dir = prompts_dir / "en"
+        if not en_dir.exists():
+            continue
+
+        targets: list[tuple[str, Path]] = []
+        if args.target in ("zh", "both"):
+            targets.append(("zh", prompts_dir / "zh"))
+        if args.target in ("cn", "both"):
+            targets.append(("cn", prompts_dir / "cn"))
+
+        en_files = [p for p in en_dir.rglob("*.yaml") if p.is_file()]
+        for en_file in sorted(en_files):
+            rel = en_file.relative_to(en_dir)
+            en_obj = _load_yaml(en_file)
+            for lang_name, lang_dir in targets:
+                zh_file = lang_dir / rel
+                if not zh_file.exists():
+                    if not args.create_missing_files:
+                        print(f"[MISSING {lang_name}] {module_dir.name}: {rel.as_posix()}")
+                        continue
+                    zh_obj = {}
+                else:
+                    zh_obj = _load_yaml(zh_file)
+
+                new_obj, added = _merge_missing(en_obj, zh_obj)
+                if added == 0:
+                    continue
+
+                total_added += added
+                total_files += 1
+                print(f"[SYNC {lang_name}] {module_dir.name}: {rel.as_posix()} (+{added} keys)")
+
+                if args.write:
+                    _dump_yaml(zh_file, new_obj)
+
+    if total_files == 0:
+        print("No changes needed.")
+        return 0
+
+    if args.write:
+        print(f"Updated {total_files} file(s), added {total_added} key(s).")
+    else:
+        print(
+            f"Dry-run: would update {total_files} file(s), add {total_added} key(s). Use --write to apply."
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/__init__.py

@@ -17,7 +17,7 @@ Core Modules:
 Usage:
     # Import as a package for integration with other services
     from src.api.main import app
-    
+
     # Or use individual modules
     from src.services.rag import RAGService
     from src.agents import ChatAgent
@@ -30,7 +30,7 @@ __package_name__ = "realtimex-deeptutor"
 # These are imported lazily to avoid circular imports and heavy startup
 __all__ = [
     "agents",
-    "api", 
+    "api",
     "services",
     "knowledge",
     "logging",

src/agents/ideagen/material_organizer_agent.py

@@ -25,6 +25,7 @@ class MaterialOrganizerAgent(BaseAgent):
         language: str = "en",
         api_key: str | None = None,
         base_url: str | None = None,
+        api_version: str | None = None,
         model: str | None = None,
     ):
         super().__init__(
@@ -32,6 +33,7 @@ class MaterialOrganizerAgent(BaseAgent):
             agent_name="material_organizer",
             api_key=api_key,
             base_url=base_url,
+            api_version=api_version,
             model=model,
             language=language,
         )

src/agents/solve/__init__.py

@@ -42,6 +42,9 @@ from .memory import (
     ToolCallRecord,
 )
 
+# Session management
+from .session_manager import SolverSessionManager, get_solver_session_manager
+
 # Solve loop
 from .solve_loop import (
     ManagerAgent,
@@ -77,4 +80,7 @@ __all__ = [
     "ToolAgent",
     # Main Controller
     "MainSolver",
+    # Session Management
+    "SolverSessionManager",
+    "get_solver_session_manager",
 ]

src/agents/solve/main_solver.py

@@ -43,6 +43,7 @@ class MainSolver:
         api_key: str | None = None,
         base_url: str | None = None,
         api_version: str | None = None,
+        language: str | None = None,
         kb_name: str = "ai_textbook",
         output_base_dir: str | None = None,
     ):
@@ -55,6 +56,7 @@ class MainSolver:
             api_key: API key (if not provided, read from environment)
             base_url: API URL (if not provided, read from environment)
             api_version: API version (if not provided, read from environment)
+            language: Preferred language for prompts ("en"/"zh"/"cn")
             kb_name: Knowledge base name
             output_base_dir: Output base directory (optional, overrides config)
         """
@@ -63,6 +65,7 @@ class MainSolver:
         self._api_key = api_key
         self._base_url = base_url
         self._api_version = api_version
+        self._language = language
         self._kb_name = kb_name
         self._output_base_dir = output_base_dir
 
@@ -108,6 +111,7 @@ class MainSolver:
         api_version = self._api_version
         kb_name = self._kb_name
         output_base_dir = self._output_base_dir
+        language = self._language
 
         # Load config from config directory (main.yaml unified config)
         if config_path is None:
@@ -156,6 +160,11 @@ class MainSolver:
         if self.config is None or not isinstance(self.config, dict):
             self.config = {}
 
+        # Override system language from UI if provided
+        if language:
+            self.config.setdefault("system", {})
+            self.config["system"]["language"] = parse_language(language)
+
         # Override output directory config
         if output_base_dir:
             if "system" not in self.config:

src/agents/solve/prompts/zh/analysis_loop/investigate_agent.yaml

@@ -11,18 +11,19 @@ system: |
   4. **聚焦核心**：只关注解题必须的"硬知识"（定义、公式、定理）。除非用户明确要求，否则不要查询应用案例或背景故事。
 
   # 工具使用指南
-  - `rag_naive`: **首选**。用于查询明确的术语定义、核心公式、或验证某个概念是否存在。速度快。
+  - `query_item`: **编号条目优先**。当用户问题中**明确提到具体编号条目**（例如“公式 2.1.2 / Equation (2.1.2)”、“定理 3.1 / Theorem 3.1”、“图 1.2 / Figure 1.2”）时，**必须优先使用该工具（ALWAYS use this first）**。请从问题中提取标识符并直接查询（常见格式：方程用 `(X.X.X)`，图用 `Figure X.X`，定理用 `Theorem X.X`）。这是检索编号内容最直接、最准确的方式。
+  - `rag_naive`: **通用查询首选**。用于查询明确的术语定义、核心公式，或验证某个概念是否存在。速度快。
   - `rag_hybrid`: 用于需要综合多个概念、探究复杂实体关系或深层原理的场景。
   - `web_search`: **慎用**。仅当信息极有可能超出教材范围（如最新新闻、特定技术参数、开源库用法）时使用。
-  - `query_item`: **专用**。仅当你明确知道需要获取某个特定编号（如 "Fig 1.2", "Theorem 3.1"）的内容时使用。
   - `none`: 当现有信息足以支撑解题，或缺口无法通过检索填补（如需要用户提供）时，返回此状态。
 
   # 思考路径
-  1. **解析需求**：解题真正缺的是什么？是某个变量的定义？是某个定理的公式？还是某个常数的数值？
-  2. **核查存量**：查看`已有查询内容`。答案是否已经存在？或者是否隐含在已知信息中？
-  3. **构建查询**：如果确有缺口，构建原子化的、互不重叠的查询请求。
-  4. **判断终止**：如果核心定义和公式都已齐备，果断停止。
-  5. **及时止损**：如果某话题的第一轮查询没有返回有用信息（结果为空、不相关或质量低），说明知识库中可能没有相关内容，应该放弃该话题，换其他话题，或直接进入下一阶段。不要对同一个话题反复查询。
+  1. **识别编号条目**：**首先扫描用户问题中是否存在明确的编号引用**（例如“公式 2.1.2 / Equation (2.1.2)”、“定理 3.1 / Theorem 3.1”、“图 1.2 / Figure 1.2”）。若存在，提取标识符并立即使用 `query_item`。编号条目优先于语义检索。
+  2. **解析需求**：解题真正缺的是什么？是某个变量的定义？是某个定理的公式？还是某个常数的数值？
+  3. **核查存量**：查看`已有查询内容`。答案是否已经存在？或者是否隐含在已知信息中？
+  4. **构建查询**：如果确有缺口，构建原子化的、互不重叠的查询请求。
+  5. **判断终止**：如果核心定义和公式都已齐备，果断停止。
+  6. **⚠️ 关键 - 及时止损（Know When to Cut Losses）**：如果某话题的第一轮查询没有返回有用信息（结果为空、不相关或质量低），通常意味着知识库不包含相关内容。**你必须立即放弃该话题**，改查其他话题，或直接进入下一阶段。**不要对同一个话题反复查询**——这会浪费资源并拖慢解题。
 
   # 输出格式
   直接输出 JSON 对象（无 Markdown 格式）：
@@ -46,6 +47,7 @@ user_template: |
 
   ## 任务
   分析是否存在阻碍解题的知识缺口。
+  - **编号条目优先**：若问题提到具体编号条目（公式/定理/图/方程编号如“2.1.2”“3.1”等），**立即使用 `query_item`** 并传入提取的标识符（例如方程用 `(2.1.2)`，图用 `Figure 2.1`）。
   - 检查重复：新查询不得与已有内容重叠。
   - 灵活决策：如果前序工具查询出错，考虑通过其他工具来达到相同的目的。
   - 及时止损：如果某话题的第一轮查询没有返回有用信息，不要反复查询该话题，应该换其他话题或进入下一阶段。

src/agents/solve/session_manager.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python
+"""
+SolverSessionManager - Solver session persistence and management.
+
+This module handles:
+- Creating new solver sessions
+- Updating sessions with new messages
+- Retrieving session history
+- Listing recent sessions
+- Deleting sessions
+"""
+
+import json
+from pathlib import Path
+import time
+from typing import Any
+import uuid
+
+
+class SolverSessionManager:
+    """
+    Manages persistent storage of solver sessions.
+
+    Sessions are stored in a JSON file at data/user/solver_sessions.json.
+    Each session contains:
+    - session_id: Unique identifier
+    - title: Session title (usually first user question)
+    - messages: List of messages with role, content, outputDir, timestamp
+    - kb_name: Knowledge base used
+    - token_stats: Cost and token usage statistics
+    - created_at: Creation timestamp
+    - updated_at: Last update timestamp
+    """
+
+    def __init__(self, base_dir: str | None = None):
+        """
+        Initialize SolverSessionManager.
+
+        Args:
+            base_dir: Base directory for session storage.
+                     Defaults to project_root/data/user
+        """
+        if base_dir is None:
+            # Current file: src/agents/solve/session_manager.py
+            # Project root: 4 levels up
+            project_root = Path(__file__).resolve().parents[3]
+            base_dir_path = project_root / "data" / "user"
+        else:
+            base_dir_path = Path(base_dir)
+
+        self.base_dir = base_dir_path
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+
+        self.sessions_file = self.base_dir / "solver_sessions.json"
+        self._ensure_file()
+
+    def _ensure_file(self):
+        """Ensure the sessions file exists with correct format."""
+        if not self.sessions_file.exists():
+            initial_data = {
+                "version": "1.0",
+                "sessions": [],
+            }
+            self._save_data(initial_data)
+
+    def _load_data(self) -> dict[str, Any]:
+        """Load sessions data from file."""
+        try:
+            with open(self.sessions_file, encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, FileNotFoundError):
+            return {"version": "1.0", "sessions": []}
+
+    def _save_data(self, data: dict[str, Any]):
+        """Save sessions data to file."""
+        with open(self.sessions_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+    def _get_sessions(self) -> list[dict[str, Any]]:
+        """Get list of all sessions."""
+        data = self._load_data()
+        return data.get("sessions", [])
+
+    def _save_sessions(self, sessions: list[dict[str, Any]]):
+        """Save sessions list."""
+        data = self._load_data()
+        data["sessions"] = sessions
+        self._save_data(data)
+
+    def create_session(
+        self,
+        title: str = "New Solver Session",
+        kb_name: str = "",
+        token_stats: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Create a new solver session.
+
+        Args:
+            title: Session title
+            kb_name: Knowledge base name
+            token_stats: Optional token usage statistics
+
+        Returns:
+            New session dict with session_id
+        """
+        session_id = f"solver_{int(time.time() * 1000)}_{uuid.uuid4().hex[:8]}"
+        now = time.time()
+
+        session = {
+            "session_id": session_id,
+            "title": title[:100],  # Limit title length
+            "messages": [],
+            "kb_name": kb_name,
+            "token_stats": token_stats
+            or {
+                "model": "Unknown",
+                "calls": 0,
+                "tokens": 0,
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "cost": 0.0,
+            },
+            "created_at": now,
+            "updated_at": now,
+        }
+
+        sessions = self._get_sessions()
+        sessions.insert(0, session)  # Add to front (newest first)
+
+        # Limit total sessions to prevent file bloat
+        max_sessions = 100
+        if len(sessions) > max_sessions:
+            sessions = sessions[:max_sessions]
+
+        self._save_sessions(sessions)
+
+        return session
+
+    def get_session(self, session_id: str) -> dict[str, Any] | None:
+        """
+        Get a session by ID.
+
+        Args:
+            session_id: Session identifier
+
+        Returns:
+            Session dict or None if not found
+        """
+        sessions = self._get_sessions()
+        for session in sessions:
+            if session.get("session_id") == session_id:
+                return session
+        return None
+
+    def update_session(
+        self,
+        session_id: str,
+        messages: list[dict[str, Any]] | None = None,
+        title: str | None = None,
+        kb_name: str | None = None,
+        token_stats: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | None:
+        """
+        Update a session with new data.
+
+        Args:
+            session_id: Session identifier
+            messages: New messages list (replaces existing)
+            title: New title (optional)
+            kb_name: New knowledge base name (optional)
+            token_stats: New token stats (optional)
+
+        Returns:
+            Updated session or None if not found
+        """
+        sessions = self._get_sessions()
+
+        for i, session in enumerate(sessions):
+            if session.get("session_id") == session_id:
+                if messages is not None:
+                    session["messages"] = messages
+                if title is not None:
+                    session["title"] = title[:100]
+                if kb_name is not None:
+                    session["kb_name"] = kb_name
+                if token_stats is not None:
+                    session["token_stats"] = token_stats
+
+                session["updated_at"] = time.time()
+
+                # Move to front (most recently updated)
+                sessions.pop(i)
+                sessions.insert(0, session)
+
+                self._save_sessions(sessions)
+                return session
+
+        return None
+
+    def add_message(
+        self,
+        session_id: str,
+        role: str,
+        content: str,
+        output_dir: str | None = None,
+    ) -> dict[str, Any] | None:
+        """
+        Add a single message to a session.
+
+        Args:
+            session_id: Session identifier
+            role: Message role ('user' or 'assistant')
+            content: Message content
+            output_dir: Optional output directory (for assistant messages)
+
+        Returns:
+            Updated session or None if not found
+        """
+        session = self.get_session(session_id)
+        if not session:
+            return None
+
+        message = {
+            "role": role,
+            "content": content,
+            "timestamp": time.time(),
+        }
+        if output_dir:
+            message["output_dir"] = output_dir
+
+        messages = session.get("messages", [])
+        messages.append(message)
+
+        # Update title from first user message if still default
+        if session.get("title") == "New Solver Session" and role == "user":
+            new_title = content[:50] + ("..." if len(content) > 50 else "")
+            return self.update_session(session_id, messages=messages, title=new_title)
+
+        return self.update_session(session_id, messages=messages)
+
+    def update_token_stats(
+        self,
+        session_id: str,
+        token_stats: dict[str, Any],
+    ) -> dict[str, Any] | None:
+        """
+        Update token stats for a session.
+
+        Args:
+            session_id: Session identifier
+            token_stats: Token usage statistics
+
+        Returns:
+            Updated session or None if not found
+        """
+        return self.update_session(session_id, token_stats=token_stats)
+
+    def list_sessions(
+        self,
+        limit: int = 20,
+        include_messages: bool = False,
+    ) -> list[dict[str, Any]]:
+        """
+        List recent sessions.
+
+        Args:
+            limit: Maximum number of sessions to return
+            include_messages: Whether to include full message history
+
+        Returns:
+            List of session dicts (newest first)
+        """
+        sessions = self._get_sessions()[:limit]
+
+        if not include_messages:
+            # Return summary only (without full messages)
+            return [
+                {
+                    "session_id": s.get("session_id"),
+                    "title": s.get("title"),
+                    "message_count": len(s.get("messages", [])),
+                    "kb_name": s.get("kb_name"),
+                    "token_stats": s.get("token_stats"),
+                    "created_at": s.get("created_at"),
+                    "updated_at": s.get("updated_at"),
+                    # Include preview of last message
+                    "last_message": (
+                        s.get("messages", [])[-1].get("content", "")[:100]
+                        if s.get("messages")
+                        else ""
+                    ),
+                }
+                for s in sessions
+            ]
+
+        return sessions
+
+    def delete_session(self, session_id: str) -> bool:
+        """
+        Delete a session.
+
+        Args:
+            session_id: Session identifier
+
+        Returns:
+            True if deleted, False if not found
+        """
+        sessions = self._get_sessions()
+        original_count = len(sessions)
+
+        sessions = [s for s in sessions if s.get("session_id") != session_id]
+
+        if len(sessions) < original_count:
+            self._save_sessions(sessions)
+            return True
+
+        return False
+
+    def clear_all_sessions(self) -> int:
+        """
+        Delete all sessions.
+
+        Returns:
+            Number of sessions deleted
+        """
+        sessions = self._get_sessions()
+        count = len(sessions)
+        self._save_sessions([])
+        return count
+
+
+# Singleton instance for convenience
+_solver_session_manager: SolverSessionManager | None = None
+
+
+def get_solver_session_manager() -> SolverSessionManager:
+    """Get or create the global SolverSessionManager instance."""
+    global _solver_session_manager
+    if _solver_session_manager is None:
+        _solver_session_manager = SolverSessionManager()
+    return _solver_session_manager
+
+
+__all__ = ["SolverSessionManager", "get_solver_session_manager"]

src/api/main.py

@@ -16,6 +16,7 @@ from src.api.routers import (
     knowledge,
     notebook,
     question,
+    realtimex,
     research,
     settings,
     solve,
@@ -23,6 +24,7 @@ from src.api.routers import (
 )
 from src.logging import get_logger
 
+# Note: Don't set service_prefix here - start_web.py already adds [Backend] prefix
 logger = get_logger("API")
 
 CONFIG_DRIFT_ERROR_TEMPLATE = (
@@ -130,6 +132,17 @@ async def lifespan(app: FastAPI):
     # Validate configuration consistency
     validate_tool_consistency()
 
+    # Initialize LLM client early to set environment variables for LightRAG
+    # LightRAG reads OPENAI_API_KEY from os.environ internally, so we must
+    # set it before any RAG operations can happen
+    try:
+        from src.services.llm import get_llm_client
+
+        llm_client = get_llm_client()
+        logger.info(f"LLM client initialized: model={llm_client.config.model}")
+    except Exception as e:
+        logger.warning(f"Failed to initialize LLM client at startup: {e}")
+
     yield
     # Execute on shutdown
     logger.info("Application shutdown")
@@ -189,6 +202,7 @@ app.include_router(settings.router, prefix="/api/v1/settings", tags=["settings"]
 app.include_router(system.router, prefix="/api/v1/system", tags=["system"])
 app.include_router(config.router, prefix="/api/v1/config", tags=["config"])
 app.include_router(agent_config.router, prefix="/api/v1/agent-config", tags=["agent-config"])
+app.include_router(realtimex.router, prefix="/api/v1", tags=["realtimex"])
 
 
 @app.get("/")

src/api/routers/chat.py

@@ -18,6 +18,7 @@ from src.agents.chat import ChatAgent, SessionManager
 from src.logging import get_logger
 from src.services.config import load_config_with_main
 from src.services.llm.config import get_llm_config
+from src.services.settings.interface_settings import get_ui_language
 
 # Initialize logger
 project_root = Path(__file__).parent.parent.parent.parent
@@ -113,13 +114,12 @@ async def websocket_chat(websocket: WebSocket):
     """
     await websocket.accept()
 
-    # Get system language for agent
-    language = config.get("system", {}).get("language", "en")
-
     try:
         while True:
             # Receive message
             data = await websocket.receive_json()
+            # Use current UI language (fallback to config/main.yaml system.language)
+            language = get_ui_language(default=config.get("system", {}).get("language", "en"))
             message = data.get("message", "").strip()
             session_id = data.get("session_id")
             explicit_history = data.get("history")  # Optional override