deep-learning-core 0.0.24__tar.gz → 0.0.26__tar.gz

deep_learning_core-0.0.26/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  validate:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install locked dependencies
+        run: uv sync --locked --extra dev --python ${{ matrix.python-version }}
+
+      - name: Run Ruff
+        run: uv run --no-sync ruff check src tests
+
+      - name: Run tests with coverage
+        run: >-
+          uv run --no-sync python -m pytest
+          --cov=dl_core
+          --cov-report=term
+          --cov-fail-under=45
+
+      - name: Compile package
+        run: uv run --no-sync python -m compileall src/dl_core
+
+      - name: Build distribution artifacts
+        run: uv build --no-sources
+
+      - name: Check distribution metadata
+        run: uv run --no-sync twine check dist/*

{deep_learning_core-0.0.24 → deep_learning_core-0.0.26}/.github/workflows/publish-testpypi.yml

@@ -31,28 +31,14 @@ jobs:
       - name: Set up Python
         run: uv python install 3.11
 
-      - name: Create virtual environment
-        run: uv venv
+      - name: Install locked dependencies
+        run: uv sync --locked --extra dev --python 3.11
 
-      - name: Install test dependencies
-        run: |
-          python3 - <<'PY'
-          from pathlib import Path
-          import tomllib
-
-          pyproject = tomllib.loads(Path("pyproject.toml").read_text())
-          dependencies = pyproject["project"]["dependencies"]
-          dev_dependencies = pyproject["project"]["optional-dependencies"]["dev"]
-          Path("requirements-ci.txt").write_text(
-              "\n".join([*dependencies, *dev_dependencies, "twine"]) + "\n",
-              encoding="utf-8",
-          )
-          PY
-          uv pip install --python .venv/bin/python -r requirements-ci.txt
-          uv pip install --python .venv/bin/python --no-deps --editable .
+      - name: Run Ruff
+        run: uv run --no-sync ruff check src tests
 
       - name: Run tests
-        run: VIRTUAL_ENV="$PWD/.venv" PATH="$PWD/.venv/bin:$PATH" .venv/bin/python -m pytest
+        run: uv run --no-sync python -m pytest
 
       - name: Build distribution artifacts
         run: |
@@ -60,7 +46,7 @@ jobs:
           uv build --no-sources
 
       - name: Check distribution metadata
-        run: .venv/bin/python -m twine check dist/*
+        run: uv run --no-sync twine check dist/*
 
       - name: Upload distribution artifacts
         uses: actions/upload-artifact@v6

{deep_learning_core-0.0.24 → deep_learning_core-0.0.26}/.github/workflows/publish.yml

@@ -31,28 +31,14 @@ jobs:
       - name: Set up Python
         run: uv python install 3.11
 
-      - name: Create virtual environment
-        run: uv venv
+      - name: Install locked dependencies
+        run: uv sync --locked --extra dev --python 3.11
 
-      - name: Install test dependencies
-        run: |
-          python3 - <<'PY'
-          from pathlib import Path
-          import tomllib
-
-          pyproject = tomllib.loads(Path("pyproject.toml").read_text())
-          dependencies = pyproject["project"]["dependencies"]
-          dev_dependencies = pyproject["project"]["optional-dependencies"]["dev"]
-          Path("requirements-ci.txt").write_text(
-              "\n".join([*dependencies, *dev_dependencies, "twine"]) + "\n",
-              encoding="utf-8",
-          )
-          PY
-          uv pip install --python .venv/bin/python -r requirements-ci.txt
-          uv pip install --python .venv/bin/python --no-deps --editable .
+      - name: Run Ruff
+        run: uv run --no-sync ruff check src tests
 
       - name: Run tests
-        run: VIRTUAL_ENV="$PWD/.venv" PATH="$PWD/.venv/bin:$PATH" .venv/bin/python -m pytest
+        run: uv run --no-sync python -m pytest
 
       - name: Build distribution artifacts
         run: |
@@ -60,7 +46,7 @@ jobs:
           uv build --no-sources
 
       - name: Check distribution metadata
-        run: .venv/bin/python -m twine check dist/*
+        run: uv run --no-sync twine check dist/*
 
       - name: Upload distribution artifacts
         uses: actions/upload-artifact@v6

{deep_learning_core-0.0.24 → deep_learning_core-0.0.26}/AGENTS.md

@@ -28,6 +28,7 @@
     <rule>Use f-strings for string formatting.</rule>
     <rule>Keep functions focused and avoid unnecessary nesting.</rule>
     <rule>No formatter or linter configuration is defined in <code>pyproject.toml</code>; mirror nearby files instead of re-styling code arbitrarily.</rule>
+    <rule>Whenever package behavior, public APIs, CLI behavior, scaffold output, dependencies, or versions change, review <code>README.md</code> and the relevant <code>readme/</code> docs and keep them consistent with the code. If no documentation update is needed, state why.</rule>
   </development_rules>
 
   <architecture_rules>

{deep_learning_core-0.0.24 → deep_learning_core-0.0.26}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: deep-learning-core
-Version: 0.0.24
+Version: 0.0.26
 Summary: Reusable deep learning framework core.
 Project-URL: Homepage, https://github.com/Blazkowiz47/dl-core
-Project-URL: Documentation, https://github.com/Blazkowiz47/dl-core/tree/main/readme
+Project-URL: Documentation, https://github.com/Blazkowiz47/dl-core/tree/master/readme
 Project-URL: Repository, https://github.com/Blazkowiz47/dl-core
 Project-URL: Issues, https://github.com/Blazkowiz47/dl-core/issues
 Author-email: blazkowiz47 <sushrutpatwardhan@gmail.com>
@@ -42,8 +42,10 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: albumentations
+Requires-Dist: gymnasium<2,>=1.3
 Requires-Dist: numpy
 Requires-Dist: opencv-python-headless
 Requires-Dist: psutil
@@ -53,13 +55,16 @@ Requires-Dist: torch
 Requires-Dist: torchvision
 Requires-Dist: tqdm
 Provides-Extra: azure
-Requires-Dist: deep-learning-azure<0.1,>=0.0.17; extra == 'azure'
+Requires-Dist: deep-learning-azure<0.1,>=0.0.18; extra == 'azure'
 Provides-Extra: dev
-Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.12; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
 Provides-Extra: mlflow
-Requires-Dist: deep-learning-mlflow<0.1,>=0.0.10; extra == 'mlflow'
+Requires-Dist: deep-learning-mlflow<0.1,>=0.0.11; extra == 'mlflow'
 Provides-Extra: wandb
-Requires-Dist: deep-learning-wandb<0.1,>=0.0.11; extra == 'wandb'
+Requires-Dist: deep-learning-wandb<0.1,>=0.0.12; extra == 'wandb'
 Description-Content-Type: text/markdown
 
 # deep-learning-core
@@ -71,28 +76,38 @@ 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.
 
-## What's New?
-
-- `dl-init` is now the primary scaffold command
-- `dl-core list` makes built-in and local registry discovery easier
-- `dl-core add` defaults to plain base classes unless `--base` is given
-- `dl-analyze` is the primary sweep-analysis CLI
-- `dl-analyze` now supports explicit ranking metrics and rank methods
-- `dl-analyze` now persists `analysis_cache.json` next to `sweep_tracking.json`
-- `dl-analyze` now writes versioned reports under `analysis/vN.md`
-- `dl-sync --sweep ... --artifacts` now syncs tracked remote artifacts into the
-  local repository when the active backend supports it
-- EMA checkpoints now include a drop-in `ema_models_state_dict` alongside the
-  normal training weights and EMA resume metadata
-- `dl-run --validate-only` now performs a real preflight by resolving the
-  configured components without starting training
-- `dl-inspect-dataset` now summarizes split sizes and one collated batch from
-  the current config
-- `dl-smoke` now checks one dataset batch and one model forward pass from a
-  config file
-- local artifacts now use:
-  - `artifacts/runs/<run_name>/...`
-  - `artifacts/sweeps/<sweep_name>/<run_name>/...`
+Current release: `deep-learning-core==0.0.26`.
+
+Compatible companion package floors:
+
+- `deep-learning-azure>=0.0.18,<0.1`
+- `deep-learning-mlflow>=0.0.11,<0.1`
+- `deep-learning-wandb>=0.0.12,<0.1`
+
+## What's New in 0.0.26?
+
+- Gymnasium-compatible environments can now be registered, discovered, and
+  created through a first-class environment contract
+- `RLTrainer` provides an episode-based lifecycle, deterministic evaluation,
+  RL callback hooks, and resumable algorithm checkpoints alongside
+  `EpochTrainer`
+- `QLearningTrainer` adds tabular epsilon-greedy learning for finite discrete
+  Gymnasium environments
+- `DQNTrainer` adds replay-based discrete control with target networks,
+  Double-DQN targets, and a built-in MLP Q-network
+- `PPOTrainer` adds clipped on-policy optimization, GAE, and discrete or
+  bounded-continuous actor-critic policies
+- `SACTrainer` adds replay-based bounded-continuous control with twin critics,
+  Polyak targets, and optional automatic entropy tuning
+- `dl-run --validate-only` now resolves RL environments, models, optimizers,
+  and callbacks without resetting or stepping an environment
+- `dl-core add trainer MyPolicy --base rltrainer` scaffolds custom algorithms
+  against the episode-oriented lifecycle
+- the local metric callback records RL episode, update, and evaluation metrics
+- local component loading now cleans up registrations and import paths between
+  projects, while registry lookups prefer the most specific matching prefix
+- configuration validation rejects malformed root and component structures
+  more consistently
 
 ## Install
 
@@ -202,7 +217,9 @@ 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
-uv run dl-run --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
@@ -241,10 +258,12 @@ Then:
    - `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 root-level reproducibility defaults you need (`seed` and
-   `deterministic`)
+   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:
 
 ```bash
@@ -258,7 +277,9 @@ uv run python scripts/temporary/test_model.py
 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
-uv run dl-run --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:
@@ -318,6 +339,20 @@ That means evaluator-side code can load:
 
 without needing to reconstruct EMA state manually.
 
+## Post-Training Checkpoint Hooks
+
+After a successful training loop, `BaseTrainer.run()` 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.
+
 If Azure support is installed, `uv run dl-init --with-azure` will
 also scaffold Azure-ready config placeholders and `azure-config.json`.
 
@@ -348,6 +383,7 @@ Common local component scaffolds:
 ```bash
 uv run dl-core add model MyResNet
 uv run dl-core add trainer MyTrainer
+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 sampler MySampler
@@ -482,7 +518,7 @@ provided through `dl-azure`.
 
 ## Documentation
 
-- [Documentation Index](https://github.com/Blazkowiz47/dl-core/tree/main/readme)
+- [Documentation Index](https://github.com/Blazkowiz47/dl-core/tree/master/readme)
 - [GitHub Repository](https://github.com/Blazkowiz47/dl-core)
 
 ## License
@@ -493,5 +529,7 @@ MIT. See [LICENSE](LICENSE).
 
 ```bash
 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
 ```

{deep_learning_core-0.0.24 → deep_learning_core-0.0.26}/README.md

@@ -7,28 +7,38 @@ 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.
 
-## What's New?
-
-- `dl-init` is now the primary scaffold command
-- `dl-core list` makes built-in and local registry discovery easier
-- `dl-core add` defaults to plain base classes unless `--base` is given
-- `dl-analyze` is the primary sweep-analysis CLI
-- `dl-analyze` now supports explicit ranking metrics and rank methods
-- `dl-analyze` now persists `analysis_cache.json` next to `sweep_tracking.json`
-- `dl-analyze` now writes versioned reports under `analysis/vN.md`
-- `dl-sync --sweep ... --artifacts` now syncs tracked remote artifacts into the
-  local repository when the active backend supports it
-- EMA checkpoints now include a drop-in `ema_models_state_dict` alongside the
-  normal training weights and EMA resume metadata
-- `dl-run --validate-only` now performs a real preflight by resolving the
-  configured components without starting training
-- `dl-inspect-dataset` now summarizes split sizes and one collated batch from
-  the current config
-- `dl-smoke` now checks one dataset batch and one model forward pass from a
-  config file
-- local artifacts now use:
-  - `artifacts/runs/<run_name>/...`
-  - `artifacts/sweeps/<sweep_name>/<run_name>/...`
+Current release: `deep-learning-core==0.0.26`.
+
+Compatible companion package floors:
+
+- `deep-learning-azure>=0.0.18,<0.1`
+- `deep-learning-mlflow>=0.0.11,<0.1`
+- `deep-learning-wandb>=0.0.12,<0.1`
+
+## What's New in 0.0.26?
+
+- Gymnasium-compatible environments can now be registered, discovered, and
+  created through a first-class environment contract
+- `RLTrainer` provides an episode-based lifecycle, deterministic evaluation,
+  RL callback hooks, and resumable algorithm checkpoints alongside
+  `EpochTrainer`
+- `QLearningTrainer` adds tabular epsilon-greedy learning for finite discrete
+  Gymnasium environments
+- `DQNTrainer` adds replay-based discrete control with target networks,
+  Double-DQN targets, and a built-in MLP Q-network
+- `PPOTrainer` adds clipped on-policy optimization, GAE, and discrete or
+  bounded-continuous actor-critic policies
+- `SACTrainer` adds replay-based bounded-continuous control with twin critics,
+  Polyak targets, and optional automatic entropy tuning
+- `dl-run --validate-only` now resolves RL environments, models, optimizers,
+  and callbacks without resetting or stepping an environment
+- `dl-core add trainer MyPolicy --base rltrainer` scaffolds custom algorithms
+  against the episode-oriented lifecycle
+- the local metric callback records RL episode, update, and evaluation metrics
+- local component loading now cleans up registrations and import paths between
+  projects, while registry lookups prefer the most specific matching prefix
+- configuration validation rejects malformed root and component structures
+  more consistently
 
 ## Install
 
@@ -138,7 +148,9 @@ 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
-uv run dl-run --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
@@ -177,10 +189,12 @@ Then:
    - `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 root-level reproducibility defaults you need (`seed` and
-   `deterministic`)
+   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:
 
 ```bash
@@ -194,7 +208,9 @@ uv run python scripts/temporary/test_model.py
 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
-uv run dl-run --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:
@@ -254,6 +270,20 @@ That means evaluator-side code can load:
 
 without needing to reconstruct EMA state manually.
 
+## Post-Training Checkpoint Hooks
+
+After a successful training loop, `BaseTrainer.run()` 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.
+
 If Azure support is installed, `uv run dl-init --with-azure` will
 also scaffold Azure-ready config placeholders and `azure-config.json`.
 
@@ -284,6 +314,7 @@ Common local component scaffolds:
 ```bash
 uv run dl-core add model MyResNet
 uv run dl-core add trainer MyTrainer
+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 sampler MySampler
@@ -418,7 +449,7 @@ provided through `dl-azure`.
 
 ## Documentation
 
-- [Documentation Index](https://github.com/Blazkowiz47/dl-core/tree/main/readme)
+- [Documentation Index](https://github.com/Blazkowiz47/dl-core/tree/master/readme)
 - [GitHub Repository](https://github.com/Blazkowiz47/dl-core)
 
 ## License
@@ -429,5 +460,7 @@ MIT. See [LICENSE](LICENSE).
 
 ```bash
 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
 ```

{deep_learning_core-0.0.24 → deep_learning_core-0.0.26}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "deep-learning-core"
-version = "0.0.24"
+version = "0.0.26"
 description = "Reusable deep learning framework core."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -34,9 +34,11 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
 ]
 dependencies = [
     "albumentations",
+    "gymnasium>=1.3,<2",
     "numpy",
     "opencv-python-headless",
     "psutil",
@@ -49,21 +51,24 @@ dependencies = [
 
 [project.optional-dependencies]
 azure = [
-    "deep-learning-azure>=0.0.17,<0.1",
+    "deep-learning-azure>=0.0.18,<0.1",
 ]
 mlflow = [
-    "deep-learning-mlflow>=0.0.10,<0.1",
+    "deep-learning-mlflow>=0.0.11,<0.1",
 ]
 wandb = [
-    "deep-learning-wandb>=0.0.11,<0.1",
+    "deep-learning-wandb>=0.0.12,<0.1",
 ]
 dev = [
-    "pytest",
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.12",
+    "twine>=6.0",
 ]
 
 [project.urls]
 Homepage = "https://github.com/Blazkowiz47/dl-core"
-Documentation = "https://github.com/Blazkowiz47/dl-core/tree/main/readme"
+Documentation = "https://github.com/Blazkowiz47/dl-core/tree/master/readme"
 Repository = "https://github.com/Blazkowiz47/dl-core"
 Issues = "https://github.com/Blazkowiz47/dl-core/issues"
 
@@ -81,11 +86,6 @@ dl-smoke = "dl_core.smoke:main"
 dl-sweep = "dl_core.sweep.runner:main"
 dl-train-worker = "dl_core.worker:main"
 
-[tool.uv.sources]
-"deep-learning-azure" = { path = "../dl-azure", editable = true }
-"deep-learning-mlflow" = { path = "../dl-mlflow", editable = true }
-"deep-learning-wandb" = { path = "../dl-wandb", editable = true }
-
 [tool.hatch.build.targets.sdist]
 exclude = [
     "/.tmp-ci-venv",

{deep_learning_core-0.0.24 → deep_learning_core-0.0.26}/readme/README.md

@@ -4,6 +4,8 @@ This documentation is split into quick references, workflow guides, and
 technical notes. The goal is the same as in the original framework repo, but
 focused on the extracted package and the experiment-repo workflow around it.
 
+Current public release: `deep-learning-core==0.0.26`.
+
 ## Companion Packages
 
 - [`dl-azure`](https://github.com/Blazkowiz47/dl-azure): Azure execution and
@@ -41,6 +43,7 @@ mechanics.
 - [Sweep System](./technical/3_sweep_system.md)
 - [Local Component Loading](./technical/4_local_component_loading.md)
 - [Testing](./technical/5_testing.md)
+- [Reinforcement Learning](./technical/6_reinforcement_learning.md)
 
 ## Common Tasks
 
@@ -65,11 +68,15 @@ uv run dl-init --root-dir .
 ### Run a local training job
 
 ```bash
-uv run dl-run --config configs/base.yaml
+uv run dl-run --config configs/base.yaml --validate-only
+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
 ```
 
 Generated `configs/base.yaml` files include root-level `seed` and
-`deterministic` defaults so reproducibility can be controlled explicitly.
+`deterministic` defaults so reproducibility can be controlled explicitly. Keep
+concrete single-run configs under `experiments/`, including debug runs.
 
 ### Smoke-check generated dataset and model helpers
 

{deep_learning_core-0.0.24 → deep_learning_core-0.0.26}/readme/guide/1_getting_started.md

@@ -54,7 +54,7 @@ Inside the generated repository:
 ```bash
 uv add --editable ../dl-core
 uv sync
-uv run dl-run --config configs/base.yaml
+uv run dl-run --config configs/base.yaml --validate-only
 ```
 
 If that succeeds, your local package plus experiment repo integration is

{deep_learning_core-0.0.24 → deep_learning_core-0.0.26}/readme/guide/2_creating_an_experiment_repository.md

@@ -32,6 +32,8 @@ uv run dl-init --name my-exp --root-dir . --with-mlflow
 
 ```text
 my-exp/
+  AGENTS.md
+  CLAUDE.md
   pyproject.toml
   configs/
     base.yaml
@@ -78,6 +80,8 @@ By default:
 - `configs/presets.yaml`
 - `experiments/lr_sweep.yaml`
 - `experiments/experiments.log`
+- `AGENTS.md`
+- `CLAUDE.md`
 
 Start there before editing the wrapper classes. After updating the dataset or
 model wrapper, use:
@@ -88,3 +92,8 @@ uv run python scripts/temporary/test_model.py
 ```
 
 before committing to a full `dl-run`.
+
+Use `configs/base.yaml` for reusable shared defaults. Before a real single run,
+copy or derive it into a named file under `experiments/`, for example
+`experiments/debug.yaml`, validate that concrete config, and run `dl-run`
+against the `experiments/` file.

{deep_learning_core-0.0.24 → deep_learning_core-0.0.26}/readme/guide/3_local_components_and_sweeps.md

@@ -104,7 +104,9 @@ The core dataset bases are intended for different data shapes:
 ## Local Training
 
 ```bash
-uv run dl-run --config configs/base.yaml
+uv run dl-run --config configs/base.yaml --validate-only
+cp configs/base.yaml experiments/debug.yaml
+uv run dl-run --config experiments/debug.yaml
 ```
 
 ## Sweeps

{deep_learning_core-0.0.24 → deep_learning_core-0.0.26}/readme/technical/1_configuration.md

@@ -125,6 +125,13 @@ trainer:
 That wrapper extends `dl_core.trainers.standard_trainer.StandardTrainer`,
 which builds on the epoch-based `dl_core.core.EpochTrainer`.
 
+After successful training, `BaseTrainer.run()` calls `select_checkpoint()` and
+passes that path to `post_training(checkpoint_path)`. The default selector
+returns final `best.pth` when the checkpoint callback created it, falls back to
+final `latest.pth`, and otherwise returns `None`. Override `select_checkpoint()`
+for custom single- or multi-metric model selection, and override
+`post_training()` for completed-run evaluation or export work.
+
 ## Reproducibility
 
 Generated base configs expose reproducibility at the root level:

{deep_learning_core-0.0.24 → deep_learning_core-0.0.26}/readme/technical/2_entry_points.md

@@ -73,7 +73,7 @@ scripts.
 Runs a single local training job through the local executor.
 
 ```bash
-uv run dl-run --config configs/base.yaml
+uv run dl-run --config experiments/debug.yaml
 ```
 
 Useful flags:
@@ -88,7 +88,8 @@ Notes:
 - `--validate-only` now performs a lightweight preflight: it validates the
   config, resolves the configured components, safely instantiates the dataset,
   models, criterions, optimizer, and optional scheduler, then exits without
-  starting training
+  starting training. Malformed YAML roots and section types are reported as
+  validation errors instead of failing with an internal exception.
 
 ## `dl-smoke`