Home

Awesome

EGG 🐣: Emergence of lanGuage in Games

GitHub Python 3.6

Introduction

EGG is a toolkit that allows researchers to quickly implement multi-agent games with discrete channel communication. In such games, the agents are trained to communicate with each other and jointly solve a task. Often, the way they communicate is not explicitly determined, allowing agents to come up with their own 'language' in order to solve the task. Such setup opens a plethora of possibilities in studying emergent language and the impact of the nature of task being solved, the agents' models, etc. This subject is a vibrant area of research often considered as a prerequisite for general AI. The purpose of EGG is to offer researchers an easy and fast entry point into this research area.

EGG is based on PyTorch and provides: (a) simple, yet powerful components for implementing communication between agents, (b) a diverse set of pre-implemented games, (c) an interface to analyse the emergent communication protocols.

Key features:

To fully leverage EGG one would need at least a high-level familiarity with PyTorch. However, to get a taste of communication games without writing any code, you could try a dataset-based game, which allow you to experiment with different signaling games by simply editing input files.

List of implemented games

<details><summary>List of example and tutorial games</summary><p> </p></details> <details><summary>Games used in published work</summary><p> </p></details>

We are adding games all the time: please look at the egg/zoo directory to see what is available right now. Submit an issue if there is something you want to have implemented and included.

More details on each game's command line parameters are provided in the games' directories.

An important technical point

EGG supports Reinforce and Gumbel-Softmax optimization of the communication channel. Currently, Gumbel-Softmax-based optimization is only supported if the game loss is differentiable. The MNIST autoencoder game tutorial illustrates both Reinforce and Gumbel-Softmax channel optimization when using a differentiable game loss. The signaling game has a non-differentiable game loss, and the communication channel is optimized with Reinforce.

Installing EGG

Generally, we assume that you use PyTorch 1.1.0 or newer and Python 3.6 or newer.

  1. (optional) It is a good idea to develop in a new conda environment, e.g. like this:
    conda create --name egg36 python=3.6
    conda activate egg36
    
  2. EGG can be installed as a package to be used as a library
    pip install git+ssh://git@github.com/facebookresearch/EGG.git
    
    or via https
    pip install git+https://github.com/facebookresearch/EGG.git
    
    Alternatively, EGG can be cloned and installed in editable mode, so that the copy can be changed:
    git clone git@github.com:facebookresearch/EGG.git && cd EGG
    pip install --editable .
    
  3. Then, we can run a game, e.g. the MNIST auto-encoding game:
    python -m egg.zoo.mnist_autoenc.train --vocab=10 --n_epochs=50
    

EGG structure

The repo is organised as follows:

- tests # tests for the common components
- docs # documentation for EGG
- egg
-- core # common components: trainer, wrappers, games, utilities, ...
-- zoo  # pre-implemented games 
-- nest # a tool for hyperparameter grid search

How-to-Start and Learning more

Citation

If you find EGG useful in your research, please cite this repository:

@misc{kharitonov:etal:2021,
  author = "Kharitonov, Eugene  and Dess{\`i}, Roberto and Chaabouni, Rahma  and Bouchacourt, Diane  and Baroni, Marco",
  title = "{EGG}: a toolkit for research on {E}mergence of lan{G}uage in {G}ames",
  howpublished = {\url{https://github.com/facebookresearch/EGG}},
  year = {2021}
}

Contributing

Please read the contribution guide.

Testing

Run pytest:

python -m pytest

All tests should pass.

Licence

The majority of EGG is licensed under MIT, however portions of the project are available under separate license terms: LARC is licensed under the BSD 3-Clause license.

The text of the license for EGG can be found here.