DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
DeepTutor — Agent-Native Architecture
Overview
DeepTutor is an agent-native intelligent learning companion organized around a two-layer plugin model — single-shot Tools invoked by the LLM, and multi-stage Capabilities that take over a turn — exposed through three entry points: CLI, WebSocket API, and Python SDK. All three enter the durable turn application service before the shared turn engine routes a normalized context to the selected capability.
Architecture
Entry Points: CLI (Typer) | WebSocket /ws | Python SDK
↓ ↓ ↓
┌─────────────────────────────────────────────────┐
│ TurnApplicationService │
│ persists, coordinates, and replays turns │
└──────────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ TurnEngine → ChatOrchestrator │
│ routes UnifiedContext → selected Capability │
│ (defaults to `chat`) │
└──────────┬──────────────┬───────────────────────┘
│ │
┌──────────▼──┐ ┌────────▼──────────┐
│ ToolRegistry │ │ CapabilityRegistry │
│ (Level 1) │ │ (Level 2) │
└──────────────┘ └────────────────────┘
TurnApplicationService owns durable turn state and replay through the
session store and runtime coordinator. Each execution uses a per-turn
StreamBus; the orchestrator emits events, the turn runtime persists them,
and adapters replay them to consumers. Runtime settings live in
data/user/settings/*.json — project-root .env files are intentionally
ignored.
Level 1 — Tools
Single-function tools the LLM picks on demand. Eight user-toggleable tools
surface in /settings/tools:
| Tool | Description |
|---|---|
brainstorm |
Breadth-first idea exploration with rationale |
web_search |
Web search with citations |
paper_search |
arXiv preprint search |
zotero_search |
Search a configured Zotero library |
reason |
Dedicated deep-reasoning LLM call |
geogebra_analysis |
Analyze math images into GeoGebra commands |
imagegen |
Generate images |
videogen |
Generate videos |
USER_TOGGLEABLE_TOOL_NAMES in deeptutor/tools/builtin/__init__.py is the
authoritative toggle list. Other built-ins are context-gated or
capability-owned: CONFIGURABLE_BUILTIN_TOOL_NAMES declares the context-gated
surface, while deeptutor/agents/_shared/tool_composition.py owns the mount
rules (ToolMountFlags) and the always-available workspace tools. Examples
include rag, memory and notebook tools, read_skill, deferred MCP/CLI tools,
exec, ask_user, and mastery navigation. --tool selects from the
user-toggleable whitelist; it does not bypass context or capability gates.
Level 2 — Capabilities
Multi-stage pipelines that own the turn:
| Capability | Stages |
|---|---|
chat |
exploring → responding (single agentic loop, default) |
ask_questions |
responding (chat loop forced through ask_user) |
deep_solve |
responding (chat loop + solve planning tools) |
deep_question |
ideation → generation |
deep_research |
rephrasing → decomposing → researching → reporting |
visualize |
analyzing → generating → reviewing (SVG / Chart.js / Mermaid / HTML; or routes to Manim sub-stages via render_type) |
math_animator |
concept_analysis → concept_design → code_generation → code_retry → summary → render_output |
mastery_path |
responding (Guided Learning — chat loop + mastery tools, gated per topic type) |
immersive_reading |
responding (document- or timestamp-grounded media reading loop) |
video_lesson |
code_generation → render_check → render_output (Remotion lesson played live in the browser, with TTS narration) |
All capabilities converge on emit_capability_result() in
deeptutor/agents/_shared/capability_result.py so every turn emits the same envelope
(response payload + cost_summary from UsageTracker). Status copy and
prompts are i18n'd via capabilities/prompts/{en,zh}/<name>.yaml.
CLI Usage
# Install from the current dev source checkout
python -m pip install -r requirements/full.txt
python -m pip install -e . --no-deps
# Alternative in 1.7.0: choose one in a separate wheel environment
python -m pip install "deeptutor[full]" # Full app, CLI + Web/API
python -m pip install deeptutor # Core CLI/SDK (chat + ask_questions)
python -m pip install deeptutor-cli # Compatibility alias for core
# Run any capability
deeptutor run chat "Explain Fourier transform"
deeptutor run deep_solve "Solve x^2=4" --kb my-kb
deeptutor run visualize "Animate sine wave" --config render_mode=manim_video
# Interactive REPL
deeptutor chat
# (inside the REPL: /regenerate or /retry re-runs the last user message)
# Partners (IM-connected companions)
deeptutor partner list
# Knowledge bases, memory, server
deeptutor kb list
deeptutor kb create my-kb --doc textbook.pdf
deeptutor memory show
deeptutor serve --port 8001 # API server only
deeptutor start # backend + frontend together
Examples beyond core require their owning modules; use deeptutor module list
to inspect installed/enabled/ready states and deeptutor plugin list to discover
registered capabilities and tools. Source Web startup also needs Node.js 22 LTS
and npm ci --legacy-peer-deps in web/. CLI-only source users can skip frontend
setup, but still need the full Python dependencies. Follow
Agent Setup for credentials and verification.
Key Files
| Path | Purpose |
|---|---|
deeptutor/runtime/orchestrator.py |
ChatOrchestrator — unified entry |
deeptutor/runtime/launcher.py |
Backend + frontend lifecycle / port discovery |
deeptutor/runtime/registry/ |
Tool + Capability registries |
deeptutor/runtime/bootstrap/builtin_capabilities.py |
Built-in capability class paths |
deeptutor/services/config/runtime_settings.py |
JSON settings + process-env overrides |
deeptutor/services/subagent/ |
Local/remote agent connectors; register each backend in registry.py and its model options in models.py (Grok CLI uses native streaming-json) |
deeptutor/core/stream.py, deeptutor/runtime/stream_bus.py |
StreamEvent protocol + async fan-out |
deeptutor/core/tool_protocol.py |
BaseTool + ToolDefinition |
deeptutor/core/capability_protocol.py |
TurnCapability + CapabilityManifest |
deeptutor/core/context.py |
UnifiedContext dataclass |
deeptutor/tools/builtin/__init__.py |
All built-in tool wrappers |
deeptutor/capabilities/ |
Built-in capability implementations |
deeptutor/app/ |
DeepTutorApp SDK facade + durable application service |
deeptutor_cli/main.py |
Typer CLI entry point |
deeptutor/api/routers/unified_ws.py |
Unified WebSocket endpoint |
Dependency Layers
The 1.7.0 layout is modular; 1.6.15 and earlier packages use the
previous layout. Core owns the CLI, SDK and shared runtime; feature wheels must
match its version. deeptutor-cli is a metadata-only compatibility alias.
For development, use source or local wheels.
Module manifests own dependency groups; generated requirements files support
source, Docker and CI installs. pyproject.toml stores extra templates under
tool.deeptutor.optional-dependencies; build_metadata.py resolves same-version
wheel pins. Source checkouts expose all modules and install external dependencies
through requirements/full.txt, followed by pip install -e . --no-deps.
Use the source helper for optional extras rather than installing feature wheels
over the checkout:
python scripts/install_extras.py partners # Partner channel SDKs
python scripts/install_extras.py matrix # Matrix channel without E2EE/libolm
python scripts/install_extras.py matrix-e2e # Matrix with end-to-end encryption
python scripts/install_extras.py math-animator # Manim; also needs system LaTeX/ffmpeg
python scripts/install_extras.py dev # Test / lint tooling
python scripts/install_extras.py all # Full + Manim + dev dependencies
Stop DeepTutor before module changes. Source supports module enable/disable;
wheel environments also support module install/uninstall. Upgrading a legacy
deeptutor-cli installation requires uninstalling it before installing the new
packages, preserving the same DEEPTUTOR_HOME; see the setup guide. Validate
with python -m pip check, deeptutor module list, and the setup readiness checks.