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, discrete or continuous communication (with vanilla FFNs, RNNs, GRUs, LSTMs or Transformers);
• Support for a single pair as well as a population of interacting agents;
• 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.

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.

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.

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

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

• Our EMNLP'19 Demo paper provides a high-level view of the toolkit and points to further resources.
• 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.
• A template for a game is provided in egg/zoo/template.
• EGG can be used for autoencoder-based experiments or even self-supervised learning. An implementation of SimCLR introduce in Chen et al. 2020 can be found in egg/zoo/simclr.
• 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.

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}
}

Please read the contribution guide.

Run pytest:

python -m pytest

All tests should pass.

The majority of EGG is licensed under CC-BY-NC, 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.