How to Contribute to the DeepTutor Project: A Developer's Guide to Agent-Native Architecture

You contribute to DeepTutor by extending its agent-native architecture through new Tools (single-function utilities) or Capabilities (multi-step pipelines), submitting pull requests to the dev branch after running pre-commit checks.

DeepTutor is an open-source educational AI framework built around a modular, extensible architecture that separates lightweight utilities from complex agent workflows. Whether you want to add a new search provider, implement a custom reasoning pipeline, or enhance the CLI, understanding how to contribute to the DeepTutor project requires familiarity with its registry-based component system. This guide walks through the complete development workflow, from environment setup to submitting production-ready code.

Understanding the DeepTutor Architecture

DeepTutor uses a registry-based discovery system that distinguishes between single-function utilities and multi-stage agent pipelines. When you understand this separation, you can effectively extend the system without breaking existing functionality.

Tools vs Capabilities

Tools are atomic, single-purpose utilities registered in deeptutor/runtime/registry/tool_registry.py. The system auto-discovers built-in tools like rag, web_search, code_execution, reason, brainstorm, paper_search, and geogebra_analysis from the deeptutor/tools/builtin/ directory.

Capabilities are complex, multi-step pipelines registered in deeptutor/runtime/registry/capability_registry.py. These include the default chat capability, as well as specialized workflows like deep_solve and deep_question.

Entry Points and Orchestration

All requests flow through the ChatOrchestrator (deeptutor/runtime/orchestrator.py), which routes inputs from the CLI, WebSocket API (deeptutor/api/routers/unified_ws.py), or Python SDK to the appropriate capability. Each capability receives a UnifiedContext (deeptutor/core/context.py) containing session metadata and knowledge base handles, plus a StreamBus (deeptutor/core/stream_bus.py) for streaming staged output back to callers.

Setting Up Your Development Environment

Contributions target the dev branch, which serves as the integration branch for all new features.

1. Fork and clone the repository:

git clone https://github.com/<your-username>/DeepTutor.git
cd DeepTutor
git checkout dev && git pull origin dev

2. Create a virtual environment and install all dependencies:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

pip install -e ".[all]"

3. Install pre-commit hooks to enforce code quality:

pre-commit install

The project enforces strict quality gates using ruff, prettier, detect-secrets, bandit, and mypy.

Implementing New Features

Creating a Custom Tool

To add a new tool, subclass BaseTool from deeptutor/core/tool_protocol.py and place your file in deeptutor/tools/builtin/. The ToolRegistry auto-discovers any class implementing the base protocol.

# deeptutor/tools/builtin/awesome_tool.py

from deeptutor.core.tool_protocol import BaseTool, ToolResult

class AwesomeTool(BaseTool):
    name = "awesome_tool"
    description = "Performs advanced mathematical reasoning with symbolic computation."

    async def run(self, query: str, **kwargs) -> ToolResult:
        # Implementation logic here

        result = await self._compute_symbolic_math(query)
        return ToolResult(content=result)

No manual registration is required—the registry scans the builtin directory at startup.

Building a New Capability

Capabilities subclass BaseCapability from deeptutor/core/capability_protocol.py. They orchestrate multiple tools and manage conversation state through the UnifiedContext.

When implementing a capability, you access tools via the context's tool registry and stream intermediate results through the StreamBus using StreamEvent objects defined in deeptutor/core/stream.py.

Testing and Validation

Before submitting changes, validate your implementation using the CLI entry point in deeptutor_cli/main.py.

Test a capability directly:

deeptutor run deep_solve "Derive the formula for the area of an ellipse" -t rag --kb my-kb

This command routes through ChatOrchestrator → CapabilityRegistry → deep_solve, optionally invoking the rag tool for knowledge-base retrieval.

Run the full pre-commit suite to catch style and security issues:

pre-commit run --all-files

Submitting Your Contribution

Once your code passes local validation:

1. Create a feature branch from dev:

git checkout -b feature/your-feature-name

2. Commit using structured format:

git add .
git commit -m "feat: add awesome_tool for symbolic mathematics"

3. Push and open a Pull Request targeting the upstream dev branch.

Ensure CI passes all checks and reference the Contributing Guide at CONTRIBUTING.md for detailed commit message conventions and review requirements.

Summary

• DeepTutor separates concerns between Tools (single-function utilities) and Capabilities (multi-step pipelines) using registries that auto-discover components.
• All contributions flow through the dev branch and must pass pre-commit checks including ruff, mypy, and bandit.
• New tools extend BaseTool in deeptutor/core/tool_protocol.py and live in deeptutor/tools/builtin/.
• New capabilities extend BaseCapability and receive UnifiedContext and StreamBus for state management and output streaming.
• The ChatOrchestrator in deeptutor/runtime/orchestrator.py routes requests from CLI, WebSocket, or SDK entry points to your custom implementations.

Frequently Asked Questions

What branch should I target when contributing to DeepTutor?

Target the dev branch. According to the HKUDS/DeepTutor repository structure, dev serves as the integration branch where all features are merged before release. Creating feature branches from dev and submitting pull requests against it ensures your changes integrate cleanly with ongoing development.

How do I test my custom tool or capability locally?

Use the Typer-based CLI entry point at deeptutor_cli/main.py. Run deeptutor run <capability_name> "<query>" to execute your capability through the full orchestration stack, or invoke your tool directly through the Python SDK. Ensure you activate your virtual environment with pip install -e ".[all]" installed to access all runtime dependencies.

What is the difference between the ToolRegistry and CapabilityRegistry?

The ToolRegistry (deeptutor/runtime/registry/tool_registry.py) manages lightweight, stateless functions like web_search or rag, while the CapabilityRegistry (deeptutor/runtime/registry/capability_registry.py) manages complex agent pipelines like deep_solve that coordinate multiple tools across several reasoning steps. Tools receive simple parameters; capabilities receive UnifiedContext and StreamBus objects for session management.

Which code quality tools does DeepTutor require?

The project mandates ruff for linting, prettier for formatting, detect-secrets for credential scanning, bandit for security analysis, and mypy for type checking. These run automatically via pre-commit hooks, but you can invoke them manually with pre-commit run --all-files before pushing your branch.

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