Metadata-Version: 2.4
Name: MASA-Safe-RL
Version: 0.1.0
Summary: A safe reinforcement library for providing a common interface for different constraints and environments
Project-URL: Homepage, https://github.com/sacktock/MASA-Safe-RL
Project-URL: Repository, https://github.com/sacktock/MASA-Safe-RL
Project-URL: Documentation, https://sacktock.github.io/MASA-Safe-RL/
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gymnasium>=1.3.0
Requires-Dist: pettingzoo>=1.26.1
Requires-Dist: tensorflow>=2.20.0
Requires-Dist: tensorflow-probability==0.25.0
Requires-Dist: tensorstore>=0.1.65
Requires-Dist: tf-keras>=2.17.0
Requires-Dist: numpy>=1.26.4
Requires-Dist: tensorboard>=2.17.1
Requires-Dist: tqdm>=4.66.5
Requires-Dist: jax>=0.4.30
Requires-Dist: optax>=0.1.9
Requires-Dist: flax>=0.9.0
Requires-Dist: ml-dtypes>=0.4.1
Requires-Dist: ruamel.yaml<0.20.0
Requires-Dist: ipykernel>=7.2.0
Requires-Dist: moviepy<3.0.0,>=2.2.1
Requires-Dist: pillow<12.0.0,>=11.3.0
Requires-Dist: pygame>=2.6.1
Requires-Dist: ipywidgets>=8.1.5
Requires-Dist: typer>=0.25.1
Dynamic: license-file

# MASA-Safe-RL

![title card](images/logo_large.png)

--------------------------------------------------------------------------------


Welcome to MASA-Safe-RL, the Multi and Single Agent (MASA) Safe Reinforcement Learning library. The primary goal of this library is to develop a set of common constraints and environments for safe reinforcement learning research, built on top of the popular [gymnasium](https://gymnasium.farama.org/) interface. We span, CMPDs, probabilistic constraints, Reach-Avoid and LTL-Safety (DFA) properties.  

The library is in very early stage development and we greatly appreciate and encourage feedback from the community about what they would like to see implemented. Currently we provide a set of basic tabular algroithms for safe RL, but we provide a modular and resuable framework for developing more complex algorithms and constraints.

If you use MASA-Safe-RL in your research please cite it in your publications.

```bibtex
@misc{Goodall2025MASASafeRL,
  title        = {{MASA-Safe-RL}: Multi and Single Agent Safe Reinforcement Learning},
  author       = {Goodall, Alexander W. and Adalat, Omar and Hamel De-le Court, Edwin and Belardinelli, Francesco},
  year         = {2025},
  howpublished = {\url{https://github.com/sacktock/MASA-Safe-RL/}},
  note         = {GitHub repository}
}
```

## Quick Start

### Installation

#### Prequisites

Python 3.10+ is required, although later Python versions may not be supported.

#### Installation with conda 
- Install conda, e.g., via [anaconda](https://anaconda.org/channels/anaconda/packages/conda/overview).
- Clone the repo:
```bash
git clone https://github.com/sacktock/MASA-Safe-RL.git
cd MASA-Safe-RL
```
- Create a conda virtual environment:
```bash
conda env create --name masa --file conda-environment.yaml
conda activate masa
```
- Install dependencies:
```bash
pip install -e .
```

#### Installation with uv
`uv sync` installs the base package from the repository root.

* For building docs, use `uv sync --group docs` from the repository root.
* Adding GPU support for Jax: `uv sync --group cuda12` (or `cuda13` if supported by your device)
* All groups (docs and GPU support): `uv sync --all-groups`.

#### Installation with PyPI

Coming soon!

### Enabling GPU Acceleration with JAX (Optional)

MASA-Safe-RL relies on [JAX](https://docs.jax.dev/) for GPU acceleration. If you are only interested in the gymnasium wrappers and constraints API then you do not need to complete the following steps.

## Mac and Windows
**MAC** and **Windows**: we recommend JAX with CPU. No further action is required if you correctly followed the earlier steps.

#### pip 
- **Linux x86_64/aarch64** and **Windows WSL2 x86_64**: W+we strongly recommend using [Ubuntu 22.04](https://apps.microsoft.com/detail/9pn20msr04dw?hl=en-GB&gl=BE) or similar, jax and jaxlib should already be installed via the `requirements.txt`. You need to reinstall [JAX](https://docs.jax.dev/) based on your cuda driver compatibility. Do not use the ```-U``` option here as it may break earlier dependencies!
```bash
pip install "jax[cuda13]"
```
```bash
pip install "jax[cuda12]"
```

#### uv
Alternatively with `uv`,
```bash
uv sync --group cuda12
```
```bash
uv sync --group cuda13
```

## How to run MASA
- You can run masa with the prebuilt CLI:
```bash
masa run --env-id bridge_crossing --algo ppo --seed 0
```
- You can run examples from the ```\examples``` folder via:
```bash
masa examples prob_shield_example
```

## Editing documentation

Documentation uses the root `pyproject.toml` and `uv.lock`, so you can build and serve it directly from the repository root.

```bash
uv sync --group docs
uv run --locked --group docs sphinx-build -b html docs docs/_build/html
```

The built site will be available at `docs/_build/html/index.html`.

For live reload while editing, run:

```bash
uv run --locked --group docs sphinx-autobuild docs docs/_build/html
```


## Getting in Touch

MASA-Safe-RL is primarliy managed by [Alex Goodall](https://github.com/sacktock) and [Omar Adalat](https://github.com/nightly). For correspondence in the early stages of the library we prefer you contact us directly via email (a.goodall22@imperial.ac.uk), rather than raising issues on GitHub directly.

## License

MASA-Safe-RL is released under Apache License 2.0.
