DeepTutor: AI-Powered Personalized Learning Assistant

Quick Start · Core Modules · FAQ

🇨🇳 中文 · 🇯🇵 日本語 · 🇪🇸 Español · 🇫🇷 Français · 🇸🇦 العربية · 🇷🇺 Русский · 🇮🇳 हिन्दी · 🇵🇹 Português

📚 Massive Document Knowledge Q&A • 🎨 Interactive Learning Visualization
🎯 Knowledge Reinforcement • 🔍 Deep Research & Idea Generation

📰 News

[2026.1.15] DeepTutor v0.5.0 is out! Fixed multiple environment configuration and stability issues. We recommend everyone to pull the latest version! 🎉

[2026.1.1] Happy New Year! Join our Discord Community, Wechat Community, or Discussions - shape the future of DeepTutor! 💬

[2025.12.30] Visit our Official Website for more details!

[2025.12.29] DeepTutor is now live! ✨

📦 Releases

[2026.1.15] Release v0.5.0 - Unified LLM & Embedding services, RAG pipeline selection, and major enhancements to Home, History, QuestionGen & Settings modules -- Thanks to all the contributors!

History releases

[2026.1.9] Release v0.4.1 with LLM Provider system overhaul, Question Generation robustness improvements, and codebase cleanup - Thanks to all the contributors!

[2026.1.9] Release v0.4.0 with new code structure, multiple llm & embeddings support - Thanks to all the contributors!

[2026.1.5] v0.3.0 - Unified PromptManager architecture, CI/CD automation & pre-built Docker images on GHCR

[2026.1.2] v0.2.0 - Docker deployment, Next.js 16 & React 19 upgrade, WebSocket security & critical vulnerability fixes

Key Features of DeepTutor

📚 Massive Document Knowledge Q&A

• Smart Knowledge Base: Upload textbooks, research papers, technical manuals, and domain-specific documents. Build a comprehensive AI-powered knowledge repository for instant access.
• Multi-Agent Problem Solving: Dual-loop reasoning architecture with RAG, web search, and code execution -- delivering step-by-step solutions with precise citations.

🎨 Interactive Learning Visualization

• Knowledge Simplification & Explanations: Transform complex concepts, knowledge, and algorithms into easy-to-understand visual aids, detailed step-by-step breakdowns, and engaging interactive demonstrations.
• Personalized Q&A: Context-aware conversations that adapt to your learning progress, with interactive pages and session-based knowledge tracking.

🎯 Knowledge Reinforcement with Practice Exercise Generator

• Intelligent Exercise Creation: Generate targeted quizzes, practice problems, and customized assessments tailored to your current knowledge level and specific learning objectives.
• Authentic Exam Simulation: Upload reference exams to generate practice questions that perfectly match the original style, format, and difficulty—giving you realistic preparation for the actual test.

🔍 Deep Research & Idea Generation

• Comprehensive Research & Literature Review: Conduct in-depth topic exploration with systematic analysis. Identify patterns, connect related concepts across disciplines, and synthesize existing research findings.
• Novel Insight Discovery: Generate structured learning materials and uncover knowledge gaps. Identify promising new research directions through intelligent cross-domain knowledge synthesis.

📚 Massive Document Knowledge Q&A

_{Multi-agent Problem Solving with Exact Citations}

🎨 Interactive Learning Visualization

_{Step-by-step Visual Explanations with Personal QAs.}

🎯 Knowledge Reinforcement

Custom Questions
_{Auto-Validated Practice Questions Generation}

Mimic Questions
_{Clone Exam Style for Authentic Practice}

🔍 Deep Research & Idea Generation

Deep Research
_{Knowledge Extension from Textbook with RAG, Web and Paper-search}

Automated IdeaGen
_{Brainstorming and Concept Synthesis with Dual-filter Workflow}

Interactive IdeaGen
_{RAG and Web-search Powered Co-writer with Podcast Generation}

🏗️ All-in-One Knowledge System

Personal Knowledge Base
_{Build and Organize Your Own Knowledge Repository}

Personal Notebook
_{Your Contextual Memory for Learning Sessions}

_{🌙 Use DeepTutor in Dark Mode!}

🏛️ DeepTutor's Framework

💬 User Interface Layer

• Intuitive Interaction: Simple bidirectional query-response flow for intuitive interaction.
• Structured Output: Structured response generation that organizes complex information into actionable outputs.

🤖 Intelligent Agent Modules

• Problem Solving & Assessment: Step-by-step problem solving and custom assessment generation.
• Research & Learning: Deep Research for topic exploration and Guided Learning with visualization.
• Idea Generation: Automated and interactive concept development with multi-source insights.

🔧 Tool Integration Layer

• Information Retrieval: RAG hybrid retrieval, real-time web search, and academic paper databases.
• Processing & Analysis: Python code execution, query item lookup, and PDF parsing for document analysis.

🧠 Knowledge & Memory Foundation

• Knowledge Graph: Entity-relation mapping for semantic connections and knowledge discovery.
• Vector Store: Embedding-based semantic search for intelligent content retrieval.
• Memory System: Session state management and citation tracking for contextual continuity.

📋 Todo

🌟 Star to follow our future updates!

[ x ] Multi-linguistic support
[ x ] DeepTutor Community
[ x ] Video & Audio file support
[ x ] Atomic RAG pipeline customize
[ - ] Incremental Knowledge-base Edit
[ - ] Personalized Workspace
[ - ] DataBase Visualization
[ - ] Online Demo

🚀 Getting Started

Step 1: Pre-Configuration

① Clone Repository

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

② Set Up Environment Variables

cp .env.example .env
# Edit .env file with your API keys

📋 Environment Variables Reference

Variable	Required	Description
`LLM_MODEL`	Yes	Model name (e.g., `gpt-4o`)
`LLM_API_VERSION`	No	API version for Azure OpenAI (e.g., `2024-02-15-preview`)
`LLM_API_KEY`	Yes	Your LLM API key
`LLM_HOST`	Yes	API endpoint URL
`EMBEDDING_MODEL`	Yes	Embedding model name
`EMBEDDING_API_VERSION`	No	API version for Azure OpenAI Embeddings
`EMBEDDING_API_KEY`	Yes	Embedding API key
`EMBEDDING_HOST`	Yes	Embedding API endpoint
`BACKEND_PORT`	No	Backend port (default: `8001`)
`FRONTEND_PORT`	No	Frontend port (default: `3782`)
`NEXT_PUBLIC_API_BASE`	No	Frontend API URL - Set this for remote/LAN access (e.g., `http://192.168.1.100:8001`)
`TTS_*`	No	Text-to-Speech settings
`SEARCH_PROVIDER`	No	Search provider (options: `perplexity`, `tavily`, `serper`, `jina`, `exa`, `baidu`, default: `perplexity`)
`SEARCH_API_KEY`	No	Unified API key for all search providers

💡 Remote Access: If accessing from another device (e.g., 192.168.31.66:3782), add to .env:
NEXT_PUBLIC_API_BASE=http://192.168.31.66:8001

③ Configure Ports & LLM (Optional)

Ports: Set in .env file → BACKEND_PORT / FRONTEND_PORT (defaults: 8001/3782)
LLM: Edit config/agents.yaml → temperature / max_tokens per module
See Configuration Docs for details

④ Try Demo Knowledge Bases (Optional)

📚 Available Demos

Research Papers — 5 papers from our lab (AI-Researcher, LightRAG, etc.)
Data Science Textbook — 8 chapters, 296 pages (Book Link)

Download from Google Drive
Extract into data/ directory

Demo KBs use text-embedding-3-large with dimensions = 3072

⑤ Create Your Own Knowledge Base (After Launch)

Go to http://localhost:3782/knowledge
Click "New Knowledge Base" → Enter name → Upload PDF/TXT/MD files
Monitor progress in terminal

Step 2: Choose Your Installation Method

🐳 Option A: Docker Deployment

No Python/Node.js setup required

Prerequisites: Docker & Docker Compose

Quick Start — Build from source:

docker compose up --build -d    # Build and start (~5-10 min first run)
docker compose logs -f          # View logs

Or use pre-built image (faster):

# Linux/macOS (AMD64)
docker run -d --name deeptutor \
  -p 8001:8001 -p 3782:3782 \
  --env-file .env \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config:/app/config:ro \
  ghcr.io/hkuds/deeptutor:latest

# Apple Silicon (ARM64): use ghcr.io/hkuds/deeptutor:latest-arm64
# Windows PowerShell: use ${PWD} instead of $(pwd)

Common Commands:

docker compose up -d      # Start
docker compose down       # Stop
docker compose logs -f    # View logs
docker compose up --build # Rebuild after changes

📋 More Docker Options (Pre-built images, Cloud deployment, Custom ports)

Pre-built Image Architecture Reference:

Architecture	Image Tag	Use Case
AMD64	`ghcr.io/hkuds/deeptutor:latest`	Intel/AMD (most servers, Windows/Linux PCs)
ARM64	`ghcr.io/hkuds/deeptutor:latest-arm64`	Apple Silicon, AWS Graviton, Raspberry Pi

💡 Run uname -m to check: x86_64 = AMD64, arm64/aarch64 = ARM64

Cloud Deployment — Must set external API URL:

docker run -d --name deeptutor \
  -p 8001:8001 -p 3782:3782 \
  -e NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001 \
  --env-file .env \
  -v $(pwd)/data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

Custom Ports Example:

docker run -d --name deeptutor \
  -p 9001:9001 -p 3000:3000 \
  -e BACKEND_PORT=9001 \
  -e FRONTEND_PORT=3000 \
  -e NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:9001 \
  --env-file .env \
  -v $(pwd)/data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

💻 Option B: Manual Installation

For development or non-Docker environments

Prerequisites: Python 3.10+, Node.js 18+

1. Set Up Environment:

# Using conda (Recommended)
conda create -n deeptutor python=3.10 && conda activate deeptutor

# Or using venv
python -m venv venv && source venv/bin/activate  # Windows: venv\Scripts\activate

2. Install Dependencies:

# One-click installation (Recommended)
python scripts/install_all.py
# Or: bash scripts/install_all.sh

# Or manual installation
pip install -r requirements.txt
npm install --prefix web

3. Launch:

python scripts/start_web.py    # Start frontend + backend
# Or: python scripts/start.py  # CLI only
# Stop: Ctrl+C

🔧 Start Frontend & Backend Separately

Backend (FastAPI):

python src/api/run_server.py
# Or: uvicorn src.api.main:app --host 0.0.0.0 --port 8001 --reload

Frontend (Next.js):

cd web && npm install && npm run dev -- -p 3782

Note: Create web/.env.local:

NEXT_PUBLIC_API_BASE=http://localhost:8001

Service	Default Port
Backend	`8001`
Frontend	`3782`

Access URLs

Service	URL	Description
Frontend	http://localhost:3782	Main web interface
API Docs	http://localhost:8001/docs	Interactive API documentation

📂 Data Storage

All user content and system data are stored in the data/ directory:

data/
├── knowledge_bases/              # Knowledge base storage
└── user/                         # User activity data
    ├── solve/                    # Problem solving results and artifacts
    ├── question/                 # Generated questions
    ├── research/                 # Research reports and cache
    ├── co-writer/                # Interactive IdeaGen documents and audio files
    ├── notebook/                 # Notebook records and metadata
    ├── guide/                    # Guided learning sessions
    ├── logs/                     # System logs
    └── run_code_workspace/       # Code execution workspace

Results are automatically saved during all activities. Directories are created automatically as needed.

📦 Core Modules

🧠 Smart Solver

Architecture Diagram

Intelligent problem-solving system based on Analysis Loop + Solve Loop dual-loop architecture, supporting multi-mode reasoning and dynamic knowledge retrieval.

Core Features

Feature	Description
Dual-Loop Architecture	Analysis Loop: InvestigateAgent → NoteAgent Solve Loop: PlanAgent → ManagerAgent → SolveAgent → CheckAgent → Format
Multi-Agent Collaboration	Specialized agents: InvestigateAgent, NoteAgent, PlanAgent, ManagerAgent, SolveAgent, CheckAgent
Real-time Streaming	WebSocket transmission with live reasoning process display
Tool Integration	RAG (naive/hybrid), Web Search, Query Item, Code Execution
Persistent Memory	JSON-based memory files for context preservation
Citation Management	Structured citations with reference tracking

Usage

Visit http://localhost:{frontend_port}/solver
Select a knowledge base
Enter your question, click "Solve"
Watch the real-time reasoning process and final answer

Python API

import asyncio
from src.agents.solve import MainSolver

async def main():
    solver = MainSolver(kb_name="ai_textbook")
    result = await solver.solve(
        question="Calculate the linear convolution of x=[1,2,3] and h=[4,5]",
        mode="auto"
    )
    print(result['formatted_solution'])

asyncio.run(main())

Output Location

data/user/solve/solve_YYYYMMDD_HHMMSS/
├── investigate_memory.json    # Analysis Loop memory
├── solve_chain.json           # Solve Loop steps & tool records
├── citation_memory.json       # Citation management
├── final_answer.md            # Final solution (Markdown)
├── performance_report.json    # Performance monitoring
└── artifacts/                 # Code execution outputs

📝 Question Generator

Architecture Diagram

Dual-mode question generation system supporting custom knowledge-based generation and reference exam paper mimicking with automatic validation.

Core Features

Feature	Description
Custom Mode	Background Knowledge → Question Planning → Generation → Single-Pass Validation Analyzes question relevance without rejection logic
Mimic Mode	PDF Upload → MinerU Parsing → Question Extraction → Style Mimicking Generates questions based on reference exam structure
ReAct Engine	QuestionGenerationAgent with autonomous decision-making (think → act → observe)
Validation Analysis	Single-pass relevance analysis with `kb_coverage` and `extension_points`
Question Types	Multiple choice, fill-in-the-blank, calculation, written response, etc.
Batch Generation	Parallel processing with progress tracking
Complete Persistence	All intermediate files saved (background knowledge, plan, individual results)
Timestamped Output	Mimic mode creates batch folders: `mimic_YYYYMMDD_HHMMSS_{pdf_name}/`

Usage

Custom Mode:

Visit http://localhost:{frontend_port}/question
Fill in requirements (topic, difficulty, question type, count)
Click "Generate Questions"
View generated questions with validation reports

Mimic Mode:

Visit http://localhost:{frontend_port}/question
Switch to "Mimic Exam" tab
Upload PDF or provide parsed exam directory
Wait for parsing → extraction → generation
View generated questions alongside original references

Python API

Custom Mode - Full Pipeline:

import asyncio
from src.agents.question import AgentCoordinator

async def main():
    coordinator = AgentCoordinator(
        kb_name="ai_textbook",
        output_dir="data/user/question"
    )

    # Generate multiple questions from text requirement
    result = await coordinator.generate_questions_custom(
        requirement_text="Generate 3 medium-difficulty questions about deep learning basics",
        difficulty="medium",
        question_type="choice",
        count=3
    )

    print(f"✅ Generated {result['completed']}/{result['requested']} questions")
    for q in result['results']:
        print(f"- Relevance: {q['validation']['relevance']}")

asyncio.run(main())

Mimic Mode - PDF Upload:

from src.agents.question.tools.exam_mimic import mimic_exam_questions

result = await mimic_exam_questions(
    pdf_path="exams/midterm.pdf",
    kb_name="calculus",
    output_dir="data/user/question/mimic_papers",
    max_questions=5
)

print(f"✅ Generated {result['successful_generations']} questions")
print(f"Output: {result['output_file']}")

Output Location

Custom Mode:

data/user/question/custom_YYYYMMDD_HHMMSS/
├── background_knowledge.json      # RAG retrieval results
├── question_plan.json              # Question planning
├── question_1_result.json          # Individual question results
├── question_2_result.json
└── ...

Mimic Mode:

data/user/question/mimic_papers/
└── mimic_YYYYMMDD_HHMMSS_{pdf_name}/
    ├── {pdf_name}.pdf                              # Original PDF
    ├── auto/{pdf_name}.md                          # MinerU parsed markdown
    ├── {pdf_name}_YYYYMMDD_HHMMSS_questions.json  # Extracted questions
    └── {pdf_name}_YYYYMMDD_HHMMSS_generated_questions.json  # Generated questions

🎓 Guided Learning

Architecture Diagram

Personalized learning system based on notebook content, automatically generating progressive learning paths through interactive pages and smart Q&A.

Core Features

Feature	Description
Multi-Agent Architecture	LocateAgent: Identifies 3-5 progressive knowledge points InteractiveAgent: Converts to visual HTML pages ChatAgent: Provides contextual Q&A SummaryAgent: Generates learning summaries
Smart Knowledge Location	Automatic analysis of notebook content
Interactive Pages	HTML page generation with bug fixing
Smart Q&A	Context-aware answers with explanations
Progress Tracking	Real-time status with session persistence
Cross-Notebook Support	Select records from multiple notebooks

Usage Flow

Select Notebook(s) — Choose one or multiple notebooks (cross-notebook selection supported)
Generate Learning Plan — LocateAgent identifies 3-5 core knowledge points
Start Learning — InteractiveAgent generates HTML visualization
Learning Interaction — Ask questions, click "Next" to proceed
Complete Learning — SummaryAgent generates learning summary

Output Location

data/user/guide/
└── session_{session_id}.json    # Complete session state, knowledge points, chat history

✏️ Interactive IdeaGen (Co-Writer)

Architecture Diagram

Intelligent Markdown editor supporting AI-assisted writing, auto-annotation, and TTS narration.

Core Features

Feature	Description
Rich Text Editing	Full Markdown syntax support with live preview
EditAgent	Rewrite: Custom instructions with optional RAG/web context Shorten: Compress while preserving key information Expand: Add details and context
Auto-Annotation	Automatic key content identification and marking
NarratorAgent	Script generation, TTS audio, multiple voices (Cherry, Stella, Annie, Cally, Eva, Bella)
Context Enhancement	Optional RAG or web search for additional context
Multi-Format Export	Markdown, PDF, etc.

Usage

Visit http://localhost:{frontend_port}/co_writer
Enter or paste text in the editor
Use AI features: Rewrite, Shorten, Expand, Auto Mark, Narrate
Export to Markdown or PDF

Output Location

data/user/co-writer/
├── audio/                    # TTS audio files
│   └── {operation_id}.mp3
├── tool_calls/               # Tool call history
│   └── {operation_id}_{tool_type}.json
└── history.json              # Edit history

🔬 Deep Research

Architecture Diagram

DR-in-KG (Deep Research in Knowledge Graph) — A systematic deep research system based on Dynamic Topic Queue architecture, enabling multi-agent collaboration across three phases: Planning → Researching → Reporting.

Core Features

Feature	Description
Three-Phase Architecture	Phase 1 (Planning): RephraseAgent (topic optimization) + DecomposeAgent (subtopic decomposition) Phase 2 (Researching): ManagerAgent (queue scheduling) + ResearchAgent (research decisions) + NoteAgent (info compression) Phase 3 (Reporting): Deduplication → Three-level outline generation → Report writing with citations
Dynamic Topic Queue	Core scheduling system with TopicBlock state management: `PENDING → RESEARCHING → COMPLETED/FAILED`. Supports dynamic topic discovery during research
Execution Modes	Series Mode: Sequential topic processing Parallel Mode: Concurrent multi-topic processing with `AsyncCitationManagerWrapper` for thread-safe operations
Multi-Tool Integration	RAG (hybrid/naive), Query Item (entity lookup), Paper Search, Web Search, Code Execution — dynamically selected by ResearchAgent
Unified Citation System	Centralized CitationManager as single source of truth for citation ID generation, ref_number mapping, and deduplication
Preset Configurations	quick: Fast research (1-2 subtopics, 1-2 iterations) medium/standard: Balanced depth (5 subtopics, 4 iterations) deep: Thorough research (8 subtopics, 7 iterations) auto: Agent autonomously decides depth

Citation System Architecture

The citation system follows a centralized design with CitationManager as the single source of truth:

┌─────────────────────────────────────────────────────────────────┐
│                      CitationManager                            │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │  ID Generation  │  │  ref_number Map │  │   Deduplication │  │
│  │  PLAN-XX        │  │  citation_id →  │  │   (papers only) │  │
│  │  CIT-X-XX       │  │  ref_number     │  │                 │  │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘  │
└───────────┼────────────────────┼────────────────────┼───────────┘
            │                    │                    │
     ┌──────┴──────┐      ┌──────┴──────┐      ┌──────┴──────┐
     │DecomposeAgent│      │ReportingAgent│      │ References │
     │ ResearchAgent│      │ (inline [N]) │      │  Section   │
     │  NoteAgent   │      └─────────────┘      └────────────┘
     └─────────────┘

Component	Description
ID Format	PLAN-XX (planning stage RAG queries) + CIT-X-XX (research stage, X=block number)
ref_number Mapping	Sequential 1-based numbers built from sorted citation IDs, with paper deduplication
Inline Citations	Simple `[N]` format in LLM output, post-processed to clickable `[[N]](#ref-N)` links
Citation Table	Clear reference table provided to LLM: `Cite as [1] → (RAG) query preview...`
Post-processing	Automatic format conversion + validation to remove invalid citation references
Parallel Safety	Thread-safe async methods (`get_next_citation_id_async`, `add_citation_async`) for concurrent execution

Parallel Execution Architecture

When execution_mode: "parallel" is enabled, multiple topic blocks are researched concurrently:

┌─────────────────────────────────────────────────────────────────────────┐
│                    Parallel Research Execution                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   DynamicTopicQueue                    AsyncCitationManagerWrapper      │
│   ┌─────────────────┐                  ┌─────────────────────────┐      │
│   │ Topic 1 (PENDING)│ ──┐             │  Thread-safe wrapper    │      │
│   │ Topic 2 (PENDING)│ ──┼──→ asyncio  │  for CitationManager    │      │
│   │ Topic 3 (PENDING)│ ──┤   Semaphore │                         │      │
│   │ Topic 4 (PENDING)│ ──┤   (max=5)   │  • get_next_citation_   │      │
│   │ Topic 5 (PENDING)│ ──┘             │    id_async()           │      │
│   └─────────────────┘                  │  • add_citation_async() │      │
│            │                           └───────────┬─────────────┘      │
│            ▼                                       │                    │
│   ┌─────────────────────────────────────────────────────────────┐      │
│   │              Concurrent ResearchAgent Tasks                  │      │
│   │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │      │
│   │  │ Task 1  │  │ Task 2  │  │ Task 3  │  │ Task 4  │  ...   │      │
│   │  │(Topic 1)│  │(Topic 2)│  │(Topic 3)│  │(Topic 4)│        │      │
│   │  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │      │
│   │       │            │            │            │              │      │
│   │       └────────────┴────────────┴────────────┘              │      │
│   │                         │                                    │      │
│   │                         ▼                                    │      │
│   │              AsyncManagerAgentWrapper                        │      │
│   │              (Thread-safe queue updates)                     │      │
│   └─────────────────────────────────────────────────────────────┘      │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Component	Description
`asyncio.Semaphore`	Limits concurrent tasks to `max_parallel_topics` (default: 5)
`AsyncCitationManagerWrapper`	Wraps CitationManager with `asyncio.Lock()` for thread-safe ID generation
`AsyncManagerAgentWrapper`	Ensures queue state updates are atomic across parallel tasks
Real-time Progress	Live display of all active research tasks with status indicators

Agent Responsibilities

Agent	Phase	Responsibility
RephraseAgent	Planning	Optimizes user input topic, supports multi-turn user interaction for refinement
DecomposeAgent	Planning	Decomposes topic into subtopics with RAG context, obtains citation IDs from CitationManager
ManagerAgent	Researching	Queue state management, task scheduling, dynamic topic addition
ResearchAgent	Researching	Knowledge sufficiency check, query planning, tool selection, requests citation IDs before each tool call
NoteAgent	Researching	Compresses raw tool outputs into summaries, creates ToolTraces with pre-assigned citation IDs
ReportingAgent	Reporting	Builds citation map, generates three-level outline, writes report sections with citation tables, post-processes citations

Report Generation Pipeline

1. Build Citation Map     →  CitationManager.build_ref_number_map()
2. Generate Outline       →  Three-level headings (H1 → H2 → H3)
3. Write Sections         →  LLM uses [N] citations with provided citation table
4. Post-process           →  Convert [N] → [[N]](#ref-N), validate references
5. Generate References    →  Academic-style entries with collapsible source details

Usage

Visit http://localhost:{frontend_port}/research
Enter research topic
Select research mode (quick/medium/deep/auto)
Watch real-time progress with parallel/series execution
View structured report with clickable inline citations
Export as Markdown or PDF (with proper page splitting and Mermaid diagram support)

CLI

# Quick mode (fast research)
python src/agents/research/main.py --topic "Deep Learning Basics" --preset quick

# Medium mode (balanced)
python src/agents/research/main.py --topic "Transformer Architecture" --preset medium

# Deep mode (thorough research)
python src/agents/research/main.py --topic "Graph Neural Networks" --preset deep

# Auto mode (agent decides depth)
python src/agents/research/main.py --topic "Reinforcement Learning" --preset auto

Python API

import asyncio
from src.agents.research import ResearchPipeline
from src.core.core import get_llm_config, load_config_with_main

async def main():
    # Load configuration (main.yaml merged with any module-specific overrides)
    config = load_config_with_main("research_config.yaml")
    llm_config = get_llm_config()

    # Create pipeline (agent parameters loaded from agents.yaml automatically)
    pipeline = ResearchPipeline(
        config=config,
        api_key=llm_config["api_key"],
        base_url=llm_config["base_url"],
        kb_name="ai_textbook"  # Optional: override knowledge base
    )

    # Run research
    result = await pipeline.run(topic="Attention Mechanisms in Deep Learning")
    print(f"Report saved to: {result['final_report_path']}")

asyncio.run(main())

Output Location

data/user/research/
├── reports/                          # Final research reports
│   ├── research_YYYYMMDD_HHMMSS.md   # Markdown report with clickable citations [[N]](#ref-N)
│   └── research_*_metadata.json      # Research metadata and statistics
└── cache/                            # Research process cache
    └── research_YYYYMMDD_HHMMSS/
        ├── queue.json                # DynamicTopicQueue state (TopicBlocks + ToolTraces)
        ├── citations.json            # Citation registry with ID counters and ref_number mapping
        │                             #   - citations: {citation_id: citation_info}
        │                             #   - counters: {plan_counter, block_counters}
        ├── step1_planning.json       # Planning phase results (subtopics + PLAN-XX citations)
        ├── planning_progress.json    # Planning progress events
        ├── researching_progress.json # Researching progress events
        ├── reporting_progress.json   # Reporting progress events
        ├── outline.json              # Three-level report outline structure
        └── token_cost_summary.json   # Token usage statistics

Citation File Structure (citations.json):

{
  "research_id": "research_20241209_120000",
  "citations": {
    "PLAN-01": {"citation_id": "PLAN-01", "tool_type": "rag_hybrid", "query": "...", "summary": "..."},
    "CIT-1-01": {"citation_id": "CIT-1-01", "tool_type": "paper_search", "papers": [...], ...}
  },
  "counters": {
    "plan_counter": 2,
    "block_counters": {"1": 3, "2": 2}
  }
}

Configuration Options

Key configuration in config/main.yaml (research section) and config/agents.yaml:

# config/agents.yaml - Agent LLM parameters
research:
  temperature: 0.5
  max_tokens: 12000

# config/main.yaml - Research settings
research:
  # Execution Mode
  researching:
    execution_mode: "parallel"    # "series" or "parallel"
    max_parallel_topics: 5        # Max concurrent topics
    max_iterations: 5             # Max iterations per topic

  # Tool Switches
    enable_rag_hybrid: true       # Hybrid RAG retrieval
    enable_rag_naive: true        # Basic RAG retrieval
    enable_paper_search: true     # Academic paper search
    enable_web_search: true       # Web search (also controlled by tools.web_search.enabled)
    enable_run_code: true         # Code execution

  # Queue Limits
  queue:
    max_length: 5                 # Maximum topics in queue

  # Reporting
  reporting:
    enable_inline_citations: true # Enable clickable [N] citations in report

  # Presets: quick, medium, deep, auto

# Global tool switches in tools section
tools:
  web_search:
    enabled: true                 # Global web search switch (higher priority)

💡 Automated IdeaGen

Architecture Diagram

Research idea generation system that extracts knowledge points from notebook records and generates research ideas through multi-stage filtering.

Core Features

Feature	Description
MaterialOrganizerAgent	Extracts knowledge points from notebook records
Multi-Stage Filtering	Loose Filter → Explore Ideas (5+ per point) → Strict Filter → Generate Markdown
Idea Exploration	Innovative thinking from multiple dimensions
Structured Output	Organized markdown with knowledge points and ideas
Progress Callbacks	Real-time updates for each stage

Usage

Visit http://localhost:{frontend_port}/ideagen
Select a notebook with records
Optionally provide user thoughts/preferences
Click "Generate Ideas"
View generated research ideas organized by knowledge points

Python API

import asyncio
from src.agents.ideagen import IdeaGenerationWorkflow, MaterialOrganizerAgent
from src.core.core import get_llm_config

async def main():
    llm_config = get_llm_config()

    # Step 1: Extract knowledge points from materials
    organizer = MaterialOrganizerAgent(
        api_key=llm_config["api_key"],
        base_url=llm_config["base_url"]
    )
    knowledge_points = await organizer.extract_knowledge_points(
        "Your learning materials or notebook content here"
    )

    # Step 2: Generate research ideas
    workflow = IdeaGenerationWorkflow(
        api_key=llm_config["api_key"],
        base_url=llm_config["base_url"]
    )
    result = await workflow.process(knowledge_points)
    print(result)  # Markdown formatted research ideas

asyncio.run(main())

📊 Dashboard + Knowledge Base Management

Unified system entry providing activity tracking, knowledge base management, and system status monitoring.

Key Features

Feature	Description
Activity Statistics	Recent solving/generation/research records
Knowledge Base Overview	KB list, statistics, incremental updates
Notebook Statistics	Notebook counts, record distribution
Quick Actions	One-click access to all modules

Usage

Web Interface: Visit http://localhost:{frontend_port} to view system overview
Create KB: Click "New Knowledge Base", upload PDF/Markdown documents
View Activity: Check recent learning activities on Dashboard

📓 Notebook

Unified learning record management, connecting outputs from all modules to create a personalized learning knowledge base.

Core Features

Feature	Description
Multi-Notebook Management	Create, edit, delete notebooks
Unified Record Storage	Integrate solving/generation/research/Interactive IdeaGen records
Categorization Tags	Auto-categorize by type, knowledge base
Custom Appearance	Color, icon personalization

Usage

Visit http://localhost:{frontend_port}/notebook
Create new notebook (set name, description, color, icon)
After completing tasks in other modules, click "Add to Notebook"
View and manage all records on the notebook page

📖 Module Documentation

Configuration	Data Directory	API Backend	Core Utilities
Knowledge Base	Tools	Web Frontend	Solve Module
Question Module	Research Module	Interactive IdeaGen Module	Guide Module
Automated IdeaGen Module

❓ FAQ

Backend fails to start?

Checklist

Confirm Python version >= 3.10
Confirm all dependencies installed: pip install -r requirements.txt
Check if port 8001 is in use
Check .env file configuration

Solutions

Change port: Set BACKEND_PORT=9001 in .env file
Check logs: Review terminal error messages

Port occupied after Ctrl+C?

Problem

After pressing Ctrl+C during a running task (e.g., deep research), restarting shows "port already in use" error.

Cause

Ctrl+C sometimes only terminates the frontend process while the backend continues running in the background.

Solution

# macOS/Linux: Find and kill the process
lsof -i :8001
kill -9 <PID>

# Windows: Find and kill the process
netstat -ano | findstr :8001
taskkill /PID <PID> /F

Then restart the service with python scripts/start_web.py.

npm: command not found error?

Problem

Running scripts/start_web.py shows npm: command not found or exit status 127.

Checklist

Check if npm is installed: npm --version
Check if Node.js is installed: node --version
Confirm conda environment is activated (if using conda)

Solutions

# Option A: Using Conda (Recommended)
conda install -c conda-forge nodejs

# Option B: Using Official Installer
# Download from https://nodejs.org/

# Option C: Using nvm
nvm install 18
nvm use 18

Verify Installation

node --version  # Should show v18.x.x or higher
npm --version   # Should show version number

Long path names on Windows installation?

Problem

On Windows, you may encounter errors related to long file paths during installation, such as "The filename or extension is too long" or similar path length issues.

Cause

Windows has a default limitation on path lengths (260 characters), which can be exceeded by DeepTutor's nested directory structures and dependencies.

Solution

Enable long path support system-wide by running the following command in an Administrator Command Prompt:

reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f

After running this command, restart your terminal for the changes to take effect.

Frontend cannot connect to backend?

Checklist

Confirm backend is running (visit http://localhost:8001/docs)
Check browser console for error messages

Solution

Create .env.local in web directory:

NEXT_PUBLIC_API_BASE=http://localhost:8001

Docker: Frontend cannot connect in cloud deployment?

Problem

When deploying to a cloud server, the frontend shows connection errors like "Failed to fetch" or "NEXT_PUBLIC_API_BASE is not configured".

Cause

The default API URL is localhost:8001, which points to the user's local machine in the browser, not your server.

Solution

Set the NEXT_PUBLIC_API_BASE_EXTERNAL environment variable to your server's public URL:

# Using docker run
docker run -d --name deeptutor \
  -e NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001 \
  ... other options ...
  ghcr.io/hkuds/deeptutor:latest

# Or in .env file
NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001

Custom Port Example:

# If using backend port 9001
-e BACKEND_PORT=9001 \
-e NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:9001

Docker: How to use custom ports?

Solution

Set both the port environment variables AND the port mappings:

docker run -d --name deeptutor \
  -p 9001:9001 -p 4000:4000 \
  -e BACKEND_PORT=9001 \
  -e FRONTEND_PORT=4000 \
  -e NEXT_PUBLIC_API_BASE_EXTERNAL=http://localhost:9001 \
  ... other env vars ...
  ghcr.io/hkuds/deeptutor:latest

Important: The -p port mapping must match the BACKEND_PORT/FRONTEND_PORT values.

WebSocket connection fails?

Checklist

Confirm backend is running
Check firewall settings
Confirm WebSocket URL is correct

Solution

Check backend logs
Confirm URL format: ws://localhost:8001/api/v1/...

Settings page shows "Error loading data" with HTTPS reverse proxy?

Problem

When deploying behind an HTTPS reverse proxy (e.g., nginx), the Settings page shows "Error loading data" and browser DevTools reveals that HTTPS requests are being redirected to HTTP (307 redirect).

Cause

This issue has been fixed in v0.5.0+. If you're using an older version, the problem was caused by FastAPI's automatic trailing slash redirects generating HTTP URLs instead of preserving the original HTTPS protocol.

Solution (for v0.5.0+)

Update to the latest version. The fix disables automatic slash redirects to prevent protocol downgrade.

Recommended nginx Configuration

When using nginx as an HTTPS reverse proxy, use the following configuration:

# Frontend
location / {
    proxy_pass http://localhost:3782;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

# Backend API
location /api/ {
    proxy_pass http://localhost:8001;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;  # Important: preserves original protocol
}

# WebSocket support
location /api/v1/ {
    proxy_pass http://localhost:8001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Environment Variable

Set in .env:

NEXT_PUBLIC_API_BASE=https://your-domain.com:port

See: GitHub Issue #112

Where are module outputs stored?

Module	Output Path
Solve	`data/user/solve/solve_YYYYMMDD_HHMMSS/`
Question	`data/user/question/question_YYYYMMDD_HHMMSS/`
Research	`data/user/research/reports/`
Interactive IdeaGen	`data/user/co-writer/`
Notebook	`data/user/notebook/`
Guide	`data/user/guide/session_{session_id}.json`
Logs	`data/user/logs/`

How to add a new knowledge base?

Web Interface

Visit http://localhost:{frontend_port}/knowledge
Click "New Knowledge Base"
Enter knowledge base name
Upload PDF/TXT/MD documents
System will process documents in background

CLI

python -m src.knowledge.start_kb init <kb_name> --docs <pdf_path>

How to incrementally add documents to existing KB?

CLI (Recommended)

python -m src.knowledge.add_documents <kb_name> --docs <new_document.pdf>

Benefits

Only processes new documents, saves time and API costs
Automatically merges with existing knowledge graph
Preserves all existing data

Numbered items extraction failed with uvloop.Loop error?

Problem

When initializing a knowledge base, you may encounter this error:

ValueError: Can't patch loop of type <class 'uvloop.Loop'>

This occurs because Uvicorn uses uvloop event loop by default, which is incompatible with nest_asyncio.

Solution

Use one of the following methods to extract numbered items:

# Option 1: Using the shell script (recommended)
./scripts/extract_numbered_items.sh <kb_name>

# Option 2: Direct Python command
python src/knowledge/extract_numbered_items.py --kb <kb_name> --base-dir ./data/knowledge_bases

This will extract numbered items (Definitions, Theorems, Equations, etc.) from your knowledge base without reinitializing it.

⭐ Star History

🤝 Contribution

We hope DeepTutor could become a gift for the community. 🎁

🔗 Related Projects

⚡ LightRAG	🎨 RAG-Anything	💻 DeepCode	🔬 AI-Researcher
Simple and Fast RAG	Multimodal RAG	AI Code Assistant	Research Automation

Data Intelligence Lab @ HKU

⭐ Star us · 🐛 Report a bug · 💬 Discussions

This project is licensed under the AGPL-3.0 License.

✨ Thanks for visiting DeepTutor!

Name		Name	Last commit message	Last commit date
Latest commit History 264 Commits
.github		.github
assets		assets
config		config
data		data
docs		docs
scripts		scripts
src		src
tests		tests
web		web
.dockerignore		.dockerignore
.env.example		.env.example
.env.example_CN		.env.example_CN
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.secrets.baseline		.secrets.baseline
CONTRIBUTING.md		CONTRIBUTING.md
Communication.md		Communication.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

License

HKUDS/DeepTutor

Folders and files

Latest commit

History

Repository files navigation

DeepTutor: AI-Powered Personalized Learning Assistant

📰 News

📦 Releases

Key Features of DeepTutor

📚 Massive Document Knowledge Q&A

🎨 Interactive Learning Visualization

🎯 Knowledge Reinforcement with Practice Exercise Generator

🔍 Deep Research & Idea Generation

📚 Massive Document Knowledge Q&A

🎨 Interactive Learning Visualization

🎯 Knowledge Reinforcement

🔍 Deep Research & Idea Generation

🏗️ All-in-One Knowledge System

🏛️ DeepTutor's Framework

💬 User Interface Layer

🤖 Intelligent Agent Modules

🔧 Tool Integration Layer

🧠 Knowledge & Memory Foundation

📋 Todo

🚀 Getting Started

Step 1: Pre-Configuration

Step 2: Choose Your Installation Method

🐳 Option A: Docker Deployment

💻 Option B: Manual Installation

Access URLs

📂 Data Storage

📦 Core Modules

📖 Module Documentation

❓ FAQ

⭐ Star History

🤝 Contribution

🔗 Related Projects

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors 23

Uh oh!

Languages

Packages