The Problem

Training a language model from scratch is usually framed as requiring deep expertise, large GPU clusters, and days of compute. GuppyLM demonstrates that a working transformer can be built, trained, and deployed in about five minutes on a single GPU. For engineers evaluating whether to invest in custom small models, it provides a concrete, minimal reference implementation of the full pipeline: data generation, tokenizer training, model definition, training loop, and inference.

What This Does

GuppyLM is an 8.7M-parameter transformer that generates short, lowercase sentences in the persona of a fish. It is trained on 60K synthetic conversations across 60 topics. The model is deliberately vanilla — no GQA, RoPE, or SwiGLU — to keep every component understandable.

The repository is organized into three areas: the guppylm/ package (model, training, inference, data prep), tools/ (export scripts for ONNX, datasets, and Colab notebooks), and docs/ (a browser demo with a pre-exported model.onnx and tokenizer.json). Two Jupyter notebooks (train_guppylm.ipynb, use_guppylm.ipynb) are the intended entry points for most users.

How It Is Wired

Execution starts in the notebooks, which call functions from the guppylm/ package. The training flow is: guppylm/generate_data.py creates synthetic conversations, guppylm/prepare_data.py builds the tokenizer and dataset, and guppylm/train.py runs the loop. Inference is in guppylm/inference.py, with guppylm/__main__.py as a CLI wrapper.

The central hub is guppylm/model.py, which defines the transformer architecture used by both training and inference. It carries the widest blast radius because any architectural change affects training, export, and the browser demo. The tools/export_onnx.py script converts the trained model to ONNX format, which is what the browser demo in docs/index.html actually loads.

The wiring has not been fully mapped for this repository. The internal call graph and detailed data flow between modules are not documented in the codebase, so a new contributor will need to trace the notebook cells to understand the exact sequence.

How To Use It

Setup: Install dependencies from requirements.txt via pip. The Makefile defines common targets, though the specific targets are not documented in the README.

Configuration: A .env.example file exists, but the README does not document which environment variables are required. The Colab notebooks likely handle configuration inline.

Running it: The primary path is the Colab notebooks. To train locally:

pip install -r requirements.txt
python -m guppylm

The __main__.py entry point wires the CLI, but its exact arguments are not documented in the README. The notebooks train_guppylm.ipynb and use_guppylm.ipynb are the safest starting points.

Real-World Use

This fits in educational settings or as a starting scaffold for a custom small model. A team evaluating whether a domain-specific mini-model is viable could use GuppyLM's pipeline to generate synthetic data, train in minutes, and export to ONNX for edge deployment. The browser demo (docs/index.html) shows the end-to-end path from training to in-browser inference, which is useful for prototyping client-side AI features.

Code Health & Issues

Deep static analysis has not run for this repository, so the following are structural observations:

  • Med - No test files detected. The training and inference code paths have no automated verification.
  • Med - No CI/CD pipeline configured. No .github/ directory exists to gate changes.
  • Med - No LICENSE file in this fork, despite the upstream repo being MIT-licensed. Unclear redistribution rights.
  • Low - requirements.txt has no lockfile. Builds are not reproducible.

The Bottom Line

GuppyLM is a well-scoped educational artifact that proves small-model training is accessible. It is not production software — no tests, no CI, no license in this fork. Use it as a learning reference or a scaffold for a custom mini-model, not as a dependency.