Contributing Guide

We welcome contributions to the Hierarchical Reasoning Model project. This guide provides information on setting up a development environment and the general workflow for development.

Development Environment Setup

  1. Follow the Installation Guide: Ensure you have completed all steps in the Installation Guide, including setting up CUDA, PyTorch, and all Python dependencies.

  2. VS Code Configuration: If you use Visual Studio Code, the repository includes helpful configuration in the .vscode/ directory:

    • settings.json: Enables standard type checking with Pylance.
    • launch.json: Provides debugger configurations. The "Debug: Single GPU" configuration is particularly useful. It launches pretrain.py with DISABLE_COMPILE=true, which disables torch.compile to allow for step-through debugging of the model code.

Development Workflow

A typical development cycle might involve the following steps:

  1. Modify the Code: Make changes to the model architecture, data pipeline, or training loop.

  2. Build a Dataset: If you've changed the data processing logic, you'll need to rebuild the relevant dataset. For example: 

    python dataset/build_arc_dataset.py --output-dir data/my-test-dataset

  3. Run a Test Training: Launch a training run on a small dataset (like the quick start Sudoku example) to verify your changes. Use the single-GPU debug configuration or run from the command line: 

    # Disable torch.compile for easier debugging
export DISABLE_COMPILE=true

# Run with a small batch size
python pretrain.py data_path=data/my-test-dataset global_batch_size=8

  4. Run Tests (if applicable): While the project doesn't currently have a formal test suite, the evaluation scripts serve as a key validation tool. Ensure your changes don't cause regressions by running evaluate.py on a standard checkpoint.

  5. Submit a Pull Request: Once your changes are complete and tested, please open a pull request against the main branch. Provide a clear description of the changes and the motivation behind them.

Code Style

Please adhere to standard Python coding conventions (PEP 8). The code uses type hints extensively, and new contributions should also be fully type-hinted.

Reporting Issues

If you encounter a bug or have a feature request, please open an issue on the GitHub repository. Provide as much detail as possible, including:

  • Your operating system and environment details.
  • The exact command you ran.
  • The full error message and stack trace.
  • Steps to reproduce the issue.