DeepTutor: Lifelong Personalized Tutoring

[2026.10.19] v1.6.15 — Reviewed learning-path changes, grouped assessments, bounded tutoring memory, reliable chat recovery, sturdier parsing, retrieval comparisons, and native Gemini speech.

[2026.10.8] v1.6.14 — Original-source visual practice, recoverable indexing, unified video Reading, scientific research tools, managed plugins, a learning journal, and provider setup improvements.

[2026.10.4] v1.6.13 — Reading and listening improvements, question-bank practice, resilient document parsing, configurable speech, workspace-visible attachments, Polish, and new providers.

[2026.9.27] v1.6.12 — Workspace KB moves, Kiwix archives, source figures, Task Board, German UI, and chat recovery.

[2026.9.24] v1.6.11 — French and Ukrainian interfaces, reading folders with in-chat selection actions, figures sent to vision models, paged Office previews, and self-syncing knowledge bases.

[2026.9.22] v1.6.10 — Native LightRAG role models, a published index that records and enforces what built it, PDF attachments that follow your parsing engine, visible truncation, and unfiltered provider choices.

[2026.9.21] v1.6.9 — Folder-based learning workspaces, daily practice, redesigned Settings, clearer streaming conversations, persistent usage accounting, and recoverable archives with explicit permanent deletion.

[2026.9.14] v1.6.8 — A recycle bin for deleted chats, search across your whole conversation history, a tool that looks past your knowledge base, and a sweep of fixes for quiet failures.

[2026.9.11] v1.6.7 — A fix release: books that arrived as one empty chapter, quizzes that produced nothing, the model's scratchpad in the text, formulas printed raw, and cards you could not submit.

[2026.9.8] v1.6.6 — A fix release: answers that could not submit, a copy button that lied, connected knowledge bases for partners, Codex sign-in inside Docker, and a 100 KB lighter home route.

[2026.9.6] v1.6.5 — A content workspace you point at any folder, one exec tool for every language, Mastery Path modes that gate its tools, and Settings that grades readiness.

[2026.9.3] v1.6.4 — Faster isolated runtimes, controllable Book generation, source-complete Mastery paths and Chat hand-offs, durable Reading, unified activity UI, recoverable sessions, and explicit per-model API capabilities.

[2026.9.2] v1.6.3 — Breaking front/back-end refactor, strict canonical routes and recoverable streams, plus learner/guardian accounts, grounded Reading, WeKnora, broader parsing, Python 3.14, and DashScope media.

[2026.8.31] v1.6.2 — Immersive YouTube learning, a plugin-driven Visualize catalog, three new agent harnesses, safer reading citations, multi-format MinerU, live Partner channel status, and guided updates.

[2026.8.30] v1.6.1 — One vendor key linked to every service it serves, a task model for background work, Settings as a searchable navigator, a sidebar you arrange, and first-party LightRAG.

[2026.8.27] v1.6.0 — Faithful EPUB reading and annotations, Courses with Little Tutor and Ask Questions, bounded web-source sync, shared Books with private learning state, and Serply/native search.

[2026.8.25] v1.5.17 — Partners each member owns with private conversations and linkable chat accounts, GitHub repos as a knowledge source, Antigravity CLI, browser WeChat QR login, and deeptutor doctor.

[2026.8.22] v1.5.16 — MarginNote 4 libraries you connect and its add-on fills, Book pages that turn again, and tool-call ids, embeddings and temperature limits that stop breaking behind a gateway.

[2026.8.20] v1.5.15 — PageIndex OSS you host yourself with reasoning retrieval, a question bank you can finally file into, third-party tool/capability plugins, and Apache Tika parsing.

[2026.8.19] v1.5.14 — Immersive Reading: a document open beside the thread, cited page by page; DeepTutor configures itself from chat; IMA libraries you browse and write to; a notebook console.

[2026.8.17] v1.5.13 — Books stream while they compile, track your progress, and export to Markdown; a cost estimate before you approve a spine; and home starter suggestions drawn from memory.

[2026.8.13] v1.5.12 — Web search rebuilt with six new providers (Doubao, Bocha, Zhipu, Firecrawl, Qianfan, Aliyun IQS), a LiteParse parsing engine, MCP servers that reconnect on credential change, and CodeBuddy + OrcaRouter.

[2026.8.10] v1.5.11 — Prose around a DSML tool call stops vanishing, a truncated reply continues instead of ending, live memory usage in Settings, and LightRAG indexing off the event loop.

[2026.8.7] v1.5.10 — Every account signs in to its own Codex, model output language becomes its own setting, empty tool calls are rejected instead of retried, and uploads stop blocking the loop.

[2026.8.4] v1.5.9 — Gemini Embedding 2 on its native endpoint, a per-model reasoning effort control, a Novita AI gateway, retrieval roles for queries, and Compose deployments that keep all of data/.

[2026.8.2] v1.5.8 — Memory: a real heap ceiling for the dev server, source installs serve a production build, bounded LLM client and index caches, and a keep-alive fix for stray 500s.

[2026.7.31] v1.5.7 — A per-account MCP Services store, 101 CLI Apps the tutor can run, credentials moved out of the sandbox's reach, and a mobile layout.

[2026.7.29] v1.5.6 — Remote Codex sign-in completes behind an SSH tunnel, generated files get their own card in Activity, non-English languages stop collapsing to Chinese, and book creation no longer times out.

[2026.7.26] v1.5.5 — Sign in with your ChatGPT plan via OpenAI Codex OAuth, an Eden AI provider, knowledge bases that report what they hold, traceable rag citations, and GraphRAG indexing without a workaround.

[2026.7.24] v1.5.4 — Maintenance sweep: the post-answer "generating" stall is gone, IM partners render Markdown tables faithfully, LLM JSON parsing is sturdier, plus quiz, create-KB form, and Math Animator fixes.

[2026.7.24] v1.5.3 — Themeable code blocks, four more coding CLIs in My Agents (Gemini, Kimi, opencode, MiMo), an Atlas Cloud LLM provider, and a broad chat, memory, embedding, and parsing reliability sweep.

[2026.7.19] v1.5.2 — Configurable chat attachment limits, PageIndex retrieval that reasons across your documents via agentic tool calls, broader Anthropic/OpenAI model support, and steadier Book, Knowledge Base, and chat UI.

[2026.7.9] v1.5.1 — Remove a single failed document from a knowledge base — even one stuck in an error state — instead of deleting and rebuilding the whole base.

[2026.7.4] v1.5.0 — LlamaIndex ingestion now honors your Document Parsing engine with multimodal image extraction, Partner & Soul ids stay URL-safe for non-Latin names, and optional RAG extras install cleanly on Python 3.14+.

[2026.6.30] v1.4.15 — A native Mattermost channel for Partners, plus fixes so Guided Learning multiple-choice questions grade correctly and a configured zero chunk overlap is honored.

[2026.6.29] v1.4.14 — Click an assigned partner to chat in one step, Deep Research flags partial reports, LightRAG indexes without MinerU, FAISS handles non-ASCII paths, and PocketBase sessions are isolated per user.

[2026.6.27] v1.4.13 — Partners support non-Latin names and become assignable to users, logos render after login (#599), tiny knowledge bases retrieve reliably, and containers start cleanly under rootless Podman.

[2026.6.24] v1.4.12 — A new LightRAG Server retrieval engine, a lightweight PyMuPDF4LLM parsing engine, and a FAISS vector backend that makes large knowledge-base retrieval dramatically faster.

[2026.6.23] v1.4.11 — Native tool calling on every cloud OpenAI-compatible provider, a redesigned admin Users page, LaTeX in quiz options, an honest session-loading spinner, and configurable container host binding.

[2026.6.21] v1.4.10 — A self-service Profile page with avatars, a rootless-ready container guide with a single-port request-time proxy, and deny-by-default MCP tools for non-admin users.

[2026.6.19] v1.4.9 — Settings polish: Search shows only the fields your provider needs, connection profiles can be renamed and auto-named by provider, and graded Mastery Path questions flow into your Question Bank.

[2026.6.18] v1.4.8 — Connect your own Partners under My Agents and consult them live in chat — answering through their own persona, library and skills — each with its own private memory.

[2026.6.18] v1.4.7 — Connect your local Claude Code / Codex and consult it live mid-turn, My Agents graduates to a top-level /agents, and Partner conversations gain branch / resume / delete with a replayable trace.

[2026.6.17] v1.4.6 — Four-surface consolidation: a Space learning dashboard with importable My Agents and top-level Memory, a Knowledge Center with GraphRAG / PageIndex / LightRAG / linked-KB / Obsidian, opened-up Settings, and per-model capability gating.

[2026.6.14] v1.4.5 — Guided Learning rebuilt on the chat agent loop with a hard per-type mastery gate and a /learning dashboard, a new loop-plugin framework, plus Markdown export / save-to-notebook for Partner conversations.

[2026.6.13] v1.4.4 — Install community skills from ClawHub with deeptutor skill install behind a security gate, plus real in-browser DOCX/XLSX previews for knowledge-base files.

[2026.6.12] v1.4.3 — TutorBot becomes Partners on a production-grade IM pipeline (15 channels, live streaming), Chat moves to a single agent loop, real per-user isolation, and a rebuilt Visualize.

[2026.5.28] v1.4.2 — Stability + polish: Gemini 2.5+ unblocked across Visualize and Chat, auth-routing fix (#485), smooth-streaming chat UX, a Recents sidebar, and Lemonade local-provider support.

[2026.5.27] v1.4.1 — Security + stability: TutorBot tool sandbox locked down, per-user resource isolation, multimodal image fallback, an HTTP/SSE API for TutorBots, 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, 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.

[2026.5.10] v1.3.10 — Remote Docker CORS recovery, DISABLE_SSL_VERIFY across SDK providers, safer code-block citations, and optional Matrix E2EE add-on.

[2026.5.9] v1.3.9 — TutorBot Zulip and NVIDIA NIM support, safer thinking-model routing, deeptutor start, sidebar tooltips, and session-store parity.

[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.22] 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 — Per-stage token limits, Regenerate response across all entry points, RAG & Gemma compatibility fixes.

[2026.4.20] v1.2.0 — Book Engine "living book" compiler, multi-document Co-Writer, interactive HTML visualizations, Question Bank @-mention.

[2026.4.18] v1.1.2 — Schema-driven Channels tab, RAG single-pipeline consolidation, externalized chat prompts.

[2026.4.17] v1.1.1 — Universal "Answer now", Co-Writer scroll sync, unified settings panel, streaming Stop button.

[2026.4.15] v1.1.0 — LaTeX block math overhaul, LLM diagnostic probe, Docker + local LLM guidance.

[2026.4.14] v1.1.0-beta — Bookmarkable sessions, Snow theme, WebSocket heartbeat & auto-reconnect, embedding registry overhaul.

[2026.4.13] 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 — Search consolidation with SearXNG fallback, provider switch fix, and frontend resource leak fixes.

[2026.4.10] v1.0.1 — Visualize capability (Chart.js/SVG), quiz duplicate prevention, and o4-mini model support.

[2026.4.10] 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 — 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 — Hot settings reload, MinerU nested output, WebSocket fix, and Python 3.11+ minimum.

[2026.4.4] 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 — Session persistence, incremental document upload, flexible RAG pipeline import, and full Chinese localization.

[2026.1.18] v0.5.2 — Docling support for RAG-Anything, logging system optimization, and bug fixes.

[2026.1.15] v0.5.0 — Unified service configuration, RAG pipeline selection per knowledge base, question generation overhaul, and sidebar customization.

[2026.1.9] v0.4.0 — Multi-provider LLM & embedding support, new home page, RAG module decoupling, and environment variable refactor.

[2026.1.5] v0.3.0 — Unified PromptManager architecture, GitHub Actions CI/CD, and pre-built Docker images on GHCR.

[2026.1.2] v0.2.0 — Docker deployment, Next.js 16 & React 19 upgrade, WebSocket security hardening, and critical vulnerability fixes.

Open DeepTutor bundles Python, Node.js, and the full learning workspace, so no terminal or separate runtime installation is needed. Desktop previews are available on dev; the v1.7.0 Release does not include desktop installers.

Open a successful Desktop Release workflow run, scroll to Artifacts, and download the matching target. GitHub sign-in is required, and artifacts expire after seven days.

Windows preview builds are unsigned and may show a SmartScreen warning. See the desktop guide for signing, local data, and source builds.

Run the full Web app without installing Python or Node.js:

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

Open http://127.0.0.1:3782. The named volume preserves settings and local data; only port 3782 is required for the Web app. See the Docker guide for host workspaces, local model services, reverse proxies, and production deployment.

Use Python 3.11–3.14 and Node.js 20.9+. In the modular 1.7.0 release, deeptutor[full] installs the Web app and CLI; bare deeptutor installs core chat and the SDK.

mkdir -p my-deeptutor && cd my-deeptutor
python -m pip install -U "deeptutor[full]"
deeptutor init     # ports + LLM provider + optional embedding/search
deeptutor start    # starts backend + frontend

Open the URL printed in the terminal, by default http://127.0.0.1:3782. Press Ctrl+C to stop both services.

Upgrading from 1.6.15 or earlier: stop DeepTutor, back up the runtime home, and uninstall a legacy deeptutor-cli package before installing the new family. Keep the same DEEPTUTOR_HOME, then run python -m pip check and deeptutor module list. See the PyPI and migration guide for the exact upgrade commands.

Use Python 3.11–3.14 and Node.js 22 LTS to match CI and Docker.

git clone --branch dev https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
python3 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements/full.txt
python -m pip install -e . --no-deps
( cd web && npm ci --legacy-peer-deps )
deeptutor init
deeptutor start --dev

Use deeptutor start without --dev for a production build. Optional dependencies are installed from the repository root, for example python scripts/install_extras.py dev,partners,math-animator. See the source installation guide for Conda, extras, and troubleshooting, or the Agent Setup guide to let a terminal-capable agent perform and verify the setup.

For a minimal terminal installation, use the core wheel; no Node.js or Web frontend is required:

mkdir -p my-deeptutor && cd my-deeptutor
python -m pip install -U deeptutor
deeptutor init --cli
deeptutor chat

Core includes Chat, Ask Questions, the CLI, and the SDK; other capabilities and management commands require their matching feature modules. For the current dev source installation and optional dependencies, see the CLI-only guide. The CLI reference below covers one-shot runs and machine-readable output.

Home is where daily work begins: talk to the tutor, organize next actions, and develop your own notes in the current workspace. Calendar provides an account-wide view while retaining the source workspace for study events.

💬 Chat — The Agent Loop You Actually Use

Chat is the default capability and where most work begins. A single thread can talk normally, call tools, ground itself in selected knowledge bases, read attachments, generate images, consult subagents, write notebook records, and continue with the same context across turns.

The tutor calls tools as needed and can pause to ask clarifying questions. Customize page, at the upper right, chooses the visible modes and Skills, MCP, Partners, Preferences, and voice-input controls. Under Starting prompts, add, edit, or remove the titles and prompts in Explain, Solve, Practice, Plan, and Research. Save applies your account preferences; Cancel discards edits, and Restore defaults brings back the original choices.

User-toggleable tools are brainstorm, web_search, paper_search, zotero_search, reason, and geogebra_analysis — plus imagegen and videogen once you configure the matching generation model. Contextual tools such as rag, kb_files, knowledge_frontier, read_source, read_memory, write_memory, read_skill, load_tools, exec, web_fetch, ask_user, list_favorites, save_favorite, write_note, search_notes, question_bank, github, consult_subagent, workspace_list, workspace_read, workspace_search, workspace_present, and workspace_export mount automatically when the turn has the right context.

Context comes in two kinds: sticky session context (capability, workspace or course, tools, knowledge bases, persona, model, and Reading / Mastery state) persists across turns; references (files, chat history, books, reading sections, notebooks, selected question-bank entries, imported agents) come from the + menu for one turn by default, or every turn when pinned. The voice button only transcribes the current message.

With the full profile, Home keeps Chat, Ask Questions, Quiz, Visualize, and Video Lesson one click away; Research for cited reports and Solve for worked reasoning sit under More Capabilities. Select text in an answer to open Little Tutor, a focused sidebar thread that stays nested under the source conversation. With at least three sent messages, the left gutter shows a tick for each question when space allows; hover to preview, click to jump back, or use Alt/Option + ↑/↓ to move between questions.

✍️ Learning Notebook — Pages, Sources, and Dito

The Learning notebook, formerly Co-Writer, organizes your own writing into pages, subpages, and blocks within the active workspace. Import Word documents, arrange a page tree, and insert original records from Favorites as evidence. Pages keep their save status visible and export as Markdown or Word; interactive content becomes static in Word.

Export flashcards to Anki. Notebook pages can include Flash Cards. On a page that has them, open the page menu and choose Export flashcards (Anki). From the notebook review queue, choose Export all for Anki. In Anki, use File → Import and select the downloaded .txt file. Cards land in a deck named DeepTutor::<note title> with front/back fields, tags, and math preserved. Re-importing the same file updates existing cards instead of duplicating them. DeepTutor's own review schedule is not included.

Discuss a passage or block with Dito: ask for an explanation, example, rewrite, or practice question. Conversations remain attached to the relevant page and line. Review proposed changes before accepting them, or insert an answer below the line and keep working. Favorites preserve source records; the notebook is where you build your own understanding.

Learning is the current workspace's study area. Create an activity from Learning → New learning, then reopen it from All learning with its progress, conversations, and source context intact.

📖 Book — Living Books from Your Materials

Book turns selected sources into an interactive living book — not a static PDF, but a reading environment built from typed blocks. A book can start from knowledge bases, Favorites, question banks, or chat history; the creation flow proposes a chapter outline before content is generated, so you review the shape instead of accepting a blind one-shot output.

   

Each chapter compiles into editable typed blocks — text, callouts, quizzes, flash cards, timelines, code, figures, interactive HTML, animations, concept graphs, deep dives, and user notes — with its own Page Chat. Insert, move, regenerate, rewrite, or switch a block type; selected passages enter a reviewable learning-capture inbox. Progress, bookmarks, quiz attempts, captures, and Page Chat stay private per reader even when an admin book is shared read-only or for collaborative editing; shared deletion stays admin-only. Any book exports to Markdown, long compiles pause and resume, deeptutor book health flags source drift, and deeptutor book refresh-fingerprints refreshes the source baseline.

Resources is the current workspace's reusable library. Keep original material, saved results, and learning records here so they can be attached to new conversations and activities without mixing projects.

📚 Knowledge Center — Multi-Engine RAG Libraries

Knowledge bases are the document collections behind RAG — they ground Chat turns, Learning notebook edits, Book generation, and Partner conversations. What's distinctive is a choice of retrieval engines: LlamaIndex (the default, hybrid vector + BM25 with optional cross-encoder reranking and exact-flat or HNSW FAISS indexes), PageIndex (reasoning retrieval with page-level citations, hosted or self-hosted OSS), GraphRAG and LightRAG (knowledge-graph retrieval), LightRAG Server (retrieval offloaded to an external LightRAG instance you connect over HTTP), WeKnora (retrieval from a knowledge base in your self-hosted deployment, without a local index or document copy), Tencent IMA (a library you curate in IMA — searched, browsed, and written back to over its OpenAPI), MarginNote 4 (your MN4 study data — documents, excerpts, mind-map cards and the links between them — pushed in by the app's Add-on and navigated with dedicated tools), Kiwix (a searchable ZIM archive served over HTTP without local indexing), or a linked Obsidian vault the tutor reads and writes in place. Each KB is bound to one engine.

Migrating an existing Obsidian, Hermes, or Markdown library? See Knowledge migration guide for connected-vault and indexed-copy paths.

Creating a KB, you can create new (upload and index documents), link existing (reuse an index in place), or connect Kiwix (search one served ZIM archive on demand). Choose its storage workspace at creation; an existing KB can move between workspaces after a preview, keeping assignments and saved references. A KB can also track GitHub repositories (repo, branch, glob) or documentation-site URLs (bounded crawl depth and page count, re-synced every 24 h by default); sync hash-diffs added, changed, and removed content so followed documentation stays current without re-uploading, and linked folders pick up new or changed local files on sync. Re-indexing writes a new flat version-N directory and keeps prior ones, so a working index is never destroyed mid-rebuild. A single document can be removed even from an error-state base — dropping a file that failed to parse without a full delete-and-rebuild. Document parsing — Text-only, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM, or LiteParse — and an optional image-description model are chosen in Settings → Knowledge & documents, with local model downloads off by default. Docling can also run in remote mode against a Docling Serve server (no local install or models needed), configured on that page (mode=remote, a server base URL, and an optional API key) or the DOCLING_MODE / DOCLING_API_BASE_URL / DOCLING_API_TOKEN environment variables. Tika is remote-only and points at the Apache Tika server configured on that page. The CLI mirrors the lifecycle with list/info/create/connect-kiwix/add/search/eval/eval-diff/set-default/delete, source add/remove commands, list-sources, and sync.

The built-in LightRAG engine is installed with pip install 'deeptutor[rag-lightrag]'. That extra contains the supported LightRAG SDK but does not install MinerU. Choose MinerU independently in Document Parsing and either configure its cloud mode or install its current local CLI when structured parsing is wanted. MinerU accepts PDF, common raster images, DOCX, PPTX, and XLSX; the legacy magic-pdf command remains PDF-only. Text-only and the other parsing engines do not require MinerU.

Native LightRAG queries and incremental indexing require the embedding configuration recorded by the published index, including the model, dimension, and endpoint identity. If it changes, restore the original configuration or rebuild with the current embedding; indexes without a recorded embedding identity require a rebuild. The knowledge-base detail and index-version views show recovery guidance, while files remain available for viewing and download.

Scoring a knowledge base. With several engines available, "which one retrieves best here?" is an empirical question — so deeptutor kb eval answers it. Write a QA set (one JSON object per line: a query plus the gold passages an ideal retrieval should return), then score the KB with deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]. Each case is retrieved through the same path a chat turn uses, its ranked citations are matched against the gold passages using exact text or lexical overlap (thresholds are tunable with --min-ratio; semantic equivalence is not assessed), and the run reports Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k. Metrics are pure functions over the ranking; no model judges the output. Compare saved reports with deeptutor kb eval-diff baseline.json candidate.json for per-metric and per-case changes. Use --rewrite off or --rewrite standalone on kb eval to compare original and rewritten queries; reports retain rewrite provenance. Cases whose search failed (a missing index, bad credentials) carry no score and are reported separately rather than dragging the means down. PageIndex uses reasoning as retrieval and returns no ranked chunks, so it is excluded.

{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}

🗃️ History, Favorites, Journal, and Question Bank

Chat History reopens conversations with their original learning context. Favorites preserves useful original conversations and results in movable collections with Markdown export, ready to insert into a Learning notebook. The Learning journal records the current mission, session handoff, and confirmed learning records. The Question Bank organizes questions, answers, explanations, and mistakes; select a set for Learning → Practice to review weak areas and schedule repetition.

Partners belong to the account rather than one subject workspace. Each companion keeps its own identity, instructions, model policy, relationships, and channels while using either a private library or an existing workspace's resources.

Identity, Workspace Resources, Groups, and Channels

Every inbound Web or IM message becomes a normal ChatOrchestrator turn — a Partner is "a chat that has a personality and a phone number." Its SOUL.md, model selection, tool policy, and library remain editable after creation. A private Partner workspace copies assigned knowledge bases, skills, and Favorites collections; a bound workspace shares its current files and resources instead. Soul, conversations, and relationship memory stay separate in either mode.

Partner Groups bring two or more Partners into one shared conversation with distinct seats, selectable discussion and shared-memory modes, and durable history. Authenticated users keep private Partner sessions and relationship memory even when a companion is shared.

Schema-driven channels connect companions to Feishu, Telegram, Slack, Discord, DingTalk, QQ/NapCat, WeCom, WhatsApp, Zulip, Mattermost, Matrix, Mochat, and Microsoft Teams, depending on installed extras and credentials. Browser-based setup supports QR onboarding for selected channels. A Partner can also be connected through Personalization → My Agents and consulted from a normal Chat turn.

Personalization follows the account across workspaces. Choose how the tutor should behave and which agents, skills, services, applications, and memories it may reuse; workspace and conversation selections can narrow that access further.

🧑‍🚀 My Agents — Consult Live Agents and Import History

Connect a live agent — Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo Code, Hermes Agent, OpenClaw, DeepSeek Harness, or a Partner — and consult it from a Chat turn. DeepTutor runs the selected agent and streams its work into the Activity panel through consult_subagent; the Agent chip or @ keeps the connection attached to the session. Local harnesses use their own authentication, working directory, and session storage.

Import past conversations from ChatGPT, Claude Code, and Codex as searchable, resumable references. ChatGPT uses an official conversations.json export; Claude history is selected by project or working directory, and Codex history by date. Reference an imported conversation through + → My Agents without turning it into DeepTutor's own voice.

🎭 Personas, Skills, MCP Services, and CLI Apps

Personas reuse a voice, teaching style, or response policy and can also seed a Partner's soul. Skills package repeatable workflows as SKILL.md playbooks, with account-shared and workspace-local libraries. Import from EduHub browses community skills and installs them through a security gate (see Ecosystem).

MCP Services authorize external tools, while CLI Apps expose installed programs from the CLI-Anything catalog through the execution sandbox. Workspace assignments and user grants determine which resources each turn may use.

🧠 Memory — Inspectable Personalization

Memory is a file-backed, three-layer system you can read, curate, and audit — deliberately not a hidden vector store. L1 is the workspace mirror plus an append-only event trace (trace/<surface>/<date>.jsonl); L2 is per-surface curated facts (L2/<surface>.md) with references to L1 entities; L3 is cross-surface synthesis (L3/<profile|recent|scope|preferences>.md) that records its contributing L2 surfaces.

The Memory Graph shows the whole pyramid — L3 synthesis at the centre, L2 in the middle ring, L1 traces on the outside — with exact L2 → L1 evidence edges and L3 → contributing-surface links. Memory is tracked across chat, notebook, quiz, kb, book, partner, and cowriter surfaces; the consolidator's Update / Audit / Dedup budgets are tuned in Settings → Memory.

⚙️ Settings — One Control Plane

Settings is the operational control plane, opening on General for interface and model output language. Its searchable navigator links to independent pages: Personal covers Workspaces, Data migration, Appearance, and Usage statistics; Learning & conversation covers starting points, attachments, Video Learning, learner and guardian controls, Learning progress, and Memory; Models & services covers Providers, Language models, Task models, Embedding, Search, Voice, and Multimodal generation; Features & integrations covers tools, capability parameters, Partners & agents, and Knowledge & documents. System holds Network, Runtime status, and About; Archived chats lets you search, restore, or permanently delete archived conversations. Runtime status contains backend health, resident memory, and the Readiness matrix grading capability blockers, warnings, and suggestions. Workspaces keeps topic files and learning state separate, with verified migration and export under Data migration. A provider holds a vendor's address and credential for reuse by its service models; the model pages choose saved providers and configure model names and capabilities. Task models pin a small, fast model for automatic work — from naming conversations and writing starting points to Math Animator and Video Lesson repairs — and resolve to the active default when empty. Voice groups speech synthesis and transcription; Multimodal generation groups image and video models. Partners & agents configures local harnesses and a remote Hermes gateway.

Vietnamese: In Settings → General, choose Tiếng Việt for Interface language and select Apply changes. Model output language is independent: choose Tiếng Việt there for Vietnamese replies, or keep another reply language while using the Vietnamese interface. Reply quality depends on the selected model's Vietnamese support.

Xiaomi MiMo speech. Add a Xiaomi MiMo provider with https://api.xiaomimimo.com/v1 and its API key, then add mimo-v2.5-tts under Settings → Voice. Choose a preset such as mimo_default, 冰糖, or 苏打, use wav or pcm16 output, and audition it before applying. Voice instructions control style and speaking speed. This adapter supports preset speech only; voice design and voice cloning require separate models and are not supported. If an older MiMo speech model was configured through the generic OpenAI-compatible adapter, recreate its speech entry using the Xiaomi MiMo provider so it uses the chat-completions protocol. See the official MiMo speech guide.

MiniMax speech — in Settings → Voice, choose MiniMax for text-to-speech and select speech-2.8-hd. Configure a MiniMax API key and explicitly select a system voice or enter a custom voice ID. The API base defaults to https://api.minimax.io/v1; for the China region use https://api.minimaxi.com/v1. Read-aloud and voice previews use the native speech endpoint, with MP3, WAV, FLAC or PCM output, sample rate, speed and language controls. See the MiniMax speech API for voice IDs and account availability.

Video Learning under Settings → Learning & conversation configures YouTube captions and Invidious access for Reading. To use Invidious, set its administrator-managed backend API origin (for example http://127.0.0.1:3000) and browser-accessible public origin, test the connection, select Invidious, and save. Browse Invidious in Reading's add-material dialog searches videos and accesses connected subscriptions and playlists. YouTube playback uses the official privacy-enhanced player; missing captions remain visible and limit the tutor's evidence without blocking native playback. In a source checkout, run python scripts/install_extras.py video-learning for the default YouTube caption loader. Existing Watching links migrate into Reading with conversation history, compatible transcripts, notes, and progress preserved; new timestamp notes are Reading annotations. Bilibili uses its own playback and caption path.

Most sections use a draft-and-apply flow, so you can test a provider before committing it. You can also just ask in Chat: the assistant reads the current configuration, applies a change, and says whether it needs a restart or a re-index — probing a new model before it commits, so it cannot switch itself onto something unreachable. API keys never pass through the model, which opens the matching form for you instead. Four themes ship in the box — Default, Cream, Dark, and Glass. Project-root .env files are intentionally ignored; runtime configuration lives under data/user/settings/*.json unless DEEPTUTOR_HOME or deeptutor start --home points the app elsewhere.

OpenAI Codex OAuth (experimental). Adding OpenAI Codex under Settings → Providers opens a browser sign-in that runs against your own ChatGPT plan, so no OPENAI_API_KEY is needed. Tokens live only in data/system/user-secrets/<owner>/private/openai-codex/ — in the multi-container Compose deployment, outside every tree the exec sandbox can reach — and DeepTutor never reads or modifies your ~/.codex CLI login. The model list comes from that account's live catalog; signing in publishes the profile but only becomes the active model when no LLM is configured yet. Because a token authorizes one person's plan, the profile is not shareable through user grants — each account signs in for itself, ordinary users included: their sign-in card sits under Providers, and the resulting models, catalog, and sign-out stay private to that account.

On sign-in and Refresh models, DeepTutor reads the latest stable @openai/codex version from the official npm registry and uses it as the catalog request's client_version. This is metadata-only: it does not install, download, or upgrade the Codex CLI, and the npm request carries no OAuth credentials. Discovery has a three-second deadline and a 64 KiB response limit. If it fails, DeepTutor uses the last successful version for that account, or its built-in fallback when none is cached. Only a successfully parsed live catalog saves a new version; validators are never reused across versions or credential generations. A version rejection or incompatible catalog structure permits one retry with the previous version; authentication, rate-limit, and TLS failures are not retried as version problems. A failed manual refresh reports an error rather than presenting an old cached catalog as refreshed.

Successful version history survives same-account token renewal and catalog authentication errors, without making invalidated model data or ETags usable again. Signing out clears that account's local cache, including the version history. Ordinary status reads and inference do not query npm. New catalog entries do not replace a model you already selected or restart learning sessions; appearing in the catalog does not establish full inference-protocol compatibility. There is no background version updater or user version setting.

Default local Docker and Podman deployments use separate loopback networks and need a temporary bridge during sign-in. Follow the temporary local Codex OAuth bridge guide for the exact Docker, Compose, Podman, and teardown commands.

For a remote deployment, the browser's localhost and the server's localhost are different machines, so an ordinary reverse proxy alone cannot carry the browser's localhost callback to the server. Use an SSH tunnel as the callback bridge. The tunnel reaches the already-published Web port; Next.js rewrites only the exact callback path to the public callback broker, and the broker validates state before routing to the original OAuth operation. The callback listener remains on the backend loopback, ports 1455 and 1457 are not published, and this path supports the default Docker bridge network.

ssh -N -L 1455:127.0.0.1:3782 <ssh-user>@<server-host>

If DeepTutor reports fallback callback port 1457, use:

ssh -N -L 1457:127.0.0.1:3782 <ssh-user>@<server-host>

Run only the one command that matches the actual callback port; never run both. 3782 is only the example Web port: it is the configured frontend/container port reported as callback_forward_port. That value does not guarantee that the same port is listening on the SSH host's 127.0.0.1. If Docker or Podman publishes a different host port, or a reverse proxy listens on a different port, replace only the right-hand target port (3782 above) with the Web port actually listening on the SSH host's 127.0.0.1; keep the left-hand callback port as 1455 or 1457. <server-host> is the SSH host whose loopback owns that listening port. If the browser URL names a reverse proxy or load balancer, replace it with the correct SSH frontend host.

The CLI prints the tunnel command and then immediately tries to open the browser. On a remote deployment, keep the authorization page open without completing it, establish the printed tunnel in another terminal, and only then continue authorization.

Remote-topology detection has a localhost boundary. If Web itself is reached through an SSH or IDE localhost forward, the browser cannot tell that the server is remote. For the current Web operation, leave its authorization page unfinished, read redirect_uri in that operation's authorize URL to identify callback port 1455 or 1457, and create the second tunnel from that local port to the actual Web port. Alternatively, cancel that Web operation and start a new one with the CLI; the CLI output belongs to the new operation and must not be used for the existing Web operation. Quota errors and catalog failures are reported as-is and never fall back to a paid provider. This compatibility path is experimental: the upstream interface may change.

Authentication is off by default — DeepTutor runs single-user. Turn it on and one data/ tree hosts an admin workspace, isolated per-user workspaces, and partner workspaces side by side:

data/
├── user/                    # Admin workspace + global settings
├── users/<uid>/             # Per-user scope: chat history, memory, notebooks, KBs
├── partners/<id>/workspace/ # Partner (synthetic-user) scope
├── cli-apps/                # Installed CLI apps, mounted read-only into the sandbox
└── system/                  # auth · grants · audit · user-secrets/<owner> (OAuth tokens)

The first registered user becomes admin and owns model catalogs, provider credentials, shared knowledge bases, skills, canonical shared books, and per-user grants. Admin-created local users choose Standard, Learner, or Custom. Learner locks learning capabilities and material policy, adds an adaptive profile, and supports revocable device credentials with expiry and daily limits; authorized guardians can view reports, approve materials, and reset credentials. Other users get isolated workspaces plus scoped models, KBs, skills, partners, and shared-book access without receiving raw API keys. If auth.json already carries a username + password_hash, that account is the admin: /register stays closed and accounts created from /admin/users are always role=user until you promote them.

Enable it: turn auth on in data/user/settings/auth.json, restart deeptutor start, register the first admin at /register, then add users from /admin/users and assign models, KBs, skills, partners, tool/MCP/CLI-app policy, and code-execution access through grants; configure shared books under each user's Book access panel.

For split private/public origins, set auth.private_login_hosts (or AUTH_PRIVATE_LOGIN_HOSTS) to the private frontend hosts that may show password sign-in and registration. The frontend forwards the incoming HTTP Host to the backend as its frontend-host assertion. Preserve the browser's Host through your reverse proxy, and make the public ingress reject requests naming a private host; do not expose a raw Next.js port that accepts arbitrary Host values. HTTP Host can be forged by a direct client, so private-host authorization depends on that ingress boundary. The backend accepts frontend-host assertions only from loopback by default. If the Web frontend connects from another container or host, set AUTH_TRUSTED_FRONTEND_PROXY_IPS to that frontend proxy's exact IP address on the backend process (comma-separated for more than one). This replaces the defaults; include 127.0.0.1,::1 if local frontend connections are also needed. Keep the backend API private to the frontend proxy and do not include general client networks in this list. When private_login_hosts is non-empty, an authenticated user on a private origin can open Profile → Public device sign-in and create a short-lived, host-bound pairing link for an HTTPS public origin. The public /handoff page exchanges the one-time code for an equally short JWE ticket in a POST body, consumes the ticket once, and receives the normal HttpOnly session cookie.

PocketBase stays a single-user integration — keep integrations.pocketbase_url blank for multi-user deployments unless you've wired up an external user store.

deeptutor chat opens an interactive REPL and selects a mode with --capability; deeptutor run <capability> "<message>" takes that capability as its first positional argument and exits after one turn. Both accept --tool, --kb, --config, and --workspace to select a registered workspace.

deeptutor chat                                              # interactive REPL
deeptutor chat --capability deep_solve --kb my-kb
deeptutor run chat "Explain the Fourier transform" --kb textbook
deeptutor run chat "Find recent work beyond this material" --kb textbook
deeptutor run deep_research "Survey 2026 papers on RAG" \
  --config mode=report --config depth=standard

--kb supplies context for automatic RAG and Knowledge Frontier tools; Frontier needs both knowledge and research modules. --tool selects user-toggleable tools. Enabled modules also provide KB, session, partner, skill, notebook, memory, and config commands.

DeepTutor is built to be operated by another agent. Add --format json to any run and each turn streams NDJSON — one event per line (content, tool_call, tool_result, done, …), every line tagged with its session_id. Runs are headless-safe: an ask_user pause with no TTY auto-resolves with an empty reply instead of hanging.

# One shot, machine-readable
deeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json

# Chain turns in one stateful session — capture the id, reuse it
SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \
  --config mode=report --config depth=standard --format json \
  | jq -r 'select(.type=="done").session_id')
deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json

The repo ships a root SKILL.md — a compact handover doc for the CLI. Ask your agent to read it explicitly; its Agent Setup guide covers installation and configuration. You can also wrap deeptutor run as a tool in a LangChain / AutoGen loop. Full recipes: Agent Handoff.

Set enable_visual_review=true to inspect rendered frames for overlap, readability, and framing, then feed detected issues into the existing code repair loop:

deeptutor run math_animator "Animate a sine wave" --config enable_visual_review=true
deeptutor run visualize "Animate a sine wave" \
  --config render_mode=manim_video --config enable_visual_review=true

The option defaults to false. It also works with output_mode=image for math_animator and render_mode=manim_image for visualize. Other visualizers, including the general auto loop, ignore it. Manim's optional dependencies are still required.

For SDK turns, pass config={"enable_visual_review": True} in the TurnRequest sent to DeepTutorApp.start_turn(). API clients use the same config object with JSON true. For book animation blocks, set params={"enable_visual_review": True} on the animation Block.

Review adds vision model calls and may add repair calls and re-renders, increasing cost and latency. It uses the existing limit of four retries, with a 120-second review timeout and a 180-second repair timeout. If no frames are available or the configured review model cannot inspect images, review is skipped with a summary. An unsuccessful review after all retries returns the best available render and its failed review result; a review timeout follows the existing render error/retry path. Capability results expose render.visual_review; book blocks retain the same review data in metadata.visual_review (null when review did not run).

The table covers the full installation and optional add-ons; commands and capabilities require their modules to be enabled. Core provides chat and ask_questions.

GitHub Copilot credentials belong to the signed-in DeepTutor owner and live only at <runtime-home>/data/system/user-secrets/<owner-id>/private/github-copilot/credentials.v1.json, outside sandbox workspaces. CLI/admin partners use the administrator's credentials; other users sign in separately, and Copilot profiles cannot be shared through model grants. External nanobot/Copilot token files are never imported: after upgrading, run deeptutor provider login github-copilot again.

Login validates inference with a currently discovered model; init validates the selected model and aborts on failure without saving the draft configuration. Successful GitHub authentication alone does not establish Copilot model access (the saved login is retained if validation fails). Runtime requests follow the API endpoint returned by token exchange, including refreshes, and respect each model's Responses/Chat Completions endpoint metadata.

Copilot-specific Responses compatibility is applied at dispatch without rewriting stored history.

The core wheel supplies CLI and SDK; deeptutor-cli is a compatibility metapackage. Source exposes all checked-in modules, so install their Python dependencies and skip frontend setup for CLI use:

python -m pip install -r requirements/full.txt
python -m pip install -e . --no-deps

For a minimal installation, use the core wheel. Optional distributions contribute tools, capabilities, API routes, background services, and navigation. Modules share one Python environment and must match the core version. deeptutor[full] selects the common app modules at installation; individual features can still be removed later.

Stop DeepTutor (Ctrl+C in its terminal), then use the same Python environment and DEEPTUTOR_HOME:

deeptutor module list                       # installed / enabled / ready
deeptutor module disable research           # hide and deactivate; keep code
deeptutor module enable research            # restore it and required modules

# Package installations only; source checkouts use enable / disable:
deeptutor module install solve              # install the matching module and dependencies
deeptutor module uninstall solve --dry-run  # inspect the plan and dependency blockers
deeptutor module uninstall solve            # remove only this module's distribution
deeptutor chat                              # restart the CLI; use start for an installed Web app

Examples: solve, research, questions, knowledge, parsing, reading, mastery, books, memory, notebook, and partners. Dependents block removal; core cannot be removed through the module command. Disabling or uninstalling preserves settings, conversations, knowledge bases, and generated files. Shared third-party dependencies are retained.

In the browser: Settings → Runtime status → Modules shows module status and the corresponding terminal commands. Package changes require a stopped environment and are performed in the CLI. Chat → Customize page and Learning → New learning activity → Customize page change personal page choices immediately; hiding an entry does not uninstall its module or revoke access.

The 1.7.0 package family uses matching versions across core and feature wheels. For local wheel installation, pass --wheelhouse /path/to/wheels to module install. See module installation and source development for building the wheels and deployment details.

EduHub is the community hub DeepTutor launched for sharing teaching-oriented agent skills — Socratic tutors, flashcard builders, essay feedback, exam blueprints, concept explainers, and more. It is built into DeepTutor, so there's nothing to configure: a bare slug or an eduhub: prefix resolves to it.

Find and install — in the browser, open Personalization → Skills → Import from EduHub to browse the catalog and download a skill straight into your library. From the terminal:

deeptutor skill search "socratic tutor"               # search EduHub (the default hub)
deeptutor skill install socratic-tutor                # fetch → verify → register
deeptutor skill install eduhub:socratic-tutor@1.2.0   # pin a hub and a version
deeptutor skill list                                  # local skills with their hub provenance

Publish your own — package a SKILL.md and share it back to the community:

deeptutor skill login                                 # browser sign-in to EduHub
deeptutor skill publish ./my-skill                    # interactive: pick a track + tags, then upload
deeptutor skill update                                # roll back or release a new version

EduHub is also a standalone, ClawHub-compatible registry, so agents that aren't DeepTutor (Claude Code, Codex, …) can use it directly through the eduhub CLI — npx eduhub install socratic-tutor.

Whatever the source, every import passes the same safety gate before anything touches your workspace:

• the registry's security verdict is checked first — flagged packages are refused unless you pass --allow-unverified;
• archives are extracted defensively with path-traversal, entry-count, size, compression-ratio, suffix, and symlink checks; executable bits are stripped, while extensionless files remain allowed;
• frontmatter is normalized to DeepTutor's schema and always: is stripped, so a downloaded skill can never force itself into every system prompt;
• provenance — hub, version, verdict, and install time — is written to .hub-lock.json for audits and updates.

In multi-user deployments, browser imports land in the authenticated caller's skill layer, while CLI and admin-console installs target the owner/admin workspace; admin skills stay hidden and read-only for ordinary users until granted.

Because DeepTutor speaks the open Agent-Skills format, ClawHub works as a first-class source too — it's built in alongside EduHub. Pick it with the hub prefix:

deeptutor skill search "git release notes" --hub clawhub
deeptutor skill install clawhub:git-release-notes@1.0.1
deeptutor skill install clawhub:udiedrichsen/stock-analysis

When several publishers share the same slug, search shows each publisher and a fully scoped install ref (clawhub:<ownerHandle>/<slug>).

Add more registries in data/user/settings/skill_hubs.json: a type: "clawhub" entry points at any compatible HTTP API (EduHub and ClawHub both speak it), type: "command" wraps whatever fetch CLI a registry ships, and "default" chooses the hub used for bare slugs. All of them feed the same import gate.