git:20261026.9237139 to git:20261028.a6389d7

# 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

surface in `/settings/tools`:

| Tool | Description |

| -------------------- | --------------------------------------------- |

| `brainstorm` | Breadth-first idea exploration with rationale |

| `web_search` | Web search with citations |

| `paper_search` | arXiv preprint search |

| `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/capabilities/_shared.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

```bash

# Run any capability

deeptutor run chat "Explain Fourier transform"

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

```

## 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.py` | `DeepTutorApp` — Python SDK facade |

| `deeptutor_cli/main.py` | Typer CLI entry point |

| `deeptutor/api/routers/unified_ws.py` | Unified WebSocket endpoint |

## Dependency Layers

```