AI Coding Training Platform

A local-first, feedback-driven learning environment for teaching "ai coding" through structured practice.

---

Prerequisites

You will need the following tools installed before getting started:

1. Git

Download and install Git from https://git-scm.com/downloads

Verify the installation:

git --version

2. Python 3.11+

Download and install Python from https://www.python.org/downloads/

⚠️ On Windows, make sure to check "Add Python to PATH" during installation.

Verify the installation:

python --version

---

Quick Start

Option A — Run locally with Python

Using a virtual environment is recommended to prevent library conflicts and ensure you are using the correct Python version:

Windows:

# 1. Clone the repository
git clone https://gitlab.empa.ch/empa-scientific-it/ai-coding-tutorial.git
cd ai-coding-tutorial

# 2. Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate

# 3. Install the dependencies and run
python -m pip install -e supervisor/
python run.py

macOS / Linux:

# 1. Clone the repository
git clone https://gitlab.empa.ch/empa-scientific-it/ai-coding-tutorial.git
cd ai-coding-tutorial

# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install the dependencies and run
pip install -e supervisor/
python run.py

Open http://localhost:10000 in your browser.

---

Option B — Docker (no Python setup needed)

Install Docker Desktop from https://www.docker.com/products/docker-desktop/

Then run:

git clone https://gitlab.empa.ch/empa-scientific-it/ai-coding-tutorial.git
cd ai-coding-tutorial
docker compose up

Open http://localhost:10000 in your browser.

---

How it works

1. The Supervisor runs at http://localhost:10000 and watches your work
2. You implement a small data-driven app inside /workspace
3. The platform tracks your progress automatically and gives hints when you're stuck
4. Complete all steps to finish the exercise

Exercise

See exercise/task.md for the full task description.

Your work area is the workspace/ folder — only edit files there.

---

Architecture

ai-coding-tutorial/
├── supervisor/         # FastAPI platform backend
├── workspace/          # YOUR WORK AREA
└── exercise/           # Task definition and rubric

The Supervisor:

• watches workspace/ for changes
• runs checks and tests on every save
• serves the progress dashboard at :10000
• pushes live updates via WebSocket