Make PyTorch optional, fix the seeding bug behind the flaky CI, and hold the advertised counts to the code

.github/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-python@v7

CHANGELOG.md

@@ -6,6 +6,51 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Changed
+- The top-level package now resolves its public names lazily (PEP 562 `__getattr__`),
+  so `import decisionrl` imports nothing on its own. `decisionrl.envs`,
+  `decisionrl.baselines`, `decisionrl.core`, `decisionrl.solvers` and
+  `decisionrl.wrappers` import with PyTorch absent entirely; torch arrives on first
+  use of anything that trains (`decisionrl.algorithms`, `PPO`, `decisionrl.networks`).
+  `import decisionrl.envs` drops from ~1.9 s to ~0.2 s, the remainder being NumPy.
+  The public API is unchanged — `from decisionrl import PPO` resolves as before.
+- `decisionrl.utils` defers its `torch_utils` re-exports (`get_device`, `to_tensor`,
+  `soft_update`, …) for the same reason: `decisionrl.core` imports it for `Logger`.
+- **Breaking (packaging): PyTorch is now an optional dependency.** `pip install
+  decisionrl` installs NumPy only and gives you the environments, the classical
+  baselines, the solvers and the core API. Install `decisionrl[torch]` for the
+  algorithms — everything that trains. Touching a torch-backed name without it raises
+  a `ModuleNotFoundError` that names the attribute and the command that fixes it,
+  rather than a bare "No module named 'torch'". `decisionrl[dev]` includes torch, so
+  contributor setup is unchanged.
+- `test_neuroevolution_cem_solves_cartpole` is now
+  `test_neuroevolution_cem_beats_random_on_cartpole`: it takes the median of three
+  seeds and measures it against the random-policy return rather than asserting a single
+  seed clears 300 of a possible 500. At this budget CEM returns roughly 283 / 105 / 241
+  / 97 across seeds 0–3, so the old threshold was a threshold on luck — it is what made
+  CI fail on unrelated pull requests.
+
+### Added
+- Python 3.13 to the CI matrix and to the packaging classifiers.
+- `decisionrl.envs.APPLIED_ENVIRONMENTS`: the applied subset named in code instead of
+  counted by hand, since its size is quoted in the README, the packaging description
+  and `CITATION.cff`.
+- `tests/test_documented_counts.py`: the advertised algorithm and environment counts are
+  now checked against the package, and `CITATION.cff`'s version against
+  `decisionrl.__version__`.
+
+### Fixed
+- `NeuroevolutionAgent` never seeded its environment, so `seed=` reached only the
+  optimizer's search while the rollout start states — the fitness signal itself — came
+  from OS entropy. Every run was irreproducible regardless of the seed. It now seeds the
+  environment once at the top of `learn`, as every other agent already did.
+- The advertised counts disagreed with the package and with each other: `CITATION.cff`
+  claimed twenty-two environments where twenty-four ship, and the algorithm count was
+  31 in the README, the packaging description and the citation file where 32 agents are
+  exported. All three now read 32 algorithms and 24 environments, 9 of them applied.
+- `CITATION.cff` had no `version`, `date-released` or `type`, which left the citation
+  incomplete.
+
 ## [0.4.0] - 2026-07-18
 
 ### Added

CITATION.cff

@@ -1,13 +1,16 @@
 cff-version: 1.2.0
+type: software
 title: >-
   decisionrl — reinforcement learning for operational decisions
 message: >-
   If you use decisionrl in work you publish, please cite it using this entry.
 abstract: >-
-  A reinforcement learning library aimed at operational decisions with a cost function -- pricing, inventory, energy, queueing and supply chains -- rather than at benchmark scores. Thirty-one algorithms and twenty-two environments, nine of them applied. Every applied environment ships with the classical operations-research baseline beside it, so a learned policy is measured against the standard method rather than asserted to improve on it.
+  A reinforcement learning library aimed at operational decisions with a cost function -- pricing, inventory, energy, queueing and supply chains -- rather than at benchmark scores. 32 algorithms and 24 environments, 9 of them applied. Every applied environment ships with the classical operations-research baseline beside it, so a learned policy is measured against the standard method rather than asserted to improve on it.
 authors:
   - family-names: Drobyshev
     given-names: Denis
+version: 0.4.0
+date-released: '2026-07-18'
 repository-code: https://github.com/DrobyshevDev/decisionrl
 url: https://github.com/DrobyshevDev/decisionrl
 license: MIT

README.md

@@ -31,12 +31,15 @@ energy, queueing, and supply chains. Each of these problems ships as a first-cla
 environment paired with the classical operations-research baseline, so a learned
 policy can be measured against the standard method rather than asserted to be good.
 
-Underneath the applied layer is a dependency-light (NumPy and PyTorch) library of 31
-algorithms with a single `predict` / `learn` / `save` / `load` interface, static
-typing, and a test suite that checks both component correctness and learning behaviour.
+Underneath the applied layer is a dependency-light library of 32 algorithms with a single
+`predict` / `learn` / `save` / `load` interface, static typing, and a test suite that
+checks both component correctness and learning behaviour. The environments, the classical
+baselines and the solvers are pure NumPy; PyTorch is an extra, needed only by the half
+that trains.
 
 ```bash
-pip install decisionrl
+pip install "decisionrl[torch]"   # everything, including the deep-RL algorithms
+pip install decisionrl            # environments, baselines and solvers only (no torch)
 ```
 
 ## Results
@@ -101,7 +104,11 @@ by hand.
 ## Installation
 
 ```bash
-# from PyPI
+# from PyPI, with PyTorch - needed by every algorithm that trains
+pip install "decisionrl[torch]"
+
+# without PyTorch: the environments, the classical baselines and the solvers are
+# pure NumPy, so simulating and evaluating needs no multi-gigabyte wheel
 pip install decisionrl
 
 # with the optional Gymnasium environments

docs/index.md

@@ -14,7 +14,9 @@ so it runs the moment you `pip install` it.
   (TD3+BC, IQL, CQL) — plus multi-agent PPO (self-play / IPPO).
 - **Correctness-first** — proper `terminated`/`truncated` bootstrapping, GAE,
   target-policy smoothing, automatic entropy tuning, orthogonal init.
-- **Dependency-light** — only NumPy + PyTorch in the core; Gymnasium optional.
+- **Dependency-light** — NumPy alone in the core. The environments, the classical
+  baselines and the solvers need nothing else; PyTorch is an extra that the
+  algorithms pull in, and Gymnasium is optional.
 - **Batteries included** — built-in environments (classic control + applied),
   image observations (CNN), vectorized envs (sync & multiprocessing), a CLI and
   a tuned-hyperparameter registry.
@@ -26,6 +28,9 @@ so it runs the moment you `pip install` it.
 ## Install
 
 ```bash
+# with PyTorch, needed by every algorithm that trains:
+pip install "decisionrl[torch] @ git+https://github.com/DrobyshevDev/decisionrl.git"
+# without it - environments, baselines and solvers only:
 pip install git+https://github.com/DrobyshevDev/decisionrl.git
 # with Gymnasium environments:
 pip install "decisionrl[gym] @ git+https://github.com/DrobyshevDev/decisionrl.git"

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 # One name everywhere: pip install decisionrl / import decisionrl.
 name = "decisionrl"
 version = "0.4.0"
-description = "Applied reinforcement learning for operational decisions: pricing, inventory, energy, queues and supply chains — plus a correctness-first library of 31 algorithms."
+description = "Applied reinforcement learning for operational decisions: pricing, inventory, energy, queues and supply chains — plus a correctness-first library of 32 algorithms."
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "MIT" }
@@ -32,22 +32,29 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Typing :: Typed",
 ]
+# NumPy alone. PyTorch is an extra rather than a hard requirement: the environments,
+# the classical baselines, the solvers and the core API are pure NumPy, and a consumer
+# that only simulates or evaluates should not be made to install a multi-gigabyte wheel
+# to do it. Everything that trains imports torch on first use and says so if it is
+# missing -- see decisionrl/_lazy.py. Install `decisionrl[torch]` for the deep-RL half.
 dependencies = [
     "numpy>=1.21",
-    "torch>=1.13",
 ]
 
 [project.optional-dependencies]
+torch = ["torch>=1.13"]
 gym = ["gymnasium>=0.29"]
 config = ["pyyaml>=6.0"]
 logging = ["tensorboard>=2.10"]
 serve = ["onnx>=1.14", "onnxruntime>=1.16", "fastapi>=0.100", "uvicorn>=0.23"]
 hub = ["huggingface_hub>=0.20", "onnx>=1.14", "onnxruntime>=1.16"]
 dashboard = ["flask>=2.0", "plotly>=5.0"]
 dev = [
+    "torch>=1.13",
     "pytest>=7.0",
     "pytest-cov>=4.0",
     "pytest-xdist>=3.0",