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

[DenisDrobyshev]

Four related pieces of maintenance. The first two are what a consumer notices; the last two are what keeps the repository honest.

PyTorch is now optional

decisionrl.envs, decisionrl.baselines and decisionrl.core are useful to anything that only simulates or evaluates, but importing any of them pulled in the whole of PyTorch: the top-level package imported every subpackage eagerly, and decisionrl.utils re-exported torch_utils, which decisionrl.core reaches through core/agent.py's Logger import.

The public names now resolve through a PEP 562 module __getattr__. Nothing is imported when the package is; each name is resolved and cached on first access. __all__ is the same list, from decisionrl import PPO resolves as before, and a TYPE_CHECKING block keeps the static imports so type checkers and IDEs see what the runtime serves.

With that in place torch moves from dependencies to an extra:

• pip install decisionrl — NumPy only: environments, classical baselines, solvers, core API.
• pip install "decisionrl[torch]" — the half that trains.
• [dev] carries torch, so contributor setup is unchanged.

import decisionrl.envs drops from ~1.9 s to ~0.2 s, the remainder being NumPy. Reaching a torch-backed name without torch raises a ModuleNotFoundError naming the attribute asked for and the command that fixes it, rather than a bare No module named 'torch' from somewhere inside the package. Only torch gets the rewritten message — any other missing module still surfaces as itself, and there is a test for that.

The seeding bug behind the flaky CI

NeuroevolutionAgent passed its seed to the optimizer's search and to BaseAgent's RNG but never to the environment. _fitness only ever called env.reset() unseeded, and an unseeded env draws start states from OS entropy — and those start states are the fitness signal. Every run was irreproducible regardless of the seed. Every other agent already seeds the env once at the top of its own learn; this one did not.

That is what failed test_neuroevolution_cem_solves_cartpole on unrelated pull requests, most recently the Dockerfile bump in #13, where assert 117.6 > 300.0 had nothing to do with the change under test.

Seeding the env makes runs reproducible and shows what the method actually does at this budget: across seeds 0–3 CEM returns roughly 283 / 105 / 241 / 97 against a 500-step ceiling, with a random policy at 23.5. It beats random by a wide margin but does not reliably solve CartPole, so assert mean_return > 300.0 was an assertion about luck. The test now takes the median of three seeds against the measured random-policy floor and is renamed to match the claim. A second, fast test pins the reproducibility this restores.

The advertised counts disagreed with the package, and with each other

CITATION.cff claimed twenty-two environments where twenty-four ship. The README, the packaging description and the citation file all said 31 algorithms where 32 concrete agents are exported — a number matching no consistent definition, since decisionrl.algorithms holds 30 classes of which two are abstract bases, and BC, DAgger, DPO and NeuroevolutionAgent are agents living elsewhere.

All three now read 32 algorithms and 24 environments, 9 of them applied, and tests/test_documented_counts.py checks them against the package rather than against each other. The applied subset is named in decisionrl.envs.APPLIED_ENVIRONMENTS instead of counted by hand. CITATION.cff gains the version, date-released and type fields it was missing, and its version is now checked against decisionrl.__version__.

This changes a public claim from 31 to 32. If 31 stood for a deliberate definition — excluding DPO, say, or neuroevolution — say so and I will restore it and write the exclusion into the test explicitly.

Python 3.13

The matrix stopped at 3.12 while the serving image was being bumped to 3.14, so the versions claimed and the versions tested had drifted apart. 3.13 joins the CI matrix and the classifiers.

Verification

ruff clean, mypy clean across 130 source files. Locally the fast suite's failure set is identical to main's — 19 against 19, empty difference both ways — so this introduces no regressions; those 19 are this machine's environment (matplotlib native aborts, a CUDA/CPU mismatch, relocated PettingZoo MPE envs) and do not occur on CI.

🤖 Generated with Claude Code