How to Train a DeepTutor Model: A Complete Configuration Guide

DeepTutor does not train model weights internally; instead, you fine-tune an external LLM and register it via the model-catalog configuration to integrate custom models into the agent-native orchestration layer.

The HKUDS/DeepTutor repository provides an agent-native orchestration system that augments large language models with tools, retrieval, and multi-step capabilities. If you want to learn how to train a DeepTutor model, you must first understand that DeepTutor itself contains no training loop or weight update mechanisms. The framework functions as a pluggable interface layer that consumes externally hosted LLM services through a unified provider abstraction.

Understanding DeepTutor's Architecture

DeepTutor operates as an agent-native orchestration layer rather than a training framework. It connects to external LLM services including OpenAI, Ollama, and OpenVINO Model Server through standardized provider interfaces. The codebase contains no gradient descent logic, loss functions, or parameter optimization routines.

The system expects all model training to occur outside its ecosystem. Once you have a fine-tuned model served via an HTTP API, DeepTutor handles the integration through environment-specific configurations and a centralized model catalog. This architecture separates the concerns of model development from agent orchestration, allowing you to swap underlying LLMs without modifying agent logic.

Prerequisites for Training a DeepTutor Model

Before integrating with DeepTutor, you must complete the external training pipeline. Fine-tune your base model using libraries such as Hugging Face Transformers, vLLM, or OpenVINO Model Server. Export the trained weights to a format compatible with your serving infrastructure, such as an OpenAI-compatible endpoint, Ollama model package, or OVMS model ID.

Your trained model must expose an HTTP API that implements the LLM provider interface expected by DeepTutor. The OpenAIProvider class in deeptutor/services/llm/providers/open_ai.py expects endpoints supporting the /v1/chat/completions route with standard request/response schemas. Ensure your serving infrastructure supports these protocol requirements before attempting integration.

Configuring Your Custom Model in DeepTutor

Step 1: Register the Model in model_catalog.json

DeepTutor discovers available models through the ModelCatalogService, which manages a JSON-based registry at data/user/model_catalog.json. You can programmatically add your custom model using the Python API:

from pathlib import Path
from deeptutor.services.config.model_catalog import ModelCatalogService

# Load (or create) the catalog

catalog_path = Path("data/user/model_catalog.json")
service = ModelCatalogService(path=catalog_path)
catalog = service.load()

# Add a new LLM profile & model

svc = "llm"
profile_id = f"{svc}-profile-myfine"
model_id = f"{svc}-model-myfine"

catalog["services"][svc]["profiles"].append(
    {"id": profile_id, "name": "My Fine‑Tuned LLM", "host": "http://localhost:8000/v1", "api_key": "none"}
)
catalog["services"][svc]["profiles"][-1].setdefault("models", []).append(
    {"id": model_id, "name": "my-fine‑tuned", "model": "my-fine-tuned"}
)

# Persist the changes

service.save(catalog)

The ModelCatalogService.save() method in deeptutor/services/config/model_catalog.py handles atomic writes and validation of the catalog structure. This registration creates the necessary metadata for DeepTutor to route requests to your custom endpoint.

Step 2: Configure Environment Variables

Runtime behavior depends on environment variables that map to your catalog entries. Copy the template from .env.example and specify the connection parameters:

# Copy the template and edit it

cp .env.example .env

# In .env, point to the new model

export LLM_MODEL=my-fine-tuned
export LLM_HOST=http://localhost:8000/v1
export LLM_API_KEY=none

The .env.example file documents all required variables including LLM_MODEL, LLM_HOST, and LLM_API_KEY. These variables override default configurations and establish the connection context for the LLM provider abstraction layer.

Step 3: Apply the Catalog Configuration

After updating the model catalog, render the configuration into environment variables using the CLI helper:

deeptutor config apply

This command invokes the configuration logic in deeptutor_cli/config_cmd.py, which loads the current catalog, resolves the active profile, and writes the appropriate values to .env. Running this step ensures synchronization between the JSON registry and the runtime environment.

Step 4: Run DeepTutor with Your Model

With the configuration applied, launch DeepTutor capabilities using the CLI entry point in deeptutor_cli/main.py:

deeptutor run chat "Explain the chain rule" -t rag --kb my-physics-kb

All downstream capabilities including deep_solve and deep_question will automatically route inference requests to your custom model endpoint. The agent orchestration logic remains agnostic to the underlying model, allowing your fine-tuned weights to power the full capability stack.

Key Implementation Files

Understanding these source files helps debug integration issues and extend the configuration system:

• deeptutor/services/config/model_catalog.py – Contains the ModelCatalogService class that loads, validates, and persists the model-catalog JSON registry.
• deeptutor_cli/config_cmd.py – Implements the deeptutor config apply command that renders catalog entries into environment variables.
• deeptutor/services/llm/providers/open_ai.py – Provides the OpenAIProvider class that abstracts HTTP calls to external LLM endpoints; compatible with any OpenAI-style API.
• .env.example – Template defining required environment variables for LLM connection strings and authentication.
• deeptutor_cli/main.py – Central CLI entry point that initializes capabilities using the configured model profile.

Summary

• DeepTutor functions as an orchestration layer, not a training framework, requiring external LLM fine-tuning before integration.
• Custom models integrate through the ModelCatalogService by registering profiles in model_catalog.json with specific host endpoints and API keys.
• Environment variables in .env activate specific catalog entries, with the deeptutor config apply CLI command automating the synchronization.
• All DeepTutor capabilities automatically use the configured model once registered, routing chat, retrieval, and reasoning tasks through your custom endpoint.
• The provider abstraction in deeptutor/services/llm/providers/ supports OpenAI-compatible APIs, Ollama, and OpenVINO Model Server interfaces.

Frequently Asked Questions

Does DeepTutor support fine-tuning LLMs directly?

No, DeepTutor does not contain training code or support direct fine-tuning of model weights. The repository focuses exclusively on orchestration and tool augmentation. You must fine-tune your model using external frameworks such as Hugging Face Transformers or PyTorch, then serve the resulting weights through a compatible HTTP API that DeepTutor can consume.

What LLM providers are compatible with DeepTutor?

DeepTutor supports any provider implementing the standard LLM interface, including OpenAI, Ollama, and OpenVINO Model Server. The OpenAIProvider class specifically expects endpoints compatible with the /v1/chat/completions schema. You can extend support by implementing additional provider classes following the pattern established in deeptutor/services/llm/providers/.

How do I switch between different models in DeepTutor?

Switch models by changing the LLM_MODEL environment variable or modifying the active profile in model_catalog.json. Run deeptutor config apply to update the runtime environment, then restart your DeepTutor session. The system dynamically selects the model specified in the environment without requiring code changes or reinstallation.

Can I use a local model with DeepTutor?

Yes, you can use locally hosted models by serving them through a local HTTP endpoint such as those provided by vLLM, Ollama, or OpenVINO Model Server. Register the local endpoint (e.g., http://localhost:8000/v1) in the model catalog, set the appropriate environment variables, and DeepTutor will route requests to your local inference server exactly as it would to a remote API.

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