Skip to content
Projects

mhdijas-2001/torch-hydra-forge

View on GitHub

mhdijas-2001/torch-hydra-forge has 53 GitHub stars and 0 forks. GitHot measured 0 in 7 days. Last checked 2026-11-15 21:28 UTC. Last push 2026-11-03.

How these counts are measured

What you can do

  • 🧩 Hydra-native configuration graph with hierarchical composition and override resolution.
  • 🔁 Deterministic run replay using seed snapshots and environment fingerprinting.
  • 📦 Pluggable module registry for models, datasets, losses, optimizers, and schedulers.
  • 📊 Metric routing layer supporting local CSV, JSONL, and pluggable sinks.

Measured star growth

in 24h
Update delayed
in 7 days
0
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

PyTorch Hydra Boilerplate 2026: Best Open Source Deep Learning Project Template

Machine Learning

README.md

Original

preview Download

🧠 NeuralForge — Modular Deep Learning Experiment Framework

A production-minded orchestration layer for PyTorch research pipelines, built on Hydra’s configuration philosophy.

NeuralForge is a structured experiment framework for teams and solo researchers who want reproducibility without rigidity. Instead of treating training scripts as disposable artifacts, NeuralForge treats every experiment as a contract: declared inputs, versioned configs, deterministic seeds, and pluggable modules that snap together like well-machined parts.

This repository is an independent, reimagined evolution inspired by the minimalist boilerplate tradition — it keeps the spirit of “just PyTorch + Hydra” while adding the scaffolding that real projects eventually need: structured logging, checkpoint lineage, metric routing, and a configuration graph that can be composed, overridden, and diffed.


📚 Table of Contents


🌌 Vision & Philosophy

Most deep learning repositories begin as a single train.py and end as a graveyard of commented-out flags. NeuralForge begins where that graveyard would have started — with a deliberate separation between what an experiment is and how it runs.

We think of a training run the way a conductor thinks of a symphony: the score (config) is authoritative, the orchestra (modules) is replaceable, and the performance (run artifacts) is recorded for later study. Nothing is implicit. Nothing is hidden in a mutable global. Every decision is traceable to a config node.

Three principles guide the design:

  1. Declarative over imperative — Hydra configs own the experiment definition.
  2. Composable over monolithic — datasets, models, optimizers, and callbacks are independent registries.
  3. Observable over opaque — every run emits structured artifacts you can diff, plot, and audit.

🚀 Why NeuralForge Exists

The original boilerplate solved a small problem elegantly: get PyTorch and Hydra talking without friction. NeuralForge asks a bigger question: what does that conversation look like across dozens of experiments, multiple collaborators, and months of iteration?

The answer involves:

  • Config inheritance trees that mirror your research questions.
  • Run registries that let you replay any past experiment bit-for-bit.
  • Metric routers that push results to local files, dashboards, or remote observability stacks.
  • Module contracts that make swapping a ResNet for a ViT a one-line change.

If you have ever lost the exact hyperparameters behind a promising checkpoint, NeuralForge is built for you.


✨ Feature Highlights

  • 🧩 Hydra-native configuration graph with hierarchical composition and override resolution.
  • 🔁 Deterministic run replay using seed snapshots and environment fingerprinting.
  • 📦 Pluggable module registry for models, datasets, losses, optimizers, and schedulers.
  • 📊 Metric routing layer supporting local CSV, JSONL, and pluggable sinks.
  • 🗂️ Checkpoint lineage tracking linking weights to the config that produced them.
  • 🌍 Multilingual support for CLI messages and generated reports (locale-aware templates).
  • 📱 Responsive dashboard UI that adapts to desktop, tablet, and mobile viewports.
  • 🕒 24/7 customer support channel routing for enterprise and research teams.
  • 🔒 Reproducibility manifests capturing library versions, hardware, and RNG state.
  • 🧪 Experiment diffing to compare two runs across config and metric space.
  • 🧭 Structured logging with JSON and human-readable modes.
  • 🛠️ Extensible hooks for custom callbacks without forking core logic.

🏗️ Architecture Overview

NeuralForge is organized into four cooperating layers:

1. Configuration Layer

Hydra composes a final config from a tree of YAML fragments. Each fragment represents a decision surface — data, model, optimizer, training loop, logging. The composed config is immutable at runtime and hashed for identification.

2. Registry Layer

A lightweight registry maps string keys to Python objects. When a config says model: resnet50, the registry resolves it. You can register your own classes without touching framework internals.

3. Execution Layer

The trainer consumes the composed config and resolved objects, running the training loop with callbacks injected at defined lifecycle points: on_start, on_epoch_end, on_checkpoint, on_complete.

4. Artifact Layer

Every run produces a directory containing the resolved config, environment manifest, metric logs, and optional checkpoints. This directory is the canonical record of the experiment.


⚙️ Configuration System

The configuration system is the heart of NeuralForge. Instead of scattering hyperparameters across code, everything lives in composable YAML fragments.

Example structure of a config group:

  • configs/data/ — dataset definitions
  • configs/model/ — architecture definitions
  • configs/optim/ — optimizer and scheduler definitions
  • configs/trainer/ — loop behavior, epochs, precision
  • configs/logger/ — metric sinks and verbosity

You select a combination at launch time by naming the fragments. Overrides are explicit and logged. Nothing is silently mutated.


🗂️ Project Layout

A typical NeuralForge project adopts this shape:

  • src/neuralforge/ — framework core
  • src/neuralforge/registry/ — module registries
  • src/neuralforge/trainer/ — training loop and callbacks
  • src/neuralforge/artifacts/ — run artifact writers
  • configs/ — Hydra configuration tree
  • experiments/ — user-defined experiment entry points
  • reports/ — generated dashboards and summaries
  • tests/ — unit and integration tests

The separation between framework and experiment code is deliberate: upgrade the framework without rewriting your research.


🏁 Quick Start

Getting a first run going involves three conceptual steps:

  1. Describe your experiment by selecting config fragments.
  2. Resolve modules by pointing registry keys at your classes.
  3. Launch the run and inspect the produced artifact directory.

Because NeuralForge is framework-agnostic about your environment, you can run it inside containers, on bare metal, or on managed compute. The framework does not prescribe packaging; it prescribes structure.

Download


🔄 Experiment Lifecycle

Every NeuralForge run moves through a predictable lifecycle:

  • Compose — Hydra assembles the final config.
  • Validate — schema checks ensure required keys exist.
  • Resolve — registry maps keys to live objects.
  • Fingerprint — environment and RNG state are recorded.
  • Train — the loop executes with callbacks firing.
  • Emit — metrics, checkpoints, and manifests are written.
  • Archive — the run directory is sealed and indexed.

This lifecycle means any run can be reconstructed, compared, or exported without guesswork.


🌍 Multilingual & Accessibility Support

NeuralForge treats language as a first-class concern. CLI messages, log templates, and report headers can be localized through message catalogs. This matters for teams spread across regions and for researchers who publish reproducible pipelines to diverse audiences.

Accessibility features include:

  • Screen-reader-friendly report output where applicable.
  • High-contrast themes in the responsive dashboard.
  • Keyboard-navigable experiment browser.

📱 Responsive Dashboard

The bundled dashboard is a lightweight view over your run artifacts. It adapts fluidly across screen sizes, presenting metric trends, config diffs, and checkpoint timelines. On mobile, it collapses into a focused run summary; on desktop, it expands into a multi-panel comparison workspace.

The dashboard is designed to be embedded or self-hosted, and it never assumes a particular cloud provider.


🛎️ Support Model

NeuralForge assumes that research does not keep office hours. The support model is built around:

  • 24/7 customer support routing for teams that need guaranteed response windows.
  • Community discussions for design questions and pattern sharing.
  • Maintainer office hours published on a rolling schedule.

Support tiers are documented so you know exactly what to expect.


🗺️ Roadmap

Planned directions include:

  • Distributed training adapters for multi-node setups.
  • Deeper experiment diff tooling with visual config graphs.
  • Additional metric sinks for observability platforms.
  • Expanded locale catalogs and translation tooling.
  • Plugin marketplace conventions for community modules.

Roadmap items are tracked as discussion threads rather than promises.


🔎 SEO & Discoverability Notes

This project is described using natural language around PyTorch experiment framework, Hydra configuration management, reproducible deep learning pipelines, modular training loops, and experiment tracking for research teams. These phrases appear because they accurately describe what NeuralForge does — not because they were inserted for ranking.

If you found this repository while searching for a structured alternative to ad-hoc training scripts, you are the intended audience.


⚠️ Disclaimer

NeuralForge is provided as-is for research and engineering purposes. It does not guarantee model performance, training stability, or suitability for any particular domain. Users are responsible for complying with applicable laws, licenses of third-party dependencies, and ethical guidelines in their field.

The maintainers are not liable for any damages arising from use of this software. Always validate results independently before relying on them in production or publication.


📄 License

This project is released under the MIT License. See the license file for full terms: MIT License.

Copyright (c) 2026 NeuralForge Contributors.

Download