Metadata-Version: 2.4
Name: hermes-toolkit
Version: 0.1.0
Summary: A toolkit for the multi-agent simulation of emergent communication and languages.
License-Expression: Apache-2.0
Project-URL: Homepage, https://gitlab.ai.vub.ac.be/ehai/hermes
Project-URL: Repository, https://gitlab.ai.vub.ac.be/ehai/hermes
Project-URL: Issues, https://gitlab.ai.vub.ac.be/ehai/hermes/-/issues
Keywords: emergent communication,language games,language evolution,multi-agent simulation,agent-based modelling
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: alive-progress
Provides-Extra: torch
Requires-Dist: torch; extra == "torch"
Provides-Extra: logging
Requires-Dist: pandas; extra == "logging"
Provides-Extra: all
Requires-Dist: torch; extra == "all"
Requires-Dist: pandas; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# HERMES

*A toolkit for the multi-agent simulation of emergent communication and languages.*

HERMES provides the building blocks for running language games: populations of
agents, worlds that supply the entities agents talk about, interaction scripts
that define who says what to whom, alignment strategies that update agents after
each interaction, and monitors that record how the emerging language develops
over time.

## Installation

```bash
pip install hermes-toolkit
```

The core framework is pure Python. Experiments with neurally grounded agents
additionally need PyTorch, and the experiment logger needs pandas:

```bash
pip install "hermes-toolkit[all]"      # torch + pandas
pip install "hermes-toolkit[torch]"    # torch only
```

The distribution is named `hermes-toolkit`, but the package is imported as
`hermes`:

```python
import hermes
from hermes.experiment import Experiment
```

## Getting started

Worked examples live in [`docs/source/tutorials`](docs/source/tutorials):

- `hermes_naming_game.ipynb` — a basic naming game
- `hermes_grounded_naming_game.ipynb` — a naming game grounded in images
- `hermes-MARL-concept-learning.ipynb` — concept learning with neural agents
- `hermes_naming_game_pyfcg.ipynb` — integration with FCG

## Core concepts

| Component | Role |
|---|---|
| `Agent` | Holds a vocabulary and whatever machinery it needs to produce and interpret utterances |
| `Population` | Determines which agents interact with one another |
| `World` | Supplies the scenes and entities agents communicate about |
| `Interaction` | The script of a single communicative exchange |
| `Process` | One participant's contribution to an interaction (describing, pointing, drawing, ...) |
| `AlignmentStrategy` | How agents update after success or failure |
| `Monitor` | Records a measure over the course of an experiment |
| `Experiment` | Ties the above together and runs series of interactions |

Experiments are configured with a dictionary; each component is given as a
`(class_name, module_name)` pair, so your own subclasses drop in without
changing the framework.

## Citation

If you use HERMES in academic work, please cite it. A `CITATION.cff` file will
be added with the first tagged release.

## Contributing

The `main` branch is protected — please create a feature branch for your
contribution and open a merge request against `main`.

## License

Apache License 2.0 — see [LICENSE](LICENSE).
