A curated collection of 5 research papers from our lab covering RAG and Agent fields. This demo showcases broad knowledge coverage for research scenarios.

Used Papers: AI-Researcher | AutoAgent | RAG-Anything | LightRAG | VideoRAG

A comprehensive data science textbook with challenging content. This demo showcases deep knowledge depth for learning scenarios.

Book Link: Deep Representation Learning Book

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

Core Features

Usage

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

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())

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 

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

Core Features

Usage

Custom Mode:

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

Mimic Mode:

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

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())

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']}")

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 └── ... 

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 

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

Core Features

Usage Flow

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

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

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

Core Features

Usage

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

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 

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

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 │ └─────────────┘ └────────────┘ └─────────────┘ 

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) │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ 

Agent Responsibilities

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

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

# 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

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())

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 

{ "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} } }

# 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)

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

Core Features

Usage

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

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())

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

Key Features

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

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

Core Features

Usage

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

Checklist

• Confirm Python version >= 3.10
• Confirm all dependencies installed: pip install -r requirements.txt
• Check if port 8001 is in use (configurable in config/main.yaml)
• Check .env file configuration

Solutions

• Change port: Edit config/main.yaml server.backend_port
• Check logs: Review terminal error messages

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.

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

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

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/...

Web Interface

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

CLI

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

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

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.

This project uses pre-commit hooks to automatically format code and check for issues before commits.

Step 1: Install pre-commit

# Using pip pip install pre-commit # Or using conda conda install -c conda-forge pre-commit

Step 2: Install Git hooks

cd DeepTutor pre-commit install

Step 3: (Optional) Run checks on all files

pre-commit run --all-files

Every time you run git commit, pre-commit hooks will automatically:

• Format Python code with Ruff
• Format frontend code with Prettier
• Check for syntax errors
• Validate YAML/JSON files
• Detect potential security issues

Note: The project uses Ruff format instead of Black to avoid formatting conflicts.

# Normal commit (hooks run automatically) git commit -m "Your commit message" # Manually check all files pre-commit run --all-files # Update hooks to latest versions pre-commit autoupdate # Skip hooks (not recommended, only for emergencies) git commit --no-verify -m "Emergency fix"