DeepTutor: Agent-Native Personalized Tutoring

Features · Get Started · Explore · TutorBot · CLI · Multi-User · Roadmap · Community

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

🤝 We welcome any kinds of contributing! See our Contributing Guide for branching strategy, coding standards, and how to get started.

[2026.5.8] v1.3.8 — Optional multi-user deployments with isolated user workspaces, admin grants, auth routes, and scoped runtime access.

[2026.5.4] v1.3.7 — Thinking-model/provider fixes, visible Knowledge index history, and safer Co-Writer clear/template editing.

[2026.5.3] v1.3.6 — Catalog-based model selection for chat and TutorBot, safer RAG re-indexing, OpenAI Responses token-limit fixes, and Skills editor validation.

[2026.5.2] v1.3.5 — Smoother local launch settings, safer RAG queries, cleaner local embedding auth, and Settings dark-mode polish.

[2026.5.1] v1.3.4 — Book page chat persistence and rebuild flows, chat-to-book references, stronger language/reasoning handling, RAG document extraction hardening.

[2026.4.30] v1.3.3 — NVIDIA NIM + Gemini embedding support, unified Space context for chat history/skills/memory, session snapshots, RAG re-index resilience.

[2026.4.29] v1.3.2 — Transparent embedding endpoint URLs, RAG re-index resilience for invalid persisted vectors, memory cleanup for thinking-model output, Deep Solve runtime fix.

[2026.4.28] v1.3.1 — Stability: safer RAG routing & embedding validation, Docker persistence, IME-safe input, Windows/GBK robustness.

[2026.4.27] v1.3.0 — Versioned KB indexes with re-index workflow, rebuilt Knowledge workspace, embedding auto-discovery with new adapters, Space hub.

[2026.4.25] v1.2.5 — Persistent chat attachments with file-preview drawer, attachment-aware capability pipelines, TutorBot Markdown export.

[2026.4.25] v1.2.4 — Text/code/SVG attachments, one-command Setup Tour, Markdown chat export, compact KB management UI.

[2026.4.24] v1.2.3 — Document attachments (PDF/DOCX/XLSX/PPTX), reasoning thinking-block display, Soul template editor, Co-Writer save-to-notebook.

[2026.4.19] 🎉 We've reached 20k stars after 111 days! Thank you for the incredible support — we're committed to continuous iteration toward truly personalized, intelligent tutoring for everyone.

[2026.4.10] 📄 Our paper is now live on arXiv! Read the preprint to learn more about the design and ideas behind DeepTutor.

[2026.4.4] Long time no see! ✨ DeepTutor v1.0.0 is finally here — an agent-native evolution featuring a ground-up architecture rewrite, TutorBot, and flexible mode switching under the Apache-2.0 license. A new chapter begins, and our story continues!

[2026.2.6] 🚀 We've reached 10k stars in just 39 days! A huge thank you to our incredible community for the support!

[2026.1.1] Happy New Year! Join our Discord, WeChat, or Discussions — let's shape the future of DeepTutor together!

[2025.12.29] DeepTutor is officially released!

• Unified Chat Workspace — Six modes, one thread. Chat, Deep Solve, Quiz Generation, Deep Research, Math Animator, and Visualize share the same context — start a conversation, escalate to multi-agent problem solving, generate quizzes, visualize concepts, then deep-dive into research, all without losing a single message.
• AI Co-Writer — A multi-document Markdown workspace where AI is a first-class collaborator. Select text, rewrite, expand, or summarize — drawing from your knowledge base and the web. Every piece feeds back into your learning ecosystem.
• Book Engine — Turn your materials into structured, interactive "living books". A multi-agent pipeline designs outlines, retrieves relevant sources, and compiles rich pages with 13 block types — quizzes, flash cards, timelines, concept graphs, interactive demos, and more.
• Knowledge Hub — Upload PDFs, Markdown, and text files to build RAG-ready knowledge bases. Organize insights in color-coded notebooks, revisit quiz questions in the Question Bank, and create custom Skills that shape how DeepTutor teaches you. Your documents don't just sit there — they actively power every conversation.
• Persistent Memory — DeepTutor builds a living profile of you: what you've studied, how you learn, and where you're heading. Shared across all features and TutorBots, it gets sharper with every interaction.
• Personal TutorBots — Not chatbots — autonomous tutors. Each TutorBot lives in its own workspace with its own memory, personality, and skill set. They set reminders, learn new abilities, and evolve as you grow. Powered by nanobot.
• Agent-Native CLI — Every capability, knowledge base, session, and TutorBot is one command away. Rich terminal output for humans, structured JSON for AI agents and pipelines. Hand DeepTutor a SKILL.md and your agents can operate it autonomously.
• Optional Authentication — Disabled by default for local use. Flip two env vars to require login when hosting publicly. Multi-user support with bcrypt-hashed passwords, JWT sessions, a self-service registration page, and a built-in admin dashboard for managing accounts and roles. Optionally back auth and storage with PocketBase for OAuth-ready authentication and improved multi-user concurrency — drops in as an optional sidecar with no code changes required.

Before you begin, make sure the following are installed on your system:

Windows only (missing compiler fix): If you do not have Visual Studio, install Visual Studio Build Tools and ensure the Desktop development with C++ workload is selected.

You'll also need an API key from at least one LLM provider (e.g. OpenAI, DeepSeek, Anthropic). The Setup Tour will walk you through entering it.

A guided CLI wizard for first-time local Web setup. It checks your environment, installs Python and Node.js dependencies, writes .env, and lets you choose optional add-ons such as TutorBot, Matrix, and Math Animator.

1. Clone the repository

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

2. Create and activate a Python environment

Pick one of the following based on your system.

macOS / Linux with venv:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Windows PowerShell with venv:

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

Anaconda / Miniconda:

conda create -n deeptutor python=3.11
conda activate deeptutor
python -m pip install --upgrade pip

3. Launch the guided tour

python scripts/start_tour.py

During the install step, the tour asks which dependency profile you want:

Once the wizard finishes:

python scripts/start_web.py

Daily launch — The tour is only needed once. From now on, keep that Python environment activated and run python scripts/start_web.py to boot both the backend and frontend. The frontend URL is printed in the terminal. Re-run start_tour.py only if you want to reconfigure providers, change ports, or install optional add-ons.

Updating a local install — If you installed with Option A or Option B from a git clone, run python scripts/update.py. The updater fetches the remote for your current branch, shows the local-vs-remote commit gap, asks you to confirm the detected branch mapping, then performs a safe fast-forward pull.

Use this path if you prefer to run each setup command yourself.

1. Clone the repository

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

2. Create and activate a Python environment

Pick one of the following.

macOS / Linux with venv:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Windows PowerShell with venv:

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

Anaconda / Miniconda:

conda create -n deeptutor python=3.11
conda activate deeptutor
python -m pip install --upgrade pip

3. Install dependencies

# Backend + Web server dependencies. Includes CLI, RAG, document parsing,
# and built-in LLM provider SDKs.
python -m pip install -e ".[server]"

# Optional add-ons — install only the ones you need:
#   python -m pip install -e ".[tutorbot]"       # TutorBot engine + channel SDKs
#   python -m pip install -e ".[tutorbot,matrix]" # TutorBot + Matrix channel; requires libolm
#   python -m pip install -e ".[math-animator]"  # Manim; also requires LaTeX/ffmpeg/system build tools
#   python -m pip install -e ".[all]"            # Everything above + dev tools

# Frontend dependencies. Requires Node.js 20.9+.
cd web
npm install
cd ..

4. Configure environment

cp .env.example .env

Edit .env and fill in at least the LLM fields. Embedding fields are needed for Knowledge Base features and can be left for later if you only want to try chat first.

# LLM (required for chat)
LLM_BINDING=openai
LLM_MODEL=gpt-4o-mini
LLM_API_KEY=sk-xxx
LLM_HOST=https://api.openai.com/v1

# Embedding (required for Knowledge Base / RAG)
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_API_KEY=sk-xxx
# v1.3.0+: use the full endpoint URL, not just https://api.openai.com/v1
EMBEDDING_HOST=https://api.openai.com/v1/embeddings
# Leave empty unless you need to force a specific dimension.
EMBEDDING_DIMENSION=

5. Start services

The quickest way to launch everything:

python scripts/start_web.py

This starts both the backend and frontend. Keep the terminal open, then open the frontend URL printed in the terminal.

Alternatively, start each service manually in separate terminals:

# Backend (FastAPI)
python -m deeptutor.api.run_server

# Frontend (Next.js) — in a separate terminal
cd web && npm run dev -- -p 3782

Open http://localhost:3782 and you're ready to go.

Docker wraps the backend and frontend into a single container — no local Python or Node.js required. You only need Docker Desktop (or Docker Engine + Compose on Linux).

1. Configure environment variables (required for both options below)

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
cp .env.example .env

Edit .env and fill in at least the required fields (same as Option B above).

2a. Pull official image (recommended)

Official images are published to GitHub Container Registry on every release, built for linux/amd64 and linux/arm64.

docker compose -f docker-compose.ghcr.yml up -d

To pin a specific version, edit the image tag in docker-compose.ghcr.yml:

image: ghcr.io/hkuds/deeptutor:1.3.4  # or :latest

2b. Build from source

docker compose up -d

This builds the image locally from Dockerfile and starts the container.

3. Verify & manage

Open http://localhost:3782 once the container is healthy.

docker compose logs -f   # tail logs
docker compose down       # stop and remove container

# Set to the public URL where the backend is reachable
NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001

# Generate a bcrypt hash on any host with the project checked out:
python -c "from deeptutor.services.auth import hash_password; print(hash_password('yourpassword'))"

AUTH_ENABLED=true
AUTH_USERNAME=admin
AUTH_PASSWORD_HASH=<paste hash here>
# Optional. Auto-generated under multi-user/_system/auth/auth_secret if blank.
AUTH_SECRET=your-secret-here

# PocketBase starts automatically alongside DeepTutor when using docker compose
docker compose up -d

# 1. Open the admin panel and create your admin account
open http://localhost:8090/_/

# 2. Bootstrap collections (run once)
pip install pocketbase
python scripts/pb_setup.py

# 3. Enable PocketBase in .env and restart

POCKETBASE_URL=http://localhost:8090          # or http://pocketbase:8090 inside Docker
POCKETBASE_ADMIN_EMAIL=admin@example.com
POCKETBASE_ADMIN_PASSWORD=your-admin-password

devenv up   # starts PocketBase on :8090 alongside backend and frontend

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

BACKEND_PORT=9001
FRONTEND_PORT=4000

docker compose up -d     # or docker compose -f docker-compose.ghcr.yml up -d

If you just want the CLI without the web frontend:

# Includes RAG, document parsing, and all built-in LLM provider SDKs.
# Same set as Option B minus FastAPI/uvicorn.
python -m pip install -e ".[cli]"

You still need to configure your LLM provider. The quickest way:

cp .env.example .env   # then edit .env to fill in your API keys

Once configured, you're ready to go:

deeptutor chat                                   # Interactive REPL
deeptutor run chat "Explain Fourier transform"   # One-shot capability
deeptutor run deep_solve "Solve x^2 = 4"         # Multi-agent problem solving
deeptutor kb create my-kb --doc textbook.pdf     # Build a knowledge base

See DeepTutor CLI for the full feature guide and command reference.

Six distinct modes coexist in a single workspace, bound by a unified context management system. Conversation history, knowledge bases, and references persist across modes — switch between them freely within the same topic, whenever the moment calls for it.

Tools are decoupled from workflows — in every mode, you decide which tools to enable, how many to use, or whether to use any at all. The workflow orchestrates the reasoning; the tools are yours to compose.

Start with a quick chat question, escalate to Deep Solve when it gets hard, visualize a concept, generate quiz questions to test yourself, then launch a Deep Research to go deeper — all in one continuous thread.

Co-Writer brings the intelligence of Chat directly into a writing surface. Create and manage multiple documents, each persisted in its own workspace — not a single throwaway scratchpad, but a full-featured multi-document Markdown editor where AI is a first-class collaborator.

Select any text and choose Rewrite, Expand, or Shorten — optionally drawing context from your knowledge base or the web. The editing flow is non-destructive with full undo/redo, and every piece you write can be saved straight to your notebooks, feeding back into your learning ecosystem.

Give DeepTutor a topic, point it at your knowledge base, and it produces a structured, interactive book — not a static export, but a living document you can read, quiz yourself on, and discuss in context.

Behind the scenes, a multi-agent pipeline handles the heavy lifting: proposing an outline, retrieving relevant sources from your knowledge base, synthesizing a chapter tree, planning each page, and compiling every block. You stay in control — review the proposal, reorder chapters, and chat alongside any page.

Pages are assembled from 13 block types — text, callout, quiz, flash cards, code, figure, deep dive, animation, interactive demo, timeline, concept graph, section, and user note — each rendered with its own interactive component. A real-time progress timeline lets you watch compilation unfold as the book takes shape.

Knowledge is where you build and manage the document collections, notes, and teaching personas that power everything else in DeepTutor.

• Knowledge Bases — Upload PDFs, Office files (DOCX/XLSX/PPTX), Markdown, and a wide range of text and code files to create searchable, RAG-ready collections. Add documents incrementally as your library grows.
• Notebooks — Organize learning records across sessions. Save insights from Chat, Co-Writer, Book, or Deep Research into categorized, color-coded notebooks.
• Question Bank — Browse and revisit all generated quiz questions. Bookmark entries and @-mention them directly in chat to reason over past performance.
• Skills — Create custom teaching personas via SKILL.md files. Each skill defines a name, description, optional triggers, and a Markdown body that is injected into the chat system prompt when active — turning DeepTutor into a Socratic tutor, a peer study partner, a research assistant, or any role you design.

Your knowledge base is not passive storage — it actively participates in every conversation, every research session, and every learning path you create.

DeepTutor maintains a persistent, evolving understanding of you through two complementary dimensions:

• Summary — A running digest of your learning progress: what you've studied, which topics you've explored, and how your understanding has developed.
• Profile — Your learner identity: preferences, knowledge level, goals, and communication style — automatically refined through every interaction.

Memory is shared across all features and all your TutorBots. The more you use DeepTutor, the more personalized and effective it becomes.

TutorBot is not a chatbot — it is a persistent, multi-instance agent built on nanobot. Each TutorBot runs its own agent loop with independent workspace, memory, and personality. Create a Socratic math tutor, a patient writing coach, and a rigorous research advisor — all running simultaneously, each evolving with you.

• Soul Templates — Define your tutor's personality, tone, and teaching philosophy through editable Soul files. Choose from built-in archetypes (Socratic, encouraging, rigorous) or craft your own — the soul shapes every response.
• Independent Workspace — Each bot has its own directory with separate memory, sessions, skills, and configuration — fully isolated yet able to access DeepTutor's shared knowledge layer.
• Proactive Heartbeat — Bots don't just respond — they initiate. The built-in Heartbeat system enables recurring study check-ins, review reminders, and scheduled tasks. Your tutor shows up even when you don't.
• Full Tool Access — Every bot reaches into DeepTutor's complete toolkit: RAG retrieval, code execution, web search, academic paper search, deep reasoning, and brainstorming.
• Skill Learning — Teach your bot new abilities by adding skill files to its workspace. As your needs evolve, so does your tutor's capability.
• Multi-Channel Presence — Connect bots to Telegram, Discord, Slack, Feishu, WeChat Work, DingTalk, Matrix, QQ, WhatsApp, Email, and more. Your tutor meets you wherever you are.
• Team & Sub-Agents — Spawn background sub-agents or orchestrate multi-agent teams within a single bot for complex, long-running tasks.

deeptutor bot create math-tutor --persona "Socratic math teacher who uses probing questions"
deeptutor bot create writing-coach --persona "Patient, detail-oriented writing mentor"
deeptutor bot list                  # See all your active tutors

DeepTutor is fully CLI-native. Every capability, knowledge base, session, memory, and TutorBot is one command away — no browser required. The CLI serves both humans (with rich terminal rendering) and AI agents (with structured JSON output).

Hand the SKILL.md at the project root to any tool-using agent (nanobot, or any LLM with tool access), and it can configure and operate DeepTutor autonomously.

One-shot execution — Run any capability directly from the terminal:

deeptutor run chat "Explain the Fourier transform" -t rag --kb textbook
deeptutor run deep_solve "Prove that √2 is irrational" -t reason
deeptutor run deep_question "Linear algebra" --config num_questions=5
deeptutor run deep_research "Attention mechanisms in transformers"
deeptutor run visualize "Draw the architecture of a transformer"

Interactive REPL — A persistent chat session with live mode switching:

deeptutor chat --capability deep_solve --kb my-kb
# Inside the REPL: /cap, /tool, /kb, /history, /notebook, /config to switch on the fly

Knowledge base lifecycle — Build, query, and manage RAG-ready collections entirely from the terminal:

deeptutor kb create my-kb --doc textbook.pdf       # Create from document
deeptutor kb add my-kb --docs-dir ./papers/         # Add a folder of papers
deeptutor kb search my-kb "gradient descent"        # Search directly
deeptutor kb set-default my-kb                      # Set as default for all commands

Dual output mode — Rich rendering for humans, structured JSON for pipelines:

deeptutor run chat "Summarize chapter 3" -f rich    # Colored, formatted output
deeptutor run chat "Summarize chapter 3" -f json    # Line-delimited JSON events

Session continuity — Resume any conversation right where you left off:

deeptutor session list                              # List all sessions
deeptutor session open <id>                         # Resume in REPL

Flip on authentication and DeepTutor turns into a multi-tenant deployment with per-user isolated workspaces and admin-curated resources. The first person to register becomes the admin and configures models, API keys, and knowledge bases on behalf of everyone else. Subsequent accounts are created by the admin (invite-only), each gets their own scoped chat history / memory / notebooks / knowledge bases, and they only see the LLMs, KBs, and skills the admin assigned to them.

Quick start (5 steps):

# 1. In the project root .env, enable auth.
echo 'AUTH_ENABLED=true' >> .env
# Optional — JWT signing secret. Auto-generated on first boot if blank.
echo 'AUTH_SECRET=<paste 64+ random characters>' >> .env

# 2. Restart the web stack — start_web.py mirrors AUTH_ENABLED to the frontend.
python scripts/start_web.py

# 3. Open http://localhost:3782/register and create the first account.
#    The first registration is the only public one; that user becomes admin
#    and the /register endpoint is closed automatically afterward.

# 4. As admin, navigate to /admin/users → "Add user" to provision teammates.

# 5. For each user, click the slider icon → assign LLM profiles, knowledge
#    bases, and skills. Save. The user can now sign in and start working.

What the admin sees:

• Full Settings page at /settings — manage LLM / embedding / search providers, API keys, model catalogs, and runtime "Apply".
• User management at /admin/users — create, promote, demote, and delete accounts. The public /register endpoint is automatically closed once the first admin exists; further accounts go through POST /api/v1/auth/users (admin-only).
• Grant editor — for each non-admin user, pick the model profiles, knowledge bases, and skills they may use. Grants carry logical IDs only; API keys never cross the grant boundary.
• Audit trail — every grant change and assigned-resource access is appended to multi-user/_system/audit/usage.jsonl.

What ordinary users get:

• Isolated workspace under multi-user/<uid>/ — their own chat history (chat_history.db), memory (SUMMARY.md / PROFILE.md), notebooks, and personal knowledge bases. Nothing is shared by default.
• Read-only access to admin-assigned knowledge bases and skills, surfaced inline next to their own resources with an "Assigned by admin" badge.
• Redacted Settings page — only theme, language, and a summary of granted models. API keys, base URLs, and provider endpoints are never returned for non-admin requests.
• Scoped LLM — chat turns are routed through the admin-assigned model. If no LLM is granted, the turn is rejected up-front (no silent fallback to the admin's keys).

Workspace layout:

multi-user/
├── _system/
│   ├── auth/users.json          # Hashed credentials, roles
│   ├── auth/auth_secret         # JWT signing secret (auto-generated)
│   ├── grants/<uid>.json        # Per-user resource grants (admin-managed)
│   └── audit/usage.jsonl        # Audit trail
└── <uid>/
    ├── user/
    │   ├── chat_history.db
    │   ├── settings/interface.json
    │   └── workspace/{chat,co-writer,book,...}
    ├── memory/{SUMMARY.md,PROFILE.md}
    └── knowledge_bases/...

Configuration reference:

⚠️ PocketBase mode (POCKETBASE_URL set) is single-user only. The default PocketBase schema has no role field on users (every login resolves to role=user, no admin can be created), and sessions / messages / turns queries are not filtered by user_id. Multi-user deployments must keep POCKETBASE_URL blank and use the default JSON/SQLite backend.

⚠️ Single-process recommendation. The first-user-becomes-admin promotion is protected by an in-process threading.Lock. Multi-worker deployments should provision the first admin offline (start with AUTH_ENABLED=false, register the admin via python scripts/start_tour.py or the bootstrap flow, then flip the flag) or back the user store with an external system.

If you find DeepTutor useful, give us a star — it helps us keep going!

DeepTutor stands on the shoulders of outstanding open-source projects:

From the HKUDS ecosystem:

We hope DeepTutor becomes a gift for the community. 🎁

See CONTRIBUTING.md for guidelines on setting up your development environment, code standards, and pull request workflow.