# no-magic: forty-eight AI algorithms as single-file Python scripts with nothing to install

> A teaching repository that re-implements GPT, LSTM, ResNet, LoRA, DPO, PPO and Monte Carlo tree search as complete runnable programs, organised into four numbered tiers, with the version badge lagging behind the release history.

**no-magic-ai/no-magic** — Because `model.fit()` isn't an explanation

- Repository: https://github.com/no-magic-ai/no-magic
- Website: https://no-magic-ai.github.io/
- Stars: 1,419 · Forks: 106
- Language: Python
- License: MIT
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/no-magic-ai-no-magic

## One file, one algorithm, no import list

The repository's pitch is one line long, and it is the repository's name: because `model.fit()` isn't an explanation. The What This Is section expands it. Each script is a complete, runnable program that trains a model from scratch and performs inference, with no frameworks, no abstractions and no hidden complexity. The stated goal is explicitly not to replace PyTorch or TensorFlow, but to make a reader understand what those libraries do underneath.

The zero-dependency claim is the constraint that shapes everything else, and it is enforced by the topic list on the repository, which includes a `no-dependencies` tag. Python 3.10 or newer is the floor. That rules out NumPy-style vectorisation in a lot of places, which is arguably the point: a script that builds its own tensors in plain lists makes the shape arithmetic visible rather than hiding it behind a broadcast.

Each algorithm lives in its own file with a `micro` prefix, and the directory layout is four numbered tiers rather than one flat folder. `01-foundations/` holds fourteen scripts according to the README's own section header, `02-alignment/` holds ten, and `03-systems/` and `04-agents/` complete the set. There is no `src/`, no package manifest and no test suite at the root, which is consistent with a repository whose unit of delivery is a script you run once and read.

Running one needs nothing but an interpreter and a checkout:

```bash
git clone https://github.com/no-magic-ai/no-magic
python 01-foundations/microgpt.py
```

No `pip install` step appears anywhere in the project documentation, because there is nothing to install. That is the whole appeal and the whole constraint: these scripts cannot use the libraries that would do most of the work for them.

## What sits in each of the four tiers

The tier names are a learning sequence rather than a taxonomy, and the script filenames tell you what each one is for.

`01-foundations/` contains the architectures you meet first. There is `microgpt.py` for autoregressive token-by-token generation, `micrornn.py` for a vanilla RNN against GRU with a subtitle about vanishing gradients and gating, `microlstm.py` for the four-gate memory highway, `microtokenizer.py` for byte-pair encoding described as iterative pair merging into a vocabulary, `microembedding.py` for contrastive learning producing semantic clusters, and `microrag.py` for retrieve, augment, generate. Vision and audio-adjacent pieces are there too: `microvit.py` treats image patches as tokens, `microconv.py` slides kernels into feature maps, `microresnet.py` adds the skip connection as `F(x) + x`, `microvae.py` encodes, samples z and decodes, and `microdiffusion.py` denoises iteratively from noise to data.

`02-alignment/` is the training tier, and its filenames are the standard vocabulary of preference optimisation: `microlora.py` for low-rank weight injection, `microqlora.py` for a four-bit base with full-precision adapters, `microdpo.py` for turning preferred against rejected pairs into a policy update, `microppo.py` for clipped policy gradient, `microgrpo.py` for group-relative rewards with no critic, and `microreinforce.py`. Two entries in this tier, batch normalisation and dropout, are not alignment methods at all, which suggests the tier is really about training mechanics rather than RLHF.

`03-systems/` covers inference and retrieval infrastructure: the v2.0.0 notes name `microvectorsearch.py` with brute-force and LSH approximate search, `microbm25.py` tracing TF to TF-IDF to BM25, and `microspeculative.py` for speculative decoding with a draft-verify loop. `04-agents/` arrived in v2.0.0 as a new tier with `micromcts.py`, Monte Carlo tree search with UCB1 exploration, and `microreact.py`, a ReAct loop with a REINFORCE-trained policy.

The comparison scripts are the ones worth singling out. `attention_vs_none.py` and `rnn_vs_gru_vs_lstm.py` exist to put a mechanism next to its absence, which teaches something a single implementation cannot.

## The challenge folder asks you to predict the output

There is a `challenges/` directory at the root, and the v2.0.0 release describes what is inside: five predict-the-behaviour exercises covering attention, GPT, GAN, DPO and the optimizer. The exercise is to write down what the script will do before running it.

That is a better fit for this material than a tutorial would be. A single-file implementation of DPO is easy to skim and hard to absorb, because the code tells you what happens but not what should surprise you. Paired with `LEARNING_PATH.md` at the root, the challenges give the repository a pedagogical spine that the script collection alone does not have.

Two other learning aids came with v2.0.0: 147 Anki flashcards spread across foundations, alignment and the remaining tiers, and a set of MP4 visualisations. The videos are attached as release assets on v1.0, one per algorithm, generated with Manim, and GIF previews are embedded in each tier's README. The images load from a separate `no-magic-viz` repository, which is worth knowing if you are working offline, since the README's visual grid will render as empty space without network access.

The `resources/`, `docs/` and `scripts/` directories sit alongside those. `docs/catalog.json` is the machine-readable index that the v3.0.0 release added a `paper_slug` field to, and `TRANSLATIONS.md` with a `translations/` directory confirms the project is translated, which is consistent with the repository's language as a teaching tool rather than a research artefact.

## The version badge and the release history disagree

The badges at the top of the README read algorithms 48 and version v2.0.0. The release history says something different, and the two facts sit side by side.

There are three releases. v1.0 on 2026-02-24 shipped 30 single-file implementations with video explainers attached. v2.0.0 on 2026-03-11 expanded the collection from 16 to 41 implementations across four tiers, which is where the new `04-agents/` tier, the five challenges and the 147 flashcards appeared. v3.0.0 on 2026-04-26 is the paper-card backfill release, and it is the one that puts the count at 48 catalog scripts.

So the algorithm count on the badge is right and the version on the badge is not. Both statements are in the repository at once, and there is no way to read the README alone and tell which is current. The practical rule is to trust `docs/catalog.json` over the badge, since v3.0.0 explicitly made that file the index that carries a `paper_slug` per entry.

There is a second mismatch, smaller and more interesting. v3.0.0 reports 47 paper cards covering all 48 catalog scripts, because five cards bundle multiple comparison-style scripts behind one paper. The `mamba-2` card covers `microssm`, `microcomplexssm` and `microdiscretize`, the `adam` card covers `microoptimizer` and `adam_vs_sgd`, and the `transformer` card covers `attention_vs_none` and `microattention`. Three of the five originals are described as forward-looking for scripts not yet implemented: `nsa`, `titans-2501` and `deepseek-r1`. A card existing for a script that does not exist yet is the kind of thing worth knowing before you go looking for the file.

Also worth a glance: one of the repository topics is spelled `open-soruce` rather than `open-source`. It is a typo in a tag rather than anything substantive.

## What these scripts are not for

The clearest limitation is the one the project states itself. The goal is not to replace PyTorch or TensorFlow, and the scripts are not written to be fast, general or reusable. Every one of them is a teaching implementation at a scale chosen to be readable, which means training a GPT in `microgpt.py` produces a model that would be laughed at in any production context.

There is a subtler limitation worth naming. Because the promise is zero dependencies and single files, nothing here is importable. You cannot `pip install` a component from this repository, you cannot depend on `microlora.py` from your own code, and there is no test suite to catch a script that breaks on a future Python release. The deliverable is a file you read and run, and it stops there. That is a legitimate choice for a teaching repository and a poor foundation for anything else.

A fair comparison is with the many other from-scratch implementations that exist online. The difference here is not that the algorithms are implemented from scratch, which is common, but the combination of zero dependencies, a fixed four-tier curriculum, prediction exercises, flashcards and rendered video. Against a framework, the trade is real: you lose autograd, you lose GPU kernels, you lose every optimisation that makes large models practical. Against a pure textbook, you gain something that actually runs.

Licensing is uncomplicated: MIT, with a `LICENSE` file at the root and a matching badge. The last push was on 2026-04-26, the same day as v3.0.0, so the repository is current with its own release line rather than trailing behind it.

## Conclusion

no-magic is for the moment you open a PyTorch file and want to know what the framework is doing on your behalf, and it does that job better than a blog post because each script runs end to end with no import list to satisfy. What you get is 48 programs across four tiers, five predict-the-behaviour challenges, 147 Anki flashcards, and Manim-rendered video explainers attached to the releases. What you do not get is library code: nothing here is importable as a component, every script trains a model from scratch at teaching scale, and the README says outright that the goal is not to replace PyTorch or TensorFlow. One housekeeping warning: the README badge still reads v2.0.0 and 48 algorithms while the release history runs to v3.0.0, so trust `docs/catalog.json` over the badge. Clone it, then run `python 01-foundations/microgpt.py` and change one thing.

## FAQ

### Do the no-magic scripts need any Python packages installed?

No. The repository carries a zero-dependency claim and the `no-dependencies` topic, and the documentation shows no pip install step. Each script is a complete program that runs on Python 3.10 or newer using the standard library, which is what lets you read a file top to bottom without first working out what it imports.

### How many algorithms are in no-magic and what are the tiers?

The v3.0.0 release counts 48 catalog scripts across four numbered directories: `01-foundations/` for architectures such as microgpt, microlstm and microvit, `02-alignment/` for LoRA, DPO, PPO and REINFORCE, `03-systems/` for vector search, BM25 and speculative decoding, and `04-agents/` for Monte Carlo tree search and a ReAct loop. The README badge reports the same 48 but still labels the version v2.0.0.

### Can I use no-magic code in a real project?

The licence is MIT, so reuse is unrestricted. The practical caveat is that these are teaching implementations, not library code: each file trains a model from scratch at a small scale, nothing is packaged for import, and the repository states outright that the goal is not to replace PyTorch or TensorFlow. Read them, then write your own against a real framework.

## Sources

- [License: MIT](https://github.com/no-magic-ai/no-magic/blob/main/LICENSE)
- [no-magic-ai/no-magic on GitHub](https://github.com/no-magic-ai/no-magic)
- [Project website](https://no-magic-ai.github.io/)
- [README](https://github.com/no-magic-ai/no-magic/blob/main/README.md)
- [Releases](https://github.com/no-magic-ai/no-magic/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/no-magic-ai-no-magic