{"owner":"HKUDS","repo":"DeepTutor","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# DeepTutor — Agent-Native Architecture\n\n## Overview\n\nDeepTutor is an **agent-native** intelligent learning companion organized\naround a two-layer plugin model — single-shot **Tools** invoked by the\nLLM, and multi-stage **Capabilities** that take over a turn — exposed\nthrough three entry points: CLI, WebSocket API, and Python SDK.\n\n## Architecture\n\n```\nEntry Points:  CLI (Typer)  |  WebSocket /api/v1/ws  |  Python SDK\n                    ↓                   ↓                   ↓\n              ┌─────────────────────────────────────────────────┐\n              │              ChatOrchestrator                    │\n              │   routes UnifiedContext → selected Capability    │\n              │   (defaults to `chat`)                           │\n              └──────────┬──────────────┬───────────────────────┘\n                         │              │\n              ┌──────────▼──┐  ┌────────▼──────────┐\n              │ ToolRegistry │  │ CapabilityRegistry │\n              │  (Level 1)   │  │   (Level 2)        │\n              └──────────────┘  └────────────────────┘\n```\n\nAll capabilities emit on a shared `StreamBus`; the orchestrator fans\nevents out to consumers. Runtime settings live in\n`data/user/settings/*.json` — project-root `.env` files are intentionally\nignored.\n\n### Level 1 — Tools\n\nSingle-function tools the LLM picks on demand. Four user-toggleable tools\nsurface in `/settings/tools`:\n\n| Tool           | Description                                   |\n| -------------- | --------------------------------------------- |\n| `brainstorm`   | Breadth-first idea exploration with rationale |\n| `web_search`   | Web search with citations                     |\n| `paper_search` | arXiv preprint search                         |\n| `reason`       | Dedicated deep-reasoning LLM call             |\n\nThe rest are **context-gated**: the chat capability auto-mounts them from\n`ToolMountFlags` (presence of a KB, attachments, sandbox availability, …), and\nany of them can also be force-enabled via `--tool`. Auto-mounted set: `rag`,\n`read_source`, `read_memory`, `write_memory`, `read_skill`, `load_tools`,\n`exec`, `code_execution` (sandboxed Python: NL intent → code → run),\n`list_notebook`, `write_note`, `web_fetch`, `github`, `cron`,\n`ask_user` (pauses the turn and resumes with the user's reply), plus the\nmastery-path tools. `geogebra_analysis` is parked under\n`COMING_SOON_TOOL_TYPES`.\n\n### Level 2 — Capabilities\n\nMulti-stage pipelines that own the turn:\n\n| Capability       | Stages                                                |\n| ---------------- | ----------------------------------------------------- |\n| `chat`           | exploring → responding (single agentic loop, default) |\n| `mastery_path`   | responding (Guided Learning — chat loop + mastery tools, gated per topic type) |\n| `deep_solve`     | planning → reasoning → writing                        |\n| `deep_question`  | ideation → generation                                 |\n| `deep_research`  | rephrasing → decomposing → researching → reporting    |\n| `visualize`      | analyzing → generating → reviewing (SVG / Chart.js / Mermaid / HTML; or routes to Manim sub-stages via `render_type`) |\n| `math_animator`  | concept_analysis → concept_design → code_generation → code_retry → summary → render_output |\n\nAll capabilities converge on `emit_capability_result()` in\n`deeptutor/capabilities/_shared.py` so every turn emits the same envelope\n(response payload + `cost_summary` from `UsageTracker`). Status copy and\nprompts are i18n'd via `capabilities/prompts/{en,zh}/<name>.yaml`.\n\n## CLI Usage\n\n```bash\n# Install\npip install deeptutor      # Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  # CLI-only\n\n# Run any capability\ndeeptutor run chat \"Explain Fourier transform\"\ndeeptutor run deep_solve \"Solve x^2=4\" -t rag --kb my-kb\ndeeptutor run visualize \"Animate sine wave\" --config render_mode=manim_video\n\n# Interactive REPL\ndeeptutor chat\n# (inside the REPL: /regenerate or /retry re-runs the last user message)\n\n# Partners (IM-connected companions)\ndeeptutor partner list\n\n# Knowledge bases, memory, server\ndeeptutor kb list\ndeeptutor kb create my-kb --doc textbook.pdf\ndeeptutor memory show\ndeeptutor serve --port 8001       # API server only\ndeeptutor start                   # backend + frontend together\n```\n\n## Key Files\n\n| Path                                       | Purpose                              |\n| ------------------------------------------ | ------------------------------------ |\n| `deeptutor/runtime/orchestrator.py`        | `ChatOrchestrator` — unified entry   |\n| `deeptutor/runtime/launcher.py`            | Backend + frontend lifecycle / port discovery |\n| `deeptutor/runtime/registry/`              | Tool + Capability registries         |\n| `deeptutor/runtime/bootstrap/builtin_capabilities.py` | Built-in capability class paths |\n| `deeptutor/services/config/runtime_settings.py` | JSON settings + process-env overrides |\n| `deeptutor/core/stream.py`, `stream_bus.py` | StreamEvent protocol + async fan-out |\n| `deeptutor/core/tool_protocol.py`          | `BaseTool` + `ToolDefinition`         |\n| `deeptutor/core/capability_protocol.py`    | `BaseCapability` + `CapabilityManifest` |\n| `deeptutor/core/context.py`                | `UnifiedContext` dataclass            |\n| `deeptutor/tools/builtin/__init__.py`      | All built-in tool wrappers           |\n| `deeptutor/capabilities/`                  | Built-in capability implementations  |\n| `deeptutor/app.py`                         | `DeepTutorApp` — Python SDK facade    |\n| `deeptutor_cli/main.py`                    | Typer CLI entry point                |\n| `deeptutor/api/routers/unified_ws.py`      | Unified WebSocket endpoint           |\n\n## Dependency Layers\n\nPublic install paths and source extras are defined in `pyproject.toml`.\nRequirements files mirror the same dependency groups for Docker/CI installs.\n\n```\npip install deeptutor      — Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  — CLI-only (LLM + RAG + providers + document parsing)\npip install -e .           — Source install for development\n\nSource extras (.[ extra ], defined in pyproject.toml):\n.[cli]            — CLI-only dependency set\n.[server]         — Web/API server dependencies\n.[partners]       — Partner channel SDKs + MCP client  (legacy alias: .[tutorbot])\n.[matrix]         — Matrix channel for Partners (matrix-nio; needs libolm)\n.[matrix-e2e]     — Matrix with end-to-end encryption (matrix-nio[e2e])\n.[math-animator]  — Manim addon (powers `visualize` Manim renders + `deeptutor run math_animator`)\n.[dev]            — Test / lint tooling\n.[all]            — Everything above\n```\n"},"files":{"AGENTS.md":"# DeepTutor — Agent-Native Architecture\n\n## Overview\n\nDeepTutor is an **agent-native** intelligent learning companion organized\naround a two-layer plugin model — single-shot **Tools** invoked by the\nLLM, and multi-stage **Capabilities** that take over a turn — exposed\nthrough three entry points: CLI, WebSocket API, and Python SDK.\n\n## Architecture\n\n```\nEntry Points:  CLI (Typer)  |  WebSocket /api/v1/ws  |  Python SDK\n                    ↓                   ↓                   ↓\n              ┌─────────────────────────────────────────────────┐\n              │              ChatOrchestrator                    │\n              │   routes UnifiedContext → selected Capability    │\n              │   (defaults to `chat`)                           │\n              └──────────┬──────────────┬───────────────────────┘\n                         │              │\n              ┌──────────▼──┐  ┌────────▼──────────┐\n              │ ToolRegistry │  │ CapabilityRegistry │\n              │  (Level 1)   │  │   (Level 2)        │\n              └──────────────┘  └────────────────────┘\n```\n\nAll capabilities emit on a shared `StreamBus`; the orchestrator fans\nevents out to consumers. Runtime settings live in\n`data/user/settings/*.json` — project-root `.env` files are intentionally\nignored.\n\n### Level 1 — Tools\n\nSingle-function tools the LLM picks on demand. Four user-toggleable tools\nsurface in `/settings/tools`:\n\n| Tool           | Description                                   |\n| -------------- | --------------------------------------------- |\n| `brainstorm`   | Breadth-first idea exploration with rationale |\n| `web_search`   | Web search with citations                     |\n| `paper_search` | arXiv preprint search                         |\n| `reason`       | Dedicated deep-reasoning LLM call             |\n\nThe rest are **context-gated**: the chat capability auto-mounts them from\n`ToolMountFlags` (presence of a KB, attachments, sandbox availability, …), and\nany of them can also be force-enabled via `--tool`. Auto-mounted set: `rag`,\n`read_source`, `read_memory`, `write_memory`, `read_skill`, `load_tools`,\n`exec`, `code_execution` (sandboxed Python: NL intent → code → run),\n`list_notebook`, `write_note`, `web_fetch`, `github`, `cron`,\n`ask_user` (pauses the turn and resumes with the user's reply), plus the\nmastery-path tools. `geogebra_analysis` is parked under\n`COMING_SOON_TOOL_TYPES`.\n\n### Level 2 — Capabilities\n\nMulti-stage pipelines that own the turn:\n\n| Capability       | Stages                                                |\n| ---------------- | ----------------------------------------------------- |\n| `chat`           | exploring → responding (single agentic loop, default) |\n| `mastery_path`   | responding (Guided Learning — chat loop + mastery tools, gated per topic type) |\n| `deep_solve`     | planning → reasoning → writing                        |\n| `deep_question`  | ideation → generation                                 |\n| `deep_research`  | rephrasing → decomposing → researching → reporting    |\n| `visualize`      | analyzing → generating → reviewing (SVG / Chart.js / Mermaid / HTML; or routes to Manim sub-stages via `render_type`) |\n| `math_animator`  | concept_analysis → concept_design → code_generation → code_retry → summary → render_output |\n\nAll capabilities converge on `emit_capability_result()` in\n`deeptutor/capabilities/_shared.py` so every turn emits the same envelope\n(response payload + `cost_summary` from `UsageTracker`). Status copy and\nprompts are i18n'd via `capabilities/prompts/{en,zh}/<name>.yaml`.\n\n## CLI Usage\n\n```bash\n# Install\npip install deeptutor      # Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  # CLI-only\n\n# Run any capability\ndeeptutor run chat \"Explain Fourier transform\"\ndeeptutor run deep_solve \"Solve x^2=4\" -t rag --kb my-kb\ndeeptutor run visualize \"Animate sine wave\" --config render_mode=manim_video\n\n# Interactive REPL\ndeeptutor chat\n# (inside the REPL: /regenerate or /retry re-runs the last user message)\n\n# Partners (IM-connected companions)\ndeeptutor partner list\n\n# Knowledge bases, memory, server\ndeeptutor kb list\ndeeptutor kb create my-kb --doc textbook.pdf\ndeeptutor memory show\ndeeptutor serve --port 8001       # API server only\ndeeptutor start                   # backend + frontend together\n```\n\n## Key Files\n\n| Path                                       | Purpose                              |\n| ------------------------------------------ | ------------------------------------ |\n| `deeptutor/runtime/orchestrator.py`        | `ChatOrchestrator` — unified entry   |\n| `deeptutor/runtime/launcher.py`            | Backend + frontend lifecycle / port discovery |\n| `deeptutor/runtime/registry/`              | Tool + Capability registries         |\n| `deeptutor/runtime/bootstrap/builtin_capabilities.py` | Built-in capability class paths |\n| `deeptutor/services/config/runtime_settings.py` | JSON settings + process-env overrides |\n| `deeptutor/core/stream.py`, `stream_bus.py` | StreamEvent protocol + async fan-out |\n| `deeptutor/core/tool_protocol.py`          | `BaseTool` + `ToolDefinition`         |\n| `deeptutor/core/capability_protocol.py`    | `BaseCapability` + `CapabilityManifest` |\n| `deeptutor/core/context.py`                | `UnifiedContext` dataclass            |\n| `deeptutor/tools/builtin/__init__.py`      | All built-in tool wrappers           |\n| `deeptutor/capabilities/`                  | Built-in capability implementations  |\n| `deeptutor/app.py`                         | `DeepTutorApp` — Python SDK facade    |\n| `deeptutor_cli/main.py`                    | Typer CLI entry point                |\n| `deeptutor/api/routers/unified_ws.py`      | Unified WebSocket endpoint           |\n\n## Dependency Layers\n\nPublic install paths and source extras are defined in `pyproject.toml`.\nRequirements files mirror the same dependency groups for Docker/CI installs.\n\n```\npip install deeptutor      — Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  — CLI-only (LLM + RAG + providers + document parsing)\npip install -e .           — Source install for development\n\nSource extras (.[ extra ], defined in pyproject.toml):\n.[cli]            — CLI-only dependency set\n.[server]         — Web/API server dependencies\n.[partners]       — Partner channel SDKs + MCP client  (legacy alias: .[tutorbot])\n.[matrix]         — Matrix channel for Partners (matrix-nio; needs libolm)\n.[matrix-e2e]     — Matrix with end-to-end encryption (matrix-nio[e2e])\n.[math-animator]  — Manim addon (powers `visualize` Manim renders + `deeptutor run math_animator`)\n.[dev]            — Test / lint tooling\n.[all]            — Everything above\n```\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# DeepTutor — Agent-Native Architecture\n\n## Overview\n\nDeepTutor is an **agent-native** intelligent learning companion organized\naround a two-layer plugin model — single-shot **Tools** invoked by the\nLLM, and multi-stage **Capabilities** that take over a turn — exposed\nthrough three entry points: CLI, WebSocket API, and Python SDK.\n\n## Architecture\n\n```\nEntry Points:  CLI (Typer)  |  WebSocket /api/v1/ws  |  Python SDK\n                    ↓                   ↓                   ↓\n              ┌─────────────────────────────────────────────────┐\n              │              ChatOrchestrator                    │\n              │   routes UnifiedContext → selected Capability    │\n              │   (defaults to `chat`)                           │\n              └──────────┬──────────────┬───────────────────────┘\n                         │              │\n              ┌──────────▼──┐  ┌────────▼──────────┐\n              │ ToolRegistry │  │ CapabilityRegistry │\n              │  (Level 1)   │  │   (Level 2)        │\n              └──────────────┘  └────────────────────┘\n```\n\nAll capabilities emit on a shared `StreamBus`; the orchestrator fans\nevents out to consumers. Runtime settings live in\n`data/user/settings/*.json` — project-root `.env` files are intentionally\nignored.\n\n### Level 1 — Tools\n\nSingle-function tools the LLM picks on demand. Four user-toggleable tools\nsurface in `/settings/tools`:\n\n| Tool           | Description                                   |\n| -------------- | --------------------------------------------- |\n| `brainstorm`   | Breadth-first idea exploration with rationale |\n| `web_search`   | Web search with citations                     |\n| `paper_search` | arXiv preprint search                         |\n| `reason`       | Dedicated deep-reasoning LLM call             |\n\nThe rest are **context-gated**: the chat capability auto-mounts them from\n`ToolMountFlags` (presence of a KB, attachments, sandbox availability, …), and\nany of them can also be force-enabled via `--tool`. Auto-mounted set: `rag`,\n`read_source`, `read_memory`, `write_memory`, `read_skill`, `load_tools`,\n`exec`, `code_execution` (sandboxed Python: NL intent → code → run),\n`list_notebook`, `write_note`, `web_fetch`, `github`, `cron`,\n`ask_user` (pauses the turn and resumes with the user's reply), plus the\nmastery-path tools. `geogebra_analysis` is parked under\n`COMING_SOON_TOOL_TYPES`.\n\n### Level 2 — Capabilities\n\nMulti-stage pipelines that own the turn:\n\n| Capability       | Stages                                                |\n| ---------------- | ----------------------------------------------------- |\n| `chat`           | exploring → responding (single agentic loop, default) |\n| `mastery_path`   | responding (Guided Learning — chat loop + mastery tools, gated per topic type) |\n| `deep_solve`     | planning → reasoning → writing                        |\n| `deep_question`  | ideation → generation                                 |\n| `deep_research`  | rephrasing → decomposing → researching → reporting    |\n| `visualize`      | analyzing → generating → reviewing (SVG / Chart.js / Mermaid / HTML; or routes to Manim sub-stages via `render_type`) |\n| `math_animator`  | concept_analysis → concept_design → code_generation → code_retry → summary → render_output |\n\nAll capabilities converge on `emit_capability_result()` in\n`deeptutor/capabilities/_shared.py` so every turn emits the same envelope\n(response payload + `cost_summary` from `UsageTracker`). Status copy and\nprompts are i18n'd via `capabilities/prompts/{en,zh}/<name>.yaml`.\n\n## CLI Usage\n\n```bash\n# Install\npip install deeptutor      # Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  # CLI-only\n\n# Run any capability\ndeeptutor run chat \"Explain Fourier transform\"\ndeeptutor run deep_solve \"Solve x^2=4\" -t rag --kb my-kb\ndeeptutor run visualize \"Animate sine wave\" --config render_mode=manim_video\n\n# Interactive REPL\ndeeptutor chat\n# (inside the REPL: /regenerate or /retry re-runs the last user message)\n\n# Partners (IM-connected companions)\ndeeptutor partner list\n\n# Knowledge bases, memory, server\ndeeptutor kb list\ndeeptutor kb create my-kb --doc textbook.pdf\ndeeptutor memory show\ndeeptutor serve --port 8001       # API server only\ndeeptutor start                   # backend + frontend together\n```\n\n## Key Files\n\n| Path                                       | Purpose                              |\n| ------------------------------------------ | ------------------------------------ |\n| `deeptutor/runtime/orchestrator.py`        | `ChatOrchestrator` — unified entry   |\n| `deeptutor/runtime/launcher.py`            | Backend + frontend lifecycle / port discovery |\n| `deeptutor/runtime/registry/`              | Tool + Capability registries         |\n| `deeptutor/runtime/bootstrap/builtin_capabilities.py` | Built-in capability class paths |\n| `deeptutor/services/config/runtime_settings.py` | JSON settings + process-env overrides |\n| `deeptutor/core/stream.py`, `stream_bus.py` | StreamEvent protocol + async fan-out |\n| `deeptutor/core/tool_protocol.py`          | `BaseTool` + `ToolDefinition`         |\n| `deeptutor/core/capability_protocol.py`    | `BaseCapability` + `CapabilityManifest` |\n| `deeptutor/core/context.py`                | `UnifiedContext` dataclass            |\n| `deeptutor/tools/builtin/__init__.py`      | All built-in tool wrappers           |\n| `deeptutor/capabilities/`                  | Built-in capability implementations  |\n| `deeptutor/app.py`                         | `DeepTutorApp` — Python SDK facade    |\n| `deeptutor_cli/main.py`                    | Typer CLI entry point                |\n| `deeptutor/api/routers/unified_ws.py`      | Unified WebSocket endpoint           |\n\n## Dependency Layers\n\nPublic install paths and source extras are defined in `pyproject.toml`.\nRequirements files mirror the same dependency groups for Docker/CI installs.\n\n```\npip install deeptutor      — Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  — CLI-only (LLM + RAG + providers + document parsing)\npip install -e .           — Source install for development\n\nSource extras (.[ extra ], defined in pyproject.toml):\n.[cli]            — CLI-only dependency set\n.[server]         — Web/API server dependencies\n.[partners]       — Partner channel SDKs + MCP client  (legacy alias: .[tutorbot])\n.[matrix]         — Matrix channel for Partners (matrix-nio; needs libolm)\n.[matrix-e2e]     — Matrix with end-to-end encryption (matrix-nio[e2e])\n.[math-animator]  — Manim addon (powers `visualize` Manim renders + `deeptutor run math_animator`)\n.[dev]            — Test / lint tooling\n.[all]            — Everything above\n```\n","category":"root","tokens":1675}]}