Project Structure

Project Structure

The MLFramework Template enforces a strict separation of concerns. By decoupling configuration, data processing, model architectures, and training loops, the repository remains maintainable and scalable as the complexity of experiments grows.

Directory Tree

Below is the standard directory structure generated by the template:

.
├── .bash_scripts/          # Bash scripts, may include custom user bash scripts
├── scripts/                # Custom user scripts
├── conf/                   # Hydra configuration files
│   ├── data/               # DataModule configurations
│   ├── model/              # Architecture configurations
│   └── example_config.yaml # Main entrypoint configuration
├── data/                   # Local dataset storage (ignored by Git, tracked by DVC)
├── src/                    # Source code
│   ├── cli.py              # Command Line Interface (Typer + Hydra)
│   ├── data/               # PyTorch Lightning DataModules
│   └── models/             # PyTorch Lightning Modules (Tasks)
│       └── architectures/  # Pure PyTorch neural network abstractions
├── flake.nix               # Nix environment and system dependencies configuration
├── Makefile                # Task automation (lint, format, init operations)
└── pyproject.toml          # Python dependencies and tool configurations (uv, ruff, mypy)

Component Overview

src/ (Source Code)

The source directory is architected to isolate framework-agnostic logic from training orchestration wrappers.

• src/models/architectures/: Contains pure PyTorch network definitions (e.g., CNN, KAN). These modules should only define the neural network graph and the forward pass. They must remain completely decoupled from PyTorch Lightning.
• src/models/: Contains PyTorch Lightning LightningModule classes, referred to as Tasks. These modules encapsulate the training loop, optimization strategy, loss computation, and metric tracking. They receive the pure architecture dynamically via dependency injection.
• src/data/: Contains PyTorch Lightning LightningDataModule classes. These modules standardize data downloading, deterministic splitting, augmentations, and DataLoader instantiation.
• src/cli.py: The primary execution entrypoint powered by Typer. It orchestrates the dynamic parsing of Hydra configurations, instantiates required classes, and executes PyTorch Lightning Trainer methods.

conf/ (Configuration Management)

This directory is strictly managed by Hydra, utilizing a hierarchical and modular YAML structure.

• Global Configuration (example_config.yaml): Defines high-level execution parameters, trainer arguments, and logger settings. It acts as the root node that composes sub-configurations.
• Sub-configurations (data/, model/): Define specific hyperparameters for data processing and model initialization. The parameters declared in these files must strictly map to the __init__ signatures of their corresponding Python classes.

Root Infrastructure Files

• flake.nix & .envrc: Define the deterministic system-level environment. This ensures exact parity of underlying C++ libraries, CUDA toolkits, and binary dependencies across all development machines.

• pyproject.toml: The standard Python project metadata definition. It specifies dependencies resolved by uv and maintains configurations for static analysis tools (ruff and mypy).

• Makefile: Provides a standardized interface for common execution targets, abstracting away verbose underlying shell commands for linting, formatting, and DVC initialization.