Installation Guide

Installation Guide

Take this slow the first time. Once you've done it end to end, re-running is a 30-second job. I'm assuming you've never deployed anything before, so I'll spell everything out.

Prerequisites

• First, make sure you have Python installed. If you don't, grab it from python.org — get the latest 3.x version, not 2.7. During install on Windows, tick the "Add Python to PATH" box or you'll fight the terminal later.
• A code editor. VS Code is free and fine.
• About 30–40 minutes total. Most of that is the model training itself while you go make chai.

Step 1 — Set up a virtual environment

Open a terminal inside the project folder and run:

python -m venv venv

Then activate it. On Windows:

venv\Scripts\activate

On macOS or Linux:

source venv/bin/activate

You'll know it worked when you see (venv) at the start of your terminal line.

Step 2 — Install the dependencies

pip install -r requirements.txt

This pulls in the CPU build of PyTorch plus Django. Heads up — PyTorch is a chunky download, so give it a minute or two on slower internet. It's normal.

Step 3 — Train the model

python -m model.train

This runs the default 3000 iterations. It prints a tokenizer demo, an untrained sample (pure gibberish — that's expected), the loss dropping every 250 steps, and finally a trained sample. When it finishes it writes checkpoints/model.pt and the log files the web demo reads. In a hurry? Run python -m model.train --max_iters 1000 for a faster, rougher run.

Step 4 — Set up the database

python manage.py migrate

This creates db.sqlite3 with Django's auth tables and the GenerationLog table that records each generation.

Step 5 — Run the demo

python manage.py runserver

Now open http://127.0.0.1:8000/ in your browser. Type a prompt, adjust temperature and top-k, and hit Generate.

Common issues

• "That port is already in use." Something else is squatting on port 8000. Just run it on another port: python manage.py runserver 8001 and open http://127.0.0.1:8001/ instead.
• Demo loads but there's no model / it errors on Generate. You skipped training. The web demo needs checkpoints/model.pt to exist, so run Step 3 before Step 5. And if you swapped in a new data/input.txt, retrain so the checkpoint's vocab matches the new text — otherwise decoding goes weird.

How to verify it's working

Two quick checks. During training, the untrained sample should look like random junk and the trained sample should look at least a little more like real text — that gap means it learned. On the web page, all six panels should load: generation box, tokenization, loss curve, before-vs-after, next-character probabilities, and the attention heatmap. If you want to see the logging in action, create an admin user with python manage.py createsuperuser, then check /admin/ after a couple of generations.