🤝 We welcome any kinds of contributing! Vote on roadmap items or propose new ones at Roadmap, and see our Contributing Guide for branching strategy, coding standards, and how to get started.

📦 Releases

[2026.5.28] v1.4.2 — Stability + polish on v1.4.1: Gemini 2.5+ unblocked across Visualize and Chat, ContextVar auth-routing fix (#485), reasoning + native-tools label protocol hardened, smooth-streaming UX on every chat surface, new collapsible Recents sidebar, and Lemonade local-provider support.

[2026.5.27] v1.4.1 — Security + stability patch: TutorBot tool sandbox locked down, per-user resource isolation, multimodal image fallback for vision-capable providers, an HTTP/SSE API for talking to a TutorBot, and a v1.4.0 chat regression fix.

[2026.5.22] v1.4.0 — GA cut of v1.4: Auto Mode, three-layer Memory, agentic Deep Research / Solve / Question, LlamaIndex RAG refactor, Visualize/Animator merge, plus reasoning-effort normalization, tool-schema fallback, and restart-safe turn runtime.

[2026.5.21] v1.4.0-beta — Three-layer Memory workbench (L1/L2/L3), every chat capability rebuilt on a single agentic engine, LlamaIndex-only RAG, and a unified Settings + Capabilities surface.

📰 News

[2026.5.22] 🌐 Our official docs site is live at deeptutor.info — guides, references, and capability tours all in one place.

[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!

✨ Key Features

Work surfaces

• Chat — Chat, Solve, Quiz, Research, and Visualize share one session, knowledge base, and citation history, so you can escalate mid-conversation without losing context.
• Co-Writer — split-view Markdown workspace where any selection can be rewritten, expanded, or shortened, optionally grounded by your KB or the web. Drafts save straight to notebooks.
• Book Engine — a multi-agent pipeline compiles your materials into interactive "living books" with 13 block types: quizzes, flash cards, timelines, concept graphs, an embedded GeoGebra viewer, animations, and more. Pages are KB-fingerprinted, so drift is detectable.

Your library

• Knowledge Bases — versioned RAG-ready collections, end-to-end on LlamaIndex. Every (re-)index is tracked, comparable, and rollback-able.
• Space — a personal review library bundling chat history, notebooks, question bank, and user-authored skills (SKILL.md) that switch DeepTutor's persona.
• Three-layer memory — append-only L1 traces, L2 per-surface curated facts with citations, and L3 cross-surface synthesis. An inspectable workbench and a memory graph let you audit why DeepTutor knows what it knows.

Extensibility & control

• Composable tools — RAG, web search, code execution, reasoning, brainstorming, paper search, GeoGebra analysis, and chat helpers (ask_user, web_fetch, write_note, list_notebook, github_query). MCP servers plug in alongside built-ins.
• Personal TutorBots — persistent, autonomous tutors, each with its own workspace, soul, skills, and channels (Telegram, Discord, Slack, Matrix, Zulip, …). Built on nanobot.
• Unified settings — one draft / Apply workbench for appearance, models, embeddings, search, capabilities, memory, MCP servers, and tools, with shared per-call cost tracking.
• Agent-native CLI — every capability, KB, session, and TutorBot is one command away; rich output for humans, structured JSON for agents. Hand any tool-using LLM the SKILL.md and it can drive DeepTutor on its own.
• Optional authentication — off by default; opt in for multi-user deployments with bcrypt + JWT, an admin dashboard, and an optional PocketBase / OAuth sidecar.

🚀 Get Started

DeepTutor ships four installation paths. They all share one workspace layout: settings live in data/user/settings/ under the directory you launch from (or under DEEPTUTOR_HOME / deeptutor start --home if you set one explicitly). For the full app, the recommended flow is pick a workspace directory → install → deeptutor init → deeptutor start.

✨ v1.4.2 is live. pip install -U deeptutor picks up the latest stable. Pre-releases (when available) opt in with pip install --pre -U deeptutor.

Option 1 — Install From PyPI

Full local Web app + CLI, no clone required. Needs Python 3.11+ and a Node.js 20+ runtime on PATH (the packaged Next.js standalone server is spawned by deeptutor start).

mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init     # prompts for ports + LLM provider + optional embedding
deeptutor start    # starts backend + frontend; keep the terminal open

deeptutor init prompts for backend port (default 8001), frontend port (default 3782), LLM provider / base URL / API key / model, and an optional embedding provider for Knowledge Base / RAG.

After deeptutor start, open the frontend URL printed in the terminal — by default http://127.0.0.1:3782. Press Ctrl+C in that terminal to stop both backend and frontend. Skipping deeptutor init is fine for a quick trial; the app boots with default ports and empty model settings, configure them later in Settings → Models.

Option 2 — Install From Source

For development against a checkout. Use Python 3.11+ and Node.js 22 LTS to match CI and Docker.

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

# Create a venv (macOS/Linux). Windows PowerShell:
#   py -3.11 -m venv .venv ; .\.venv\Scripts\Activate.ps1
python3 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip

# Install backend + frontend deps
python -m pip install -e .
( cd web && npm ci --legacy-peer-deps )

deeptutor init
deeptutor start

Source installs run Next.js in dev mode against the local web/ directory; everything else (config layout, ports, stop with Ctrl+C) matches Option 1.

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

pip install -e ".[dev]"             # tests/lint tools
pip install -e ".[tutorbot]"        # TutorBot engine + channel SDKs
pip install -e ".[matrix]"          # Matrix channel without E2EE/libolm
pip install -e ".[matrix-e2e]"      # Matrix E2EE; requires libolm
pip install -e ".[math-animator]"   # Manim addon; requires LaTeX/ffmpeg/system libs

rm -f web/.next/dev/lock web/.next/lock
deeptutor start

Option 3 — Docker

One container for the full Web app. Images on GitHub Container Registry:

• ghcr.io/hkuds/deeptutor:latest — stable release
• ghcr.io/hkuds/deeptutor:pre — pre-release, when available

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -p 127.0.0.1:8001:8001 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

⚠️ Map both 3782 and 8001. 3782 serves the web UI; 8001 is the FastAPI backend that your browser calls directly — there is no in-container proxy. Skip the 8001 mapping and the page still loads, but Settings shows "Backend unreachable" and stays unusable.

Open http://127.0.0.1:3782. The container creates /app/data/user/settings/*.json on first boot; configure model providers from the Web Settings page. Config, API keys, logs, workspace files, memory, and knowledge bases persist in the deeptutor-data volume.

• Different host ports: change the left side of each -p host:container mapping (e.g. -p 127.0.0.1:8088:3782). If you change container-side ports in /app/data/user/settings/system.json, restart and update the right side of each mapping to match.
• Detached: add -d, then docker logs -f deeptutor to follow, docker stop deeptutor to stop, docker rm deeptutor before reusing the name. The deeptutor-data volume keeps your settings and workspace across restarts.

Remote Docker / reverse proxy: the Web UI runs in the browser, so the browser needs a backend URL it can reach. For remote servers, open Settings -> Network or edit data/user/settings/system.json:

{
  "next_public_api_base_external": "https://deeptutor.example.com"
}

public_api_base is accepted as a compatibility alias and is normalized into next_public_api_base_external on save. CORS uses frontend origins, not API URLs. With auth disabled, DeepTutor permits normal HTTP/HTTPS browser origins by default. With auth enabled, add exact frontend origins:

{
  "cors_origins": ["https://deeptutor.example.com"]
}

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 -p 127.0.0.1:8001:8001 \
  --add-host=host.docker.internal:host-gateway \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

Option 4 — CLI Only

When you don't need the Web UI. The CLI-only package is installed from a source checkout, not from PyPI.

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

# Create a venv (macOS/Linux). Windows PowerShell:
#   py -3.11 -m venv .venv-cli ; .\.venv-cli\Scripts\Activate.ps1
python3 -m venv .venv-cli && source .venv-cli/bin/activate
python -m pip install --upgrade pip

python -m pip install -e ./packaging/deeptutor-cli
deeptutor init --cli
deeptutor chat

deeptutor init --cli shares the same data/user/settings/ layout as the full app but skips the backend/frontend port prompts and defaults embeddings to off (choose Yes if you plan to use deeptutor kb … or RAG tools). It still writes a complete runtime layout (system.json, auth.json, integrations.json, model_catalog.json, main.yaml, agents.yaml) and still prompts for the active LLM provider and model.

deeptutor chat                                          # interactive REPL
deeptutor chat --capability deep_solve --tool rag --kb my-kb
deeptutor run chat "Explain Fourier transform"
deeptutor run deep_solve "Solve x^2 = 4" --tool rag --kb my-kb
deeptutor kb create my-kb --doc textbook.pdf
deeptutor memory show
deeptutor config show

The local deeptutor-cli install ships no Web assets or server dependencies. Keep the source checkout around — the editable install points to it. To add the Web app later, install the PyPI package (Option 1) and run deeptutor init + deeptutor start from the same workspace.

Configuration Reference

📖 Explore DeepTutor

The v1.4.0-beta refactor reorganises DeepTutor around five core surfaces — Chat, Co-Writer, Book, Knowledge, Space — plus a three-layer Memory that sits underneath all of them and a unified Settings workbench that exposes every knob. Capabilities (Solve / Quiz / Research / Visualize) and tools (RAG, web, code, reason, brainstorm, paper search, ask_user, web_fetch, write_note, list_notebook, github_query) compose freely on top.

💬 Chat — Unified Intelligent Workspace

One thread, five modes, any tool. The capability picker lives in the composer; the same session, knowledge base, attachments, and references travel with you across modes — switch from a casual question into multi-agent solving, into a quiz, into a full research report, without losing context.

New chat tools shipped with the refactor: ask_user (asks a structured clarifying question mid-turn), web_fetch (pulls a specific URL into context), write_note / list_notebook (saves and lists notebook records from the chat surface), and github_query (issue / PR / repo lookups). Tools stay decoupled from workflows — every mode lets you opt tools in or out per turn.

A session also carries a cumulative source inventory across turns, so citations from earlier RAG / web hits remain reusable later in the same conversation.

✍️ Co-Writer — Multi-Document AI Writing Workspace

Co-Writer is a split-view Markdown workbench (raw editor on the left, live preview on the right) for notes, reports, tutorials, and AI-assisted drafts. Each document lives in its own workspace with autosave, downloadable Markdown, and one-click Save to Notebook.

Select any text and choose Rewrite, Expand, or Shorten — every action runs as a tracked agent edit that can optionally pull from a knowledge base or the web. Co-Writer renders standard Markdown / CommonMark / GFM (tables, code, math, flowcharts, sequence diagrams), supports a HTML tag escape hatch (<sub>, <sup>, <abbr>, <mark>), and ships a starter template tuned for DeepTutor product docs and learning notes.

📖 Book Engine — Interactive "Living Books"

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 KB, synthesising 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 (now including a GeoGebra viewer), timeline, concept graph, section, and user note — each rendered with its own interactive component. Book pages are fingerprinted against their source KB; deeptutor book health reports drift and deeptutor book refresh-fingerprints clears stale pages when sources change.

📚 Knowledge Bases — RAG-Ready Document Libraries

A dedicated workspace for the document collections that power RAG. Each knowledge base has four tabs:

• Files — Browse uploaded sources, preview PDFs inline, and see per-file size / status.
• Add documents — Drop in PDFs, Office files (DOCX / XLSX / PPTX), Markdown, plain text, and a wide range of code / data file types. Documents are routed through the appropriate extractor automatically.
• Index versions — Every (re-)index is a tracked version. Roll back to an earlier index, compare embedding models, or inspect chunking stats without losing the previous build.
• Settings — Pick the embedding provider / model, chunking parameters, and reranker for the KB. Defaults are inherited from your global LLM and embedding profiles.

Indexing is built on LlamaIndex end-to-end (the previous dual-pipeline split was consolidated in the v1.4 refactor), with retry-safe re-index, embedding-mismatch detection, and resilient handling of corrupt persisted vectors.

🌐 Space — Your Personal Learning Library

Space is the read / review counterpart to the active surfaces. Where Chat / Co-Writer / Book are where you produce, Space is where everything you produce lives, searchable and replayable.

• Chat History — Every conversation across every mode, with title-rename, delete, and resume; deleting individual turns is supported on every entry point.
• Notebooks — Save outputs from Chat, Research, and Co-Writer into categorised, colour-coded notebooks; each record links back to the originating session and surface.
• Question Bank — Every auto-generated quiz question, bookmarkable and @-mention-able in chat to reason over past performance.
• Skills — User-authored SKILL.md files that define teaching personas (name, description, triggers, body). When active, a skill is injected into the chat system prompt — turning DeepTutor into a Socratic tutor, a research assistant, or any role you design.

🧠 Memory — Three-Layer Architecture

DeepTutor's memory is now a three-layer pipeline with an inspectable workbench at /memory. The two-file v1 SUMMARY.md / PROFILE.md model is gone; everything is migrated into the new layout on first boot.

Seven surfaces feed the pipeline: chat, notebook, quiz, kb, book, tutorbot, cowriter. The consolidator is LLM-driven and runs asynchronously (POST /memory/runs/start) — you can fire it from the workbench, watch L1 → L2 → L3 propagate, and edit any layer by hand.

The Memory Graph (/memory/graph) renders all three layers at once: L3 synthesis at the centre, L2 facts in the middle ring, L1 traces on the outside, grouped by surface. Hover any node for an inline preview; click to lock the highlight and trace the L3 → L2 → L1 references inward, so you can audit why DeepTutor "knows" something about you.

⚙️ Settings — Unified Control Center

The settings surface was unified in v1.4 and split by concern, with a draft / Apply model so changes are atomic and can be reverted before save:

• Appearance — UI language and theme (Cream, Snow, Dark, Glass).
• Status — Live health probe across LLM, embedding, search, and storage backends.
• LLM, Embedding, Search — Provider catalog, base URLs, API keys, and active model selection. Active models are picked from the catalog so every surface stays in sync.
• Capabilities — Per-capability tunables (chunking, LLM budget, dedup and reference policies, max iterations) for Chat, Solve, Quiz, Research, Visualize, and Co-Writer. Backed by a unified emit_capability_result envelope and a shared UsageTracker that surfaces per-call cost.
• Memory — Toggle consolidator runs, configure cadence and budget, and jump into the memory workbench.
• MCP servers — Register external Model Context Protocol servers; their tools are surfaced alongside built-in tools.
• Tools — Inspect every built-in tool, its parameters, status (enabled / coming-soon), and i18n status copy.

A "Tour" launcher walks new users through the page, and every capability ships a canonical capabilities/prompts/{en,zh}/<name>.yaml so status messages stay consistent in both English and 中文.

🦞 TutorBot — Persistent, Autonomous AI Tutors

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 CLI — Agent-Native Interface

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.

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"

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

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

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

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

👥 Multi-User — Shared Deployments with Per-User Workspaces

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. Enable auth in data/user/settings/auth.json:
#    {"enabled": true, "token_expire_hours": 24, "cookie_secure": false}
#    Use cookie_secure=true for HTTPS deployments where Web and API are cross-site.

# 2. Restart the web stack.
deeptutor start

# 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 (integrations.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 integrations.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.json.enabled=false, register the admin via the bootstrap flow, then set auth.json.enabled=true) or back the user store with an external system.

🌐 Community & Ecosystem

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

From the HKUDS ecosystem:

🤝 Contributing

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.

⭐ Star History