A complete production-ready ecosystem for Hierarchical Reasoning Models with 110M+ parameters, multi-platform support, and enterprise-grade deployment capabilities.

Edu-HRM has evolved from a research tool into a comprehensive ML ecosystem featuring:

• 3 Specialized Models (110M+ total parameters)
• Multi-Platform Architecture (Python + C++ + SafeTensors)
• Production-Ready Deployment (Docker/Kubernetes)
• Comprehensive API Integration (OpenAI-compatible)
• Enterprise-Grade Security (SafeTensors, memory-safe)

📁 EDU-HRM ECOSYSTEM
├── 🐍 Python Research Environment
│   ├── Enhanced PyTorch 2.8.0 (MPS/CUDA support)
│   ├── Multi-dataset training pipelines
│   ├── Advanced model architectures (RoPE, SwiGLU, RMSNorm)
│   └── W&B integration for experiment tracking
├── ⚡ C++ Production Engine
│   ├── Native HRM implementation
│   ├── Memory-optimized tensor operations
│   ├── Multi-model loading system
│   └── SafeTensors integration
├── 🔄 Weight Conversion Pipeline
│   ├── PyTorch → Binary conversion
│   ├── PyTorch → SafeTensors conversion
│   ├── Model registry management
│   └── Cross-platform validation
└── 🌐 Production API Templates
    ├── OpenAI-compatible chat completions
    ├── Batch processing systems
    ├── Docker/Kubernetes deployment
    └── Monitoring and observability

# Python Environment
python >= 3.9
torch >= 2.8.0
safetensors
wandb

# C++ Environment
g++ with C++17 support
cmake (optional)

git clone https://github.com/ascii-edu/Edu-HRM.git
cd Edu-HRM
pip install -r requirements.txt

from models.layers import HierarchicalReasoningModel
import torch

# Load model
model = HierarchicalReasoningModel(config)
model.load_state_dict(torch.load('checkpoints/sudoku-extreme/checkpoint'))

# Run inference
output = model(input_tensor)

cd hrm_cpp_distribution
make
./complete_hrm_system

# Convert model to SafeTensors
python convert_to_safetensors.py --model sudoku_expert

# Load in C++
./test_safetensors_simple hrm_sudoku_extreme.safetensors

The system includes comprehensive datasets for training and evaluation:

• Sudoku Extreme (1K+ puzzles with augmentation)
• Complex Mazes (30x30 pathfinding challenges)
• ARC Reasoning (1.9M+ puzzle variations from ARC-AGI-2)
• Custom Dataset Builders (extensible framework)

• Solves extreme difficulty Sudoku puzzles
• Constraint satisfaction reasoning
• Step-by-step logical deduction
• 95%+ accuracy on validation sets

• Advanced text generation
• Creative writing capabilities
• Context-aware completions
• Coherent long-form content

• General-purpose reasoning
• Question answering
• Text analysis and summarization
• Multi-domain knowledge

• Inference Speed: 50%+ faster (C++ vs PyTorch)
• Memory Usage: Optimized tensor operations
• Loading Time: Reduced by binary format
• Security: Memory-safe SafeTensors loading
• Cross-Platform: macOS, Linux, Windows ready

• OpenAI-compatible endpoints
• Streaming support
• Batch processing
• Real-time model switching
• Comprehensive error handling

• Docker containerization
• Kubernetes orchestration
• Auto-scaling configurations
• Load balancing
• Health monitoring

• SafeTensors memory-safe loading
• API key authentication
• Request validation
• Audit logging
• Rate limiting

Edu-HRM/
├── models/                     # Core model architectures
├── dataset/                    # Dataset builders and processors
├── hrm_cpp_distribution/       # C++ production engine
├── checkpoints/                # Trained model weights
├── data/                       # Processed datasets
├── config/                     # Training configurations
├── utils/                      # Utility functions
├── requirements.txt            # Python dependencies
└── README.md                   # This file

• System Evolution Guide - Complete transformation story
• Organizational Handbook - Detailed system documentation
• System Inventory - Current state analysis
• API Templates - Production integration guides

# Configure training
python pretrain.py --config config/sudoku_config.yaml

# Monitor with W&B
wandb login your_api_key
python pretrain.py --wandb

# Convert all models to production formats
cd hrm_cpp_distribution
python convert_all_models.py

# Validate conversions
./test_integration

# Build C++ system
make release

# Run production server
./complete_hrm_system --port 8080 --models all

1. Research (Python) → Train models with enhanced PyTorch environment
2. Convert → Transform to binary and SafeTensors formats
3. Deploy (C++) → Production inference with native performance
4. Monitor → Real-time metrics and performance tracking

We welcome contributions! Please see our Contributing Guidelines for details.

# Clone repository
git clone https://github.com/ascii-edu/Edu-HRM.git

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python -m pytest tests/

This project is licensed under the MIT License - see the LICENSE file for details.

• Original HRM research and implementation
• PyTorch and SafeTensors communities
• Contributors and early adopters
• Educational institutions using this system

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

Edu-HRM: From Research Tool to Production Ecosystem 🚀

Complete hierarchical reasoning capabilities for educational and research applications.