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

> Contribute to DeepTutor by extending its agent-native architecture with new Tools or Capabilities. Submit pull requests to the dev branch after pre-commit checks.

- Repository: [✨Data Intelligence Lab@HKU✨/DeepTutor](https://github.com/HKUDS/DeepTutor)
- Tags: how-to-guide
- Published: 2026-04-08

---

**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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/orchestrator.py)), which routes inputs from the CLI, WebSocket API ([`deeptutor/api/routers/unified_ws.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/api/routers/unified_ws.py)), or Python SDK to the appropriate capability. Each capability receives a **UnifiedContext** ([`deeptutor/core/context.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/core/context.py)) containing session metadata and knowledge base handles, plus a **StreamBus** ([`deeptutor/core/stream_bus.py`](https://github.com/HKUDS/DeepTutor/blob/main/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/core/tool_protocol.py) and place your file in `deeptutor/tools/builtin/`. The **ToolRegistry** auto-discovers any class implementing the base protocol.

```python

# 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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/core/stream.py).

## Testing and Validation

Before submitting changes, validate your implementation using the CLI entry point in [`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py).

Test a capability directly:

```bash
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:

```bash
pre-commit run --all-files

```

## Submitting Your Contribution

Once your code passes local validation:

1. **Create a feature branch** from `dev`:

```bash
git checkout -b feature/your-feature-name

```

2. **Commit using structured format**:

```bash
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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/registry/tool_registry.py)) manages lightweight, stateless functions like `web_search` or `rag`, while the **CapabilityRegistry** ([`deeptutor/runtime/registry/capability_registry.py`](https://github.com/HKUDS/DeepTutor/blob/main/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.