How DeepTutor Turns AI into a Personal Learning Mentor

Technical Stack and Core Architecture

DeepTutor is implemented with Python 3.10+ for backend services, FastAPI 0.100+ as the HTTP API framework, and Next.js 14 for the web front‑end. The project is released under the AGPL‑3.0 license and supports multilingual interaction.

Four‑Layer Architecture

Input/Output Layer – Manages bidirectional communication between user queries and structured responses, handling session state and formatting.

Intelligent Agent Layer – Contains an analysis loop, a solving loop, problem‑generation logic, and note‑planning modules. The layer can operate in custom or simulated modes to guide users from problem comprehension to solution.

Tool Layer – Integrates Retrieval‑Augmented Generation (RAG) with hybrid search, real‑time web search, academic paper search, a sandboxed Python executor, and PDF parsing to provide diverse learning resources.

Knowledge & Memory Layer – Utilizes a knowledge graph, entity‑relationship storage, semantic search, and conversation memory to persist and retrieve contextual knowledge efficiently.

Core Functionalities

1. Interactive Visualization

DeepTutor transforms abstract mathematical concepts and algorithmic logic into interactive HTML visualizations. Users can click, drag, and modify parameters in real time, observing immediate changes in data and flow, which accelerates comprehension compared with static text or code snippets.

2. Dual‑Loop Reasoning Architecture

The system employs a two‑stage process to mitigate hallucinations:

Analysis Loop – Reviews the question, performs relevant retrieval (RAG, web, paper), extracts key information, and constructs a lesson‑plan style outline.

Solving Loop – Executes step‑by‑step reasoning, invokes tools (e.g., Python sandbox, PDF parser), runs code, and validates intermediate results before a summarization agent formats the final answer.

3. Exam Cloning & Deep Research

Exam Simulation – Users upload past exam PDFs; DeepTutor analyses question style, difficulty distribution, and knowledge‑point coverage, then automatically generates a highly similar mock exam for targeted practice.

Deep Document Analysis – In “Deep Research” mode, private notes, unpublished papers, or internal documents can be uploaded for long‑chain analysis and report generation. All processing occurs locally, preserving data privacy.

One‑Click Docker Deployment

DeepTutor provides a Docker image that can be started with a single command. Replace the placeholder API keys with your own values and run:

-p 8001:8001 -p 3782:3782 \
-e LLM_MODEL=gpt-4o \
-e LLM_BINDING_API_KEY=your-api-key \
-e LLM_BINDING_HOST=https://api.openai.com/v1 \
-e EMBEDDING_MODEL=text-embedding-3-large \
-e EMBEDDING_BINDING_API_KEY=your-api-key \
-e EMBEDDING_BINDING_HOST=https://api.openai.com/v1 \
-v $(pwd)/data:/app/data \
-v $(pwd)/config:/app/config:ro \
ghcr.io/hkuds/deeptutor:latest

Key Takeaway

DeepTutor is designed to act as an “AI mentor” that guides users through reasoning steps rather than delivering direct answers. By combining interactive visualizations, a dual‑loop reasoning pipeline, and extensible tool integration, it supports both exam preparation and deep research workflows while keeping user data local.

GitHub repository: https://github.com/HKUDS/DeepTutor