deeptutor 1.4.0b0

An agent-native intelligent learning companion with multi-agent collaboration and RAG

 

DeepTutor: Agent-Native Personalized Tutoring

                   

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

---

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

🗺️ Roadmap is tracked in the open at HKUDS/DeepTutor#498 — comment there to vote on items or propose new ones.

📦 Releases

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

Past releases (more than 2 weeks ago)

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

📰 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 to learn more about the design and ideas behind DeepTutor.

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

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

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

[2025.12.29] DeepTutor is officially released!

✨ Key Features

Work surfaces

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

Your library

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

Extensibility & control

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

---

🚀 Get Started

DeepTutor now has four parallel installation paths. All of them use the same runtime configuration layout:

• Settings live in data/user/settings/ under your current workspace, or under DEEPTUTOR_HOME / deeptutor start --home when you choose one explicitly.
• model_catalog.json stores model provider profiles, base URLs, API keys, active models, embedding settings, and search settings.
• system.json stores launch ports, public API base, CORS, TLS, and attachment options.
• auth.json stores the optional auth toggle and bootstrap credential hash.
• integrations.json stores optional sidecars such as PocketBase.
• Project-root .env is no longer used as an application configuration file.

For the full local app, the recommended order is choose a workspace → install → deeptutor init → deeptutor start. deeptutor start can backfill missing default files as a safety net, but normal first-run setup should go through deeptutor init so ports and model settings are explicit before the Web app starts.

Option 1 — Install DeepTutor

Use this when you want the full local Web app and CLI without cloning the repository.

mkdir -p my-deeptutor
cd my-deeptutor
pip install -U deeptutor
deeptutor init
deeptutor start

🧪 Trying the v1.4.0 beta? PyPI normalizes 1.4.0-beta to 1.4.0b0, so pip install -U deeptutor will stay on the latest stable. Opt in to the pre-release with either of:

pip install --pre -U deeptutor      # latest pre-release
pip install -U deeptutor==1.4.0b0   # pin to v1.4.0-beta exactly

deeptutor init writes configuration under data/user/settings/ in the directory where you run it. It prompts for:

• Backend port, default 8001
• Frontend port, default 3782
• LLM provider binding, base URL, API key, and model name
• Optional embedding provider for Knowledge Base / RAG

After deeptutor start, open the frontend URL printed in the terminal. With default ports, that URL is http://127.0.0.1:3782. If you changed frontend_port during deeptutor init or later edited data/user/settings/system.json, use that configured port instead.

Keep the deeptutor start terminal open. Press Ctrl+C in that terminal to stop both backend and frontend.

Notes:

• deeptutor start starts the FastAPI backend and the packaged Next.js frontend together.
• The packaged Web app does not require git clone or npm install, but it still needs a local Node.js 20+ runtime to execute the bundled Next.js standalone server.
• If you deliberately skip deeptutor init for a quick trial, the app starts with safe default ports and empty model settings; configure models afterward in Settings → Models.

Option 2 — Install From Source

Use this when you are developing DeepTutor or want to run directly from a checkout. Use Python 3.11+ and Node.js 22 LTS for the closest match to CI and Docker.

1. Clone the repository

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

2. Create a Python environment

macOS / Linux with venv:

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

Windows PowerShell with venv:

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

Conda / Miniconda:

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

3. Install the local package and frontend dependencies

python -m pip install -e .
cd web
npm ci --legacy-peer-deps
cd ..

If you intentionally change frontend dependencies, use npm install --legacy-peer-deps to refresh web/package-lock.json, then commit both web/package.json and web/package-lock.json.

4. Configure and start

deeptutor init
deeptutor start

Source installs use the local web/ directory for the frontend and start it with Next.js dev mode. Keep the deeptutor start terminal open while using the app. They are intentionally developer-friendly and do not write configuration to .env; edit data/user/settings/*.json or use the Web Settings page.

If deeptutor start reports an existing frontend that is not responding, stop the PID printed in the message. If no Next.js process is running, remove the stale lock files and start again:

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

Useful developer extras:

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

Option 3 — Docker

Use this when you want the full Web app in one container. Images are published to GitHub Container Registry:

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

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

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

Then open http://127.0.0.1:3782. Config, API keys, logs, workspace files, memory, and knowledge bases are stored in the deeptutor-data volume under /app/data.

The container creates /app/data/user/settings/*.json automatically on first boot. You can configure model providers directly in the Web Settings page without preparing local JSON files manually.

To use different host ports, change the left side of the -p mappings. For example, -p 127.0.0.1:8088:3782 makes the Web UI available at http://127.0.0.1:8088 while the container still listens on 3782. If you change the container-side ports in /app/data/user/settings/system.json, restart the container and make the right side of each -p host:container mapping match the configured container port.

Connecting To Ollama Or Other Host Services

Inside a Docker container, localhost refers to the container itself, not your host machine. If you run Ollama, LM Studio, llama.cpp, vLLM, or another model service on the host, use one of these approaches.

Option A — host gateway, recommended for normal Docker runs:

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

Then in DeepTutor Settings → Models, set the provider Base URL to host.docker.internal:

• Ollama LLM endpoint: http://host.docker.internal:11434/v1
• Ollama embedding endpoint: http://host.docker.internal:11434/api/embed
• LM Studio: http://host.docker.internal:1234/v1
• llama.cpp: http://host.docker.internal:8080/v1

On Docker Desktop for macOS/Windows, host.docker.internal is usually available even without --add-host. On Linux, the --add-host=host.docker.internal:host-gateway flag is the portable way to create that hostname on modern Docker Engine.

Option B — host networking, Linux only:

docker run --network=host \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

No -p mapping is needed in host-network mode. The container shares the host network directly, so open http://127.0.0.1:3782 by default, or the frontend_port configured in /app/data/user/settings/system.json. In this mode, host services can usually be reached with normal localhost URLs such as http://127.0.0.1:11434/v1. Host networking exposes container ports directly on the host and may conflict with existing services.

To run in the background instead, add -d and follow logs by name:

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

To stop a foreground Docker run, press Ctrl+C. If you used the named detached container above, run docker stop deeptutor. Before starting another container with the same name, remove the stopped one with docker rm deeptutor; the deeptutor-data volume keeps your settings and workspace.

Option 4 — CLI Only

Use this when you do not need the Web UI. The CLI-only package is installed from a local source checkout instead of PyPI.

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

python3 -m venv .venv-cli
source .venv-cli/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ./packaging/deeptutor-cli
deeptutor init --cli
deeptutor chat

Windows PowerShell:

py -3.11 -m venv .venv-cli
.\.venv-cli\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ./packaging/deeptutor-cli
deeptutor init --cli
deeptutor chat

deeptutor init --cli uses the same data/user/settings/ layout as the full app, but changes the wizard behavior:

• It skips backend/frontend port prompts because CLI-only usage does not start the Web app.
• It still writes default system.json, auth.json, integrations.json, model_catalog.json, main.yaml, and agents.yaml so the runtime layout is complete.
• It still prompts for the active LLM provider and model.
• It asks whether to configure embeddings, but the default answer is No; choose Yes if you plan to use deeptutor kb ... or RAG tools.

Common CLI commands:

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

The local deeptutor-cli install does not ship Web assets or server dependencies. Keep the source checkout around because the editable install points to it. If you later want the Web app, either follow Option 2 in the same checkout, or uninstall the local CLI package, install the full PyPI package with pip install -U deeptutor, run deeptutor init if you want to add Web ports, and then run deeptutor start from the same workspace.

Configuration Reference

The Web Settings page is the recommended editor, but the files are plain JSON/YAML and can be managed directly:

File	Purpose
data/user/settings/model_catalog.json	LLM, embedding, and search provider profiles; API keys; active models
data/user/settings/system.json	Backend/frontend ports, public API base, CORS, SSL verification, attachment directory
data/user/settings/auth.json	Optional auth toggle, username, password hash, token/cookie settings
data/user/settings/integrations.json	Optional PocketBase and sidecar integration settings
data/user/settings/interface.json	UI language/theme/sidebar preferences
data/user/settings/main.yaml	Runtime behavior defaults and path injection
data/user/settings/agents.yaml	Capability/tool temperature and token settings

Minimal model setup can be done in the browser: open Settings → Models, add an LLM profile, set Base URL / API key / model name, and save. Add an embedding profile only if you plan to use Knowledge Base / RAG features.

📖 Explore DeepTutor

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

💬 Chat — Unified Intelligent Workspace

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

Mode	What it does	Built on
Chat	Flexible conversation with any tool; pick from RAG, web search, code execution, deep reasoning, brainstorming, paper search, GeoGebra analysis.	LlamaIndex-backed RAG + tool registry
Solve	Multi-step plan → investigate → solve → verify, with precise source citations.	Agentic engine (deep_solve)
Quiz	Auto-validated question generation grounded in your KB; spawns a follow-up chat composer per question.	Agentic engine (deep_question)
Research	Decomposes a topic into subtopics, dispatches parallel agents across RAG / web / arXiv, and produces a cited report with iterative append-mode revisions.	Rebuilt pipeline.py (~45% smaller, citations + iterative reporting preserved)
Visualize	Generate SVG diagrams, Chart.js charts, Mermaid graphs, interactive HTML pages, or Manim videos / storyboards — the analyzer picks the right render_type.	Visualize pipeline (Animator merged in)

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

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

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

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

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

📖 Book Engine — Interactive "Living Books"

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

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

Pages are assembled from 13 block types — text, callout, quiz, flash cards, code, figure, deep dive, animation, interactive demo (now including a GeoGebra viewer), timeline, concept graph, section, and user note — each rendered with its own interactive component. Book pages are fingerprinted against their source KB; deeptutor book health reports drift and deeptutor book refresh-fingerprints clears stale pages when sources change.

📚 Knowledge Bases — RAG-Ready Document Libraries

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

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

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

🌐 Space — Your Personal Learning Library

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

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

🧠 Memory — Three-Layer Architecture

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

Layer	Role	Storage
L1 · Workspace mirror (LIVE)	Append-only trace of every interaction, per surface, per day. The lossless record of what actually happened.	trace/<surface>/<YYYY-MM-DD>.jsonl
L2 · Per-surface summaries (CURATED)	Surface-specific facts extracted by the consolidator. Each fact carries footnote citations back to L1 traces. Supports per-doc Update / Audit / Dedup runs.	L2/<surface>.md
L3 · Cross-surface knowledge (SYNTHESIS)	Cross-surface synthesis: your profile, recent timeline, scope of knowledge, and preferences. Hedged claims, each backed by L2 evidence.	L3/<recent|profile|scope|preferences>.md

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

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

⚙️ Settings — Unified Control Center

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

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

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

---

🦞 TutorBot — Persistent, Autonomous AI Tutors

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

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

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

---

⌨️ DeepTutor CLI — Agent-Native Interface

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

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

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

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

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

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

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

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

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

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

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

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

Full CLI command reference

Top-level

Command	Description
deeptutor run <capability> <message>	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 <id>	Create and start a new bot (--name, --persona, --model)
deeptutor bot start <id>	Start a bot
deeptutor bot stop <id>	Stop a bot

deeptutor kb

Command	Description
deeptutor kb list	List all knowledge bases
deeptutor kb info <name>	Show knowledge base details
deeptutor kb create <name>	Create from documents (--doc, --docs-dir)
deeptutor kb add <name>	Add documents incrementally
deeptutor kb search <name> <query>	Search a knowledge base
deeptutor kb set-default <name>	Set as default KB
deeptutor kb delete <name>	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 <id>	View session messages
deeptutor session open <id>	Resume session in REPL
deeptutor session rename <id>	Rename a session (--title)
deeptutor session delete <id>	Delete a session

deeptutor notebook

Command	Description
deeptutor notebook list	List notebooks
deeptutor notebook create <name>	Create a notebook (--description)
deeptutor notebook show <id>	View notebook records
deeptutor notebook add-md <id> <path>	Import markdown as record
deeptutor notebook replace-md <id> <rec> <path>	Replace a markdown record
deeptutor notebook remove-record <id> <rec>	Remove a record

deeptutor book

Command	Description
deeptutor book list	List all books in the workspace
deeptutor book health <book_id>	Check KB drift and book health
deeptutor book refresh-fingerprints <book_id>	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 <name>	Show tool or capability details
deeptutor provider login <provider>	Provider auth (openai-codex OAuth login; github-copilot validates an existing Copilot auth session)

---

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

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

Quick start (5 steps):

# 1. Enable auth in data/user/settings/auth.json:
#    {"enabled": true, "token_expire_hours": 24, "cookie_secure": false}

# 2. Restart the web stack.
deeptutor start

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

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

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

What the admin sees:

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

What ordinary users get:

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

Workspace layout:

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

Configuration reference:

Setting	Required	Description
data/user/settings/auth.json: enabled	Yes	Set to true to enable multi-user auth. Default false (single-user mode — admin paths everywhere).
multi-user/_system/auth/auth_secret	Recommended	JWT signing secret. Auto-generated on first authenticated boot if missing.
data/user/settings/auth.json: token_expire_hours	No	JWT lifetime; defaults to 24.
data/user/settings/auth.json: username/password_hash	No	Optional headless single-user bootstrap credential. Leave blank when using browser registration.
data/user/settings/system.json	No	deeptutor start derives frontend auth flags and API base from runtime settings.

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

⚠️ Single-process recommendation. The first-user-becomes-admin promotion is protected by an in-process threading.Lock. Multi-worker deployments should provision the first admin offline (start with auth.json.enabled=false, register the admin via the bootstrap flow, then set auth.json.enabled=true) or back the user store with an external system.

🌐 Community & Ecosystem

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

Project	Role in DeepTutor
nanobot	Ultra-lightweight agent engine powering TutorBot
LlamaIndex	RAG pipeline and document indexing backbone
ManimCat	AI-driven math animation generation for Math Animator

From the HKUDS ecosystem:

⚡ LightRAG	🤖 AutoAgent	🔬 AI-Researcher	🧬 nanobot
Simple & Fast RAG	Zero-Code Agent Framework	Automated Research	Ultra-Lightweight AI Agent

🤝 Contributing

We hope DeepTutor becomes a gift for the community. 🎁

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

⭐ Star History

Data Intelligence Lab @ HKU

⭐ Star us · 🐛 Report a bug · 💬 Discussions

---

Licensed under the Apache License 2.0.