Python Tutor

Python Tutor is an AI-assisted coding workspace designed for learning Python through guided practice, explanation, and feedback.

The core idea is simple: instead of using AI to just provide answers, this project uses AI as a learning partner that adapts to the learner's current level and explains code in a way that builds understanding.

Project Goal

This project aims to make AI a practical tool for code learning by:

• Explaining code and debugging decisions, not only outputting final code.
• Adapting responses to learner preferences (skill level, explanation style, response depth).
• Keeping the learner's current code/document in context so feedback is specific.
• Supporting iterative learning through chat, diagnostics, and imported reference material.

What It Includes

• Interactive coding UI with editor + AI chat panel.
• Streaming AI responses for fast conversational feedback.
• Audience profile controls to tune how explanations are delivered.
• Python diagnostics endpoint (syntax + undefined-name checks).
• Documentation import from URLs and files (converted to markdown for study context).
• LangChain/LangGraph-based backend agent that injects learner code context into prompts.

Architecture

Frontend

• Framework: Next.js (React + TypeScript)
• Location: frontend/
• Main responsibilities:
  • Code/notebook editing
  • Chat UI and streaming token rendering
  • Calling backend APIs for chat and diagnostics
  • Managing imported learning materials

Backend

• Framework: FastAPI (Python)
• Location: backend/
• Main responsibilities:
  • Chat endpoints (/api/chat, /api/chat/stream)
  • Python diagnostics endpoint (/api/diagnostics/python)
  • Document import endpoints (/api/docs/import-url, /api/docs/import-file)
  • Agent orchestration using LangChain + LangGraph

Getting Started

Prerequisites

• Python 3.13+
• Node.js 20+
• One package manager for frontend: pnpm (recommended), npm, yarn, or bun
• A configured LLM provider for the backend (for example OpenAI, Anthropic, Ollama, or Google via optional dependencies)

1. Backend Setup

From the repository root:

cd backend
uv sync

Create a .env file in backend/ (example):

CHAT_MODEL=gpt-4o-mini
CHAT_MODEL_PROVIDER=openai

Then start the API server:

uv run fastapi dev src/api/main.py

Backend runs at http://localhost:8000.

2. Frontend Setup

From the repository root:

cd frontend
pnpm install
pnpm dev

Frontend runs at http://localhost:3000.

3. Use the Tutor

1. Open the frontend in your browser.
2. Paste or edit Python code in the editor.
3. Ask the assistant questions about logic, bugs, design, or improvements.
4. Adjust audience profile options to control teaching style:
   • Skill Level: beginner / intermediate / master
   • Explanation Style: step-by-step / concept-first / concise
   • Response Depth: short / balanced / detailed
5. Optionally import docs/files to give the assistant additional learning context.

API Overview

• POST /api/chat: Returns full response text.
• POST /api/chat/stream: Streams response tokens using SSE.
• POST /api/diagnostics/python: Returns editor diagnostics for Python source.
• POST /api/docs/import-url: Imports and converts URL content to markdown.
• POST /api/docs/import-file: Imports and converts supported files to markdown.

Why This Is a Learning Tool (Not Just a Code Generator)

This project is intentionally structured around learning behavior:

• The assistant is guided to explain and justify, not only provide snippets.
• Responses are tailored to learner background and desired depth.
• The active code context is part of every tutoring interaction.
• Fast iteration loop (edit -> ask -> diagnose -> revise) supports deliberate practice.