How maincodehq/mainrun works
Project Type and Purpose
• This is a single-repository, standardized ML training pipeline focused on training and optimizing a small GPT-2 style language model on a Hacker News headline dataset.
• It’s neither a web app nor microservices architecture; it’s a data-centric, experiment-driven Python codebase with a thin CLI layer for orchestration.
Core Components
a. Data Ingestion & Preparation
• mainrun/download_dataset.py
– Downloads or loads the raw dataset.
• mainrun/utils.py
– Contains tokenization, dataset splitting (train/validation), and any auxiliary preprocessing functions.
b. Model Definition & Training Loop
• mainrun/train.py
– Defines the transformer model architecture.
– Sets up the optimizer (e.g., Adam/Warmup), scheduler, loss function, random seed.
– Implements the training loop for 7 epochs, calls evaluate() each epoch.
c. Evaluation & Logging
• mainrun/train.py → evaluate() (immutable per spec)
• mainrun/logs/baseline.log and other epoch logs
– Records training/validation loss per epoch.
d. Orchestration & CLI
• Taskfile.yml
– Defines “task train” and “task submit” commands.
• scripts/checkpoint.mjs
– Creates periodic model checkpoints before full training.
• scripts/submit.mjs
– Packages up the repo and logs into a submission archive and triggers upload.
e. Reporting
• The user-added report.pdf (placed in mainrun/ before “task submit”) documents changes and results.
Relationships & Workflow
[Dataset Source]
↓
[download_dataset.py]
↓
[Preprocessing / Tokenization (utils.py)]
↓
[DataLoader] → [Training Loop (train.py)] ← [Model Definition]
↓
[evaluate()] → [Validation Loss]
↓
[Logging → Logs Directory]
↘
[Checkpoint.mjs] (pre-training)
↓
[submit.mjs] (pack & upload)
Architectural Patterns & Principles
• Pipeline pattern: clear separation of data ingestion, preprocessing, training, and evaluation stages.
• Single-entry orchestration: All functionality is exposed via “task train” and “task submit” for reproducibility.
• Immutable evaluation: evaluate() is encapsulated and should not be modified (per rules).
• Modularity: utils.py for shared helpers, scripts folder for CLI tooling, mainrun for core logic.
Technologies & Frameworks
• Python 3.10 (main runtime)
• PyTorch 2.x (model & training)
• Taskfile (Make-like CLI orchestration)
• Node.js (for the .mjs checkpoint & submit scripts)
• Optional: VS Code Dev Container (irrelevant to code logic per instructions)