dragon-torch 1.1.0__tar.gz

dragon_torch-1.1.0/.github/workflows/release.yml

@@ -0,0 +1,107 @@
+name: Release
+
+# Builds dragon-torch and publishes it to PyPI with the next version number
+# (scripts/release.py: patch bump, each part capped at 10.10.20).
+#
+# Started by tests.yml after the tests pass on main. It's a separate workflow
+# because tests.yml cancels in-progress runs when a new push arrives, and an
+# upload must never be cancelled halfway. It can also be run by hand for a commit
+# on main; either way it re-checks that the commit's tests passed on main.
+#
+# One-time setup: on PyPI, add a trusted publisher for this repo with workflow
+# `release.yml` and environment `pypi` (a "pending publisher" before the first
+# upload), and create the `pypi` environment under the repo's settings.
+
+on:
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: Commit on main to release (its Tests run on main must have passed)
+        required: true
+
+# releases run one at a time and are never cancelled: each one reads the last
+# released version, so two at once could pick the same number
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    environment: pypi
+    permissions:
+      contents: write # push the v* release tag
+      id-token: write # PyPI trusted publishing
+      actions: read # look up the commit's test runs
+    env:
+      SHA: ${{ inputs.sha }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.sha }}
+          fetch-depth: 0 # tags: released versions + "already released" check
+
+      - name: Check the commit is releasable
+        id: gate
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if ! git merge-base --is-ancestor "$SHA" origin/main; then
+            echo "::error::${SHA::7} is not on main"; exit 1
+          fi
+          # check the `test` job, not the whole run: the run that dispatched this
+          # release is still in progress (its release job is what started us)
+          passed=false
+          for run in $(gh api "repos/$GITHUB_REPOSITORY/actions/workflows/tests.yml/runs?head_sha=$SHA&branch=main" \
+                         --jq '.workflow_runs[].id'); do
+            conclusion=$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$run/jobs" \
+                           --jq '.jobs[] | select(.name == "test") | .conclusion')
+            if [ "$conclusion" = "success" ]; then passed=true; break; fi
+          done
+          if [ "$passed" != "true" ]; then
+            echo "::error::no Tests run on main passed its test job for ${SHA::7}"; exit 1
+          fi
+          released=$(git tag --points-at "$SHA" --list 'v*')
+          if [ -n "$released" ]; then
+            echo "${SHA::7} is already released as $released, nothing to do"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: astral-sh/setup-uv@v6
+        if: steps.gate.outputs.skip == 'false'
+        with:
+          python-version: "3.13"
+
+      - name: Pick the next version
+        id: version
+        if: steps.gate.outputs.skip == 'false'
+        run: uv run --no-project python scripts/release.py next-version --write
+
+      - name: Build
+        if: steps.gate.outputs.skip == 'false'
+        run: uv build --out-dir dist
+
+      - name: Check the package
+        if: steps.gate.outputs.skip == 'false'
+        run: |
+          # refuse wheels that would install stray top-level packages (utils, tests, ...)
+          uv run --no-project python scripts/release.py check-wheel dist/*.whl
+          uvx twine check --strict dist/*
+
+      - name: Publish to PyPI
+        if: steps.gate.outputs.skip == 'false'
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Tag the release
+        if: steps.gate.outputs.skip == 'false'
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "v$VERSION" "$SHA" -m "dragon-torch $VERSION"
+          git push origin "v$VERSION"
+          echo "Released dragon-torch $VERSION (${SHA::7}): https://pypi.org/project/dragon-torch/$VERSION/" >> "$GITHUB_STEP_SUMMARY"

dragon_torch-1.1.0/.github/workflows/tests.yml

@@ -0,0 +1,138 @@
+name: Tests
+
+on:
+  push:
+    branches: [dev, main]
+  workflow_dispatch:
+
+# a newer push supersedes an in-flight run on the same branch, so main never gets a stale merge
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write # publish the test-count badge to the `badges` branch
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Install dependencies
+        run: uv sync --extra test --extra torch-cpu --extra torch-ext --extra RL --extra tune
+
+      - name: Cache Hugging Face downloads
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/huggingface
+          key: hf-${{ runner.os }}-${{ hashFiles('tests/conftest.py') }}
+
+      - name: Run tests
+        run: uv run pytest -v --junitxml=report.xml
+
+      # the README badge tracks main only, and is updated whether the tests passed or failed
+      - name: Build test-count badge
+        if: always() && github.ref == 'refs/heads/main'
+        run: |
+          python3 - <<'PY'
+          import json, os
+          import xml.etree.ElementTree as ET
+
+          if os.path.exists('report.xml'):
+              root = ET.parse('report.xml').getroot()
+              suites = [root] if root.tag == 'testsuite' else root.findall('testsuite')
+              count = lambda key: sum(int(s.get(key, 0)) for s in suites)
+              total, skipped = count('tests'), count('skipped')
+              failed = count('failures') + count('errors')
+              passed = total - skipped - failed
+              ran = total - skipped
+              message = f'{passed} passed' if failed == 0 else f'{passed}/{ran} passed'
+              color = 'brightgreen' if failed == 0 else 'red'
+          else:  # pytest never ran (e.g. dependency install failed)
+              message, color = 'error', 'lightgrey'
+
+          with open('tests.json', 'w') as f:
+              json.dump({'schemaVersion': 1, 'label': 'tests on main',
+                         'message': message, 'color': color}, f)
+          print(message)
+          PY
+
+      - name: Publish test-count badge
+        if: always() && github.ref == 'refs/heads/main' && hashFiles('tests.json') != ''
+        run: |
+          cp tests.json "$RUNNER_TEMP/tests.json"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git fetch origin badges || true
+          if git rev-parse --verify -q origin/badges; then
+            git switch -f -C badges origin/badges
+          else
+            git switch -f --orphan badges
+            git rm -rfq --cached . || true
+          fi
+          git clean -fdxq
+          cp "$RUNNER_TEMP/tests.json" tests.json
+          git add tests.json
+          git diff --cached --quiet || git commit -m "badge: $(jq -r .message tests.json) @ ${GITHUB_SHA::7}"
+          git push origin badges
+
+  merge-to-main:
+    needs: test
+    # only commits pushed to dev are merged; pushes to main just run the tests
+    if: github.ref == 'refs/heads/dev'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # push to main
+      actions: write # trigger the main test run
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Merge dev into main
+        id: merge
+        run: |
+          # skip commits main already has (e.g. dev was fast-forwarded to main)
+          if git merge-base --is-ancestor "$GITHUB_SHA" HEAD; then
+            echo "Commit ${GITHUB_SHA::7} is already on main, nothing to merge"
+            echo "merged=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          # merge the exact commit that was tested, not whatever dev points at now
+          git merge --ff-only "$GITHUB_SHA" || git merge --no-edit "$GITHUB_SHA"
+          git push origin main
+          echo "merged=true" >> "$GITHUB_OUTPUT"
+
+      # pushes made with GITHUB_TOKEN don't trigger workflows, so start the
+      # main run (which refreshes the badge) explicitly
+      - name: Run tests on main
+        if: steps.merge.outputs.merged == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh workflow run tests.yml --ref main --repo "$GITHUB_REPOSITORY"
+
+  release:
+    needs: test
+    # every commit whose tests pass on main is released (release.yml skips commits
+    # that already have a v* tag, e.g. a re-run)
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write # trigger the release workflow
+    steps:
+      # release.yml runs outside this workflow's cancel-in-progress group, so a
+      # newer push to main can't cancel an upload halfway
+      - name: Start the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh workflow run release.yml --ref main --repo "$GITHUB_REPOSITORY" -f sha="$GITHUB_SHA"

dragon_torch-1.1.0/.gitignore

@@ -0,0 +1,223 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+uv.lock
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+*.ipynb
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# optuna studies / trial dirs
+runs/

dragon_torch-1.1.0/.python-version

@@ -0,0 +1 @@
+3.13

dragon_torch-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Campbell Rankine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dragon_torch-1.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: dragon-torch
+Version: 1.1.0
+Summary: PyTorch Deep Learning Research framework. Focused on RL but support for extending the framework to other areas of research
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: jax
+Requires-Dist: optuna>=5.0.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: python-dotenv>=1.2.4
+Requires-Dist: requests>=2.34.2
+Provides-Extra: rl
+Requires-Dist: gymnasium>=1.1; extra == 'rl'
+Requires-Dist: stable-baselines3; extra == 'rl'
+Requires-Dist: stable-retro[extra]; extra == 'rl'
+Provides-Extra: test
+Requires-Dist: pytest>=9.1.1; extra == 'test'
+Provides-Extra: torch-cpu
+Requires-Dist: jax>=0.11.2; extra == 'torch-cpu'
+Requires-Dist: torch>=2.14.0; extra == 'torch-cpu'
+Requires-Dist: torchvision>=0.29.0; extra == 'torch-cpu'
+Requires-Dist: transformers>=5.20.2; extra == 'torch-cpu'
+Provides-Extra: torch-cuda12
+Requires-Dist: jax[cuda12]>=0.11.2; extra == 'torch-cuda12'
+Requires-Dist: torch>=2.11.0; extra == 'torch-cuda12'
+Requires-Dist: torchvision>=0.26.0; extra == 'torch-cuda12'
+Requires-Dist: transformers>=5.20.2; extra == 'torch-cuda12'
+Provides-Extra: torch-cuda13
+Requires-Dist: jax[cuda13]>=0.11.2; extra == 'torch-cuda13'
+Requires-Dist: torch>=2.14.0; extra == 'torch-cuda13'
+Requires-Dist: torchvision>=0.29.0; extra == 'torch-cuda13'
+Requires-Dist: transformers>=5.20.2; extra == 'torch-cuda13'
+Provides-Extra: torch-ext
+Requires-Dist: accelerate>=1.15.0; extra == 'torch-ext'
+Requires-Dist: datasets>=5.1.0; extra == 'torch-ext'
+Requires-Dist: transformers[torch]>=5.20.2; extra == 'torch-ext'
+Provides-Extra: tune
+Requires-Dist: optuna-dashboard; extra == 'tune'
+Description-Content-Type: text/markdown
+
+# dragon-torch
+
+[![Tests on main](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FCampbell-Rankine%2Fdragon-torch%2Fbadges%2Ftests.json)](https://github.com/Campbell-Rankine/dragon-torch/actions/workflows/tests.yml)
+
+PyTorch Deep Learning Dev Modules
+
+### Sources:
+
+Define source for data in a dataset. Source.__getitem__() is cached and returns the full dataset. Supported types:
+
+- disk
+- hugging-face
+- hugging-face-polars
+
+### Datasets:
+
+take a source as input. Dataset.__getitem__() returns an iterable of batches from the input source
+
+**NOTE**: Dataset aggregators define batching rules / filters for combining two datasets
+
+### Tests:
+
+Pushes to `dev` run the full test suite in GitHub Actions; when every test passes, `dev` is merged into `main` automatically. Pushes to `main` run the tests without merging anything. The badge above shows how many tests pass on `main`, and is refreshed after every `main` run. Run them locally with:
+
+```bash
+uv run --extra test --extra torch-cpu --extra torch-ext pytest            # everything
+uv run --extra test --extra torch-cpu --extra torch-ext pytest -m "not network"  # skip Hugging Face Hub tests
+```
+
+### Releases:
+
+Install with `pip install dragon-torch`. Add extras as needed: `dragon-torch[RL,torch-cpu]` for RL training, `[tune]` for the dashboard. Everything imports from `dragon_torch`, for example `from dragon_torch.trainers.RL import PPOTrainer`.
+
+When the tests pass on `main`, `tests.yml` starts `release.yml`. That workflow:
+
+1. Re-checks that the commit is on `main` and that its `test` job passed.
+2. Picks the next version with `scripts/release.py`.
+3. Builds the package and uploads it to PyPI.
+4. Tags the commit `vX.Y.Z`. A commit that already has a tag is never released twice.
+
+Each release bumps the patch number of the latest release, carrying over when a part reaches its cap. The caps are 10, 10 and 20, so `1.1.20` is followed by `1.2.0`, `1.10.20` by `2.0.0`, and `10.10.20` is the last possible version. The version in `pyproject.toml` acts as a floor: set it higher, for example to `2.0.0`, to jump straight to that version.
+
+Uploads use PyPI trusted publishing. Add a publisher for this repo on PyPI with workflow `release.yml` and environment `pypi`.
+
+### Tuning / monitoring:
+
+`dragon_torch/utils/tuning/` runs optuna studies over any `_DragonModel` (pruning, multi-objective, shared storage for parallel workers) and serves them in `optuna-dashboard`. `dragon_torch/utils/tuning/RL.py` and `dragon_torch/utils/tuning/presets/` tune any RL trainer with PPO / A2C search spaces; `scripts/tune_rl.py` runs a study worker. See [docs/tuning.md](docs/tuning.md).
+
+```bash
+uv sync --extra tune
+dragon-tune dashboard --storage sqlite:///runs/optuna.db
+```
+
+### TODO:
+
+- [ ] : Setup Lazy Loading for hugging face sources.
+- [x] : Set up monitoring / experimentation with optuna
+- [ ] : Implement off policy algorithms / dependencies.
+- [ ] : Test Accelerate.prepare works with loaders
+- [ ] : Test Accelerate.prepare works with gyms
+- [ ] : OUActionNoise for RL 
+- [ ] : Research better state memory solutions
+- [ ] : Trading environment as a test case in self implemented problem
+
+
+### RL
+
+| Layer | Files | Contents |
+|---|---|---|
+| Env utils | `dragon_torch/data/envs/` | `DragonEnvConfig` and `make_vec_env`, which always uses `SAME_STEP` autoreset. Also `validate_env`, `register_dragon_env`, space conversions (`obs_to_tensor`, `action_to_env`), running normalisation, and `Discretizer` for stable-retro's button actions |
+| Sources | `dragon_torch/data/RL/` | `EnvCollector` (env stepping, shared by all sources), the `Actor` protocol, `Transition`, `RolloutSource` with GAE, and `EpisodeSource` for evaluation |
+| Networks | `dragon_torch/modules/RL/` | `ActorCritic`, `PolicyOutput`, and distribution heads for Discrete, MultiDiscrete, MultiBinary and Box actions |
+| Losses | `dragon_torch/loss/RL.py` | `PPOLoss` and `A2CLoss`; each records its components (KL, clip fraction, entropy) |
+| Model | `dragon_torch/models/RL/base.py` | `DragonRLModel` adds gradient clipping and returns episode return from `evaluate`. Its epoch count comes from `total_timesteps`, minus the steps already taken |
+| Trainers | `dragon_torch/trainers/RL/` | `DragonRLTrainer` builds a whole run from one config: rollout source, evaluator, network, loss, optimizer, LR annealing, step-scheduled eval and a divergence guard. `PPOTrainer` and `A2CTrainer` add their loss. See [docs/rl_trainers.md](docs/rl_trainers.md) |
+| SB3 | `dragon_torch/modules/external/sb3.py` | `DragonFeaturesExtractor` and `sb3_policy_kwargs` |
+
+

dragon_torch-1.1.0/README.md

@@ -0,0 +1,78 @@
+# dragon-torch
+
+[![Tests on main](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FCampbell-Rankine%2Fdragon-torch%2Fbadges%2Ftests.json)](https://github.com/Campbell-Rankine/dragon-torch/actions/workflows/tests.yml)
+
+PyTorch Deep Learning Dev Modules
+
+### Sources:
+
+Define source for data in a dataset. Source.__getitem__() is cached and returns the full dataset. Supported types:
+
+- disk
+- hugging-face
+- hugging-face-polars
+
+### Datasets:
+
+take a source as input. Dataset.__getitem__() returns an iterable of batches from the input source
+
+**NOTE**: Dataset aggregators define batching rules / filters for combining two datasets
+
+### Tests:
+
+Pushes to `dev` run the full test suite in GitHub Actions; when every test passes, `dev` is merged into `main` automatically. Pushes to `main` run the tests without merging anything. The badge above shows how many tests pass on `main`, and is refreshed after every `main` run. Run them locally with:
+
+```bash
+uv run --extra test --extra torch-cpu --extra torch-ext pytest            # everything
+uv run --extra test --extra torch-cpu --extra torch-ext pytest -m "not network"  # skip Hugging Face Hub tests
+```
+
+### Releases:
+
+Install with `pip install dragon-torch`. Add extras as needed: `dragon-torch[RL,torch-cpu]` for RL training, `[tune]` for the dashboard. Everything imports from `dragon_torch`, for example `from dragon_torch.trainers.RL import PPOTrainer`.
+
+When the tests pass on `main`, `tests.yml` starts `release.yml`. That workflow:
+
+1. Re-checks that the commit is on `main` and that its `test` job passed.
+2. Picks the next version with `scripts/release.py`.
+3. Builds the package and uploads it to PyPI.
+4. Tags the commit `vX.Y.Z`. A commit that already has a tag is never released twice.
+
+Each release bumps the patch number of the latest release, carrying over when a part reaches its cap. The caps are 10, 10 and 20, so `1.1.20` is followed by `1.2.0`, `1.10.20` by `2.0.0`, and `10.10.20` is the last possible version. The version in `pyproject.toml` acts as a floor: set it higher, for example to `2.0.0`, to jump straight to that version.
+
+Uploads use PyPI trusted publishing. Add a publisher for this repo on PyPI with workflow `release.yml` and environment `pypi`.
+
+### Tuning / monitoring:
+
+`dragon_torch/utils/tuning/` runs optuna studies over any `_DragonModel` (pruning, multi-objective, shared storage for parallel workers) and serves them in `optuna-dashboard`. `dragon_torch/utils/tuning/RL.py` and `dragon_torch/utils/tuning/presets/` tune any RL trainer with PPO / A2C search spaces; `scripts/tune_rl.py` runs a study worker. See [docs/tuning.md](docs/tuning.md).
+
+```bash
+uv sync --extra tune
+dragon-tune dashboard --storage sqlite:///runs/optuna.db
+```
+
+### TODO:
+
+- [ ] : Setup Lazy Loading for hugging face sources.
+- [x] : Set up monitoring / experimentation with optuna
+- [ ] : Implement off policy algorithms / dependencies.
+- [ ] : Test Accelerate.prepare works with loaders
+- [ ] : Test Accelerate.prepare works with gyms
+- [ ] : OUActionNoise for RL 
+- [ ] : Research better state memory solutions
+- [ ] : Trading environment as a test case in self implemented problem
+
+
+### RL
+
+| Layer | Files | Contents |
+|---|---|---|
+| Env utils | `dragon_torch/data/envs/` | `DragonEnvConfig` and `make_vec_env`, which always uses `SAME_STEP` autoreset. Also `validate_env`, `register_dragon_env`, space conversions (`obs_to_tensor`, `action_to_env`), running normalisation, and `Discretizer` for stable-retro's button actions |
+| Sources | `dragon_torch/data/RL/` | `EnvCollector` (env stepping, shared by all sources), the `Actor` protocol, `Transition`, `RolloutSource` with GAE, and `EpisodeSource` for evaluation |
+| Networks | `dragon_torch/modules/RL/` | `ActorCritic`, `PolicyOutput`, and distribution heads for Discrete, MultiDiscrete, MultiBinary and Box actions |
+| Losses | `dragon_torch/loss/RL.py` | `PPOLoss` and `A2CLoss`; each records its components (KL, clip fraction, entropy) |
+| Model | `dragon_torch/models/RL/base.py` | `DragonRLModel` adds gradient clipping and returns episode return from `evaluate`. Its epoch count comes from `total_timesteps`, minus the steps already taken |
+| Trainers | `dragon_torch/trainers/RL/` | `DragonRLTrainer` builds a whole run from one config: rollout source, evaluator, network, loss, optimizer, LR annealing, step-scheduled eval and a divergence guard. `PPOTrainer` and `A2CTrainer` add their loss. See [docs/rl_trainers.md](docs/rl_trainers.md) |
+| SB3 | `dragon_torch/modules/external/sb3.py` | `DragonFeaturesExtractor` and `sb3_policy_kwargs` |
+
+