# sapientinc/hrm architecture

> Architecture diagram of the GitHub repository sapientinc/hrm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sapientinc/hrm
- Repository: https://github.com/sapientinc/hrm

## Overview

##### Project type and purpose
- This is a machine-learning research codebase for the “Hierarchical Reasoning Model” (HRM), not a web or enterprise full-stack app.
- It provides:
- Dataset builders for puzzles (ARC, Sudoku, Maze)
- Model definitions and losses
- Training orchestration (pretrain.py)
- Evaluation scripts (evaluate.py + arc_eval.ipynb)
- Visualization tool (puzzle_visualizer.html)
- Configuration management for different architectures and pre-training settings

##### File structure
- Top-level directories and responsibilities:
- config/         ← YAML specs for model architectures and training
- dataset/        ← raw data + builders for ARC, Sudoku, Maze
- models/         ← HRM modules (high-level planner, low-level module), layers, losses, embeddings
- utils/          ← shared functions
- assets/         ← static JS for dataset visualization
- Key scripts:
- pretrain.py     ← main training driver using PyTorch + CUDA extensions
- evaluate.py     ← checkpoint evaluation on held-out puzzles
- arc_eval.ipynb  ← notebook for final ARC metrics
- Support files:
- puzzle_visualizer.html ← interactive dataset browser
- requirements.txt, .gitmodules, .gitignore

##### Extract architectural insights from the README
- Two interdependent recurrent modules (high-level abstract planner, low-level detail processor)
- Single forward pass hierarchical design (27M parameters)
- Integration with PyTorch, CUDA, FlashAttention, Weights & Biases (W&B)

a. Main components
- Data Layer
– Raw puzzle repositories (ARC-AGI, ARC-AGI-2, ConceptARC)
– Dataset builders (build_arc_dataset.py, build_sudoku_dataset.py, build_maze_dataset.py)
– Processed datasets on disk
- Model Layer
– HRM high-level module (models/hrm/hrm_act_v1.py)
– HRM low-level module and shared components (models/common.py, layers, sparse_embedding)
– Loss functions (models/losses.py)
- Training Orchestrator
– pretrain.py
– Hyperparameter/config loader (config/*.yaml)
– CUDA extensions (FlashAttention)
- Evaluation & Visualization
– evaluate.py
– arc_eval.ipynb
– puzzle_visualizer.html
- External Services & Infrastructure
– Weights & Biases for logging
– GPU compute cluster (CUDA toolkit)
– Python environment (requirements.txt)

b. Relationships & data flow
1. Raw data → Dataset builders → Processed dataset
2. Processed dataset → DataLoader → Training script
3. Training script + config → HRM model → GPU → Checkpoint outputs
4. Metrics → W&B API
5. Checkpoints + dataset → evaluate.py → metrics, which arc_eval.ipynb consumes
6. Processed dataset → puzzle_visualizer.html (static asset)

c. Architectural patterns & design principles
- Modular separation: dataset, model, utils, config
- Config-driven orchestration (YAML + CLI overrides)
- Single-pass hierarchical recurrence (high- vs. low-level modules)

d. Key technologies/frameworks
- PyTorch with CUDA extensions (FlashAttention)
- Hydra-style config management in config/
- Weights & Biases integration
- Jupyter notebook for post-processing (arc_eval.ipynb)
- Static HTML/JS for dataset exploration (puzzle_visualizer.html)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Raw1["ARC-AGI (Raw Repo)"]:::data
        Raw2["ARC-AGI-2 (Raw Repo)"]:::data
        Raw3["ConceptARC (Raw Repo)"]:::data
        subgraph "Dataset Builders"
            direction TB
            ArcBuilder["build_arc_dataset.py"]:::code
            SudokuBuilder["build_sudoku_dataset.py"]:::code
            MazeBuilder["build_maze_dataset.py"]:::code
            CommonDS["common.py"]:::code
        end
        ProcessedDS["puzzle_dataset.py (Processed Dataset)"]:::data
    end

    %% Configuration
    Config["Config Manager\n(arch/hrm_v1.yaml,\ncfg_pretrain.yaml)"]:::code

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        subgraph "HRM Modules"
            direction TB
            HLPlanner["hrm_act_v1.py\n(High-Level Planner)"]:::code
            LLCommon["models/common.py"]:::code
            Layers["layers.py"]:::code
            Embedding["sparse_embedding.py"]:::code
            Losses["losses.py"]:::code
        end
    end

    %% Training Orchestrator
    Trainer["pretrain.py\n(Training Orchestrator)"]:::code

    %% Evaluation & Visualization
    subgraph "Evaluation"
        direction TB
        EvalScript["evaluate.py"]:::code
        EvalNotebook["arc_eval.ipynb"]:::code
    end
    subgraph "Visualization"
        direction TB
        VisualHTML["puzzle_visualizer.html"]:::code
        VisualJS["npyjs.js"]:::code
    end

    %% External Services & Infrastructure
    subgraph "External Services"
        direction TB
        WnB["Weights & Biases"]:::ext
        GPU["GPU Cluster\n& CUDA Toolkit"]:::ext
        PythonEnv["Python Env\n(requirements.txt)"]:::ext
        GitMod[".gitmodules"]:::ext
    end

    %% Connections
    Raw1 -->|raw puzzles| ArcBuilder
    Raw2 -->|raw puzzles| ArcBuilder
    Raw3 -->|raw puzzles| ArcBuilder
    ArcBuilder -->|processed data| ProcessedDS
    SudokuBuilder -->|processed data| ProcessedDS
    MazeBuilder -->|processed data| ProcessedDS
    CommonDS -->|helpers| ArcBuilder
    CommonDS -->|helpers| SudokuBuilder
    CommonDS -->|helpers| MazeBuilder

    ProcessedDS -->|data loader| Trainer
    Config -->|configs| ArcBuilder
    Config -->|configs| Trainer

    Trainer -->|model init| HLPlanner
    Trainer -->|model init| LLCommon
    Trainer -->|model init| Layers
    Trainer -->|model init| Embedding
    Trainer -->|model init| Losses
    Trainer -->|runs| GPU
    Trainer -->|logs metrics| WnB
    Trainer -->|outputs checkpoints| ProcessedDS

    ProcessedDS -->|data| EvalScript
    EvalScript -->|metrics| EvalNotebook

    ProcessedDS -->|input| VisualHTML
    VisualJS -->|support| VisualHTML

    %% Click Events
    click ArcBuilder "https://github.com/sapientinc/hrm/blob/main/dataset/build_arc_dataset.py"
    click SudokuBuilder "https://github.com/sapientinc/hrm/blob/main/dataset/build_sudoku_dataset.py"
    click MazeBuilder "https://github.com/sapientinc/hrm/blob/main/dataset/build_maze_dataset.py"
    click Raw1 "https://github.com/sapientinc/hrm/tree/main/dataset/raw-data/ARC-AGI"
    click Raw2 "https://github.com/sapientinc/hrm/tree/main/dataset/raw-data/ARC-AGI-2"
    click Raw3 "https://github.com/sapientinc/hrm/tree/main/dataset/raw-data/ConceptARC"
    click CommonDS "https://github.com/sapientinc/hrm/blob/main/dataset/common.py"
    click ProcessedDS "https://github.com/sapientinc/hrm/blob/main/puzzle_dataset.py"
    click HLPlanner "https://github.com/sapientinc/hrm/blob/main/models/hrm/hrm_act_v1.py"
    click LLCommon "https://github.com/sapientinc/hrm/blob/main/models/common.py"
    click Layers "https://github.com/sapientinc/hrm/blob/main/models/layers.py"
    click Embedding "https://github.com/sapientinc/hrm/blob/main/models/sparse_embedding.py"
    click Losses "https://github.com/sapientinc/hrm/blob/main/models/losses.py"
    click Trainer "https://github.com/sapientinc/hrm/blob/main/pretrain.py"
    click Config "https://github.com/sapientinc/hrm/blob/main/config/arch/hrm_v1.yaml"
    click Config "https://github.com/sapientinc/hrm/blob/main/config/cfg_pretrain.yaml"
    click EvalScript "https://github.com/sapientinc/hrm/blob/main/evaluate.py"
    click EvalNotebook "https://github.com/sapientinc/hrm/blob/main/arc_eval.ipynb"
    click VisualHTML "https://github.com/sapientinc/hrm/blob/main/puzzle_visualizer.html"
    click VisualJS "https://github.com/sapientinc/hrm/blob/main/assets/npyjs.js"
    click PythonEnv "https://github.com/sapientinc/hrm/blob/main/requirements.txt"
    click GitMod "https://github.com/sapientinc/hrm/blob/main/.gitmodules"

    %% Styles
    classDef data fill:#a0c4ff,stroke:#0366d6,color:#000;
    classDef code fill:#c8e6c9,stroke:#2e7d32,color:#000;
    classDef ext fill:#ffe082,stroke:#ef6c00,color:#000;
```
