DeepTutor Project Structure: A Modular Agent-Native Architecture Guide

DeepTutor implements a layered, agent-native architecture that cleanly separates entry points, runtime orchestration, and extensibility through a two-level registry system managing tools and capabilities.

The HKUDS/DeepTutor repository is an open-source educational AI platform engineered for flexibility and scale. Understanding the DeepTutor project structure reveals how the system isolates concerns between user interfaces, business logic, and execution primitives. This design enables seamless integration across CLI, WebSocket API, and Python SDK interfaces while maintaining a consistent internal execution model.

High-Level Architectural Layers

The DeepTutor project structure follows a strict separation of concerns across four primary layers. At the top, Entry Points provide user-facing interfaces through the Typer-based CLI (deeptutor_cli/main.py) and FastAPI server (deeptutor/api/main.py). The Orchestration Layer contains the ChatOrchestrator class that routes incoming requests to appropriate processing pipelines. The Runtime Layer implements a two-level registry system distinguishing between atomic tools and complex capabilities. Finally, the Extension Layer supports self-contained plugins and domain-specific agents.

Entry Points and Interface Layer

DeepTutor exposes three distinct interfaces that all funnel into the same core runtime.

Command-Line Interface

The CLI is implemented using Typer in deeptutor_cli/main.py, with subcommand modules located in deeptutor_cli/*.py (e.g., deeptutor_cli/chat.py). This entry point supports running capabilities directly, managing knowledge bases, and launching the web UI.

deeptutor run chat "Explain Fourier transform"

WebSocket and HTTP API

The FastAPI application bootstrap resides in deeptutor/api/main.py. Individual capability endpoints are modularized under deeptutor/api/routers/*.py, such as deeptutor/api/routers/chat.py. The system supports both standard HTTP requests and persistent WebSocket connections at /api/v1/ws for streaming responses.

Python SDK

Developers can import and invoke capabilities programmatically without using the CLI or API, accessing the same ChatOrchestrator and registry systems directly from Python code.

The Orchestration Engine

At the heart of the DeepTutor project structure sits the ChatOrchestrator, defined in deeptutor/runtime/orchestrator.py. This class acts as the central traffic controller, receiving requests from any entry point and resolving them to the appropriate capability. The orchestrator manages the lifecycle of requests, coordinates streaming output, and ensures that execution contexts are properly initialized and passed downstream.

Two-Level Registry System

DeepTutor distinguishes between atomic operations and complex workflows through a hierarchical registry model documented in the repository's AGENTS.md.

Level 1: Tool Registry

The Tool Registry (deeptutor/runtime/registry/tool_registry.py) manages lightweight, single-function utilities that LLMs can invoke on demand. These include RAG retrieval, web search, and code execution primitives. Tools registered here inherit from BaseTool and execute discrete, stateless operations.

from deeptutor.runtime.registry import tool_registry

search = tool_registry.get_tool("web_search")
result = await search.run(query="latest advances in quantum computing")
print(result)

Level 2: Capability Registry

The Capability Registry (deeptutor/runtime/registry/capability_registry.py) handles multi-step pipelines that combine tools, reasoning stages, and streaming output. Capabilities inherit from BaseCapability and include implementations like chat (deeptutor/capabilities/chat.py) and deep-solve (deeptutor/capabilities/deep_solve.py). These represent high-level user-facing features that orchestrate multiple tools and internal events to produce comprehensive responses.

{
  "type": "run_capability",
  "payload": {
    "name": "deep_solve",
    "input": "Solve x^2 = 4"
  }
}

Core Runtime Infrastructure

The execution model relies on several primitives defined in the deeptutor/core/ package.

Streaming and Context Management

The StreamBus class (deeptutor/core/stream_bus.py) provides an event-driven mechanism for streaming intermediate results, reasoning steps, and final outputs back to callers. This enables real-time feedback during long-running operations. The UnifiedContext class (deeptutor/core/context.py) maintains execution state, user session data, and configuration that persists throughout a capability's lifecycle.

Event System

Internal communication between components utilizes an event bus located in deeptutor/events/, decoupling the orchestrator from specific tool implementations and enabling asynchronous processing.

Agents and Plugin Architecture

DeepTutor supports both built-in agents and third-party extensions.

Domain-Specific Agents

Concrete agent implementations reside in deeptutor/agents/, including the Vision Solver (deeptutor/agents/vision_solver/) for image-to-text reasoning, the Math Animator (deeptutor/agents/math_animator/) for generating animated proofs, and the base abstraction in deeptutor/agents/base_agent.py.

Plugin System

Playground extensions are self-contained feature packs stored in deeptutor/plugins/<plugin_name>/. Each plugin exposes its functionality through a manifest.yaml file that declares available capabilities and configuration schemas. The PluginLoader class dynamically discovers and registers these capabilities at runtime.

from deeptutor.plugins.loader import PluginLoader

loader = PluginLoader()
loader.load("deep_research")
deep_research = loader.get_capability("deep_research")
await deep_research.run(context, stream)

Directory Structure

The physical layout of the HKUDS/DeepTutor repository reflects these architectural boundaries:

deeptutor/                 # Core library

├─ agents/                # Domain-specific agent implementations

├─ api/                   # FastAPI server and routers

├─ capabilities/          # High-level pipeline definitions (chat, deep_solve, etc.)

├─ config/                # Settings schema and defaults (settings.py)

├─ core/                  # Orchestration primitives (stream_bus.py, context.py)

├─ events/                # Internal event bus implementations

├─ plugins/               # Extension manifests and loaders

├─ runtime/               # Tool and capability registries

│  ├─ registry/
│  │  ├─ tool_registry.py
│  │  └─ capability_registry.py
│  └─ orchestrator.py
└─ services/              # Background processes and setup (setup/init.py)

deeptutor_cli/            # Typer-based CLI entry points

assets/                   # Static documentation and release assets

docs/                     # Markdown documentation

scripts/                  # Utility and migration scripts

tests/                    # Unit and integration tests

Configuration and Services

Centralized configuration management occurs in deeptutor/config/settings.py, handling LLM provider credentials, RAG pipeline parameters, and UI port assignments. Background initialization tasks, such as knowledge base setup and agent warm-up, are coordinated through deeptutor/services/setup/init.py.

Summary

• DeepTutor project structure organizes code into four distinct layers: Entry Points, Orchestration, Runtime, and Extensions.
• The ChatOrchestrator in deeptutor/runtime/orchestrator.py serves as the central request router for all interfaces.
• A two-level registry system separates atomic Tools (tool_registry.py) from complex Capabilities (capability_registry.py).
• StreamBus and UnifiedContext in deeptutor/core/ provide event-driven streaming and execution state management.
• The plugin architecture uses manifest.yaml files for declarative capability registration.
• Built-in agents for vision processing and mathematical reasoning reside in deeptutor/agents/.

Frequently Asked Questions

What is the difference between Level 1 Tools and Level 2 Capabilities in DeepTutor?

Level 1 Tools are single-function utilities registered in deeptutor/runtime/registry/tool_registry.py that perform discrete tasks like web searches or calculations. Level 2 Capabilities are multi-step pipelines defined in deeptutor/runtime/registry/capability_registry.py that orchestrate tools, reasoning, and streaming output to solve complex user requests like deep-research or problem-solving.

How does the ChatOrchestrator route requests?

The ChatOrchestrator, implemented in deeptutor/runtime/orchestrator.py, receives requests from the CLI, API, or SDK entry points. It resolves the requested capability name against the Capability Registry, initializes a UnifiedContext, and delegates execution to the appropriate pipeline while managing the StreamBus for real-time result streaming.

How do I extend DeepTutor with custom functionality?

You can extend the system by creating a plugin directory under deeptutor/plugins/<your_plugin>/ containing a manifest.yaml file that declares new capabilities. Alternatively, register custom tools directly in deeptutor/runtime/registry/tool_registry.py or capabilities in deeptutor/runtime/registry/capability_registry.py for built-in extensions.

Where is the FastAPI application defined?

The main FastAPI application bootstrap is located in deeptutor/api/main.py. Individual endpoint routers are modularized within deeptutor/api/routers/*.py, such as deeptutor/api/routers/chat.py, which handle specific capability endpoints and WebSocket connections.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}