hrm
Use the HRM repository for puzzle dataset preparation, HRM ACT model configuration, CUDA training/evaluation, and ARC checkpoint post-processing.
SKILL.mdskills/repositories/repo-skills/hrm/SKILL.md
GitHubHRM Repo Skill
Use this skill for the sapientinc/HRM repository, publicly called
Hierarchical Reasoning Model (HRM). HRM trains a recurrent, hierarchical
reasoning model on ARC, Sudoku, and Maze puzzle datasets using CUDA, PyTorch,
FlashAttention, Hydra config, W&B logging, and checkpoint evaluation scripts.
When to use
- The user names HRM, Hierarchical Reasoning Model, ARC-AGI, ConceptARC,
Sudoku Extreme, Maze 30x30,
pretrain.py,evaluate.py,arc_eval.ipynb, orpuzzle_visualizer.html. - The task involves HRM's converted dataset layout with
dataset.json,identifiers.json, and<subset>__*.npyarrays. - The task asks about
hrm.hrm_act_v1@HierarchicalReasoningModel_ACTV1,losses@ACTLossHead, StableMax loss, ACT halting, sparse puzzle embeddings, FlashAttention, oradam_atan2. - The user wants to launch or debug HRM CUDA training/evaluation, checkpoints, W&B metrics, or ARC prediction aggregation.
Sub-skill routing
| Need | Read |
|---|---|
| Build, validate, inspect, or visualize ARC/Sudoku/Maze converted datasets | data-preparation |
| Understand HRM ACT v1 model internals, dynamic identifiers, config fields, losses, or model dependency imports | model-architecture |
Launch pretrain.py, distributed torchrun, evaluate.py, checkpoint workflows, W&B/offline mode, or ARC post-processing |
training-evaluation |
Setup snapshot
The repository is a source tree rather than a packaged Python distribution.
Install dependencies in an isolated environment and run from an HRM checkout or
with the checkout on PYTHONPATH.
# PyTorch CUDA first; choose the wheel/index matching the host driver and GPU.
pip install torch torchvision torchaudio --index-url <pytorch-cuda-index>
# FlashAttention: FA2 for Ampere/A100 or earlier, FA3 for Hopper when needed.
pip install flash-attn
# Remaining repository requirements.
pip install -r requirements.txt
For hosted experiment tracking, run wandb login. For safe smoke/debug runs,
use WANDB_MODE=offline. Use DISABLE_COMPILE=true to bypass torch.compile
while diagnosing shape, dependency, or checkpoint issues.
Minimal safe checks
python dataset/build_arc_dataset.py --help
python dataset/build_sudoku_dataset.py --help
python dataset/build_maze_dataset.py --help
WANDB_MODE=offline DISABLE_COMPILE=true python pretrain.py --help
After installing CUDA dependencies, run the bundled readiness helper from this skill:
python sub-skills/training-evaluation/scripts/check_training_env.py \
--repo-root /path/to/HRM --require-cuda
Read references/troubleshooting.md when an install, dataset, model import, W&B, or checkpoint failure spans multiple sub-skills.
Provenance and freshness
Read references/repo-provenance.md before
refreshing this skill or applying it to a different HRM checkout. The skill was
built from HRM commit ac15626f8db096a63c775b84c9dc868776a6feda and records
source evidence paths plus verified dependency facts.
Structured router metadata for managed DisCo import is in references/repo-routing-metadata.json.
Important boundaries
- Do not ask future agents to open or run original repo docs/notebooks as runtime documentation. This skill bundles distilled references plus safe helper scripts.
- Full dataset downloads, submodule clones, multi-GPU training, checkpoint evaluation, W&B online logging, and browser visualization can be network-, storage-, GPU-, or manual-workflow-heavy; request explicit approval before running them as verification.
- CPU dataset validation is useful, but HRM model training/evaluation is a required CUDA workflow. Do not claim CUDA backend verification from CPU-only imports.
- A bounded current-environment model-forward smoke found a possible
FlashAttention output
.view(...)stride issue inmodels/layers.py; treat full forward/training verification as dependency-sensitive until a bounded forward run passes in the target environment.