Build a Reasoning LLM in PyTorch: A Walk Through rasbt/reasoning-from-scratch

What This Repository Actually Teaches

The repository is the official code companion to the Manning book 'Build a Reasoning Model (From Scratch)'. It targets a specific gap: most LLM material explains architecture or fine-tuning, but reasoning models like DeepSeek R1 and GPT-5 Thinking add a layer of techniques that are rarely shown in code. The README states that you start with a pretrained base LLM, specifically Qwen3, and then add reasoning capabilities yourself. That means the notebooks are not about building a transformer from scratch; they are about the post-training methods that turn a plain generator into a model that thinks before it answers. The intended audience is someone who already understands basic LLM internals and wants to see the reasoning pipeline implemented in PyTorch, line by line.

The Chapter Sequence Maps to a Mental Model

The table of contents shows a deliberate progression. Chapter 2 loads a pretrained LLM and generates text, so you have a working baseline. Chapter 3 covers evaluation, which is essential because reasoning quality is not just loss on a training set. Then the book splits into two broad strategies. Chapters 4 and 5 handle inference-time scaling: chapter 4 improves reasoning by generating more candidates or longer chains at inference, and chapter 5 adds self-refinement, where the model critiques and revises its own output. Chapters 6 and 7 move to training: chapter 6 applies reinforcement learning, specifically GRPO (Group Relative Policy Optimization), and chapter 7 shows how to improve GRPO. Chapter 8 covers distillation, which compresses a larger reasoning model into a smaller, faster one. The repository also includes appendices for batching, evaluation, chat interfaces, and a full source code walkthrough of Qwen3 in Appendix C. That structure means you can choose a single technique without reading everything, but each chapter assumes you completed the previous one.

How the Code Is Organized and What You Run

Each chapter folder contains a main notebook and an exercise solutions notebook. For example, ch02/01_main-chapter-code/ch02_main.ipynb is the entry point for chapter 2. The README says you can clone the repository with 'git clone --depth 1 https://github.com/rasbt/reasoning-from-scratch.git' or download a ZIP. There is no package installation command listed, but chapter 2 of the book gives tips on setting up Python and managing packages. The notebooks are Jupyter files, so you open them in JupyterLab or VS Code and run cells sequentially. The README mentions that the code automatically uses a GPU if available, but it does not specify which PyTorch version or CUDA version is required. That is a gap: you will need to infer the environment from the notebooks themselves or from the book's instructions. The repository also includes a troubleshooting guide, which suggests that environment issues are common enough to warrant a dedicated file.

The Core Mechanism: From Base LLM to Reasoning Model

The README does not give a full architecture diagram, but the chapter list reveals the data flow. You begin with a pretrained Qwen3 model, which is a standard transformer that predicts the next token. Reasoning is added by changing how the model generates and how it is trained. Inference-time scaling (chapters 4 and 5) does not change the weights; instead, it changes the decoding procedure. For example, you might sample multiple completions and choose the best one, or you might let the model generate a chain of thought before the final answer. Self-refinement adds a loop where the model evaluates its own output and produces a revision. Reinforcement learning (chapters 6 and 7) does change the weights. GRPO is a policy gradient method that compares a group of sampled responses for the same prompt, assigns relative advantages, and updates the model to favor responses that get higher rewards. Distillation (chapter 8) trains a smaller model to mimic the output distribution of a larger reasoning model. The repository's mental model image, referenced in the README, presumably ties these together, but the image is not reproduced in the text.

Where the Repository Falls Short as a Reference

The most obvious limitation is that this is not a standalone library. There is no pip install command, no command-line interface, and no API to import. You must run notebooks in order, and the code is likely intertwined with the book's narrative. If you skip a chapter, you might miss a variable definition or a configuration step that is only explained in prose. The README also says the main chapters are designed to run on consumer hardware 'within a reasonable timeframe', but it does not quantify that. A reasoning model with inference-time scaling can generate thousands of tokens per prompt, and even a small model might take longer than a beginner expects. The repository does not include pretrained weights; it only includes code to load Qwen3 weights, so you need to download those separately, which requires network access and disk space. Finally, the book is the primary source of explanation. If you do not buy the book, the notebooks may feel cryptic, because they are meant to accompany chapters, not stand alone.

How It Compares to Other Learning Resources

A direct alternative is the Hugging Face TRL library, which offers implemented GRPO trainers and examples for reasoning models. TRL gives you production-grade code that you can run with a few configuration arguments, but it hides the internals behind abstractions. This repository takes the opposite approach: it shows every step in PyTorch, so you see how the gradient flows and how the reward is computed, but you lose the convenience and the robustness of a maintained library. Another alternative is the original DeepSeek-R1 technical report or the open source implementations of GRPO that fork from it, but those are research codebases, often less didactic. If your goal is to ship a reasoning model, TRL is the better starting point. If your goal is to understand what GRPO actually does under the hood, this repository is more direct because it is written for learning, not for production.

Maintenance, Licensing, and Upgrade Cost

The repository is under the Apache-2.0 license, which is permissive for both academic and commercial use, but it is not legal advice. The last push was September 2026, and there is a v1.0 release from May 2026, which suggests the code is stable for the book's publication. The README includes badges for tests on Linux, macOS, and Windows, so the notebooks are at least checked for execution across platforms. However, the code depends on external packages like PyTorch and the Qwen3 model, so the upgrade cost is tied to those dependencies. As PyTorch versions change, some notebook cells may break, and you will need to consult the troubleshooting guide or the repository's issues. The book itself is static, so if the field moves (for example, new RL algorithms beyond GRPO), this repository will not update unless the author pushes new content. For a learning resource, that is acceptable, but do not expect it to track the latest research.

Editorial conclusion

Adopt this repository if you are a developer or researcher who wants to understand reasoning LLMs by reading and modifying PyTorch code, and if you are willing to work through a book-structured sequence. Do not adopt it if you need a deployable reasoning system or a plug-and-play library; it is explicitly educational and tied to a specific base model. Before you start, verify that your hardware can run the main chapter notebooks (the README says they target consumer hardware but does not specify VRAM), and check the troubleshooting guide in the repository for environment issues. Also confirm that the Qwen3 model weights you plan to load are accessible from your network, because the code depends on those pretrained weights.

Official sources

1. License: Apache-2.0
2. Project website
3. rasbt/reasoning-from-scratch on GitHub
4. README
5. Releases