Metadata-Version: 2.4
Name: datenwissenschaften
Version: 1.0.0
Summary: A powerful Reinforcement Learning toolkit for classic games, featuring the Retro Speedlab Command Center.
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: reinforcement-learning,retro-gaming,stable-baselines3,stable-retro,ai,gymnasium
Author: datenwissenschaften
Author-email: martin.franke@datenwissenschaften.com
Requires-Python: >=3.12,<3.13
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: gymnasium (>=1.3.0,<2.0.0)
Requires-Dist: itsdangerous (>=2.2.0,<3.0.0)
Requires-Dist: numpy (>=2.4.5,<3.0.0)
Requires-Dist: opencv-python (>=4.13.0.92,<5.0.0.0)
Requires-Dist: python-dotenv (>=1.2.2,<2.0.0)
Requires-Dist: requests (>=2.34.2,<3.0.0)
Requires-Dist: rich (>=15.0.0,<16.0.0)
Requires-Dist: stable-baselines3 (>=2.8.0,<3.0.0)
Requires-Dist: stable-retro (>=1.0.0,<2.0.0)
Requires-Dist: torch (>=2.12.0,<3.0.0)
Description-Content-Type: text/markdown

# datenwissenschaften: Retro Speedlab 🚀

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/release/python-3120/)

**datenwissenschaften** is a high-performance Reinforcement Learning (RL) toolkit designed to streamline training on classic video games. Built on top of `stable-baselines3` and `stable-retro`, it provides a robust framework for developing, monitoring, and perfecting RL agents.

At its core is the **Retro Speedlab Command Center**, a beautiful real-time dashboard that keeps you in control of your training sessions.

## ✨ Key Features

*   **🎮 Retro Speedlab Command Center**: A rich, interactive terminal dashboard to monitor steps, win rates, episodes per minute, and uptime in real-time.
*   **🏋️ Effortless Training**: Use the `Trainer` class to orchestrate complex training sessions with minimal boilerplate.
*   **📊 Smart Callbacks**: Automatic model checkpointing, best-episode recording (including `.bk2` replays), and episode uploading.
*   **🛠️ Robust Infrastructure**: Built-in support for environment wrappers, ROM management, and flexible configuration via environment variables.
*   **🚀 Optimized for Stable Retro**: Seamless integration with the latest classic gaming environments.

## 🚀 Quick Start

### Installation

```bash
pip install datenwissenschaften
```

### Basic Usage

```python
import os
from datenwissenschaften import Trainer, EnvironmentBuilder, ModelBuilder
from stable_baselines3 import PPO

# 1. Configure your environment
os.environ["RETRO_SPEEDLAB_GAME_ID"] = "SonicTheHedgehog-Genesis"
os.environ["RETRO_SPEEDLAB_ROM_PATH"] = "./roms"
os.environ["RETRO_SPEEDLAB_MODEL_DIR"] = "./models"
os.environ["RETRO_SPEEDLAB_RECORDING_DIR"] = "./recordings"
os.environ["RETRO_SPEEDLAB_TIMESTEPS"] = "1000000"

# 2. Build the environment (using a wrapper if needed)
def my_wrapper(env):
    return env

builder = EnvironmentBuilder(wrapper=my_wrapper)
venv = builder.build(n_envs=8)

# 3. Initialize model and trainer
model_builder = ModelBuilder(build_model=lambda env: PPO("CnnPolicy", env))
model = model_builder.build(venv)
trainer = Trainer()

# 4. Start training and watch the Command Center take off!
trainer.train(model)
```

## ⚙️ Configuration

The toolkit is highly configurable via environment variables:

| Variable | Description | Default |
| :--- | :--- | :--- |
| `RETRO_SPEEDLAB_GAME_ID` | The ID of the game to train on (e.g., `SonicTheHedgehog-Genesis`). | **Required** |
| `RETRO_SPEEDLAB_ROM_PATH` | Path to the directory containing your ROMs. | **Required** |
| `RETRO_SPEEDLAB_MODEL_DIR` | Where to save trained models and checkpoints. | **Required** |
| `RETRO_SPEEDLAB_RECORDING_DIR` | Where to store episode recordings and `.bk2` files. | **Required** |
| `RETRO_SPEEDLAB_TIMESTEPS` | Total number of timesteps to train for. | **Required** |
| `RETRO_SPEEDLAB_NUM_ENVS` | Number of parallel environments to run. | `1` |
| `RETRO_SPEEDLAB_SAVESTATE` | Specific savestate to start from. | `None` |

## 📜 License

This project is licensed under the **GNU General Public License v3.0**. See the [LICENSE](LICENSE) file for details.

---
Developed with ❤️ by [datenwissenschaften](mailto:martin.franke@datenwissenschaften.com).

