Learn ML by building it: a from-scratch machine learning framework in NumPy, and hundreds of coding questions that run in your browser.
Try it in the browser · Quickstart · Curriculum · Contributing · FAQ
Note
The CLI curriculum is our implementation of TinyTorch (Harvard CS249r), rebuilt and extended in our own style. The browser version is our own, built independently.
In the browser: open trentorch.com, sign in with GitHub, Google, or email, and start a question. Nothing to install. Python runs in your browser (Pyodide) and your code is graded instantly.
In your terminal:
git clone https://github.com/TrenTorch/TrenTorch.git
cd TrenTorch/TrenTorch_CLI
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt && pip install -e .
tren setup
tren module start 01Windows (PowerShell)
git clone https://github.com/TrenTorch/TrenTorch.git
cd TrenTorch\TrenTorch_CLI
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
pip install -e .
tren setup
tren module start 01tren setup adds tren to your PATH, so later terminals just need tren, no activating first. The command reference covers the rest (tren tui, tren serve, tren milestone, tren benchmark).
Run the web app locally
cd TrenTorch_Web
npm install
npm run devSign-in uses Supabase. Copy .env.example to .env and fill in your own project keys to use it locally.
| Command | What it does |
|---|---|
npm run check |
Type check |
npm run lint |
Prettier and ESLint |
npm run test |
Unit tests (Vitest) |
npm run test:pyodide |
Runs every question's reference solution and tests in a real Pyodide |
npm run build |
Production build (fully prerendered) |
Most people learn ML frameworks by importing them. We wanted to know how they work, so we built one. Every operation traces back to raw NumPy, the architecture matches what production frameworks use, and there is no import torch anywhere in the curriculum. You know what loss.backward() does because you wrote it.
The same ground, two ways:
| TrenTorch Web | TrenTorch CLI | |
|---|---|---|
| Where | Your browser | Your terminal and Jupyter |
| What | 350+ coding questions in 12 topic areas | 20 modules that build a framework, from tensors to a capstone |
| Progress | Saved to your account | Saved locally under user_data/ |
| Code | TrenTorch_Web/ (SvelteKit) |
TrenTorch_CLI/ (Python) |
A Problem of the Day features one new web question every day.
Web: 12 topic areas and their tracks
Every question has a problem statement, a theory section, a starter file, tests, and a reference solution.
| Area | Tracks |
|---|---|
| Math and statistics | Linear algebra, calculus, probability, information theory, data preprocessing, exploratory analysis, statistical inference |
| Classical ML | Linear regression, classification, decision trees, regularized models, ensembles, SVMs, instance-based and probabilistic models, unsupervised learning, evaluation, tabular foundation models |
| Deep learning core | Tensors, activations, losses, autograd |
| Training | Optimizers, layers, the training loop, regularization, why deep networks work |
| Sequence modeling | Tokenization, embeddings, recurrent networks, attention |
| Transformers and LLMs | The transformer block, modern architectures, language model assembly, LLM engineering |
| Inference | Attention mechanisms, KV cache and decoding, quantization, batching and serving metrics |
| Vision | Convolutions, pooling, CNN architecture and history, modern CNN concepts, vision transformers |
| Systems performance | Profiling, quantization, mixed-precision training, compression, acceleration, kernels |
| Distributed systems | Memoization, parallelism |
| RL and alignment | Reinforcement learning, post-training alignment, fine-tuning, benchmarking and a capstone |
| Production ML | Experiment tracking and versioning, deployment and serving, monitoring and drift |
CLI: 20 modules
| Part | Modules | What you build |
|---|---|---|
| I. Foundations | 01-08 | Tensors, activations, layers, losses, dataloader, autograd, optimizers, training |
| II. Vision | 09 | Conv2d, CNNs for image classification |
| III. Language | 10-13 | Tokenization, embeddings, attention, transformers |
| IV. Optimization | 14-20 | Profiling, quantization, compression, acceleration, memoization, benchmarking, capstone |
CLI: historical milestones
As you progress, you unlock recreations of landmark ML results, run on your own framework:
| Year | Milestone | What you reproduce |
|---|---|---|
| 1958 | Perceptron | Binary classification with gradient descent |
| 1969 | XOR Crisis | Multi-layer networks solving non-linear problems |
| 1986 | Backpropagation | Multi-layer network training |
| 1998 | CNN Revolution | Image classification with convolutions |
| 2017 | Transformer Era | Language generation with self-attention |
| 2018+ | MLPerf | Production-grade optimization |
Repository structure
TrenTorch/
├── TrenTorch_CLI/ # The `tren` CLI and the framework curriculum
│ ├── data/
│ │ ├── src/ # Curriculum source (edit here), 01_tensor to 20_capstone
│ │ ├── modules/ # Generated notebooks (student-facing, stubs only)
│ │ ├── solutions/ # Reference implementations (maintainer and CI only)
│ │ ├── datasets/ # Small training datasets
│ │ ├── milestones/ # Historical ML recreations
│ │ └── trentorch/ # Generated package you import from
│ ├── platforms/
│ │ ├── cli/ # The `tren` CLI
│ │ │ ├── core/ # Config, console, theme, runtime
│ │ │ ├── cli_platform/ # Setup, system, package and dev commands
│ │ │ ├── processes/ # Module workflow, milestone, benchmark, olympics, convert
│ │ │ ├── tui/ # Terminal dashboard
│ │ │ ├── server/, companion_ui/ # Local companion web UI
│ │ │ └── tests/
│ │ └── dev_tools/ # Maintainer scripts
│ ├── docs/ # Command reference, design notes, contributing guide
│ ├── user_data/ # Your progress and benchmarks (not committed)
│ └── tests/ # Integration, end-to-end and environment tests
│
├── TrenTorch_Web/ # The browser version (SvelteKit, trentorch.com)
│ ├── platform/ # Routes, components, assets
│ ├── processes/ # Question runner, IDE content, POTD, auth, progress
│ ├── data/ # Curriculum, question content (app_data/), POTD schedule
│ ├── pyodide-check/ # Runs every question in Pyodide as a repo check
│ ├── e2e/ # End-to-end and build-output checks
│ ├── supabase/migrations/ # Auth and user-data schema, with RLS policies
│ └── docs/ # Design specs and plans
│
└── .github/ # CI, bots and shared assets
The CLI workflow: TrenTorch_CLI/data/src/*.py becomes TrenTorch_CLI/data/modules/*.ipynb (you solve it), and your solutions end up in TrenTorch_CLI/data/trentorch/*.py.
Issues and pull requests are welcome. Start with the contributing guide: open an issue first, and ask to be assigned before you start on it. CI has to be green and one review from someone other than the author is required to merge. The first-contribution bot greets you on your first PR. Code quality is tracked on CodeFactor, where the repository is graded A+.
Found a security problem? Do not open a public issue. Read SECURITY.md.
The maintainers. Counts are recomputed whenever a PR merges, from real issue/PR activity via .github/workflows/update-contributors.yml.
Rocky Principal Maintainer IIT Guwahati, Debugs autograd for fun, ships before sunrise. Issues: 18 · PRs: 200 |
maanas1234 Maintainer Catches bugs, builds solutions and ships products Issues: 14 · PRs: 36 |
Aadityansha Maintainer Reducing CPU stalls, one commit at a time. Issues: 1 · PRs: 15 |
Shivtej Gaikwad Maintainer IIT Guwahati. Shows up, ships, moves on to the next thing. Issues: 6 · PRs: 27 |
Everyone else who has had a PR merged, or is credited as a Co-authored-by: on one. Want to show up here? Get a PR merged, or get credited as a co-author on someone else's: the first-contribution bot will say hello on your first PR, and this grid updates automatically after it merges. A closed-without-merging PR doesn't count, and neither does an issue on its own.
Show all 13 contributors
bernalalexis-try Spots bugs, corrects them and contributes Issues: 0 · PRs: 1 |
Copilot Spots bugs, corrects them and contributes Issues: 0 · PRs: 1 |
![dependabot[bot]](https://avatars.githubusercontent.com/dependabot[bot]?v=4)
dependabot[bot] Spots bugs, corrects them and contributes Issues: 0 · PRs: 4 |
JashT14 Spots bugs, corrects them and contributes Issues: 10 · PRs: 3 |
KeuqS Spots bugs, corrects them and contributes Issues: 0 · PRs: 2 |
lux-liang Spots bugs, corrects them and contributes Issues: 0 · PRs: 2 |
MahekPatel-2403 Spots bugs, corrects them and contributes Issues: 0 · PRs: 1 |
mayuriphad Spots bugs, corrects them and contributes Issues: 0 · PRs: 1 |
MayurK-cmd Spots bugs, corrects them and contributes Issues: 0 · PRs: 1 |
pushkarkumarvats Spots bugs, corrects them and contributes Issues: 0 · PRs: 1 |
shivamraut747-ux Spots bugs, corrects them and contributes Issues: 0 · PRs: 2 |
Shreyacodess20 Spots bugs, corrects them and contributes Issues: 1 · PRs: 1 |
VrajVed Spots bugs, corrects them and contributes Issues: 1 · PRs: 2 |
TrenTorch's CLI is our implementation, built on the curriculum and foundation of TinyTorch, created by Prof. Vijay Janapa Reddi and the ML Systems Book community at Harvard University.
Related educational frameworks
PolyForm Noncommercial License 1.0.0: free for personal, educational, and noncommercial use. Not licensed for commercial use.
This project follows the Contributor Covenant. It applies in issues, pull requests, discussions, and on trentorch.com.
Is TrenTorch free?
Yes, for personal, educational, and noncommercial use, under the PolyForm Noncommercial License 1.0.0. Commercial use is not covered. If you want to use it in a paid course or inside a company, get in touch at rocky@trentorch.com or through trentorch.com/contact.
Web or CLI: which should I start with?
Start with the web app if you want to try questions right now with nothing to install. Use the CLI if you want to build the framework yourself, module by module, in notebooks on your own machine. They cover the same ground, and progress is not shared between them.
Do I need a GPU, PyTorch, or TensorFlow?
No. Everything runs on the CPU with NumPy, and the curriculum never imports PyTorch or TensorFlow. The CLI needs Python 3.10 or newer. The web app runs Python 3.12 inside your browser.
Where does my code run on the web app?
In your browser, using Pyodide (Python compiled to WebAssembly). Running and grading a question does not need a server. Your progress (which questions you have solved) is saved to your account, which you create by signing in with GitHub, Google, or an email link.
How is this different from TinyTorch?
The CLI curriculum is our own implementation of TinyTorch from Harvard's CS249r: same foundation, rebuilt and extended in our style. The web app is a separate, independent project built on its own question bank.
How do I add or fix a question?
Open an issue first and ask to be assigned, as described in the contributing guide. Web questions are plain files under TrenTorch_Web/data/app_data/, and the authoring guide explains the layout. CLI modules are edited in TrenTorch_CLI/data/src/.
How do I get listed under Open-Source Contributors?
Get a pull request merged. A workflow updates the grid automatically after each merge. A closed-without-merging PR does not count, and neither does an issue on its own.
I found a bug. Where do I report it?
Open a GitHub issue with steps to reproduce. For a security problem, do not open a public issue: follow SECURITY.md.
Build it yourself. Understand it fully.