Metadata-Version: 2.5
Name: cleaning-robots-gym
Version: 0.1.0a1
Summary: Gymnasium-compatible MDP environment for autonomous cleaning robot reinforcement learning.
Project-URL: Homepage, https://github.com/ui-iros/cleaning-robots-gym
Project-URL: Repository, https://github.com/ui-iros/cleaning-robots-gym
Project-URL: Issues, https://github.com/ui-iros/cleaning-robots-gym/issues
Author: Simforianus Jonathan Flonas Harefa, Farrel Athalla Muljawan, Calvin Joy Tarigan, Vektor Dewanto, Wisnu Jatmiko
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: gymnasium>=0.29.1
Requires-Dist: numpy>=1.21.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: render
Requires-Dist: matplotlib>=3.4.0; extra == 'render'
Requires-Dist: pygame>=2.5.0; extra == 'render'
Provides-Extra: research
Requires-Dist: matplotlib>=3.4.0; extra == 'research'
Requires-Dist: moviepy>=1.0.3; extra == 'research'
Requires-Dist: pandas>=1.3.0; extra == 'research'
Requires-Dist: pygame>=2.5.0; extra == 'research'
Requires-Dist: sb3-contrib>=2.3.0; extra == 'research'
Requires-Dist: stable-baselines3>=2.3.0; extra == 'research'
Requires-Dist: torch>=2.0.0; extra == 'research'
Provides-Extra: video
Requires-Dist: matplotlib>=3.4.0; extra == 'video'
Requires-Dist: moviepy>=1.0.3; extra == 'video'
Requires-Dist: pygame>=2.5.0; extra == 'video'
Description-Content-Type: text/markdown

# Cleaning Robots Gym

Gymnasium-compatible reinforcement-learning environment for the cleaning-robot
MDP described in the paper preprint.

Developed by the IROS Lab team, Faculty of Computer Science (Fasilkom),
Universitas Indonesia. Current planned package version: `0.1.0a1` (alpha).

## Installation

```bash
pip install -e .
pip install -e ".[research]"
```

These commands install from this checkout. Once an alpha release is published,
install that exact release with `pip install cleaning-robots-gym==0.1.0a1`.

The first command installs the environment. The second adds training, plotting,
rendering, and video dependencies. For video only, use `pip install -e ".[video]"`.

## Repository Structure

```text
cleaning-robots-gym/
|-- cleaning_robots_gym/       # Installable environment package
|   |-- __init__.py           # Gymnasium registration and public imports
|   |-- envs/
|   |   `-- cleaning_robot_env.py
|   `-- config/
|       `-- cleaning_robots_v0.yaml
|-- scripts/                  # Training, evaluation, plotting, video
|-- docs/                     # Experiment documentation and figures
|   `-- media/
|-- logs/                     # Local results/models; excluded from Git
|-- README.md
|-- pyproject.toml
`-- requirements.txt          # Full research dependencies
```

The layout follows the package/scripts/docs separation used by BlueSky-Gym.
Only the environment package is installed into the wheel. Research scripts and
generated experiment outputs are maintained separately.
Historical results already tracked in Git are retained under `logs/`; new,
untracked experiment outputs are ignored.

## Experiments

```bash
python scripts/train.py --algorithms ppo a2c --seeds 12345
python scripts/simulate.py --algorithm ppo --num_episodes 3
python scripts/aggregate_results.py --help
python scripts/plot_comparison.py
```

See [scripts/README.md](scripts/README.md) and [docs/experiments.md](docs/experiments.md).

## Usage

The package follows the same usage pattern as third-party Gymnasium libraries:

```python
import gymnasium as gym
import cleaning_robots_gym

cleaning_robots_gym.register_envs()
env = gym.make("CleaningRobots-v0")

obs, info = env.reset(seed=12345)
terminated = truncated = False
while not (terminated or truncated):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
env.close()
```

`CleaningRobots-v0` loads `cleaning_robots_gym/config/cleaning_robots_v0.yaml`,
which is the single 7x7 journal configuration previously kept as `config_2.yaml`.

## RecordVideo

Gymnasium records videos from environments that support `render_mode="rgb_array"`.
Install `moviepy` if Gymnasium asks for it, then wrap the environment:

```python
import gymnasium as gym
from gymnasium.wrappers import RecordVideo
import cleaning_robots_gym

cleaning_robots_gym.register_envs()

env = gym.make("CleaningRobots-v0", render_mode="rgb_array")
env = RecordVideo(
    env,
    video_folder="logs/videos",
    episode_trigger=lambda episode_id: True,
    name_prefix="cleaning-robots-v0",
)

obs, info = env.reset(seed=12345)
terminated = truncated = False
while not (terminated or truncated):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)

env.close()
```

For a ready-to-run example, use:

```bash
python scripts/record_video.py --episodes 1 --steps_per_episode 500
```

## License and Releases

The code is licensed under the [MIT License](https://github.com/ui-iros/cleaning-robots-gym/blob/main/LICENSE).
Copyright is attributed to Cleaning Robots Gym contributors; the lab affiliation
above does not establish institutional ownership of every contribution.

See [the release guide](https://github.com/ui-iros/cleaning-robots-gym/blob/main/docs/releasing.md)
for TestPyPI, Trusted Publishing, version updates, and the journal release checklist.
