deep-learning-core

Reusable deep learning framework core.

deep-learning-core contains the vendor-neutral training framework that can be reused across many experiment repositories. It is intended to be the public base package, while optional integrations such as Azure are layered on through extras and companion extension packages.

Trainers own reusable optimization and rollout loops; experiment repositories own and register neural model architectures. deep-learning-core deliberately does not ship built-in neural networks.

Current public release: deep-learning-core==0.1.8. Current development version: 0.1.8.

Compatible companion package floors:

• deep-learning-azure>=0.0.22,<0.1
• deep-learning-mlflow>=0.0.15,<0.1
• deep-learning-robotics>=0.0.6,<0.1
• deep-learning-wandb>=0.0.16,<0.1

What's New in 0.1.8?

• checkpoint resume now fails loudly when all candidates are corrupt, and checkpoint writes are atomic across trainers
• sweep run names are unique before any configs are written; resume matches saved run names even when grid order changes
• an existing sweep tracker requires confirmation before a fresh run replaces it
• the PyTorch requirement is torch>2.3, with no upper cap; select the version appropriate for your project and accelerator

Previous versions are recorded in the release history.

Install

Install from PyPI:

pip install deep-learning-core

The package keeps PyTorch accelerator selection with the consuming project. With uv, the Linux development/test extra resolves CPU-only PyTorch wheels so CI does not install CUDA dependencies.

Install WebDataset-backed tar support only when needed:

pip install "deep-learning-core[webdataset]"

Install with Azure support:

pip install "deep-learning-core[azure]"

Install with local MLflow support:

pip install "deep-learning-core[mlflow]"

Install with W&B support:

pip install "deep-learning-core[wandb]"

Install with multiple variants:

pip install "deep-learning-core[azure,wandb]"

Install in a uv project:

uv add deep-learning-core

deep-learning-core intentionally ships with the full public runtime dependencies, including torch and opencv-python-headless. Generated classification projects declare torchvision directly because their example ResNet architecture belongs to the experiment repository. The Azure extra pulls in deep-learning-azure, which pins the Azure package versions used by the validated Azure packaging stack. The MLflow extra pulls in deep-learning-mlflow for local MLflow tracking. The W&B extra pulls in deep-learning-wandb and leaves the wandb package itself unpinned.

Package Variants

• deep-learning-core: local training, local sweeps, local sweep analysis, and the experiment scaffold
• deep-learning-core[azure]: adds the public dl-azure package for Azure execution and Azure dataset foundations
• deep-learning-core[mlflow]: adds the public dl-mlflow package for local MLflow integration
• deep-learning-core[wandb]: adds the public dl-wandb package for Weights & Biases integration
• deep-learning-robotics: adds fast scalar and vector 2D MAPF environments, metrics, and episode media as a separately installed companion package

The extension packages stay separate so the base package remains reusable and vendor-neutral.

You can also install the companion packages directly when you want a specific integration without using extras:

pip install deep-learning-azure
pip install deep-learning-mlflow
pip install deep-learning-robotics
pip install deep-learning-wandb

Scope

• Base abstractions and registries
• Built-in accelerators, callbacks, criterions, metrics, and schedulers
• The standard trainer and standard dataset flow
• Episode-driven tabular, DQN, PPO, SAC, and Dreamer training
• Built-in augmentations
• Local execution and sweep orchestration
• Local sweep analysis from saved artifact summaries
• Experiment repository scaffolding via dl-init

Out Of Scope

• Azure ML wiring unless the Azure extra is installed
• Workspace or datastore conventions
• Experiment-specific datasets, models, and trainers
• User-owned configs and private data

Quick Start

uv run dl-core list
uv run dl-init --name my-exp --root-dir .

To initialize the current directory in place, omit --name:

uv run dl-init --root-dir .

The generated experiment repository is the normal consumer entry point. Inside that repository, run uv sync, then run:

uv run dl-run --config configs/base.yaml --validate-only
uv run dl-inspect-dataset --config configs/base.yaml
uv run dl-smoke --config configs/base.yaml
cp configs/base.yaml experiments/debug.yaml
uv run dl-run --config experiments/debug.yaml --validate-only
uv run dl-run --config experiments/debug.yaml
uv run dl-sweep experiments/lr_sweep.yaml --preview
uv run dl-sweep experiments/lr_sweep.yaml --only "*seed_2025*"
uv run dl-sweep experiments/lr_sweep.yaml
uv run dl-analyze --sweep experiments/lr_sweep.yaml
uv run dl-sync --sweep experiments/lr_sweep.yaml --artifacts
uv run dl-analyze --sweep experiments/lr_sweep.yaml --name pareto_eer
uv run dl-analyze --sweep experiments/lr_sweep.yaml --compare latest
uv run dl-analyze --sweep experiments/lr_sweep.yaml --metric test/eer --mode min

New local runs use the flattened artifact layout:

• dl-run: artifacts/runs/<run_name>/...
• artifacts/sweeps/<sweep_name>/<run_name>/...

dl-core does not create a latest symlink for these run directories. Use the concrete run directory names directly.

First Run Workflow

If you are starting from scratch, the minimum path is:

pip install deep-learning-core
uv run dl-init --name my-exp --root-dir .
cd my-exp
uv sync

Then:

1. open these generated files first:
   • src/datasets/my_exp.py
   • configs/base.yaml
   • scripts/temporary/test_dataset.py
   • scripts/temporary/test_model.py
   • experiments/lr_sweep.yaml
   • AGENTS.md
   • CLAUDE.md
2. implement the generated dataset wrapper under src/datasets/my_exp.py
3. adjust configs/base.yaml so it points at the dataset/model/trainer you want and set the shared reproducibility defaults you need (seed and deterministic). Keep concrete single-run configs in experiments/, including debug and baseline runs.
4. smoke-check the generated helpers:

uv run python scripts/temporary/test_dataset.py
uv run python scripts/temporary/test_model.py

5. start with:

uv run dl-run --config configs/base.yaml --validate-only
uv run dl-inspect-dataset --config configs/base.yaml
uv run dl-smoke --config configs/base.yaml
cp configs/base.yaml experiments/debug.yaml
uv run dl-run --config experiments/debug.yaml --validate-only
uv run dl-run --config experiments/debug.yaml

Once that works, move on to:

uv run dl-sweep experiments/lr_sweep.yaml --preview
uv run dl-sweep experiments/lr_sweep.yaml
uv run dl-analyze --sweep experiments/lr_sweep.yaml
uv run dl-analyze --sweep experiments/lr_sweep.yaml \
  --metric test/eer --mode min \
  --metric test/accuracy --mode max \
  --rank-method rank-sum

dl-sweep --preview prints the expanded run matrix without creating configs or starting runs. Use --export sweep_preview.csv or --export sweep_preview.json when you want to save that expansion for review. Use --only and --skip with glob patterns when you want to execute or preview only a subset of generated run names. A later --resume retries only the runs selected when that sweep started, even if you omit the filters. Run names must be unique and include the grid fields they represent. If existing sweep data would be overwritten, a fresh run asks for confirmation before writing; --resume keeps the existing tracker.

dl-inspect-dataset preserves the configured split behavior, but forces single-process loading so you can quickly verify split sizes and inspect one collated batch without starting a trainer.

dl-sync --sweep ... --artifacts syncs tracked run outputs into the local repo. Backends that already write local artifacts simply refresh the tracker paths. Remote-backed integrations can download the run bundle and patch sweep_tracking.json with the resolved local artifact paths.

dl-analyze defaults to ranking by test/accuracy with max. You can make that explicit or override it with one or more --metric / --mode pairs and choose lexicographic, rank-sum, or pareto ranking.

For Azure-backed sweeps, dl-analyze fetches only the requested metric histories instead of downloading every tracked metric history. Those fetched histories are cached in experiments/<sweep_name>/analysis_cache.json. Use --force to ignore and refresh that cache. Reports are written under experiments/<sweep_name>/analysis/ as v1.md, v2.md, and so on unless you pass --name. A matching JSON report is always written next to each Markdown report, and --compare latest or --compare v1 compares the current ranking against a saved report.

EMA Checkpoints

When EMA is enabled with save_in_checkpoint: true, each checkpoint stores:

• models_state_dict: normal model weights for training resume
• ema_state_dict: EMA bookkeeping and shadow-parameter state for trainer-side resume
• ema_models_state_dict: a full drop-in model state dict with EMA parameters and the original model buffers preserved

That means evaluator-side code can load:

• checkpoint["models_state_dict"]["main"] for normal weights
• checkpoint["ema_models_state_dict"]["main"] for EMA weights

without needing to reconstruct EMA state manually.

Post-Training Checkpoint Hooks

After a successful training loop, the trainer lifecycle calls select_checkpoint() and passes the returned path into post_training(checkpoint_path). This hook runs before run-analysis artifacts are persisted and before tracking callbacks upload finalized artifacts.

The default select_checkpoint() implementation keeps the existing checkpoint callback behavior authoritative: it returns final best.pth when present, falls back to final latest.pth, and returns None if no checkpoint exists. Override select_checkpoint() when a project needs custom single- or multi-metric model selection, and override post_training() for completed-run evaluation, export, or report generation.

Trainer Lifecycles

Use EpochTrainer when a complete pass over the training loader defines progress. Use IterationTrainer for streaming data or when training should stop after an exact number of batches:

trainer:
  stream_trainer:
    iterations: 100000
    log_frequency: 1000
    validation_frequency: 5000
    test_frequency: 10000
    checkpoint_frequency: 5000

from dl_core.core import IterationTrainer


class StreamTrainer(IterationTrainer):
    ...

Every distributed rank consumes one local batch per iteration, so all ranks perform the same number of synchronized model updates. Finite loaders restart with a new deterministic data cycle; streaming loaders can remain open indefinitely. Checkpoints retain the completed iteration, data-cycle number, and position within the current finite-loader cycle. With gradient accumulation, reporting and checkpoint saves wait for a completed optimizer step; a final partial window is stepped before the final report.

BaseTrainer is no longer part of the API. Existing epoch-based subclasses should import EpochTrainer; switching a project to iteration-based training also requires replacing epochs with iterations and choosing iteration frequencies.

If Azure support is installed, uv run dl-init --with-azure will also scaffold Azure-ready config placeholders and azure-config.json.

If local MLflow support is installed, uv run dl-init --with-mlflow will also scaffold an mlflow callback block and local tracking defaults.

If W&B support is installed, uv run dl-init --with-wandb will also scaffold a wandb callback block, W&B tracking defaults, and .env.example.

Select at most one explicit sweep tracker; Azure can still provide the executor alongside W&B or local MLflow tracking. In-place init patches supported existing config and bootstrap files while preserving their other content; it never replaces a project-owned component file.

Companion Packages

• dl-azure
• dl-mlflow
• dl-robotics
• dl-wandb

Scaffold Commands

Each dl-core add ... command creates the new module and updates the matching local package __init__.py export list under src/.

uv run dl-core describe ... now also shows a minimal YAML snippet for common config-backed component types such as datasets, models, callbacks, optimizers, and trainers.

Common local component scaffolds:

uv run dl-core add model MyResNet
uv run dl-core add trainer MyTrainer
uv run dl-core add trainer StreamTrainer --base iterationtrainer
uv run dl-core add trainer MyPolicy --base rltrainer
uv run dl-core add callback MyMetrics
uv run dl-core add metric_manager MyManager
uv run dl-core add episode_manager MyEpisodeManager
uv run dl-core add sampler MySampler
uv run dl-core add optimizer MyOptimizer
uv run dl-core add scheduler MyScheduler
uv run dl-core add criterion MyLoss
uv run dl-core add augmentation MyAugmentation
uv run dl-core add metric MyMetric
uv run dl-core add executor MyExecutor

Default-base scaffolds for augmentations, metrics, metric managers, criterions, models, and executors now start with ready-to-edit method stubs instead of empty wrapper subclasses.

See Local Components and Sweeps for component implementation rules and the recommended compute_forward() structure.

Sweep scaffolds are supported too:

uv run dl-core add sweep DebugSweep
uv run dl-core add sweep AzureEval --tracking azure_mlflow
uv run dl-core add sweep MlflowBaseline --tracking mlflow
uv run dl-core add sweep WandbAblation --tracking wandb

Generated sweep files:

• live under experiments/
• extend ../configs/base_sweep.yaml
• include runnable defaults in fixed
• start with grid: {}
• default the tracker experiment destination to the repository root name unless tracking.experiment_name overrides it
• let the tracker derive sweep grouping from the filename unless tracking.sweep_name overrides it

Project-specific criterions, optimizers, and schedulers can still be added later with uv run dl-core add ... when they are actually needed.

You can inspect registered components and built-in base classes directly from the CLI:

uv run dl-core list
uv run dl-core list sampler
uv run dl-core list metric_manager --json
uv run dl-core describe dataset my_dataset --root-dir .
uv run dl-core describe model my_resnet --root-dir .
uv run dl-core describe class dl_core.core.FrameWrapper
uv run dl-core describe class dl_azure.datasets.AzureComputeMultiFrameWrapper
uv run dl-core describe dataset my_dataset --root-dir . --json

The built-in sampler list now includes label, which balances samples by any metadata key using either undersample or oversample.

Example sampler config:

dataset:
  sampler:
    label:
      key: attack
      mode: undersample

The describe command shows:

• resolved class and registered names
• constructor signature
• inheritance chain
• docstring
• declared properties
• class-level attributes
• public methods defined on the class

It does not discover instance attributes created dynamically inside __init__ without constructing the class.

Scaffolds can target a specific base when you need one:

uv run dl-core add dataset MyDataset
uv run dl-core add dataset FrameSet --base frame
uv run dl-core add dataset TextSet --base text_sequence
uv run dl-core add dataset ActSet --base adaptive_computation
uv run dl-core add dataset TarSet --base tar_shard
uv run dl-core add callback EpochLogger --base metric_logger
uv run dl-core add metric_manager PadMetrics --base standard
uv run dl-core add optimizer AdamwWrapper --base adamw
uv run dl-core add scheduler CosineWrapper --base cosine

Built-in callbacks include dataset_refresh, which rebuilds selected dataset splits at epoch boundaries. Example:

callbacks:
  dataset_refresh:
    refresh_frequency: 1
    splits: [train]

When dl-azure is importable, the dataset scaffold also exposes Azure bases:

uv run dl-core add dataset AzureFrames --base azure_compute_frame
uv run dl-core add dataset AzureSeq --base azure_compute_multiframe
uv run dl-core add dataset AzureStream --base azure_streaming
uv run dl-core add dataset AzureStreamSeq --base azure_streaming_multiframe
uv run dl-core add dataset AzureTar --base azure_streaming_tar

Plain deep-learning-core currently exposes dataset bases for:

• BaseWrapper
• FrameWrapper
• TextSequenceWrapper
• AdaptiveComputationDataset
• TarShardWrapper

TextSequenceWrapper adds sequence-aware batch padding for tokenized inputs. AdaptiveComputationDataset adds per-class sample stream helpers for adaptive-time computation trainers. Multiframe dataset bases are still provided through dl-azure.

TarShardWrapper uses the optional webdataset package to stream members such as sample.png and sample.json as one grouped sample. Project wrappers implement transform() and receive the grouped bytes in file_dict["members"]. WebDataset performs shard/sample shuffling and splits the shard stream between distributed ranks and DataLoader workers.

Explicit dataset.shards are optional. Project wrappers can construct paths and weights together:

from dl_core.datasets import TarShardWrapper


class MobaiTarWrapper(TarShardWrapper):
    def build_shard_sources(self, split: str) -> list[dict]:
        return [
            {
                "name": "bonafide",
                "weight": 0.5,
                "shards": self.find_bonafide_shards(split),
            },
            {
                "name": "replay",
                "weight": 0.3,
                "shards": self.find_replay_shards(split),
            },
            {
                "name": "print",
                "weight": 0.2,
                "shards": self.find_print_shards(split),
            },
        ]

Each shard may be a path string or a metadata dictionary containing path. Positive-weight sources are passed to WebDataset RandomMix. The weights are probabilistic rather than an exact within-batch composition and are most useful with a resampled iteration-based training stream.

Releases

• Publish is the production workflow for PyPI.
• Trusted publishing is configured through GitHub Actions environments rather than long-lived API tokens.
• The publish action may upload digital attestations alongside the package. That is expected behavior from pypa/gh-action-pypi-publish.
• Package metadata keeps runtime dependencies unpinned, so the consuming environment resolves the latest compatible public releases.

Documentation

• Documentation Index
• GitHub Repository

License

MIT. See LICENSE.

Development Validation

uv run --extra dev pytest
uv run --extra dev ruff check src tests
uv run python -m compileall src/dl_core
uv build --no-sources