train-llm-from-scratch: A Hand-Written PyTorch Pipeline From Raw Text to GRPO
A straightforward method for training your LLM, from downloading data to generating text.
At a glance
- What is it?
- FareedKhan-dev's repository walks from tokenization through pretraining, SFT, a Bradley-Terry reward model, PPO, DPO/ORPO/KTO and GRPO, all in plain PyTorch with no trl, peft or transformers. It is a teaching codebase first and a training framework second, and the difference matters when you pick a GPU.
- Who is it for?
- Adopt this if you want to read and modify every algorithm yourself, from single-head attention to GRPO, on a small Transformer that fits a free Colab or Kaggle T4 at the 13M parameter size. Do not adopt it as a production training stack or if you need a billion-parameter run on one card; the README's own table marks a 2B model as not fitting a 16 GB V100, T4 or RTX 4080.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 30 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap this repository fills: algorithms you can read, not just call
Most post-training material arrives as a library call. You import a trainer, pass a config, and the preference optimization happens somewhere you never open. This project takes the opposite route. The README states that every algorithm is hand written in plain PyTorch, explicitly without trl, peft or transformers. That constraint is the product. The pipeline runs from raw text to tokens, to a Transformer, to next-token loss, to a base model, then through SFT, a reward model, PPO or DPO, GRPO, and finally evaluation and chat. The intended reader is named in the README: a student reading top to bottom, a developer copying commands and file paths, or a researcher who cares about the post-training half. If you already know how DPO differs from PPO at the loss level, the pretraining sections will feel slow. If you have only ever called a trainer, the reward model and GAE sections are the reason to clone this.
What the code actually contains, from tokenizer to chat loop
The README describes the model as built from named pieces in sequence: an MLP, single-head attention, multi-head attention, a Transformer block, then the full Transformer. Each block of code is presented after a plain explanation, and most are followed by the output you should expect. The training story is one idea the author repeats: turn text into numbers, predict the next token, then keep changing the data and the loss until the model does what you want. Post-training is where the mechanism gets specific. SFT comes first, then a Bradley-Terry reward model, then a choice among PPO with GAE, DPO, ORPO and KTO, then GRPO or RLVR. The README also describes a Streamlit control panel and a documentation site, and the editable install is said to place config, src, data_loader and ui on the import path. One design choice worth flagging: the same small Transformer is reused across pretraining and every post-training stage. That keeps the code comparable stage to stage, but it also means nothing here demonstrates the memory or sharding problems that appear when the base model is large.
Getting it running: the install, the extras, and the memory flags
The README gives a three-command setup. Clone the repository, enter the directory, then run pip install -e . for an editable install. Optional extras are split by concern: pip install -e ".[train]" pulls in datasets and wandb for downloading data and logging, while pip install -e ".[ui]" pulls in streamlit, pandas and altair for the control panel. The README notes that the editable install removes the need to set PYTHONPATH by hand, which is the kind of detail that saves an hour on the first run. For memory pressure, the pretraining script exposes opt-in flags: --amp, --grad-checkpointing and --grad-accum. The README says these bring memory down a lot when a large config runs out of memory. Treat that as the author's description, not a measured figure. The repository also publishes a GPU table, and it is unusually candid about the ceiling: a 2B model is marked as not fitting a 16 GB V100, T4 or RTX 4080, while a 13M model fits all of them. The same table lists roughly 6B to 8B as the practical training maximum on a 40 GB A100.
Where the single-GPU premise breaks down
The headline claim is that you can train a billion or million parameter LLM on a single GPU. The README's own sizing table narrows that considerably. A free Colab or Kaggle T4 is described as enough for the 13 million parameter model and not enough for a billion parameter model. The largest practical size on a 16 GB card is listed around 1.5B to 2B, and the 2B row is marked as failing on that hardware. So the realistic envelope is a small model on modest hardware, with the memory flags as the lever when a config does not fit. There is a second limitation that is structural rather than about memory. Because everything is written by hand in plain PyTorch, you inherit none of the distributed training, checkpoint sharding or fused kernel machinery that a dedicated framework provides. There are no releases in the repository metadata, so there is no versioned artifact to pin against. If your goal is to ship a fine-tuned model on a deadline, this is the wrong tool, and the README does not pretend otherwise.
How this differs from the HF stack it deliberately avoids
The obvious comparison is the combination of transformers, trl and peft. The difference is not a feature gap in the abstract; it is where the abstraction sits. In that stack, you choose a model class, load a checkpoint, and hand a dataset to a trainer that implements the preference objective internally. Here, the objective is code you read. That has a concrete cost: you cannot swap in a pretrained base checkpoint and expect the post-training scripts to work unchanged, because the reward model and the policy are built around this repository's own Transformer definition. The benefit is the reverse. When the README says PPO with GAE or a Bradley-Terry reward model, the corresponding implementation is in the repository rather than in a dependency. A second difference is scope of data. The README says post-training is trained on real public datasets, and the train extra installs datasets and wandb for downloading and logging. That is a smaller, more legible data path than a full framework offers, and for teaching purposes that is the point.
Maintenance, licence and what a fork inherits
The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the standard reading of MIT, not legal advice; check the LICENSE file in the clone for the exact text. The last push recorded in the metadata is 2026-08-17 and the repository is not archived. No releases were retrieved, so there is no tagged version to depend on, and an editable install tracks whatever is on the default branch at the moment you clone. That matters for reproducibility: if you publish results, record the commit hash rather than a version number. The maintenance surface is also unusual. Because there are no trl, peft or transformers dependencies to upgrade, most of the churn you would normally absorb from an ecosystem simply does not reach you. What you do absorb is any change to the repository's own module layout, since config, src, data_loader and ui are the import roots the editable install creates. The README also states the author is looking for a PhD position in AI, which is worth knowing when you judge how much ongoing maintenance to expect.
The 13M sample output and what it tells you about expectations
The README prints the output of a trained 13 million parameter model so readers can see where the small end starts. The sample is grammatical in patches and incoherent across sentences, mixing years, place names and institutions without a consistent subject. That is the honest baseline for this scale, and it is useful precisely because it is unimpressive. It tells you that the value of the repository is the pipeline, not the artifact. The same sample also sets a realistic bar for anyone planning to run the post-training stages: if the base model at 13M produces text like that, the SFT and preference optimization stages are exercises in the mechanics of alignment rather than a route to a useful assistant. A reader who wants to see DPO change model behaviour in a measurable way needs a larger base, and the GPU table is the constraint that decides whether they can get there.
Editorial conclusion
Adopt this if you want to read and modify every algorithm yourself, from single-head attention to GRPO, on a small Transformer that fits a free Colab or Kaggle T4 at the 13M parameter size. Do not adopt it as a production training stack or if you need a billion-parameter run on one card; the README's own table marks a 2B model as not fitting a 16 GB V100, T4 or RTX 4080. Before committing, verify that pip install -e . puts config, src, data_loader and ui on your import path as the README claims, and confirm that the pretraining flags --amp, --grad-checkpointing and --grad-accum exist in the script you intend to run.
Community notes