# DeepTutor: Agent-Native Personalized Tutoring

[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/) [![Next.js 16](https://img.shields.io/badge/Next.js-16-000000?style=flat-square&logo=next.js&logoColor=white)](https://nextjs.org/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](LICENSE) [![GitHub release](https://img.shields.io/github/v/release/HKUDS/DeepTutor?style=flat-square&color=brightgreen)](https://github.com/HKUDS/DeepTutor/releases) [![arXiv](https://img.shields.io/badge/arXiv-2604.26962-b31b1b?style=flat-square&logo=arxiv&logoColor=white)](https://arxiv.org/abs/2604.26962) [![Discord](https://img.shields.io/badge/Discord-Community-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/eRsjPgMU4t) [![Feishu](https://img.shields.io/badge/Feishu-Group-00D4AA?style=flat-square&logo=feishu&logoColor=white)](./Communication.md) [![WeChat](https://img.shields.io/badge/WeChat-Group-07C160?style=flat-square&logo=wechat&logoColor=white)](https://github.com/HKUDS/DeepTutor/issues/78) [Features](#-key-features) · [Get Started](#-get-started) · [Explore](#-explore-deeptutor) · [TutorBot](#-tutorbot--persistent-autonomous-ai-tutors) · [CLI](#%EF%B8%8F-deeptutor-cli--agent-native-interface) · [Roadmap](#%EF%B8%8F-roadmap) · [Community](#-community--ecosystem) [🇨🇳 中文](assets/README/README_CN.md) · [🇯🇵 日本語](assets/README/README_JA.md) · [🇪🇸 Español](assets/README/README_ES.md) · [🇫🇷 Français](assets/README/README_FR.md) · [🇸🇦 العربية](assets/README/README_AR.md) · [🇷🇺 Русский](assets/README/README_RU.md) · [🇮🇳 हिन्दी](assets/README/README_HI.md) · [🇵🇹 Português](assets/README/README_PT.md) · [🇹🇭 ภาษาไทย](assets/README/README_TH.md) · 🇵🇱 [Polski](assets/README/README_PL.md)

--- > 🤝 **We welcome any kinds of contributing!** See our [Contributing Guide](CONTRIBUTING.md) for branching strategy, coding standards, and how to get started. ### 📦 Releases > **[2026.5.2]** [v1.3.5](https://github.com/HKUDS/DeepTutor/releases/tag/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](https://github.com/HKUDS/DeepTutor/releases/tag/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](https://github.com/HKUDS/DeepTutor/releases/tag/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](https://github.com/HKUDS/DeepTutor/releases/tag/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](https://github.com/HKUDS/DeepTutor/releases/tag/v1.3.1) — Stability: safer RAG routing & embedding validation, Docker persistence, IME-safe input, Windows/GBK robustness. > **[2026.4.27]** [v1.3.0](https://github.com/HKUDS/DeepTutor/releases/tag/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](https://github.com/HKUDS/DeepTutor/releases/tag/v1.2.5) — Persistent chat attachments with file-preview drawer, attachment-aware capability pipelines, TutorBot Markdown export. > **[2026.4.25]** [v1.2.4](https://github.com/HKUDS/DeepTutor/releases/tag/v1.2.4) — Text/code/SVG attachments, one-command Setup Tour, Markdown chat export, compact KB management UI. > **[2026.4.24]** [v1.2.3](https://github.com/HKUDS/DeepTutor/releases/tag/v1.2.3) — Document attachments (PDF/DOCX/XLSX/PPTX), reasoning thinking-block display, Soul template editor, Co-Writer save-to-notebook. > **[2026.4.22]** [v1.2.2](https://github.com/HKUDS/DeepTutor/releases/tag/v1.2.2) — User-authored Skills system, chat input performance overhaul, TutorBot auto-start, Book Library UI, visualization fullscreen. > **[2026.4.21]** [v1.2.1](https://github.com/HKUDS/DeepTutor/releases/tag/v1.2.1) — Per-stage token limits, Regenerate response across all entry points, RAG & Gemma compatibility fixes. > **[2026.4.20]** [v1.2.0](https://github.com/HKUDS/DeepTutor/releases/tag/v1.2.0) — Book Engine "living book" compiler, multi-document Co-Writer, interactive HTML visualizations, Question Bank @-mention. > **[2026.4.18]** [v1.1.2](https://github.com/HKUDS/DeepTutor/releases/tag/v1.1.2) — Schema-driven Channels tab, RAG single-pipeline consolidation, externalized chat prompts. > **[2026.4.17]** [v1.1.1](https://github.com/HKUDS/DeepTutor/releases/tag/v1.1.1) — Universal "Answer now", Co-Writer scroll sync, unified settings panel, streaming Stop button.

Past releases (more than 2 weeks ago)

> **[2026.4.15]** [v1.1.0](https://github.com/HKUDS/DeepTutor/releases/tag/v1.1.0) — LaTeX block math overhaul, LLM diagnostic probe, Docker + local LLM guidance. > **[2026.4.14]** [v1.1.0-beta](https://github.com/HKUDS/DeepTutor/releases/tag/v1.1.0-beta) — Bookmarkable sessions, Snow theme, WebSocket heartbeat & auto-reconnect, embedding registry overhaul. > **[2026.4.13]** [v1.0.3](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.3) — Question Notebook with bookmarks & categories, Mermaid in Visualize, embedding mismatch detection, Qwen/vLLM compatibility, LM Studio & llama.cpp support, and Glass theme. > **[2026.4.11]** [v1.0.2](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.2) — Search consolidation with SearXNG fallback, provider switch fix, and frontend resource leak fixes. > **[2026.4.10]** [v1.0.1](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.1) — Visualize capability (Chart.js/SVG), quiz duplicate prevention, and o4-mini model support. > **[2026.4.10]** [v1.0.0-beta.4](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.0-beta.4) — Embedding progress tracking with rate-limit retry, cross-platform dependency fixes, and MIME validation fix. > **[2026.4.8]** [v1.0.0-beta.3](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.0-beta.3) — Native OpenAI/Anthropic SDK (drop litellm), Windows Math Animator support, robust JSON parsing, and full Chinese i18n. > **[2026.4.7]** [v1.0.0-beta.2](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.0-beta.2) — Hot settings reload, MinerU nested output, WebSocket fix, and Python 3.11+ minimum. > **[2026.4.4]** [v1.0.0-beta.1](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.0-beta.1) — Agent-native architecture rewrite (~200k lines): Tools + Capabilities plugin model, CLI & SDK, TutorBot, Co-Writer, Guided Learning, and persistent memory. > **[2026.1.23]** [v0.6.0](https://github.com/HKUDS/DeepTutor/releases/tag/v0.6.0) — Session persistence, incremental document upload, flexible RAG pipeline import, and full Chinese localization. > **[2026.1.18]** [v0.5.2](https://github.com/HKUDS/DeepTutor/releases/tag/v0.5.2) — Docling support for RAG-Anything, logging system optimization, and bug fixes. > **[2026.1.15]** [v0.5.0](https://github.com/HKUDS/DeepTutor/releases/tag/v0.5.0) — Unified service configuration, RAG pipeline selection per knowledge base, question generation overhaul, and sidebar customization. > **[2026.1.9]** [v0.4.0](https://github.com/HKUDS/DeepTutor/releases/tag/v0.4.0) — Multi-provider LLM & embedding support, new home page, RAG module decoupling, and environment variable refactor. > **[2026.1.5]** [v0.3.0](https://github.com/HKUDS/DeepTutor/releases/tag/v0.3.0) — Unified PromptManager architecture, GitHub Actions CI/CD, and pre-built Docker images on GHCR. > **[2026.1.2]** [v0.2.0](https://github.com/HKUDS/DeepTutor/releases/tag/v0.2.0) — Docker deployment, Next.js 16 & React 19 upgrade, WebSocket security hardening, and critical vulnerability fixes.

### 📰 News > **[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](https://arxiv.org/abs/2604.26962) 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](https://discord.gg/eRsjPgMU4t), [WeChat](https://github.com/HKUDS/DeepTutor/issues/78), or [Discussions](https://github.com/HKUDS/DeepTutor/discussions) — let's shape the future of DeepTutor together! > **[2025.12.29]** DeepTutor is officially released! ## ✨ Key Features - **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 14 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](https://github.com/HKUDS/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`](SKILL.md) and your agents can operate it autonomously. --- ## 🚀 Get Started ### Prerequisites Before you begin, make sure the following are installed on your system: | Requirement | Version | Check | Notes | |:---|:---|:---|:---| | [Git](https://git-scm.com/) | Any | `git --version` | For cloning the repository | | [Python](https://www.python.org/downloads/) | 3.11+ | `python --version` | Backend runtime | | [Node.js](https://nodejs.org/) | 20.9+ | `node --version` | Frontend runtime for local Web installs | | [npm](https://www.npmjs.com/) | Bundled with Node.js | `npm --version` | Installed with Node.js | > **Windows only (missing compiler fix):** If you do not have Visual Studio, install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-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](https://platform.openai.com/api-keys), [DeepSeek](https://platform.deepseek.com/), [Anthropic](https://console.anthropic.com/)). The Setup Tour will walk you through entering it. ### Option A — Setup Tour (Recommended) 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** ```bash 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`: ```bash python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip ``` Windows PowerShell with `venv`: ```powershell py -3.11 -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip ``` Anaconda / Miniconda: ```bash conda create -n deeptutor python=3.11 conda activate deeptutor python -m pip install --upgrade pip ``` **3. Launch the guided tour** ```bash python scripts/start_tour.py ``` During the install step, the tour asks which dependency profile you want: | Choice | What it installs | When to choose it | |:---|:---|:---| | Web app (recommended) | CLI + API server + RAG/document parsing | Most first-time users | | Web + TutorBot | Adds TutorBot engine and common channel SDKs | If you want autonomous tutor bots or channel integrations | | Web + TutorBot + Matrix | Adds Matrix / Element channel support | Only if you already have `libolm` installed or are ready to install it | | Math Animator add-on | Installs Manim separately | Only if you need animation generation and have LaTeX/ffmpeg/system build tools ready | Once the wizard finishes: ```bash 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. ### Option B — Manual Local Install Use this path if you prefer to run each setup command yourself. **1. Clone the repository** ```bash 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`: ```bash python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip ``` Windows PowerShell with `venv`: ```powershell py -3.11 -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip ``` Anaconda / Miniconda: ```bash conda create -n deeptutor python=3.11 conda activate deeptutor python -m pip install --upgrade pip ``` **3. Install dependencies** ```bash # 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** ```bash 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. ```dotenv # 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= ```

Supported LLM Providers

| Provider | Binding | Default Base URL | |:--|:--|:--| | AiHubMix | `aihubmix` | `https://aihubmix.com/v1` | | Anthropic | `anthropic` | `https://api.anthropic.com/v1` | | Azure OpenAI | `azure_openai` | — | | BytePlus | `byteplus` | `https://ark.ap-southeast.bytepluses.com/api/v3` | | BytePlus Coding Plan | `byteplus_coding_plan` | `https://ark.ap-southeast.bytepluses.com/api/coding/v3` | | Custom | `custom` | — | | Custom (Anthropic API) | `custom_anthropic` | — | | DashScope | `dashscope` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | | DeepSeek | `deepseek` | `https://api.deepseek.com` | | Gemini | `gemini` | `https://generativelanguage.googleapis.com/v1beta/openai/` | | GitHub Copilot | `github_copilot` | `https://api.githubcopilot.com` | | Groq | `groq` | `https://api.groq.com/openai/v1` | | llama.cpp | `llama_cpp` | `http://localhost:8080/v1` | | LM Studio | `lm_studio` | `http://localhost:1234/v1` | | MiniMax | `minimax` | `https://api.minimaxi.com/v1` | | MiniMax (Anthropic) | `minimax_anthropic` | `https://api.minimaxi.com/anthropic` | | Mistral | `mistral` | `https://api.mistral.ai/v1` | | Moonshot | `moonshot` | `https://api.moonshot.cn/v1` | | Ollama | `ollama` | `http://localhost:11434/v1` | | OpenAI | `openai` | `https://api.openai.com/v1` | | OpenAI Codex | `openai_codex` | `https://chatgpt.com/backend-api` | | OpenRouter | `openrouter` | `https://openrouter.ai/api/v1` | | OpenVINO Model Server | `ovms` | `http://localhost:8000/v3` | | Qianfan | `qianfan` | `https://qianfan.baidubce.com/v2` | | SiliconFlow | `siliconflow` | `https://api.siliconflow.cn/v1` | | Step Fun | `stepfun` | `https://api.stepfun.com/v1` | | vLLM/Local | `vllm` | — | | VolcEngine | `volcengine` | `https://ark.cn-beijing.volces.com/api/v3` | | VolcEngine Coding Plan | `volcengine_coding_plan` | `https://ark.cn-beijing.volces.com/api/coding/v3` | | Xiaomi MIMO | `xiaomi_mimo` | `https://api.xiaomimimo.com/v1` | | Zhipu AI | `zhipu` | `https://open.bigmodel.cn/api/paas/v4` |

Supported Embedding Providers

| Provider | Binding | Model Example | Default Dim | |:--|:--|:--|:--| | OpenAI | `openai` | `text-embedding-3-large` | 3072 | | Azure OpenAI | `azure_openai` | deployment name | — | | Cohere | `cohere` | `embed-v4.0` | 1024 | | Jina | `jina` | `jina-embeddings-v3` | 1024 | | Ollama | `ollama` | `nomic-embed-text` | 768 | | vLLM / LM Studio | `vllm` | Any embedding model | — | | Any OpenAI-compatible | `custom` | — | — | OpenAI-compatible providers (DashScope, SiliconFlow, etc.) work via the `custom` or `openai` binding.

Supported Web Search Providers

| Provider | Env Key | Notes | |:--|:--|:--| | Brave | `BRAVE_API_KEY` | Recommended, free tier available | | Tavily | `TAVILY_API_KEY` | | | Serper | `SERPER_API_KEY` | Google Search results via Serper | | Jina | `JINA_API_KEY` | | | SearXNG | — | Self-hosted, no API key needed | | DuckDuckGo | — | No API key needed | | Perplexity | `PERPLEXITY_API_KEY` | Requires API key |

**5. Start services** The quickest way to launch everything: ```bash 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: ```bash # Backend (FastAPI) python -m deeptutor.api.run_server # Frontend (Next.js) — in a separate terminal cd web && npm run dev -- -p 3782 ``` | Service | Default Port | |:---:|:---:| | Backend | `8001` | | Frontend | `3782` | Open [http://localhost:3782](http://localhost:3782) and you're ready to go. ### Option C — Docker Deployment Docker wraps the backend and frontend into a single container — no local Python or Node.js required. You only need [Docker Desktop](https://www.docker.com/products/docker-desktop/) (or Docker Engine + Compose on Linux). **1. Configure environment variables** (required for both options below) ```bash 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](#option-b--manual-local-install) above). **2a. Pull official image (recommended)** Official images are published to [GitHub Container Registry](https://github.com/HKUDS/DeepTutor/pkgs/container/deeptutor) on every release, built for `linux/amd64` and `linux/arm64`. ```bash docker compose -f docker-compose.ghcr.yml up -d ``` To pin a specific version, edit the image tag in `docker-compose.ghcr.yml`: ```yaml image: ghcr.io/hkuds/deeptutor:1.3.4 # or :latest ``` **2b. Build from source** ```bash docker compose up -d ``` This builds the image locally from `Dockerfile` and starts the container. **3. Verify & manage** Open [http://localhost:3782](http://localhost:3782) once the container is healthy. ```bash docker compose logs -f # tail logs docker compose down # stop and remove container ```

Cloud / remote server deployment

When deploying to a remote server, the browser needs to know the public URL of the backend API. Add one more variable to your `.env`: ```dotenv # Set to the public URL where the backend is reachable NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001 ``` The frontend startup script applies this value at runtime — no rebuild needed.

Development mode (hot-reload)

Layer the dev override to mount source code and enable hot-reload for both services: ```bash docker compose -f docker-compose.yml -f docker-compose.dev.yml up ``` Changes to `deeptutor/`, `deeptutor_cli/`, `scripts/`, and `web/` are reflected immediately.

Custom ports

Override the default ports in `.env`: ```dotenv BACKEND_PORT=9001 FRONTEND_PORT=4000 ``` Then restart: ```bash docker compose up -d # or docker compose -f docker-compose.ghcr.yml up -d ```

Data persistence

User data and knowledge bases are persisted via Docker volumes mapped to local directories: | Container path | Host path | Content | |:---|:---|:---| | `/app/data/user` | `./data/user` | Settings, workspace, sessions, logs | | `/app/data/memory` | `./data/memory` | Shared long-term memory (`SUMMARY.md`, `PROFILE.md`) | | `/app/data/knowledge_bases` | `./data/knowledge_bases` | Uploaded documents & vector indices | These directories survive `docker compose down` and are reused on the next `docker compose up`.

Environment variables reference

| Variable | Required | Description | |:---|:---:|:---| | `LLM_BINDING` | **Yes** | LLM provider (`openai`, `anthropic`, etc.) | | `LLM_MODEL` | **Yes** | Model name (e.g. `gpt-4o`) | | `LLM_API_KEY` | **Yes** | Your LLM API key | | `LLM_HOST` | **Yes** | API endpoint URL | | `EMBEDDING_BINDING` | Knowledge Base only | Embedding provider | | `EMBEDDING_MODEL` | Knowledge Base only | Embedding model name | | `EMBEDDING_API_KEY` | Knowledge Base only | Embedding API key | | `EMBEDDING_HOST` | Knowledge Base only | Full embedding endpoint URL | | `EMBEDDING_DIMENSION` | No | Vector dimension; leave empty for auto-detection | | `SEARCH_PROVIDER` | No | Search provider (`tavily`, `jina`, `serper`, `perplexity`, etc.) | | `SEARCH_API_KEY` | No | Search API key | | `BACKEND_PORT` | No | Backend port (default `8001`) | | `FRONTEND_PORT` | No | Frontend port (default `3782`) | | `NEXT_PUBLIC_API_BASE_EXTERNAL` | No | Public backend URL for cloud deployment | | `DISABLE_SSL_VERIFY` | No | Disable SSL verification (default `false`) |

### Option D — CLI Only If you just want the CLI without the web frontend: ```bash # 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: ```bash cp .env.example .env # then edit .env to fill in your API keys ``` Once configured, you're ready to go: ```bash 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](#%EF%B8%8F-deeptutor-cli--agent-native-interface) for the full feature guide and command reference. --- ## 📖 Explore DeepTutor

DeepTutor Architecture

### 💬 Chat — Unified Intelligent Workspace

Chat Workspace

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. | Mode | What It Does | |:---|:---| | **Chat** | Fluid, tool-augmented conversation. Choose from RAG retrieval, web search, code execution, deep reasoning, brainstorming, and paper search — mix and match as needed. | | **Deep Solve** | Multi-agent problem solving: plan, investigate, solve, and verify — with precise source citations at every step. | | **Quiz Generation** | Generate assessments grounded in your knowledge base, with built-in validation. | | **Deep Research** | Decompose a topic into subtopics, dispatch parallel research agents across RAG, web, and academic papers, and produce a fully cited report. | | **Math Animator** | Turn mathematical concepts into visual animations and storyboards powered by Manim. | | **Visualize** | Generate interactive SVG diagrams, Chart.js charts, Mermaid graphs, or self-contained HTML pages from natural language descriptions. | 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 — Multi-Document AI Writing Workspace

Co-Writer

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. ### 📖 Book Engine — Interactive "Living Books"

Book Library

Book Reader

Book Animation

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 14 block types — text, callout, quiz, flash cards, code, figure, deep dive, animation, interactive demo, timeline, concept graph, section, user note, and placeholder — each rendered with its own interactive component. A real-time progress timeline lets you watch compilation unfold as the book takes shape. ### 📚 Knowledge Management — Your Learning Infrastructure

Knowledge Management

Knowledge is where you build and manage the document collections, notes, and teaching personas that power everything else in DeepTutor. - **Knowledge Bases** — Upload PDF, TXT, or Markdown 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. ### 🧠 Memory — DeepTutor Learns As You Learn

Memory

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 — Persistent, Autonomous AI Tutors

TutorBot Architecture

TutorBot is not a chatbot — it is a **persistent, multi-instance agent** built on [nanobot](https://github.com/HKUDS/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.

TutorBot

- **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, 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. ```bash 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 CLI Architecture

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`](SKILL.md) at the project root to any tool-using agent ([nanobot](https://github.com/HKUDS/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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash deeptutor session list # List all sessions deeptutor session open # Resume in REPL ```

Full CLI command reference

**Top-level** | Command | Description | |:---|:---| | `deeptutor run ` | Run any capability in a single turn (`chat`, `deep_solve`, `deep_question`, `deep_research`, `math_animator`, `visualize`) | | `deeptutor chat` | Interactive REPL with optional `--capability`, `--tool`, `--kb`, `--language` | | `deeptutor serve` | Start the DeepTutor API server | **`deeptutor bot`** | Command | Description | |:---|:---| | `deeptutor bot list` | List all TutorBot instances | | `deeptutor bot create ` | Create and start a new bot (`--name`, `--persona`, `--model`) | | `deeptutor bot start ` | Start a bot | | `deeptutor bot stop ` | Stop a bot | **`deeptutor kb`** | Command | Description | |:---|:---| | `deeptutor kb list` | List all knowledge bases | | `deeptutor kb info ` | Show knowledge base details | | `deeptutor kb create ` | Create from documents (`--doc`, `--docs-dir`) | | `deeptutor kb add ` | Add documents incrementally | | `deeptutor kb search ` | Search a knowledge base | | `deeptutor kb set-default ` | Set as default KB | | `deeptutor kb delete ` | Delete a knowledge base (`--force`) | **`deeptutor memory`** | Command | Description | |:---|:---| | `deeptutor memory show [file]` | View memory (`summary`, `profile`, or `all`) | | `deeptutor memory clear [file]` | Clear memory (`--force`) | **`deeptutor session`** | Command | Description | |:---|:---| | `deeptutor session list` | List sessions (`--limit`) | | `deeptutor session show ` | View session messages | | `deeptutor session open ` | Resume session in REPL | | `deeptutor session rename ` | Rename a session (`--title`) | | `deeptutor session delete ` | Delete a session | **`deeptutor notebook`** | Command | Description | |:---|:---| | `deeptutor notebook list` | List notebooks | | `deeptutor notebook create ` | Create a notebook (`--description`) | | `deeptutor notebook show ` | View notebook records | | `deeptutor notebook add-md ` | Import markdown as record | | `deeptutor notebook replace-md ` | Replace a markdown record | | `deeptutor notebook remove-record ` | Remove a record | **`deeptutor book`** | Command | Description | |:---|:---| | `deeptutor book list` | List all books in the workspace | | `deeptutor book health ` | Check KB drift and book health | | `deeptutor book refresh-fingerprints ` | Refresh KB fingerprints and clear stale pages | **`deeptutor config` / `plugin` / `provider`** | Command | Description | |:---|:---| | `deeptutor config show` | Print current configuration summary | | `deeptutor plugin list` | List registered tools and capabilities | | `deeptutor plugin info ` | Show tool or capability details | | `deeptutor provider login ` | Provider auth (`openai-codex` OAuth login; `github-copilot` validates an existing Copilot auth session) |

## 🗺️ Roadmap | Status | Milestone | |:---:|:---| | 🎯 | **Authentication & Login** — Optional login page for public deployments with multi-user support | | 🎯 | **Themes & Appearance** — Diverse theme options and customizable UI appearance | | 🎯 | **Interaction Improvement** — optimize icon design and interaction details | | 🔜 | **Better Memories** — integrating better memory management | | 🔜 | **LightRAG Integration** — Integrate [LightRAG](https://github.com/HKUDS/LightRAG) as an advanced knowledge base engine | | 🔜 | **Documentation Site** — Comprehensive docs page with guides, API reference, and tutorials | > If you find DeepTutor useful, [give us a star](https://github.com/HKUDS/DeepTutor/stargazers) — it helps us keep going! --- ## 🌐 Community & Ecosystem DeepTutor stands on the shoulders of outstanding open-source projects: | Project | Role in DeepTutor | |:---|:---| | [**nanobot**](https://github.com/HKUDS/nanobot) | Ultra-lightweight agent engine powering TutorBot | | [**LlamaIndex**](https://github.com/run-llama/llama_index) | RAG pipeline and document indexing backbone | | [**ManimCat**](https://github.com/Wing900/ManimCat) | AI-driven math animation generation for Math Animator | **From the HKUDS ecosystem:** | [⚡ LightRAG](https://github.com/HKUDS/LightRAG) | [🤖 AutoAgent](https://github.com/HKUDS/AutoAgent) | [🔬 AI-Researcher](https://github.com/HKUDS/AI-Researcher) | [🧬 nanobot](https://github.com/HKUDS/nanobot) | |:---:|:---:|:---:|:---:| | Simple & Fast RAG | Zero-Code Agent Framework | Automated Research | Ultra-Lightweight AI Agent | ## 🤝 Contributing

We hope DeepTutor becomes a gift for the community. 🎁

Contributors

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on setting up your development environment, code standards, and pull request workflow. ## ⭐ Star History

Star History Chart

**[Data Intelligence Lab @ HKU](https://github.com/HKUDS)** [⭐ Star us](https://github.com/HKUDS/DeepTutor/stargazers) · [🐛 Report a bug](https://github.com/HKUDS/DeepTutor/issues) · [💬 Discussions](https://github.com/HKUDS/DeepTutor/discussions) --- Licensed under the [Apache License 2.0](LICENSE).