How to Find and Run the Main Script for DeepTutor

DeepTutor’s primary entry point is a Typer-based CLI defined in deeptutor_cli/main.py, while scripts/start_web.py launches the full web interface by orchestrating the FastAPI backend and Next.js frontend.

The HKUDS/DeepTutor repository provides distinct execution paths depending on whether you need headless command-line interaction or a complete graphical interface. Understanding the exact file locations and their roles ensures you invoke the correct entry point for your use case. This guide identifies the main scripts required to run DeepTutor and explains how they interact with the underlying API and frontend components.

CLI Entry Point: deeptutor_cli/main.py

The primary command-line interface is implemented in deeptutor_cli/main.py. This file initializes a Typer application that registers sub-commands—including chat, bot, kb, and the run command—and exposes methods for executing capabilities in a single turn without launching a persistent server.

When the package is installed, it exposes a deeptutor console script mapped to this module. You can invoke specific capabilities directly from your terminal without starting the full web stack.

Run a capability using the installed console script:

deeptutor run chat "Explain the Fourier transform" -t rag --kb my-kb

Alternatively, invoke the module directly without installation:

python -m deeptutor_cli.main run chat "Explain the Fourier transform" -t rag --kb my-kb

Web Interface Launcher: scripts/start_web.py

To start the complete web application, use the helper script scripts/start_web.py. This convenience script reads port configurations from the project’s .env file and concurrently launches both the API server and the frontend interface.

Specifically, the script calls deeptutor.api.run_server to initialize the FastAPI backend and spawns the Next.js frontend process. It automatically handles port wiring between the backend (typically localhost:8000) and the frontend (typically localhost:3000), printing accessible URLs upon successful startup.

Start the full web stack in one terminal:

python scripts/start_web.py

Expected output showing the service endpoints:

Backend   http://localhost:8000
Frontend  http://localhost:3000
Open http://localhost:3000 in your browser.

Key Backend Component: deeptutor/api/run_server.py

While scripts/start_web.py handles orchestration, the actual FastAPI server implementation resides in deeptutor/api/run_server.py. This module defines the REST and WebSocket endpoints that power the chat interface. When using the web launcher or running the API server independently, this file contains the core server logic that processes incoming requests.

Summary

• deeptutor_cli/main.py defines the Typer-based CLI and registers sub-commands including run for single-turn capability execution.
• scripts/start_web.py serves as the unified launcher for the web interface, starting both the backend and frontend components.
• The backend server is implemented in deeptutor/api/run_server.py, which provides the FastAPI application instance.
• Port configurations are automatically read from the .env file when using the web launcher script.

Frequently Asked Questions

Where is the main script to run DeepTutor from the command line?

The main CLI entry point is deeptutor_cli/main.py, which implements the Typer application. You can invoke it via the deeptutor console script when installed, or run python -m deeptutor_cli.main directly from the repository root.

How do I launch the DeepTutor web interface?

Execute python scripts/start_web.py to start the full web interface. This script launches the FastAPI backend via deeptutor.api.run_server and the Next.js frontend simultaneously, reading environment variables from .env to configure ports.

Can I use DeepTutor without starting the web server?

Yes. The CLI entry point supports single-turn execution via the run sub-command, allowing you to query capabilities directly without launching the persistent API server or frontend.

What server does the web launcher script actually start?

The scripts/start_web.py script imports and executes the run_server function from deeptutor/api/run_server.py, which initializes the FastAPI application that handles REST and WebSocket connections for the chat interface.

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