Programming Languages Used in DeepTutor: Python Backend and TypeScript Frontend Architecture

DeepTutor utilizes a dual-language architecture that pairs a Python-based backend for AI orchestration with a TypeScript/React frontend for real-time user interactions.

DeepTutor is an agent-native learning companion developed by HKUDS that leverages a sophisticated dual-language stack to deliver AI-driven tutoring capabilities. Understanding the programming languages used in DeepTutor reveals how the project strategically separates concerns between its AI engine and user interface. The codebase combines Python for backend intelligence with TypeScript for frontend interactivity, connected via strongly-typed WebSocket protocols that enable seamless language-agnostic streaming.

Python Backend: Core Engine and CLI

The Python layer implements the agent-native runtime, LLM orchestration, and command-line interface that power DeepTutor's educational AI capabilities.

Orchestration and Runtime Logic

At the heart of the Python backend lies the orchestration system defined in deeptutor/runtime/orchestrator.py. This module receives turn requests and constructs a UnifiedContext object (defined in deeptutor/core/context.py) that maintains conversation state and attachments. The orchestrator dispatches requests through the ToolRegistry and CapabilityRegistry, where each capability (such as deep_solve or deep_question) extends BaseCapability and executes as an async coroutine.

Command Line Interface

The CLI entry point resides in deeptutor_cli/main.py, which utilizes the typer library to expose capabilities directly to developers. This interface allows terminal invocation of the same AI functions available through the web API, making the system accessible for scripting and automation without launching the frontend.

# Run a deep-solve capability from the terminal

# (equivalent to: deeptutor run deep_solve "Solve x^2 = 4")

from deeptutor_cli.main import run_capability
from deeptutor_cli.common import build_turn_request

request = build_turn_request(
    content="Solve x^2 = 4",
    capability="deep_solve",
    session_id=None,
    tools=[],
    knowledge_bases=[],
    language="en",
)

run_capability(request=request, fmt="rich")

TypeScript Frontend: Real-Time Web Interface

The frontend layer employs TypeScript with React to provide a responsive, interactive learning environment that communicates with the Python backend via WebSockets.

Typed WebSocket Client

The UnifiedWSClient class in web/lib/unified-ws.ts implements a strongly-typed WebSocket client that mirrors Python's StreamEvent protocol. This client handles the /api/v1/ws endpoint, processing event types including stage_start, content, tool_call, and result to drive real-time UI updates without page refreshes.

React Components and Visualization

Built on Next.js 16 and React 19 as declared in web/package.json, the frontend under web/app/ renders progressive responses using libraries like rehype-katex for mathematical notation and cytoscape for interactive visualizations. The TypeScript type system ensures that messages exchanged with the Python backend maintain strict schema consistency.

import { UnifiedWSClient, StreamEvent } from "./unified-ws";

const client = new UnifiedWSClient((ev: StreamEvent) => {
  console.log(`⏳ ${ev.type}: ${ev.content}`);
});

client.connect();

// Start a turn asking the model to explain Fourier transform
client.send({
  type: "start_turn",
  content: "Explain Fourier transform",
  capability: "deep_question",
  tools: [],            // optional tool list
  language: "en",
});

Supporting Languages and Configuration

Beyond the core Python and TypeScript components, DeepTutor incorporates auxiliary languages for tooling and infrastructure. Shell (Bash) scripts in the scripts/ directory handle installation checks (such as scripts/check_install.py invoked by shell wrappers) and CI pipeline automation. JSON in web/package.json manages Node.js dependencies, while YAML in docker-compose.yml defines container orchestration for both the Python server and Node-based web UI.

Summary

• Python powers the backend orchestration, CLI (deeptutor_cli/main.py), and AI capabilities through async coroutines and registry patterns.
• TypeScript drives the frontend via UnifiedWSClient in web/lib/unified-ws.ts, providing typed WebSocket communication with React components.
• The architecture relies on JSON and YAML for configuration, plus Shell scripts for DevOps automation.
• Both layers communicate through a shared protocol over FastAPI WebSockets, enabling real-time streaming of educational content.

Frequently Asked Questions

Is DeepTutor written entirely in Python?

No, DeepTutor is not a single-language project. While the AI engine, orchestration logic in deeptutor/runtime/orchestrator.py, and CLI are implemented in Python, the interactive web interface is built with TypeScript and React. This dual-language approach allows the backend to focus on AI processing while the frontend handles responsive user interactions.

What framework does DeepTutor use for its frontend?

The frontend utilizes Next.js 16 with React 19, as specified in web/package.json. This setup supports server-side rendering capabilities and integrates with the TypeScript WebSocket client for real-time bidirectional communication with the Python backend.

How do Python and TypeScript communicate in DeepTutor?

The languages communicate via a FastAPI WebSocket endpoint (/api/v1/ws) exposed by the Python server. The TypeScript frontend uses the UnifiedWSClient class to establish a typed connection, serializing JSON messages that mirror Python's StreamEvent dataclasses for seamless real-time streaming of LLM-driven interactions.

Can I run DeepTutor capabilities without the web interface?

Yes, the Python CLI in deeptutor_cli/main.py allows direct invocation of capabilities from the terminal using the typer library. This enables developers to execute AI functions like deep_solve or deep_question through command-line arguments without launching the TypeScript frontend or WebSocket server.

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