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

src/api/main.py

@@ -0,0 +1,240 @@
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from src.api.routers import (
+    agent_config,
+    chat,
+    co_writer,
+    config,
+    dashboard,
+    guide,
+    ideagen,
+    knowledge,
+    notebook,
+    question,
+    research,
+    settings,
+    solve,
+    system,
+)
+from src.logging import get_logger
+
+logger = get_logger("API")
+
+CONFIG_DRIFT_ERROR_TEMPLATE = (
+    "Configuration Drift Detected: Tools {drift} found in agents.yaml "
+    "investigate.valid_tools but missing from main.yaml solve.valid_tools. "
+    "Add these tools to main.yaml solve.valid_tools or remove them from "
+    "agents.yaml investigate.valid_tools."
+)
+
+
+def validate_tool_consistency():
+    """
+    Validate that the tools configured for agents are consistent with the main application
+    configuration.
+
+    This function loads the main configuration (``main.yaml``) and the agents configuration
+    (``agents.yaml``) from the project root and compares:
+
+    * ``solve.valid_tools`` in ``main.yaml``
+    * ``investigate.valid_tools`` in ``agents.yaml``
+
+    All tools referenced by agents must be present in the main configuration. If any tools are
+    defined for agents that are not listed in the main configuration, a ``RuntimeError`` is
+    raised describing the drift. The error is logged and re-raised, which causes the FastAPI
+    application startup to fail when this function is called from the ``lifespan`` handler.
+
+    Impact on startup
+    ------------------
+    This validation runs during application startup. Any configuration drift will:
+
+    * Be logged as an error with details about the unknown tools.
+    * Prevent the API from starting until the configuration is corrected.
+
+    How to resolve configuration drift
+    ----------------------------------
+    If startup fails with a configuration drift error:
+
+    1. Inspect the set of tools reported in the error message.
+    2. Either:
+       * Add the missing tools to ``solve.valid_tools`` in ``main.yaml``, **or**
+       * Remove or rename the offending tools from ``investigate.valid_tools`` in ``agents.yaml``.
+    3. Restart the application after updating the configuration files.
+
+    Example of aligned configuration
+    --------------------------------
+    ``main.yaml``::
+
+        solve:
+          valid_tools:
+            - web_search
+            - code_execution
+
+    ``agents.yaml``::
+
+        investigate:
+          valid_tools:
+            - web_search
+
+    In this case, validation passes because ``investigate.valid_tools`` is a subset of
+    ``solve.valid_tools``.
+
+    Example of configuration drift
+    ------------------------------
+    ``agents.yaml``::
+
+        investigate:
+          valid_tools:
+            - web_search
+            - unknown_tool
+
+    Here, ``unknown_tool`` is not present in ``solve.valid_tools`` in ``main.yaml``, so
+    validation will fail and prevent the application from starting until the configurations
+    are aligned.
+    """
+    try:
+        from src.services.config import load_config_with_main
+
+        project_root = Path(__file__).parent.parent.parent
+        main_config = load_config_with_main("main.yaml", project_root)
+        agent_config_data = load_config_with_main("agents.yaml", project_root)
+
+        main_tools = set(main_config.get("solve", {}).get("valid_tools", []))
+        agent_tools = set(agent_config_data.get("investigate", {}).get("valid_tools", []))
+
+        if not agent_tools.issubset(main_tools):
+            drift = agent_tools - main_tools
+            raise RuntimeError(CONFIG_DRIFT_ERROR_TEMPLATE.format(drift=drift))
+    except RuntimeError:
+        logger.exception("Configuration validation failed")
+        raise
+    except Exception:
+        logger.exception("Failed to load configuration for validation")
+        raise
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Application lifecycle management
+    Gracefully handle startup and shutdown events, avoid CancelledError
+    """
+    # Execute on startup
+    logger.info("Application startup")
+
+    # Validate configuration consistency
+    validate_tool_consistency()
+
+    yield
+    # Execute on shutdown
+    logger.info("Application shutdown")
+
+
+app = FastAPI(
+    title="DeepTutor API",
+    version="1.0.0",
+    lifespan=lifespan,
+    # Disable automatic trailing slash redirects to prevent protocol downgrade issues
+    # when deployed behind HTTPS reverse proxies (e.g., nginx).
+    # Without this, FastAPI's 307 redirects may change HTTPS to HTTP.
+    # See: https://github.com/HKUDS/DeepTutor/issues/112
+    redirect_slashes=False,
+)
+
+# Configure CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # In production, replace with specific frontend origin
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Mount user directory as static root for generated artifacts
+# This allows frontend to access generated artifacts (images, PDFs, etc.)
+# URL: /api/outputs/solve/solve_xxx/artifacts/image.png
+# Physical Path: DeepTutor/data/user/solve/solve_xxx/artifacts/image.png
+project_root = Path(__file__).parent.parent.parent
+user_dir = project_root / "data" / "user"
+
+# Initialize user directories on startup
+try:
+    from src.services.setup import init_user_directories
+
+    init_user_directories(project_root)
+except Exception:
+    # Fallback: just create the main directory if it doesn't exist
+    if not user_dir.exists():
+        user_dir.mkdir(parents=True)
+
+app.mount("/api/outputs", StaticFiles(directory=str(user_dir)), name="outputs")
+
+# Include routers
+app.include_router(solve.router, prefix="/api/v1", tags=["solve"])
+app.include_router(chat.router, prefix="/api/v1", tags=["chat"])
+app.include_router(question.router, prefix="/api/v1/question", tags=["question"])
+app.include_router(research.router, prefix="/api/v1/research", tags=["research"])
+app.include_router(knowledge.router, prefix="/api/v1/knowledge", tags=["knowledge"])
+app.include_router(dashboard.router, prefix="/api/v1/dashboard", tags=["dashboard"])
+app.include_router(co_writer.router, prefix="/api/v1/co_writer", tags=["co_writer"])
+app.include_router(notebook.router, prefix="/api/v1/notebook", tags=["notebook"])
+app.include_router(guide.router, prefix="/api/v1/guide", tags=["guide"])
+app.include_router(ideagen.router, prefix="/api/v1/ideagen", tags=["ideagen"])
+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.get("/")
+async def root():
+    return {"message": "Welcome to DeepTutor API"}
+
+
+if __name__ == "__main__":
+    from pathlib import Path
+
+    import uvicorn
+
+    # Get project root directory
+    project_root = Path(__file__).parent.parent.parent
+
+    # Ensure project root is in Python path
+    import sys
+
+    if str(project_root) not in sys.path:
+        sys.path.insert(0, str(project_root))
+
+    # Get port from configuration
+    from src.services.setup import get_backend_port
+
+    backend_port = get_backend_port(project_root)
+
+    # Configure reload_excludes with absolute paths to properly exclude directories
+    venv_dir = project_root / "venv"
+    data_dir = project_root / "data"
+    reload_excludes = [
+        str(d)
+        for d in [
+            venv_dir,
+            project_root / ".venv",
+            data_dir,
+            project_root / "web" / "node_modules",
+            project_root / "web" / ".next",
+            project_root / ".git",
+        ]
+        if d.exists()
+    ]
+
+    uvicorn.run(
+        "api.main:app",
+        host="0.0.0.0",
+        port=backend_port,
+        reload=True,
+        reload_excludes=reload_excludes,
+    )

src/api/routers/__init__.py

@@ -0,0 +1 @@
+# Init file for routers

src/api/routers/agent_config.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python
+"""
+Agent Configuration API - Provides agent metadata for data-driven UI.
+"""
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# Agent registry - single source of truth for agent UI metadata
+AGENT_REGISTRY = {
+    "solve": {
+        "icon": "HelpCircle",
+        "color": "blue",
+        "label_key": "Problem Solved",
+    },
+    "question": {
+        "icon": "FileText",
+        "color": "purple",
+        "label_key": "Question Generated",
+    },
+    "research": {
+        "icon": "Search",
+        "color": "emerald",
+        "label_key": "Research Report",
+    },
+    "co_writer": {
+        "icon": "PenTool",
+        "color": "amber",
+        "label_key": "Co-Writer",
+    },
+    "guide": {
+        "icon": "BookOpen",
+        "color": "indigo",
+        "label_key": "Guided Learning",
+    },
+    "ideagen": {
+        "icon": "Lightbulb",
+        "color": "yellow",
+        "label_key": "Idea Generated",
+    },
+}
+
+
+@router.get("/agents")
+async def get_agent_config():
+    """
+    Get agent UI configuration.
+
+    Returns:
+        Dict mapping agent type to UI metadata (icon, color, label_key)
+    """
+    return AGENT_REGISTRY
+
+
+@router.get("/agents/{agent_type}")
+async def get_single_agent_config(agent_type: str):
+    """
+    Get UI configuration for a specific agent.
+
+    Args:
+        agent_type: Agent type (solve, question, research, etc.)
+
+    Returns:
+        Agent UI metadata or 404 if not found
+    """
+    if agent_type in AGENT_REGISTRY:
+        return AGENT_REGISTRY[agent_type]
+    return {"error": f"Agent type '{agent_type}' not found"}

src/api/routers/chat.py

@@ -0,0 +1,296 @@
+"""
+Chat API Router
+================
+
+WebSocket endpoint for lightweight chat with session management.
+REST endpoints for session operations.
+"""
+
+from pathlib import Path
+import sys
+
+from fastapi import APIRouter, HTTPException, WebSocket, WebSocketDisconnect
+
+_project_root = Path(__file__).parent.parent.parent.parent
+sys.path.insert(0, str(_project_root))
+
+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
+
+# Initialize logger
+project_root = Path(__file__).parent.parent.parent.parent
+config = load_config_with_main("solve_config.yaml", project_root)
+log_dir = config.get("paths", {}).get("user_log_dir") or config.get("logging", {}).get("log_dir")
+logger = get_logger("ChatAPI", level="INFO", log_dir=log_dir)
+
+router = APIRouter()
+
+# Initialize session manager
+session_manager = SessionManager()
+
+
+# =============================================================================
+# REST Endpoints for Session Management
+# =============================================================================
+
+
+@router.get("/chat/sessions")
+async def list_sessions(limit: int = 20):
+    """
+    List recent chat sessions.
+
+    Args:
+        limit: Maximum number of sessions to return
+
+    Returns:
+        List of session summaries
+    """
+    return session_manager.list_sessions(limit=limit, include_messages=False)
+
+
+@router.get("/chat/sessions/{session_id}")
+async def get_session(session_id: str):
+    """
+    Get a specific chat session with full message history.
+
+    Args:
+        session_id: Session identifier
+
+    Returns:
+        Complete session data including messages
+    """
+    session = session_manager.get_session(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return session
+
+
+@router.delete("/chat/sessions/{session_id}")
+async def delete_session(session_id: str):
+    """
+    Delete a chat session.
+
+    Args:
+        session_id: Session identifier
+
+    Returns:
+        Success message
+    """
+    if session_manager.delete_session(session_id):
+        return {"status": "deleted", "session_id": session_id}
+    raise HTTPException(status_code=404, detail="Session not found")
+
+
+# =============================================================================
+# WebSocket Endpoint for Chat
+# =============================================================================
+
+
+@router.websocket("/chat")
+async def websocket_chat(websocket: WebSocket):
+    """
+    WebSocket endpoint for chat with session and context management.
+
+    Message format:
+    {
+        "message": str,              # User message
+        "session_id": str | null,    # Session ID (null for new session)
+        "history": [...] | null,     # Optional: explicit history override
+        "kb_name": str,              # Knowledge base name (for RAG)
+        "enable_rag": bool,          # Enable RAG retrieval
+        "enable_web_search": bool    # Enable Web Search
+    }
+
+    Response format:
+    - {"type": "session", "session_id": str}           # Session ID (new or existing)
+    - {"type": "status", "stage": str, "message": str} # Status updates
+    - {"type": "stream", "content": str}               # Streaming response chunks
+    - {"type": "sources", "rag": list, "web": list}    # Source citations
+    - {"type": "result", "content": str}               # Final complete response
+    - {"type": "error", "message": str}                # Error message
+    """
+    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()
+            message = data.get("message", "").strip()
+            session_id = data.get("session_id")
+            explicit_history = data.get("history")  # Optional override
+            kb_name = data.get("kb_name", "")
+            enable_rag = data.get("enable_rag", False)
+            enable_web_search = data.get("enable_web_search", False)
+
+            if not message:
+                await websocket.send_json({"type": "error", "message": "Message is required"})
+                continue
+
+            logger.info(
+                f"Chat request: session={session_id}, "
+                f"message={message[:50]}..., rag={enable_rag}, web={enable_web_search}"
+            )
+
+            try:
+                # Get or create session
+                if session_id:
+                    session = session_manager.get_session(session_id)
+                    if not session:
+                        # Session not found, create new one
+                        session = session_manager.create_session(
+                            title=message[:50] + ("..." if len(message) > 50 else ""),
+                            settings={
+                                "kb_name": kb_name,
+                                "enable_rag": enable_rag,
+                                "enable_web_search": enable_web_search,
+                            },
+                        )
+                        session_id = session["session_id"]
+                else:
+                    # Create new session
+                    session = session_manager.create_session(
+                        title=message[:50] + ("..." if len(message) > 50 else ""),
+                        settings={
+                            "kb_name": kb_name,
+                            "enable_rag": enable_rag,
+                            "enable_web_search": enable_web_search,
+                        },
+                    )
+                    session_id = session["session_id"]
+
+                # Send session ID to frontend
+                await websocket.send_json(
+                    {
+                        "type": "session",
+                        "session_id": session_id,
+                    }
+                )
+
+                # Build history from session or explicit override
+                if explicit_history is not None:
+                    history = explicit_history
+                else:
+                    # Get history from session messages
+                    history = [
+                        {"role": msg["role"], "content": msg["content"]}
+                        for msg in session.get("messages", [])
+                    ]
+
+                # Add user message to session
+                session_manager.add_message(
+                    session_id=session_id,
+                    role="user",
+                    content=message,
+                )
+
+                # Initialize ChatAgent
+                try:
+                    llm_config = get_llm_config()
+                    api_key = llm_config.api_key
+                    base_url = llm_config.base_url
+                    api_version = getattr(llm_config, "api_version", None)
+                except Exception:
+                    api_key = None
+                    base_url = None
+                    api_version = None
+
+                agent = ChatAgent(
+                    language=language,
+                    config=config,
+                    api_key=api_key,
+                    base_url=base_url,
+                    api_version=api_version,
+                )
+
+                # Send status updates
+                if enable_rag and kb_name:
+                    await websocket.send_json(
+                        {
+                            "type": "status",
+                            "stage": "rag",
+                            "message": f"Searching knowledge base: {kb_name}...",
+                        }
+                    )
+
+                if enable_web_search:
+                    await websocket.send_json(
+                        {
+                            "type": "status",
+                            "stage": "web",
+                            "message": "Searching the web...",
+                        }
+                    )
+
+                await websocket.send_json(
+                    {
+                        "type": "status",
+                        "stage": "generating",
+                        "message": "Generating response...",
+                    }
+                )
+
+                # Process with streaming
+                full_response = ""
+                sources = {"rag": [], "web": []}
+
+                stream_generator = await agent.process(
+                    message=message,
+                    history=history,
+                    kb_name=kb_name,
+                    enable_rag=enable_rag,
+                    enable_web_search=enable_web_search,
+                    stream=True,
+                )
+
+                async for chunk_data in stream_generator:
+                    if chunk_data["type"] == "chunk":
+                        await websocket.send_json(
+                            {
+                                "type": "stream",
+                                "content": chunk_data["content"],
+                            }
+                        )
+                        full_response += chunk_data["content"]
+                    elif chunk_data["type"] == "complete":
+                        full_response = chunk_data["response"]
+                        sources = chunk_data.get("sources", {"rag": [], "web": []})
+
+                # Send sources if any
+                if sources.get("rag") or sources.get("web"):
+                    await websocket.send_json({"type": "sources", **sources})
+
+                # Send final result
+                await websocket.send_json(
+                    {
+                        "type": "result",
+                        "content": full_response,
+                    }
+                )
+
+                # Save assistant message to session
+                session_manager.add_message(
+                    session_id=session_id,
+                    role="assistant",
+                    content=full_response,
+                    sources=sources if (sources.get("rag") or sources.get("web")) else None,
+                )
+
+                logger.info(f"Chat completed: session={session_id}, {len(full_response)} chars")
+
+            except Exception as e:
+                logger.error(f"Chat processing error: {e}")
+                await websocket.send_json({"type": "error", "message": str(e)})
+
+    except WebSocketDisconnect:
+        logger.debug("Client disconnected from chat")
+    except Exception as e:
+        logger.error(f"WebSocket error: {e}")
+        try:
+            await websocket.send_json({"type": "error", "message": str(e)})
+        except Exception:
+            pass