WAIT — Mixed signals — read the receipts

• Last commit 7w ago
• 5 active contributors
• Apache-2.0 licensed
• ⚠ Concentrated ownership — top contributor handles 50% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected
• ⚠ Scorecard: default branch unprotected (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

The Hierarchical Reasoning Model (HRM) is a 27M-parameter recurrent neural network architecture that solves complex reasoning tasks (Sudoku, mazes, ARC puzzles) in a single forward pass without Chain-of-Thought prompting. It uses two interdependent recurrent modules—a slow high-level planning module and a fast low-level computation module—to achieve near-perfect performance on reasoning benchmarks with minimal training data (1000 samples) and no pre-training. Monolithic structure: models/hrm/hrm_act_v1.py contains the core architecture, models/layers.py and models/sparse_embedding.py provide building blocks, config/arch/hrm_v1.yaml drives hyperparameters. Dataset builders (dataset/build_arc_dataset.py, build_maze_dataset.py, build_sudoku_dataset.py) load tasks; pretrain.py and evaluate.py are entry points. Visualization via puzzle_visualizer.html and Jupyter notebooks (arc_eval.ipynb).

AI researchers developing efficient reasoning systems, AGI evaluators benchmarking on the Abstraction and Reasoning Corpus (ARC), and engineers optimizing for models that avoid expensive autoregressive decoding and multi-step prompting overhead.

Active research release (arxiv 2506.21734, recent). The codebase is sparse but organized with clear config structure (config/arch/hrm_v1.yaml), evaluation notebooks (arc_eval.ipynb), and multiple dataset builders. No visible test suite or CI/CD pipeline present; this is a research repo, not production-hardened. Verdict: actively developed research code, suitable for reproducibility and experimentation, not for production deployment.

Heavy CUDA and FlashAttention dependency (Hopper/Ampere GPU required, specific CUDA 12.6 mandated) limits portability; no fallback CPU implementation visible. Minimal visible error handling, no test coverage in file list. Single organization (sapientinc) ownership with no obvious multi-maintainer structure. Custom CUDA extensions must build correctly or entire setup fails. Breaking change risk if PyTorch or FlashAttention versions diverge from pinned requirements.

This is a fresh official release accompanying the paper publication. The repo structure suggests active development on three task domains (ARC, Sudoku, mazes), with architecture version control (hrm_v1.yaml), and W&B integration for experiment tracking. No visible issue backlog or PR history in file list, indicating this is a snapshot release.

# Clone repo
git clone https://github.com/sapientinc/HRM.git
cd HRM

# Install CUDA 12.6 and PyTorch
CUDA_URL=https://developer.download.nvidia.com/compute/cuda/12.6.3/local_installers/cuda_12.6.3_560.35.05_linux.run
wget -q --show-progress -O cuda_installer.run $CUDA_URL
sudo sh cuda_installer.run --silent --toolkit --override
export CUDA_HOME=/usr/local/cuda-12.6
PYTORCH_INDEX_URL=https://download.pytorch.org/whl/cu126 pip3 install torch torchvision torchaudio --index-url $PYTORCH_INDEX_URL

# Install FlashAttention (for Ampere GPUs)
pip3 install flash-attn

# Install Python dependencies
pip install -r requirements.txt

Daily commands: Entry points inferred from file list: python pretrain.py (trains model with config/cfg_pretrain.yaml), python evaluate.py (runs inference/benchmarking). Dataset builders run as python dataset/build_arc_dataset.py, etc. Jupyter notebooks (arc_eval.ipynb) provide interactive evaluation. No Makefile or dev server; this is offline batch training/evaluation.

• models/hrm/hrm_act_v1.py — Core HRM architecture implementation with the dual-module recurrent system (high-level planning + low-level computation) that is central to the model's reasoning capability.
• pretrain.py — Main training entry point orchestrating the hierarchical reasoning model training loop with Hydra config management and W&B logging.
• evaluate.py — Evaluation pipeline for assessing HRM performance on reasoning tasks; critical for validating model behavior on Sudoku, maze, and ARC datasets.
• puzzle_dataset.py — Dataset abstraction layer that loads and manages puzzle instances (Sudoku, maze, ARC) and handles the input/output formatting for training.
• config/arch/hrm_v1.yaml — Hydra configuration defining HRM architecture hyperparameters (layer dims, recurrence depth, module sizing) essential for reproducibility.
• models/common.py — Shared model utilities and base classes used across the HRM architecture and supporting layers.
• models/losses.py — Loss function definitions for the reasoning tasks; critical for understanding training objectives and gradient flow.

• HRM (hrm_act_v1.py) — Core reasoning engine with dual recurrent modules (high-level planner for abstract goal states

Add a New Puzzle Task Type

1. Create a new dataset builder in dataset/ (e.g., dataset/build_new_puzzle.py) that converts raw puzzle instances into (input_tensor, target_tensor) pairs. (dataset/build_new_puzzle.py)
2. Update puzzle_dataset.py to register the new task type in the PuzzleDataset class, including loader logic and collate_fn handling. (puzzle_dataset.py)
3. Define task-specific loss in models/losses.py (e.g., new constraint violations or objective metrics). (models/losses.py)
4. Add a new Hydra config under config/ pointing to the new dataset builder and loss function. (config/cfg_new_task.yaml)
5. Run pretrain.py with the new config to train HRM on the task. (pretrain.py)

Extend the HRM Architecture

1. Modify the HRM module in models/hrm/hrm_act_v1.py to add new recurrent modules or cross-module attention pathways. (models/hrm/hrm_act_v1.py)
2. Add any new layer types to models/layers.py if needed. (models/layers.py)
3. Update config/arch/hrm_v1.yaml to expose new hyperparameters (e.g., new module sizes or recurrence depths). (config/arch/hrm_v1.yaml)
4. Test the modified architecture with pretrain.py and evaluate.py to ensure convergence and performance. (pretrain.py)

Add Evaluation on a New Benchmark

1. Create a new dataset loader in dataset/ that formats the benchmark (e.g., dataset/build_benchmark_x.py). (dataset/build_benchmark_x.py)
2. Update puzzle_dataset.py to support loading the benchmark. (puzzle_dataset.py)
3. Extend evaluate.py with a new evaluation function that computes benchmark-specific metrics (e.g., solve rate, execution time). (evaluate.py)
4. Run evaluate.py with a trained checkpoint to generate results. (evaluate.py)

• PyTorch — Core deep learning framework for implementing the recurrent HRM modules and gradient-based training.
• Hydra — Configuration management system for reproducible hyperparameter sweeps and architecture variations without code changes.
• Weights & Biases (W&B) — Experiment tracking, logging, and visualization for monitoring training dynamics and benchmarking results.
• Einops — Tensor reshaping and manipulation library for clean, readable multi-dimensional indexing in the recurrent modules.
• Pydantic + Argdantic — Type-safe configuration and CLI argument parsing for reducing runtime errors and improving code maintainability.

• Single-pass reasoning without explicit intermediate supervision

  • Why: Reduces data labeling burden and matches human reasoning efficiency; enables training on only 1000 samples.
  • Consequence: Requires carefully designed loss functions and may be harder to debug intermediate reasoning steps compared to step-by-step CoT.

• 27M parameter compact model instead of scaling to billions

  • Why: Achieves near-perfect performance on complex tasks with minimal compute; enables deployment on resource-constrained devices.
  • Consequence: May not generalize as well to novel puzzle distributions; requires task-specific design rather than general pretraining.

• Hierarchical dual-module architecture (high-level + low-level)

  • Why: Mirrors human multi-timescale processing; separates abstract planning from concrete execution for interpretability and stability.
  • Consequence: Adds complexity to architecture design and hyperparameter tuning; requires careful module communication mechanisms.

• Does not handle free-form natural language reasoning; tasks are restricted to structured puzzles (Sudoku, mazes, ARC).
• Does not provide step-by-step intermediate explanations; operates as a black-box predictor without explainability outputs.
• Not designed for continual learning or online adaptation; assumes static tasks during inference.
• Does not implement multi-GPU distributed training; single-device training only.

CUDA hard requirement: No CPU fallback; code will crash if CUDA unavailable or GPU memory insufficient. FlashAttention version sensitive: Hopper vs Ampere installs differ (hopper/ vs pip3 install flash-attn); wrong version silently fails or crashes. CUDA_HOME env var: Must be explicitly set post-install or CUDA extensions won't find headers. Submodule: .gitmodules present but content not shown; may require git clone --recursive. WANDB integration mandatory: Code likely expects W&B credentials; no offline mode visible. Config coupling: Changing model architecture without matching config/arch/hrm_v1.yaml will cause mismatches.

• Hierarchical Recurrent Processing — HRM's core innovation: slow high-level planning module and fast low-level computation module operating at different timescales within a single forward pass; understanding this two-timescale abstraction is essential to modifying or extending the architecture
• Sparse Embeddings — HRM uses sparse discrete token representations (see models/sparse_embedding.py) to reduce parameter count while maintaining expressiveness; critical for understanding why 27M params suffice for ARC-level reasoning
• FlashAttention (Algorithm Awareness) — HRM depends on FlashAttention 2/3 for CUDA-accelerated attention; understanding IO-aware attention (block-wise computation, minimal HBM reads) explains the GPU memory and latency claims in the paper
• Abstraction and Reasoning Corpus (ARC) — The primary benchmark used in evaluate.py and arc_eval.ipynb; 1200 tasks requiring abstract reasoning; HRM's performance on ARC is the key AGI capability claim
• Recurrent Neural Networks with Multiple Timescales — HRM extends RNN theory with explicit fast/slow module coupling; relevant to understanding how it avoids vanishing gradients and maintains training stability without Transformers
• Hydra Configuration Framework — config/arch/hrm_v1.yaml and config/cfg_pretrain.yaml use Hydra/OmegaConf for reproducible hyperparameter management; critical for experiment replication and ablation studies
• Single-Pass Reasoning (vs Chain-of-Thought) — HRM executes reasoning without intermediate supervision or autoregressive decoding; contrast to LLM CoT approaches clarifies the architectural innovation and efficiency gains

• openai/gpt-3 — Related LLM baseline that HRM paper compares against for reasoning task performance; represents Chain-of-Thought approach HRM improves upon
• deepmind/abstract-reasoning-matrices — DeepMind's original ARC dataset repository; the reasoning benchmark HRM achieves near-SOTA on
• Dao-AILab/flash-attention — Direct dependency (FlashAttention 2/3); HRM requires this for efficient attention computation on long reasoning sequences
• facebookresearch/evolutionary-scale-modeling — Alternative efficient reasoning approach using evolutionary computation; relevant comparison point for single-pass reasoning without explicit supervision
• anthropic/evals — Anthropic's evaluation suite for reasoning tasks; overlaps with HRM's benchmark scope (ARC, maze solving)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for dataset builders and puzzle_dataset.py

The repo has three dataset builders (build_arc_dataset.py, build_maze_dataset.py, build_sudoku_dataset.py) and a central puzzle_dataset.py but no test suite. Given the critical importance of data pipeline correctness for model training, adding tests would catch data loading bugs early, validate dataset transformations, and ensure reproducibility. This is especially important since the README emphasizes the model's efficiency—corrupted data would invalidate performance claims.

• [ ] Create tests/test_dataset_builders.py to test build_arc_dataset.py, build_maze_dataset.py, and build_sudoku_dataset.py with sample inputs
• [ ] Add tests/test_puzzle_dataset.py to validate puzzle_dataset.py loading, splitting, and batching logic
• [ ] Test dataset/common.py utilities and error handling for malformed data
• [ ] Add test fixtures in tests/fixtures/ with small sample datasets
• [ ] Document test execution in README.md under a 'Development' section

Add inference/evaluation utility module for models/hrm/inference.py

The repo has pretrain.py and evaluate.py at the top level, but the HRM model architecture in models/hrm/hrm_act_v1.py lacks a dedicated inference wrapper. New contributors and users need a clean API to load pretrained checkpoints, run single/batch inference, and get outputs in standard formats. This would bridge the gap between training and the notebook-based evaluation (arc_eval.ipynb) and enable easier model deployment.

• [ ] Create models/hrm/inference.py with classes for checkpoint loading and inference (e.g., HRMInference)
• [ ] Add support for batch inference with optional device management (CPU/GPU)
• [ ] Include methods to parse model config from config/arch/hrm_v1.yaml and instantiate models
• [ ] Add basic error handling for missing checkpoints and shape mismatches
• [ ] Document the inference API with docstring examples in the class

Add integration test with GitHub Actions for training and evaluation pipeline

With dependencies on Hydra, Wandb, Huggingface Hub, and PyTorch, the repo lacks automated CI to catch integration issues. A minimal GitHub Actions workflow would run pretrain.py and evaluate.py on a small subset of data (e.g., a few puzzle samples) to verify the entire pipeline works end-to-end. This prevents silent breakage from dependency updates or configuration changes, which is critical for reproducibility claims in the README.

• [ ] Create .github/workflows/integration-test.yml with Python 3.9+ matrix
• [ ] Install dependencies from requirements.txt and run a minimal pretrain.py job with max 1-2 epochs on subset data
• [ ] Run evaluate.py to verify model loading and evaluation output generation
• [ ] Add a test-only config file (e.g., config/cfg_test.yaml) with reduced dataset sizes and fast convergence settings
• [ ] Ensure workflow passes on push to main and PRs, with optional Wandb/Huggingface Hub mocking to avoid credential leaks

• Add unit tests for models/sparse_embedding.py (no test file visible in repo); write tests for embedding initialization, forward/backward pass with various input shapes to catch GPU memory regressions early
• Create missing documentation for dataset/common.py helper functions; add docstrings with examples showing how to build custom task datasets following ARC/Sudoku/Maze patterns
• Implement CPU inference mode fallback in models/hrm/hrm_act_v1.py using standard PyTorch attention (no FlashAttention) for researchers without Hopper/Ampere GPUs; wrap FlashAttention imports in try/except

The codebase demonstrates a research-focused ML project with moderate security posture. Primary concerns include unversioned dependencies, potential unsafe deserialization in PyTorch workflows, and lack of input validation in dataset builders. No critical vulnerabilities like hardcoded credentials or SQL injection were detected. The project would benefit from dependency pinning, input validation frameworks, and explicit security guidelines in documentation. The security score reflects manageable risks appropriate for research code, with improvement opportunities in dependency management and data handling practices.

• Medium · Unspecified Dependency Versions — requirements.txt. The requirements.txt file does not specify pinned versions for dependencies. This allows for automatic updates to potentially vulnerable versions during installation, which could introduce security issues or breaking changes. Fix: Pin all dependencies to specific versions using '==' operator (e.g., 'torch==2.0.1'). Alternatively, use a lock file (requirements.lock) generated by pip-compile or poetry to ensure reproducible builds.
• Medium · Potential Code Execution via Pickle/Unsafe Deserialization — puzzle_dataset.py, dataset/build_*.py, models/. PyTorch models and datasets in this ML codebase may use pickle for serialization (common in puzzle_dataset.py and models). Unpickling untrusted data can lead to arbitrary code execution. Fix: Use torch.load() with weights_only=True parameter when loading model weights. For data serialization, prefer safer formats like JSON, YAML, or use torch.save/torch.load with restricted unpickling.
• Medium · Missing Input Validation in Dataset Builders — dataset/build_arc_dataset.py, dataset/build_maze_dataset.py, dataset/build_sudoku_dataset.py. Dataset building scripts (build_arc_dataset.py, build_maze_dataset.py, build_sudoku_dataset.py) likely process raw data without visible validation. This could allow malformed or malicious input to cause crashes or unexpected behavior. Fix: Implement input validation and sanitization in all dataset builders. Validate file formats, data types, and ranges. Add error handling for malformed inputs.
• Low · Third-party JavaScript Library in Assets — assets/npyjs.js. The file assets/npyjs.js appears to be a third-party JavaScript library. If not from a trusted source or regularly updated, it could contain vulnerabilities. Fix: Verify the source and version of npyjs.js. Ensure it's from an official repository (GitHub/npm) and update regularly. Consider using npm/yarn for dependency management instead of bundling.
• Low · No .gitignore Protection for Sensitive Files — .gitignore. While .gitignore exists, there's no evidence that sensitive configuration files (*.env, *.key, *.pem) are explicitly excluded. ML projects may accumulate API keys or credentials. Fix: Explicitly add patterns to .gitignore for sensitive files: *.env, .key, .pem, credentials., secrets., .aws/, etc. Use a template like github/gitignore/Python.gitignore as a baseline.
• Low · Potential Code Injection via hydra-core Configuration — config/, pretrain.py, evaluate.py. Hydra-core allows dynamic configuration composition via YAML. If configs are loaded from untrusted sources, this could enable code execution through interpolation features. Fix: Validate all configuration files before loading. Use Hydra's restricted mode if available. Sanitize any user-provided configuration values. Document trusted configuration sources only.
• Low · Unencrypted Model Upload to Hugging Face — models/, huggingface_hub dependency. The dependency on huggingface_hub suggests model uploads/downloads. If models contain sensitive information or are downloaded over insecure channels, this poses a risk. Fix: Always use HTTPS for huggingface_hub interactions (default). Validate model checksums/signatures when downloading. Use authentication tokens securely (environment variables, not hardcoded).

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/sapientinc/HRM shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live sapientinc/HRM repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sapientinc/HRM.

What it runs against: a local clone of sapientinc/HRM — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in sapientinc/HRM | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 78 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sapientinc/HRM. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sapientinc/HRM.git
#   cd HRM
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of sapientinc/HRM and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "sapientinc/HRM(\\.git)?\\b" \\
  && ok "origin remote is sapientinc/HRM" \\
  || miss "origin remote is not sapientinc/HRM (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "models/hrm/hrm_act_v1.py" \\
  && ok "models/hrm/hrm_act_v1.py" \\
  || miss "missing critical file: models/hrm/hrm_act_v1.py"
test -f "pretrain.py" \\
  && ok "pretrain.py" \\
  || miss "missing critical file: pretrain.py"
test -f "evaluate.py" \\
  && ok "evaluate.py" \\
  || miss "missing critical file: evaluate.py"
test -f "puzzle_dataset.py" \\
  && ok "puzzle_dataset.py" \\
  || miss "missing critical file: puzzle_dataset.py"
test -f "config/arch/hrm_v1.yaml" \\
  && ok "config/arch/hrm_v1.yaml" \\
  || miss "missing critical file: config/arch/hrm_v1.yaml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 78 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~48d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/sapientinc/HRM"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.