datenwissenschaften

Python 3.12 License: GPL-3.0

The reinforcement-learning engine behind Retro Speedlab.

datenwissenschaften turns classic-game emulators into reproducible training systems. It provides visual and state-aware environments, recurrent PPO agents, parallel execution, durable checkpoints, episode recording, and a live browser dashboard in one focused Python package.

This repository contains the reusable engine. For game runners, end-to-end examples, and user-facing documentation, start with Retro Speedlab.

Why this engine

  • Exploration for sparse rewards — adaptive multi-input CNN-LSTM PPO combines visual frames, normalized RAM, temporal memory, and normalized, clipped, annealed Random Network Distillation (RND).
  • Efficient execution — vectorized environments, automatic worker selection, CUDA tuning, and CPU fallback.
  • Reliable training runs — atomic checkpoints, resumable model state, and .bk2 replay capture.
  • Operational visibility — a local Vue dashboard reports episode outcomes, reward distributions, environment details, PPO parameters, and RND progress.
  • Game-oriented infrastructure — ROM discovery, RAM models, state machines, visual encoders, and configurable action translation.

Model choices

Model Best suited to Characteristics
AdaptiveRecurrentRNDModel Sparse-reward NES games and partially observable state Automatic visual + RAM inputs, NES-tuned recurrent PPO, LSTM memory, adaptive intrinsic RND exploration
Custom SB3 model Experiments that need a standard Stable-Baselines3 algorithm Integrates through the same builder, trainer, callbacks, and dashboard

AdaptiveRecurrentRNDModel is the recommended starting point for visual agents. RND encourages the policy to visit novel observations, while its influence decays during training so learned external rewards increasingly drive behavior. The model also auto-configures score-staleness windows, missing-win windows, exploration multipliers, entropy, learning rate, clip range, and RND update pressure from the action space, rollout size, training horizon, fitness volatility, score staleness, and win staleness. The predictor, fixed target, optimizer, reward statistics, adaptation state, and annealing progress are all preserved in checkpoints. Environment wrappers always use RGB observations and one emulator step per selected action; these are fixed engine defaults rather than game-level options. The default profile uses longer 512-step rollouts, a 256-unit LSTM, gamma=0.999, gae_lambda=0.98, and a slower 5-million-step RND decay. These settings preserve more temporal context and delayed reward information than the shorter arcade baseline while retaining conservative PPO updates.

Installation

The package requires Python 3.12.

pip install datenwissenschaften

For local development:

git clone https://github.com/datenwissenschaften/datenwissenschaften.git
cd datenwissenschaften
poetry install
cp config.example.yaml config.yaml

Training dashboard

Enable the dashboard with ui.enable: true, then open http://127.0.0.1:18080. It refreshes live training telemetry without interrupting the learner.

Dashboard history and non-file training state are restored from and persisted to Redis. This includes best-episode references and metrics, callback state, and target memory. Best episodes are scoped by game identity and game savestate (for example level1-1), independently of the active training objective. Model checkpoints and .bk2 episode recordings remain on disk. The default Redis URL is redis://127.0.0.1:6379/0, and history keys use the datenwissenschaften:history prefix. The ui mapping accepts enable, host, port, max_episodes, redis_url, and history_key_prefix. Snapshots retain the latest 1,000 episodes by default and include summarized totals for discarded episodes; set max_episodes to another positive integer or null for unlimited retained rows. Binding to 0.0.0.0 makes the dashboard reachable on the local network; use that only on a trusted network and open it through the machine's actual IP address.

How a run fits together

  1. A game package defines RAM structures, training states, rewards, and action translation.
  2. The environment factory creates vectorized emulator workers and processed visual observations.
  3. A model builder creates or restores the selected policy.
  4. The trainer coordinates learning, checkpoints, replay capture, telemetry, and optional uploads.
  5. The dashboard exposes the active run without coupling the learner to a separate monitoring service.

Development

Run Python quality checks:

ruff check src
black --check src
python -m compileall -q src

Build the dashboard assets after changing the Vue frontend:

cd src/datenwissenschaften/ui/frontend
npm ci
npm run build

License

Copyright © datenwissenschaften contributors. Distributed under the GNU General Public License v3.0.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.10.10)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Datenwissenschaften from gravatar.com Datenwissenschaften

Credits

Author: datenwissenschaften

License expression

GPL-3.0-only
View SPDX License List

Requires

Python <3.13, >=3.12

Tags

reinforcement-learning retro-gaming stable-baselines3 stable-retro ai gymnasium

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

datenwissenschaften-2.10.1.tar.gz (135.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

datenwissenschaften-2.10.1-py3-none-any.whl (156.4 kB view details)

Uploaded Python 3

File details

Details for the file datenwissenschaften-2.10.1.tar.gz.

File metadata

  • Download URL: datenwissenschaften-2.10.1.tar.gz
  • Upload date:
  • Size: 135.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.4.1 CPython/3.12.13 Linux/6.17.0-1020-azure

File hashes

Hashes for datenwissenschaften-2.10.1.tar.gz
Algorithm Hash digest
SHA256 8ee302b2f7f40c9dde48f2dc6f2b4c65f1d469ad8ebc3800f1d55d02e1ca5cda
MD5 0bc258e3841fb2ac7938a60e788c41be
BLAKE2b-256 8106fa7263c43e96d7ec337eb4c308fb5b2a514698f0883a70ad8e4d16017ec6

See more details on using hashes here.

File details

Details for the file datenwissenschaften-2.10.1-py3-none-any.whl.

File metadata

  • Download URL: datenwissenschaften-2.10.1-py3-none-any.whl
  • Upload date:
  • Size: 156.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.4.1 CPython/3.12.13 Linux/6.17.0-1020-azure

File hashes

Hashes for datenwissenschaften-2.10.1-py3-none-any.whl
Algorithm Hash digest
SHA256 5d091247c962be3dccbf6b0b425b70c7f8e02ba76f4b0ac9dc18f51cb62eb8a7
MD5 008a3a9a520802076d61559449fe7338
BLAKE2b-256 e50732222198fa7940e488741c97c50a4ed25b1e6d8dff2343b94bc477a16938

See more details on using hashes here.

Release history Release notifications | RSS feed

2.10.10

2 files

2.10.9

2 files

2.10.8

2 files

2.10.7

2 files

2.10.6

2 files

2.10.5

2 files

2.10.4

2 files

2.10.3

2 files

2.10.2

2 files

This release

2.10.1 This release

2 files

2.9.33

2 files

2.9.32

2 files

2.9.31

2 files

2.9.30

2 files

2.9.29

2 files

2.9.28

2 files

2.9.27

2 files

2.9.26

2 files

2.9.25

2 files

2.9.24

2 files

2.9.23

2 files

2.9.22

2 files

2.9.21

2 files

2.9.20

2 files

2.9.19

2 files

2.9.18

2 files

2.9.17

2 files

2.9.16

2 files

2.9.15

2 files

2.9.14

2 files

2.9.13

2 files

2.9.12

2 files

2.9.11

2 files

2.9.10

2 files

2.9.9

2 files

2.9.8

2 files

2.9.7

2 files

2.9.6

2 files

2.9.5

2 files

2.9.4

2 files

2.9.3

2 files

2.9.2

2 files

2.9.1

2 files

2.8.4

2 files

2.8.3

2 files

2.8.2

2 files

2.8.1

2 files

2.7.4

2 files

2.7.3

2 files

2.7.2

2 files

2.7.1

2 files

2.6.2

2 files

2.6.1

2 files

2.5.4

2 files

2.5.3

2 files

2.5.2

2 files

2.5.1

2 files

2.5.0

2 files

2.4.0

2 files

2.3.0

2 files

2.2.0

2 files

2.1.0

2 files

2.0.0

2 files

1.11.9

2 files

1.11.5

2 files

1.11.4

2 files

1.11.3

2 files

1.11.2

2 files

1.11.1

2 files

1.11.0

2 files

1.10.11

2 files

1.10.10

2 files

1.10.9

2 files

1.10.8

2 files

1.10.7

2 files

1.10.6

2 files

1.10.5

2 files

1.10.4

2 files

1.10.3

2 files

1.10.2

2 files

1.10.1

2 files

1.10.0

2 files

1.9.4

2 files

1.9.3

2 files

1.9.2

2 files

1.9.1

2 files

1.9.0

2 files

1.8.1

2 files

1.8.0

2 files

1.7.5

2 files

1.7.4

2 files

1.7.3

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.1

2 files

1.6.0

2 files

1.5.0

2 files

1.4.6

2 files

1.4.5

2 files

1.4.4

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.1

2 files

1.2.1

2 files

1.2.0

2 files

1.1.1

2 files

1.1.0

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page