localGPT

A lightweight GPT transformer you can train and chat with entirely in the terminal. Built from scratch with PyTorch. No cloud, no API keys, no bloat.

---

Features

• Full transformer architecture (multi-head attention, feed-forward, layer norm)
• Two tokenizers switchable via config: character-level and word-level
• Optional C extension for faster encoding
• Tiny default size — trains in minutes on CPU
• Terminal chat interface with live controls
• Single config file for all hyperparameters
• Easy dataset swapping — just replace data/train.txt

---

Quickstart

1. Install PyTorch

pip install torch

2. (Optional) Build the C speedup

python scripts/build_ext.py

3. Add your dataset

Replace data/train.txt with any text file. The more text the better — aim for 100k+ characters.

4. Train

python train.py

5. Chat

python chat.py

---

Configuration

All settings live in config.py:

Setting	Default	Description
TOKENIZER	"char"	"char" or "word"
BLOCK_SIZE	128	Context window length
N_EMBD	128	Embedding dimension
N_HEAD	4	Attention heads
N_LAYER	4	Transformer blocks
MAX_ITERS	3000	Training steps
LEARNING_RATE	3e-4	AdamW learning rate
TEMPERATURE	0.8	Generation randomness
TOP_K	40	Top-k sampling
DEVICE	"cpu"	"cpu" or "cuda"

---

Updating the Dataset

Just replace data/train.txt with new text and retrain:

python train.py

The tokenizer rebuilds automatically. Previous checkpoints are overwritten.

---

Chat Commands

Command	Description
/temp 0.8	Set generation temperature
/topk 40	Set top-k sampling
/len 200	Set max response tokens
/reset	Clear rolling context
/info	Show model info
/help	List commands
/quit	Exit

---

Project Structure

localGPT/
├── config.py           ← all settings
├── train.py            ← training loop
├── chat.py             ← terminal chat
├── model/
│   └── gpt.py          ← transformer architecture
├── tokenizer/
│   ├── char_tokenizer.py
│   ├── word_tokenizer.py
│   └── __init__.py
├── scripts/
│   ├── fast_encode.c   ← optional C speedup
│   └── build_ext.py    ← builds the C extension
├── data/
│   └── train.txt       ← your training data
└── checkpoints/        ← saved model (created on training)

---

Versioning

Version	Notes
localGPT	Initial release — tiny transformer, char + word tokenizers
localGPT2	Coming soon

---

License

MIT