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

[2026.1.9] Releasev0.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

💡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

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

Pre-built Image Architecture Reference:

💡 Rununame -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

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: Createweb/.env.local:

NEXT_PUBLIC_API_BASE=http://localhost:8001

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

Core Features

Usage

1. Visithttp://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

importasynciofromsrc.agents.solveimportMainSolverasyncdefmain():solver=MainSolver(kb_name="ai_textbook")result=awaitsolver.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 supportingcustom knowledge-based generation andreference exam paper mimicking with automatic validation.

Core Features

Usage

Custom Mode:

1. Visithttp://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. Visithttp://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

importasynciofromsrc.agents.questionimportAgentCoordinatorasyncdefmain():coordinator=AgentCoordinator(kb_name="ai_textbook",output_dir="data/user/question"    )# Generate multiple questions from text requirementresult=awaitcoordinator.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")forqinresult['results']:print(f"- Relevance:{q['validation']['relevance']}")asyncio.run(main())

fromsrc.agents.question.tools.exam_mimicimportmimic_exam_questionsresult=awaitmimic_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. Visithttp://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 onDynamic 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

Whenexecution_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 table4. Post-process           →  Convert [N] → [[N]](#ref-N), validate references5. Generate References    →  Academic-style entries with collapsible source details

Usage

1. Visithttp://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

importasynciofromsrc.agents.researchimportResearchPipelinefromsrc.core.coreimportget_llm_config,load_config_with_mainasyncdefmain():# 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 researchresult=awaitpipeline.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 parametersresearch:temperature:0.5max_tokens:12000# config/main.yaml - Research settingsresearch:# Execution Moderesearching:execution_mode:"parallel"# "series" or "parallel"max_parallel_topics:5# Max concurrent topicsmax_iterations:5# Max iterations per topic# Tool Switchesenable_rag_hybrid:true# Hybrid RAG retrievalenable_rag_naive:true# Basic RAG retrievalenable_paper_search:true# Academic paper searchenable_web_search:true# Web search (also controlled by tools.web_search.enabled)enable_run_code:true# Code execution# Queue Limitsqueue:max_length:5# Maximum topics in queue# Reportingreporting:enable_inline_citations:true# Enable clickable [N] citations in report# Presets: quick, medium, deep, auto# Global tool switches in tools sectiontools: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. Visithttp://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

importasynciofromsrc.agents.ideagenimportIdeaGenerationWorkflow,MaterialOrganizerAgentfromsrc.core.coreimportget_llm_configasyncdefmain():llm_config=get_llm_config()# Step 1: Extract knowledge points from materialsorganizer=MaterialOrganizerAgent(api_key=llm_config["api_key"],base_url=llm_config["base_url"]    )knowledge_points=awaitorganizer.extract_knowledge_points("Your learning materials or notebook content here"    )# Step 2: Generate research ideasworkflow=IdeaGenerationWorkflow(api_key=llm_config["api_key"],base_url=llm_config["base_url"]    )result=awaitworkflow.process(knowledge_points)print(result)# Markdown formatted research ideasasyncio.run(main())

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

Key Features

Usage

• Web Interface: Visithttp://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. Visithttp://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
• Check.env file configuration

Solutions

• Change port: SetBACKEND_PORT=9001 in.env file
• 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 processlsof -i :8001kill -9<PID># Windows: Find and kill the processnetstat -ano| findstr :8001taskkill /PID<PID> /F

Then restart the service withpython scripts/start_web.py.

Problem

Runningscripts/start_web.py showsnpm: 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 nvmnvm install 18nvm use 18

Verify Installation

node --version# Should show v18.x.x or highernpm --version# Should show version number

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 /d1 /f

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

Checklist

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

Solution

Create.env.local inweb directory:

NEXT_PUBLIC_API_BASE=http://localhost:8001

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 islocalhost:8001, which points to the user's local machine in the browser, not your server.

Solution

Set theNEXT_PUBLIC_API_BASE_EXTERNAL environment variable to your server's public URL:

# Using docker rundocker 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 fileNEXT_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

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 theBACKEND_PORT/FRONTEND_PORT values.

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

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:

# Frontendlocation /{proxy_passhttp://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 APIlocation /api/{proxy_passhttp://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 originalprotocol}# WebSocket supportlocation /api/v1/{proxy_passhttp://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

Web Interface

1. Visithttp://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 usesuvloop event loop by default, which is incompatible withnest_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 commandpython 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.