DeepTutor: Instructions file for Codex

DeepTutor — Agent-Native Architecture

Overview

DeepTutor is an agent-native intelligent learning companion organized around a two-layer plugin model — single-shot Tools invoked by the LLM, and multi-stage Capabilities that take over a turn — exposed through three entry points: CLI, WebSocket API, and Python SDK. All three enter the durable turn application service before the shared turn engine routes a normalized context to the selected capability.

Architecture

Entry Points:  CLI (Typer)  |  WebSocket /ws  |  Python SDK
                    ↓                   ↓                   ↓
              ┌─────────────────────────────────────────────────┐
              │          TurnApplicationService                 │
              │   persists, coordinates, and replays turns      │
              └──────────────────────┬──────────────────────────┘
                                     ↓
              ┌─────────────────────────────────────────────────┐
              │       TurnEngine → ChatOrchestrator              │
              │   routes UnifiedContext → selected Capability    │
              │   (defaults to `chat`)                           │
              └──────────┬──────────────┬───────────────────────┘
                         │              │
              ┌──────────▼──┐  ┌────────▼──────────┐
              │ ToolRegistry │  │ CapabilityRegistry │
              │  (Level 1)   │  │   (Level 2)        │
              └──────────────┘  └────────────────────┘

TurnApplicationService owns durable turn state and replay through the session store and runtime coordinator. Each execution uses a per-turn StreamBus; the orchestrator emits events, the turn runtime persists them, and adapters replay them to consumers. Runtime settings live in data/user/settings/*.json — project-root .env files are intentionally ignored.

Level 1 — Tools

Single-function tools the LLM picks on demand. Eight user-toggleable tools surface in /settings/tools: