deep-learning-core 0.0.25__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.25 → 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.25 → 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.25 → deep_learning_core-0.0.26}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: deep-learning-core
-Version: 0.0.25
+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
@@ -55,7 +57,10 @@ Requires-Dist: tqdm
 Provides-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.11; extra == 'mlflow'
 Provides-Extra: wandb
@@ -71,7 +76,7 @@ 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.
 
-Current release: `deep-learning-core==0.0.25`.
+Current release: `deep-learning-core==0.0.26`.
 
 Compatible companion package floors:
 
@@ -79,31 +84,30 @@ Compatible companion package floors:
 - `deep-learning-mlflow>=0.0.11,<0.1`
 - `deep-learning-wandb>=0.0.12,<0.1`
 
-## 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
-- `BaseTrainer` now exposes `select_checkpoint()` and
-  `post_training(checkpoint_path)` hooks for completed-run evaluation or export
-  work; the default checkpoint selection uses `best.pth` then `latest.pth`
-- `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>/...`
+## 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
 
@@ -213,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
@@ -252,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
@@ -269,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:
@@ -373,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
@@ -507,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
@@ -518,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.25 → deep_learning_core-0.0.26}/README.md

@@ -7,7 +7,7 @@ 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.
 
-Current release: `deep-learning-core==0.0.25`.
+Current release: `deep-learning-core==0.0.26`.
 
 Compatible companion package floors:
 
@@ -15,31 +15,30 @@ Compatible companion package floors:
 - `deep-learning-mlflow>=0.0.11,<0.1`
 - `deep-learning-wandb>=0.0.12,<0.1`
 
-## 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
-- `BaseTrainer` now exposes `select_checkpoint()` and
-  `post_training(checkpoint_path)` hooks for completed-run evaluation or export
-  work; the default checkpoint selection uses `best.pth` then `latest.pth`
-- `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>/...`
+## 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
 
@@ -149,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
@@ -188,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
@@ -205,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:
@@ -309,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
@@ -443,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
@@ -454,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.25 → deep_learning_core-0.0.26}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "deep-learning-core"
-version = "0.0.25"
+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",
@@ -58,12 +60,15 @@ wandb = [
     "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.25 → deep_learning_core-0.0.26}/readme/README.md

@@ -4,7 +4,7 @@ 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.25`.
+Current public release: `deep-learning-core==0.0.26`.
 
 ## Companion Packages
 
@@ -43,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
 
@@ -67,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.25 → 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.25 → 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.25 → 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.25 → 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`
 

{deep_learning_core-0.0.25 → deep_learning_core-0.0.26}/readme/technical/5_testing.md

@@ -24,7 +24,9 @@ uv run python -m compileall src/dl_core
 From a generated experiment repository:
 
 ```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
 uv run dl-sweep experiments/lr_sweep.yaml
 ```