openthechests 0.7.4
Training environment for reinforcement learning with event-based context
Requires Python: >=3.9

![image](./docs/otc_logo.png)

# Open The Chests Project

Open the Chests is a game that mimics the problem of situation recognition in a concurrent event-based environment.
The player is confronted with a number of boxes, each one associated with a button. Pressing a button sometimes leads 
to a box opening, sometimes leads to nothing. The player also observes events being displayed on a screen.
The goal of the player is to deduce a set of interpretable event-based rules that allow them to determine with confidence 
at which moment the chests can be opened.

## Quick Start

**Open-the-Chests** is available on [Pypi](https://pypi.org/project/openthechests/). To install it and all its libraries simply run:
```shell
pip install openthechests
```
The environment is then ready to execute by simply running the `demo.py` file.

## Running the Demo
To test the environment, download the `docs` and `demo.py` folders.
The `docs` folder contains examples of usage of the environment that are representative of its functioning as well as an example configuration for the demonstration. 
The execution of the `demo.py` file generates an environment using a `YAML` configuration
file and allows you to interact with the environment manually.
To run the demonstration, use the following command:
```shell
python demo.py
```
This will initialize the environment and start the interactive session where you can input actions to interact with the boxes.



## Folder Structure
The `openthechests` module contains several folders and files of interest:
```plaintext
openthechests/
│
├── docs/
│   └── examples/
│
├── openthechests/
│   └── src/
│       ├── elements/
│       ├── utils/
│       ├── OpenTheChests.py
│       └── OpenTheChestsGym.py
│
├── demo.py
├── README.md
└── requirements.txt

```

## Descriptions of Key Files and Folders

- **docs/**: Contains documentation related to the project.
  - **examples/**: Example configurations and usage of the environment.
    - `__init__.py`: Initializes the examples module.

- **openthechests/**: The main code for the environment.
  - **src/**: Contains the main environment elements.
    - **elements/**: Contains classes that define the environment elements.
    - **utils/**: Contains useful functions used by other modules.
    - `OpenTheChests.py`: Defines the core environment logic.
    - `OpenTheChestsGym.py`: Provides the Gym interface for the environment.

- `demo.py`: Demonstration script for the environment.

- `requirements.txt`: Lists the dependencies required to run the project.

- `third_parties_licences.txt`: Lists the licences to apply from the dependencies

# Licence

Open-the-chests applies the 3-clauses BSD licence.

# Citation

If you use this training environmenet please cite:

```
@inproceedings{stoy24otc,
    author = {Stoyanova, Ivelina and Museux, Nicolas and Nguyen, Sao-Maï and Filliat, David},
    title = {Open the {C}hests: An {E}nvironment for {A}ctivity {R}ecognition and {S}equential {D}ecision {P}roblems {U}sing {T}emporal {L}ogic},
    year = {2024},
    month = {October},
    booktitle = {31st International Symposium on Temporal Representation and Reasoning},
    address = {Montpellier, France},
    location =	{Dagstuhl, Germany},
    publisher =	{Schloss Dagstuhl -- Leibniz-Zentrum f{\"u}r Informatik},
    series =	{Leibniz International Proceedings in Informatics (LIPIcs)},
}

```