DeepTutor: AI‑Powered Personalized Learning Assistant

DeepTutor is an end‑to‑end, open‑source platform that turns any knowledge base into an intelligent tutoring system. It was born from HKUDS’s research into large‑language‑model (LLM) workflows and has since evolved into a full‑featured, production‑ready stack.

Why DeepTutor?

• Multi‑agent architecture – separate agents handle investigation, planning, execution, and checking, giving you fine‑grained control over the reasoning flow.
• RAG + hybrid retrieval – seamlessly mix local embeddings, web search, paper discovery, and code execution to produce accurate, cited answers.
• Rich UI – a Next.js / React dashboard with live WebSocket streaming, visual learning pages, and AI‑augmented note‑taking.
• Extensible – plug in new LLMs, embeddings or search providers with minimal effort.
• Zero‑code start – Docker images are pre‑built, you can spin up a fresh instance in under 10 minutes.

Quick Start 🚀

1. Clone the repo

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

2. Create your environment (recommended with Conda)

   conda create -n deeptutor python=3.10
   conda activate deeptutor
   

3. Set your API keys

   cp .env.example .env
   # Edit .env with your Azure/OpenAI keys
   

4. Run via Docker (fastest)

   docker compose up --build -d
   

   or use the pre‑built image:

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

5. Access the web UI – http://localhost:3782

   • Backend API docs at http://localhost:8001/docs.

Core Modules Explained

Module	Purpose	Key Features
Solver	Step‑by‑step problem solving
	Dual agent loops (Investigate → Solve)
	Live WebSocket reasoning and citation tracking
	Supports custom problem types, code execution
Question Generator	Automated quiz creation
	Custom & exam‑mimic modes
	Validation via ReAct‑style agent
Guided Learning	Visual knowledge paths
	Notebook‑driven learning, interactive pages
Interactive IdeaGen	Markdown editor with AI rewrite & TTS
	Auto‑annotation, multi‑format export
Deep Research	Systematic literature reviews
	Three‑phase pipeline (Plan → Research → Report)
	Inline citations and markdown export

Extending DeepTutor

• Add a new LLM – edit config/agents.yaml and supply a LLM_MODEL that your provider supports.
• Switch embeddings – change EMBEDDING_MODEL and add the endpoint if using a private server.
• Plug new search – enable/disable providers in .env (SEARCH_PROVIDER=perplexity, etc.) or modify src/agents/agents.py.
• Contribute – the repo follows an MIT‑style development workflow. Open issues, submit PRs, and help refine the architecture.

Contributing Workflow

1. Fork and clone the repo.
2. Create a feature branch with a clear name, e.g. feature/solver-optimization.
3. Run pre-commit install to enforce linting.
4. Test locally with docker compose up --build.
5. Push and PR. Our CI will run unit tests and linting checks.

Getting Help

• Community channels – Discord, WeChat, Slack, and GitHub Discussions.
• Documentation – the docs/ folder contains in‑repo references and API docs.
• Issue tracker – search for existing problems before filing new ones.

Why AGPL‑3.0?

DeepTutor’s AGPL license ensures that any downstream service providing the software must share source changes. This encourages transparency in LLM‑powered tutoring services and protects the community’s collective improvements.

Final Thoughts

With DeepTutor you can experiment with state‑of‑the‑art LLM workflows, create a personalized learning hub, or deploy a tutor‑bot for your institution. Its modular design means you can start with the default FastAPI/Next.js stack and later plug in a different LLM or embed a domain‑specific knowledge base. Whether you’re a dev student, educator, or AI researcher, DeepTutor offers a playground and a production‑ready tool—all open source.

Start exploring today – transform any document into an interactive AI tutor!