EGG 🐣: Emergence of lanGuage in Games

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:

• Primitives for implementing a single-symbol or variable-length communication (with vanilla RNNs, GRUs, LSTMs or Transformers);
• Training with optimization of the communication channel with REINFORCE or Gumbel-Softmax relaxation via a common interface;
• Simplified configuration of the general components, such as checkpointing, optimization, tensorboard support, etc;
• Provides a simple CUDA-aware command-line tool for grid-search over parameters of the games.

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

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://[email protected]/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 [email protected]: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

• The step-by-step MNIST autoencoder tutorial goes over all essential steps to create a full-featured communication game with variable length messages between the agents. NB: depending on your computational resources, this might take a while to run! (open in colab)
• The simplest starter code is in egg/zoo/basic_games, providing implementations of basic reconstruction and discrimination games. Input can be provided through text files, and the code is thoroughly commented.
• Another good starting point to implement a Sender/Receiver game is the MNIST autoencoder game, MNIST auto-encoder game. The game features both Gumbel-Softmax and Reinforce-based implementations.
• EGG provides some utility boilerplate around commonly used command line parameters. Documentation about using it can be found here.
• A brief how-to for tensorboard is here.
• To learn more about the provided hyperparameter search tool, read this doc.
• Our paper provides a high-level view of the toolkit and points to further resources.

Citation

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

@inproceedings{Kharitonov2019Egg,
    title = "{EGG}: a toolkit for research on {E}mergence of lan{G}uage in {G}ames",
    author = "Kharitonov, Eugene  and
      Chaabouni, Rahma  and
      Bouchacourt, Diane  and
      Baroni, Marco",
    booktitle = "Proceedings of the 2019 Conference on Empirical Methods in Natural Language Processing and the 9th International Joint Conference on Natural Language Processing (EMNLP-IJCNLP): System Demonstrations",
    year = "2019",
    publisher = "Association for Computational Linguistics",
    url = "https://www.aclweb.org/anthology/D19-3010",
    doi = "10.18653/v1/D19-3010"
}

Contributing

Please read the contribution guide.

Testing

Run pytest:

python -m pytest

All tests should pass.

Licence

EGG is licensed under the MIT license. The text of the license can be found here.