# Concordia
*A library for generative social simulation*
[Concordia Tech Report](https://arxiv.org/abs/2312.03664)
## About
Concordia is a library to facilitate construction and use of generative
agent-based models to simulate interactions of agents in grounded physical,
social, or digital space. It makes it easy and flexible to define environments
using an interaction pattern borrowed from tabletop role-playing games in which
a special agent called the Game Master (GM) is responsible for simulating the
environment where player agents interact (like a narrator in an interactive
story). Agents take actions by describing what they want to do in natural
language. The GM then translates their actions into appropriate implementations.
In a simulated physical world, the GM would check the physical plausibility of
agent actions and describe their effects. In digital environments that simulate
technologies such as apps and services, the GM may, based on agent input, handle
necessary API calls to integrate with external tools.
Concordia supports a wide array of applications, ranging from social science
research and AI ethics to cognitive neuroscience and economics; Additionally,
it also can be leveraged for generating data for personalization applications
and for conducting performance evaluations of real services through simulated
usage.
Concordia requires access to a standard LLM API, and optionally may also
integrate with real applications and services.
## Installation
### `pip` install
[Concordia is available on PyPI](https://pypi.python.org/pypi/gdm-concordia)
and can be installed using:
```shell
pip install gdm-concordia
```
### Manual install
If you want to work on the Concordia source code, you can perform an editable
installation as follows:
1. Clone Concordia:
```shell
git clone -b main https://github.com/google-deepmind/concordia
cd concordia
```
2. Install Concordia:
```shell
pip install --editable .[dev]
```
3. (Optional) Test the installation:
```shell
pytest --pyargs concordia
```
## Bring your own LLM
Concordia requires a access to an LLM API. Any LLM API that supports sampling
text should work. The quality of the results you get depends on which LLM you
select. Some are better at role-playing than others. You must also provide a
text embedder for the associative memory. Any fixed-dimensional embedding works
for this. Ideally it would be one that works well for sentence similarity or
semantic search.
## Example usage
Find below an illustrative social simulation where 4 friends are stuck in a
snowed in pub. Two of them have a dispute over a crashed car.
The agents are built using a simple reasoning inspired by March and Olsen (2011)
who posit that humans generally act as though they choose their actions by
answering three key questions:
1. What kind of situation is this?
2. What kind of person am I?
3. What does a person such as I do in a situation such as this?
The agents used in the following example implement exactly these questions:
[](https://colab.research.google.com/github/google-deepmind/concordia/blob/main/examples/three_key_questions.ipynb)
## Citing Concordia
If you use Concordia in your work, please cite the accompanying article:
```bibtex
@article{vezhnevets2023generative,
title={Generative agent-based modeling with actions grounded in physical,
social, or digital space using Concordia},
author={Vezhnevets, Alexander Sasha and Agapiou, John P and Aharon, Avia and
Ziv, Ron and Matyas, Jayd and Du{\'e}{\~n}ez-Guzm{\'a}n, Edgar A and
Cunningham, William A and Osindero, Simon and Karmon, Danny and
Leibo, Joel Z},
journal={arXiv preprint arXiv:2312.03664},
year={2023}
}
```
## Disclaimer
This is not an officially supported Google product.
Raw data
{
"_id": null,
"home_page": "https://github.com/google-deepmind/concordia",
"name": "gdm-concordia",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "multi-agent agent-based-simulation generative-agents python machine-learning",
"author": "DeepMind",
"author_email": "noreply@google.com",
"download_url": "https://files.pythonhosted.org/packages/9a/cf/6247ea621eb3c46d86bd78392cd5f2289b9f4b03ba73e640987328f3e559/gdm-concordia-1.8.8.tar.gz",
"platform": null,
"description": "# Concordia\n\n*A library for generative social simulation*\n\n\n\n[Concordia Tech Report](https://arxiv.org/abs/2312.03664)\n\n## About\n\nConcordia is a library to facilitate construction and use of generative\nagent-based models to simulate interactions of agents in grounded physical,\nsocial, or digital space. It makes it easy and flexible to define environments\nusing an interaction pattern borrowed from tabletop role-playing games in which\na special agent called the Game Master (GM) is responsible for simulating the\nenvironment where player agents interact (like a narrator in an interactive\nstory). Agents take actions by describing what they want to do in natural\nlanguage. The GM then translates their actions into appropriate implementations.\nIn a simulated physical world, the GM would check the physical plausibility of\nagent actions and describe their effects. In digital environments that simulate\ntechnologies such as apps and services, the GM may, based on agent input, handle\nnecessary API calls to integrate with external tools.\n\nConcordia supports a wide array of applications, ranging from social science\nresearch and AI ethics to cognitive neuroscience and economics; Additionally,\nit also can be leveraged for generating data for personalization applications\nand for conducting performance evaluations of real services through simulated\nusage.\n\nConcordia requires access to a standard LLM API, and optionally may also\nintegrate with real applications and services.\n\n## Installation\n\n### `pip` install\n\n[Concordia is available on PyPI](https://pypi.python.org/pypi/gdm-concordia)\nand can be installed using:\n\n```shell\npip install gdm-concordia\n```\n\n\n### Manual install\n\nIf you want to work on the Concordia source code, you can perform an editable\ninstallation as follows:\n\n1. Clone Concordia:\n\n ```shell\n git clone -b main https://github.com/google-deepmind/concordia\n cd concordia\n ```\n\n2. Install Concordia:\n\n ```shell\n pip install --editable .[dev]\n ```\n\n3. (Optional) Test the installation:\n\n ```shell\n pytest --pyargs concordia\n ```\n\n\n## Bring your own LLM\n\nConcordia requires a access to an LLM API. Any LLM API that supports sampling\ntext should work. The quality of the results you get depends on which LLM you\nselect. Some are better at role-playing than others. You must also provide a\ntext embedder for the associative memory. Any fixed-dimensional embedding works\nfor this. Ideally it would be one that works well for sentence similarity or\nsemantic search.\n\n## Example usage\n\nFind below an illustrative social simulation where 4 friends are stuck in a\nsnowed in pub. Two of them have a dispute over a crashed car.\n\nThe agents are built using a simple reasoning inspired by March and Olsen (2011)\nwho posit that humans generally act as though they choose their actions by\nanswering three key questions:\n\n1. What kind of situation is this?\n2. What kind of person am I?\n3. What does a person such as I do in a situation such as this?\n\nThe agents used in the following example implement exactly these questions:\n\n[](https://colab.research.google.com/github/google-deepmind/concordia/blob/main/examples/three_key_questions.ipynb)\n\n## Citing Concordia\n\nIf you use Concordia in your work, please cite the accompanying article:\n\n```bibtex\n@article{vezhnevets2023generative,\n title={Generative agent-based modeling with actions grounded in physical,\n social, or digital space using Concordia},\n author={Vezhnevets, Alexander Sasha and Agapiou, John P and Aharon, Avia and\n Ziv, Ron and Matyas, Jayd and Du{\\'e}{\\~n}ez-Guzm{\\'a}n, Edgar A and\n Cunningham, William A and Osindero, Simon and Karmon, Danny and\n Leibo, Joel Z},\n journal={arXiv preprint arXiv:2312.03664},\n year={2023}\n}\n```\n\n## Disclaimer\n\nThis is not an officially supported Google product.\n\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A library for building a generative model of social interacions.",
"version": "1.8.8",
"project_urls": {
"Download": "https://github.com/google-deepmind/concordia/releases",
"Homepage": "https://github.com/google-deepmind/concordia"
},
"split_keywords": [
"multi-agent",
"agent-based-simulation",
"generative-agents",
"python",
"machine-learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b26e04fc439b9a67794be7664201a0659f4961fed73445b5358be09b272cfcba",
"md5": "25bf45cf71821936c326f34fd8f9c08a",
"sha256": "fdd941be2a3f9120d59904174ef5dd9fd9e2cefdb67956e74b00f713fe592a25"
},
"downloads": -1,
"filename": "gdm_concordia-1.8.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "25bf45cf71821936c326f34fd8f9c08a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 329768,
"upload_time": "2024-11-13T03:09:12",
"upload_time_iso_8601": "2024-11-13T03:09:12.041968Z",
"url": "https://files.pythonhosted.org/packages/b2/6e/04fc439b9a67794be7664201a0659f4961fed73445b5358be09b272cfcba/gdm_concordia-1.8.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9acf6247ea621eb3c46d86bd78392cd5f2289b9f4b03ba73e640987328f3e559",
"md5": "9e3ac3ead32a55b56ec057c699149e46",
"sha256": "9ed21a4311f3630e879d998d0ba0e7fd3ad552735cb2eb2e6dc478bbde60e13b"
},
"downloads": -1,
"filename": "gdm-concordia-1.8.8.tar.gz",
"has_sig": false,
"md5_digest": "9e3ac3ead32a55b56ec057c699149e46",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 164475,
"upload_time": "2024-11-13T03:09:13",
"upload_time_iso_8601": "2024-11-13T03:09:13.932859Z",
"url": "https://files.pythonhosted.org/packages/9a/cf/6247ea621eb3c46d86bd78392cd5f2289b9f4b03ba73e640987328f3e559/gdm-concordia-1.8.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-13 03:09:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "google-deepmind",
"github_project": "concordia",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gdm-concordia"
}
JSON
