Quickstart

Quickstart Guide

This guide outlines the steps required to instantiate a new project from the MLFramework Template, configure the isolated environment, and execute the baseline training pipeline.

Prerequisites

Ensure the following system-level tools are installed prior to initialization:

• Git
• Nix (with flakes feature enabled, Optional)
• direnv

Step 1: Project Instantiation

1. Navigate to the MLFramework Template repository on GitHub.
2. Click the Use this template button to generate a new repository based on this structure.
3. Clone your newly created repository to your local machine:

git clone [https://github.com/](https://github.com/)<your-username>/<your-new-project>.git
cd <your-new-project>

Step 2: Environment Initialization

This project utilizes Nix and direnv for deterministic environment provisioning. To initialize the environment, explicitly allow direnv to execute the local configuration:

direnv allow

Upon execution, this directive will automatically:

• Provision necessary system-level dependencies (e.g., CUDA toolkits, C++ binaries) via Nix.
• Trigger uv to resolve and install all Python dependencies specified in pyproject.toml into an isolated local .venv directory.
• Prepend the .venv/bin directory to your execution PATH to ensure command isolation.

Step 3: Secret Management Configuration

Local secrets and environment-specific variables (such as MLFLOW_TRACKING_URI) must be stored securely and excluded from version control. Generate the .env file using the predefined Makefile target:

make dotenv_init

Open the generated .env file and populate it with your specific infrastructure credentials.

Step 4: Data Version Control (DVC) Setup

Initialize the local DVC repository to enable tracking of large datasets and model artifacts:

make dvc_init

Step 5: Execute Baseline Training

With the environment fully configured, verify the infrastructure by executing the baseline training task. The template includes an example configuration leveraging Hydra and PyTorch Lightning.

Run the following command:

python -m src.cli train -c example_config.yaml

If the setup is successful, the CLI will output the initialization sequence, compile the DataModule and model architecture, and immediately commence the PyTorch Lightning training loop.