https://github.com/kempnerinstitute/nicewebrl
NiceWebRL is a Python library for quickly making human subject experiments that leverage machine reinforcement learning environments.
https://github.com/kempnerinstitute/nicewebrl
Last synced: 11 months ago
JSON representation
NiceWebRL is a Python library for quickly making human subject experiments that leverage machine reinforcement learning environments.
- Host: GitHub
- URL: https://github.com/kempnerinstitute/nicewebrl
- Owner: KempnerInstitute
- License: mit
- Created: 2024-08-04T16:30:59.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-07-13T18:48:11.000Z (11 months ago)
- Last Synced: 2025-07-13T20:42:59.139Z (11 months ago)
- Language: Python
- Homepage:
- Size: 604 MB
- Stars: 47
- Watchers: 1
- Forks: 7
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# NiceWebRL: a Python library for human subject experiments with reinforcement learning environments
**Table of Contents**
* [Install](#install)
* [Functional example folders](#working-examples)
* [Paper case studies](#paper-case-studies)
* [More examples](#more-examples)
* [Other Jax environments compatible with NiceWebRL](#other-jax-environments-compatible-with-nicewebrl)
NiceWebRL enables researchers to use the same environments both to train and evaluate virtual agents, and to train and evaluate humans.
It supports both single-agent and multi-agent environments.
As such, NiceWebRL enables AI researchers to easily compare their algorithms to human performance, cognitive scientists to test ML algorithms as theories for human cognition, and multi-agent researchers to develop algorithms for human-AI collaboration.
To enable the use of machine learning environments in online experiments, it exploits [Jax](https://github.com/google/jax)—a high-performance numerical computing library—to reduce the latency from having clients communicate with a remote server.
To enable easy experiment design, NiceWebRL exploits [NiceGUI](https://nicegui.io/) to enable sophisticated GUI design entirely in Python.
To facilitate its adoption, we present several [working examples](#working-examples) that researchers can use to quickly set up their own experiments.
## Install
```bash
# pip install
pip install git+https://github.com/wcarvalho/nicewebrl
# more manually (first clone then)
conda create -n nicewebrl python=3.10 pip wheel -y
conda activate nicewebrl
pip install -e .
```
## Working Examples
### Paper case studies
We present three case studies for how NiceWebRL can help researchers develop either Human-like AI, Human-compatible AI, or Human-assistive AI. The first two are from two recent papers:
* [Preemptive Solving of Future Problems: Multitask Preplay in Humans and Machines](https://arxiv.org/abs/2507.05561)
* [Cross-environment Cooperation Enables Zero-shot Multi-agent Coordination](https://arxiv.org/abs/2504.12714)
Description
Visualization
Installation
Run Command
Multitask Preplay
Case study 1 (Human-like AI): Developing a novel Deep RL cognitive science model with NiceWebRL [Paper]
[folder]
see Paper Repo
Cross Environment Cooperation
Case study 2 (Human-compatible AI): Developing a novel MARL algorithm for coordinating with humans with NiceWebRL [Paper]
[folder]
follow instructions in examples/overcooked-CEC
cd examples/overcooked-CEC; python web_app.py 'counter_circuit'
XLand-Minigrid LLM
Case study 3 (Human-assistive AI): Developing an LLM-assistant for sequential-decision making tasks in a virtual environment.
[folder]
pip install -e ".[xland-assistant]"
cd examples/xland-LLM-assistant; python web_app_assistant.py
### More examples
Description
Visualization
Installation
Run Command
Craftax
2D Minecraft domain (single agent setting)
[folder]
pip install -e ".[craftax]"
cd examples/craftax; python web_app.py
XLand-Minigrid
XLand-Minigrid (single agent setting)
[folder]
pip install -e ".[xland]"
cd examples/xland-minigrid; python web_app.py
Minigrid PPO
Minigrid (single agent setting, has PPO implementation)
[folder]
pip install -e "."
cd examples/minigrid-ppo; python web_app.py
Minigrid API LLM
Minigrid with API-based LLM assistant
[folder]
pip install -e "."
cd examples/minigrid-LLM-assistant; python web_app_Gemini.py
Minigrid Local LLM
Minigrid with local LLM assistant
[folder]
pip install -e "."
cd examples/minigrid-LLM-assistant; python web_app_Local.py
Dual Destination
Dual Destination (Human-AI setting)
[folder]
pip install -e ".[jaxmarl]"
cd examples/dual_destination-human-AI-CEC; python web_app.py
Overcooked
Overcooked (Human-Human setting)
[folder]
pip install -e ".[jaxmarl]"
cd examples/overcooked-human-human; python web_app.py
## Other Jax environments compatible with NiceWebRL
The following are all Jax environments which can be used with this framework to run human subject experiments. The power of using jax is that one can use the **exact** same environment for human subjects experiments as for developing modern machine learning algorithms (especially reinforcement learning algorithms).
When targetting normative solutions, one may want to study algorithms asymptotic behavior with a lot of data. Jax makes it cheap to do this. NiceWebRL makes it easy to compare these algorithms to human subject behavior.
Name
Domain
Visualization
Goal
Craftax
2D Minecraft
Mine and craft resources in a Minecraft-like 2D world
Kinetix
2D Physics Control
Control rigid 2D bodies to perform dynamic tasks
Navix
MiniGrid
Navigate grid environments with JAX-based MiniGrid variant
XLand–MiniGrid
XLand
Meta-RL tasks defined by dynamic rulesets
JaxMARL
Multi-agent RL
Cooperative and competitive multi-agent environments in JAX
JaxGCRL
Goal-Conditioned Robotics
Goal-conditioned control in simulated robotics tasks
Gymnax
Classic RL
Classic control, bsuite, and MinAtar environments in JAX
Jumanji
Combinatorial
From simple games to NP-hard combinatorial problems
Pgx
Board Games
Chess, Go, Shogi, and other turn-based strategy games
Brax
Physics Simulation
Differentiable physics engine for continuous control
[](https://star-history.com/#KempnerInstitute/nicewebrl&Date)