gdm-concordia

A library for generative social simulation

https://github.com/google-deepmind/concordia

Science Score: 54.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
○
DOI references
✓
Academic publication links
Links to: arxiv.org
○
Committers with academic emails
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (15.7%) to scientific vocabulary

Keywords

agent-based-simulation generative-agents multi-agent social-simulation

Keywords from Contributors

cryptocurrencies web-crawler agents transformers embedded optim interactive multiagent-reinforcement-learning jax distributed

Last synced: 6 months ago · JSON representation ·

Repository

A library for generative social simulation

Basic Info

Host: GitHub
Owner: google-deepmind
License: apache-2.0
Language: Python
Default Branch: main
Homepage:
Size: 3.55 MB

Statistics

Stars: 1,007
Watchers: 21
Forks: 211
Open Issues: 9
Releases: 24

Topics

agent-based-simulation generative-agents multi-agent social-simulation

Created over 2 years ago · Last pushed 6 months ago

Metadata Files

Readme Changelog Contributing License Citation Security

Concordia

A library for generative social simulation

Concordia Tech Report

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

Clone Concordia:

shell git clone -b main https://github.com/google-deepmind/concordia cd concordia
Install Concordia:

shell pip install --editable .[dev]
(Optional) Test the installation:

shell pytest --pyargs concordia

Devcontainer

This project includes a pre-configured development environment (devcontainer).

You can launch a working development environment with one click, using e.g. Github Codespaces or the VSCode Containers extension.

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:

What kind of situation is this?
What kind of person am I?
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:

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.

Owner

Name: Google DeepMind
Login: google-deepmind
Kind: organization

Website: https://www.deepmind.com/
Repositories: 245
Profile: https://github.com/google-deepmind

Citation (CITATION.bib)

@misc{vezhnevets2023generative,
      title={Generative agent-based modeling with actions grounded in physical,
      social, or digital space using Concordia}, 
      author={Alexander Sasha Vezhnevets and John P. Agapiou and Avia Aharon and
      Ron Ziv and Jayd Matyas and Edgar A. Duéñez-Guzmán and
      William A. Cunningham and Simon Osindero
      and Danny Karmon and Joel Z. Leibo},
      year={2023},
      eprint={2312.03664},
      archivePrefix={arXiv},
      primaryClass={cs.AI}
}

GitHub Events

Total

Create event: 37
Release event: 11
Issues event: 22
Watch event: 309
Delete event: 22
Member event: 1
Issue comment event: 75
Push event: 236
Pull request review comment event: 8
Pull request review event: 34
Pull request event: 76
Fork event: 74

Last Year

Create event: 37
Release event: 11
Issues event: 22
Watch event: 309
Delete event: 22
Member event: 1
Issue comment event: 75
Push event: 236
Pull request review comment event: 8
Pull request review event: 34
Pull request event: 76
Fork event: 74

Committers

Last synced: 8 months ago

All Time

Total Commits: 885
Total Committers: 27
Avg Commits per committer: 32.778
Development Distribution Score (DDS): 0.581

Past Year

Commits: 574
Committers: 21
Avg Commits per committer: 27.333
Development Distribution Score (DDS): 0.608

Top Committers

Name	Email	Commits
Joel Z. Leibo	j**l@g**m	371
Sasha Vezhnevets	v**k@g**m	228
John Agapiou	j**u@g**m	156
Edgar Duéñez-Guzmán	d**z@g**m	52
dependabot[bot]	4****]	27
Wil Cunningham	3****n	10
Minsuk Chang	m**g@g**m	8
Jayd Matyas	j**s@g**m	5
Concordia Contributor	c**b@g**m	3
Logan Cross	l**s@g**m	3
Ethan Jackson	j**c@g**m	3
austinmw	a**9@g**m	3
Shifat Rahman	s**n@g**m	2
Aleksey Korshuk	4****k	1
Dennis-yxchen	9****n	1
Emmanuel Ferdman	e**n@g**m	1
Felix Janda	f**a@p**e	1
Hana Joo	h**o@g**m	1
Ikko Eltociear Ashimine	e**r@g**m	1
João Galego	j**0@g**m	1
Manuel Sebastian Rios	3****8	1
Matthew Kielo	1****3	1
Ram Rachum	r**m@r**m	1
pragmaticTNT	p**T@g**m	1
simonwisdom	s****m	1
Davide Paglieri	d**i@g**m	1
RisingOrange	j**r@p**m	1

Committer Domains (Top 20 + Academic)

google.com: 10 rachum.com: 1 posteo.de: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 36
Total pull requests: 86
Average time to close issues: about 1 month
Average time to close pull requests: 13 days
Total issue authors: 20
Total pull request authors: 18
Average comments per issue: 2.61
Average comments per pull request: 1.36
Merged pull requests: 26
Bot issues: 0
Bot pull requests: 61

Past Year

Issues: 24
Pull requests: 70
Average time to close issues: about 2 months
Average time to close pull requests: 9 days
Issue authors: 15
Pull request authors: 14
Average comments per issue: 2.79
Average comments per pull request: 1.27
Merged pull requests: 20
Bot issues: 0
Bot pull requests: 50

View more stats

Top Authors

Issue Authors

vishaljoshi24 (6)
anatoleg (6)
austinmw (4)
cth127 (4)
paehal (3)
robinsonkwame (2)
SoyGema (2)
dependabot[bot] (2)
AlekseyKorshuk (1)
Dennis-yxchen (1)
depshad (1)
mptouzel (1)
AlvinKimata (1)
ronaldzgithub (1)
alcime (1)

Pull Request Authors

dependabot[bot] (104)
wacunn (6)
austinmw (4)
AlekseyKorshuk (4)
Dennis-yxchen (3)
simonwisdom (2)
doughdemon (2)
ManuelRios18 (2)
Metrossa (2)
emmanuel-ferdman (2)
jshepp27 (2)
SoyGema (2)
RisingOrange (2)
Shifat7 (2)
vishaljoshi24 (2)

Top Labels

Issue Labels

dependencies (2) python (1) enhancement (1) github_actions (1)

Pull Request Labels

dependencies (103) github_actions (65) python (38)

Packages

Total packages: 2
Total downloads:
- pypi 2,768 last-month

Total dependent packages: 0
(may contain duplicates)
Total dependent repositories: 1
(may contain duplicates)
Total versions: 50
Total maintainers: 2

proxy.golang.org: github.com/google-deepmind/concordia

Documentation: https://pkg.go.dev/github.com/google-deepmind/concordia#section-documentation
License: apache-2.0
Latest release: v2.1.0+incompatible
published 6 months ago

Versions: 23
Dependent Packages: 0
Dependent Repositories: 0

Rankings

Dependent packages count: 6.5%

Average: 6.7%

Dependent repos count: 7.0%

Last synced: 6 months ago

pypi.org: gdm-concordia

A library for building a generative model of social interacions.

Homepage: https://github.com/google-deepmind/concordia
Documentation: https://gdm-concordia.readthedocs.io/
License: Apache 2.0
Latest release: 2.1.0
published 6 months ago

Versions: 27
Dependent Packages: 0
Dependent Repositories: 1
Downloads: 2,768 Last month

Rankings

Downloads: 8.7%

Stargazers count: 9.5%

Dependent packages count: 10.1%

Average: 12.8%

Forks count: 14.2%

Dependent repos count: 21.5%

Maintainers (2)

deepmind jagapiou

Last synced: 6 months ago

Dependencies

.github/actions/install-concordia/action.yml actions

actions/cache/restore v3 composite
actions/cache/save v3 composite
actions/setup-python 61a6322f88396a6271a6ee3565807d608ecaddd1 composite

.github/actions/install-examples/action.yml actions

./.github/actions/install-concordia * composite

.github/workflows/codeql-analysis.yml actions

actions/checkout b4ffde65f46336ab88eb53be808477a3936bae11 composite
github/codeql-action/analyze 407ffafae6a767df3e0230c3df91b6443ae8df75 composite
github/codeql-action/autobuild 407ffafae6a767df3e0230c3df91b6443ae8df75 composite
github/codeql-action/init 407ffafae6a767df3e0230c3df91b6443ae8df75 composite

.github/workflows/pylint-concordia.yml actions

./.github/actions/install-concordia * composite
actions/checkout b4ffde65f46336ab88eb53be808477a3936bae11 composite

.github/workflows/pylint-examples.yml actions

./.github/actions/install-examples * composite
actions/checkout b4ffde65f46336ab88eb53be808477a3936bae11 composite

.github/workflows/pypi-publish.yml actions

actions/checkout b4ffde65f46336ab88eb53be808477a3936bae11 composite
actions/setup-python 65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236 composite
pypa/gh-action-pypi-publish 2f6f737ca5f74c637829c0f5c3acd0e29ea5e8bf composite

.github/workflows/pypi-test.yml actions

actions/setup-python 65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236 composite

.github/workflows/pytype-concordia.yml actions

./.github/actions/install-concordia * composite
actions/checkout b4ffde65f46336ab88eb53be808477a3936bae11 composite

.github/workflows/pytype-examples.yml actions

./.github/actions/install-examples * composite
actions/checkout b4ffde65f46336ab88eb53be808477a3936bae11 composite

.github/workflows/scorecards-analysis.yml actions

actions/checkout b4ffde65f46336ab88eb53be808477a3936bae11 composite
actions/upload-artifact a8a3f3ad30e3422c9c7b888a15615d19a852ae32 composite
github/codeql-action/upload-sarif 407ffafae6a767df3e0230c3df91b6443ae8df75 composite
ossf/scorecard-action 0864cf19026789058feabb7e87baa5f140aac736 composite

.github/workflows/test-concordia.yml actions

./.github/actions/install-concordia * composite
actions/checkout b4ffde65f46336ab88eb53be808477a3936bae11 composite

.github/workflows/test-examples.yml actions

./.github/actions/install-examples * composite
actions/checkout b4ffde65f46336ab88eb53be808477a3936bae11 composite

examples/requirements.txt pypi

absl-py *
docstring-parser *
gdm-concordia *
termcolor *

pyproject.toml pypi

setup.py pypi

TODO *
absl-py *
google-cloud-aiplatform *
ipython *
matplotlib *
numpy *
openai >=1.3.0
pandas ==1.5.3
python-dateutil *
reactivex *
retry *
scipy *
tensorflow *
tensorflow-hub *
tensorflow-text *
termcolor *
typing-extensions *

gdm-concordia

Science Score: 54.0%

Keywords

Keywords from Contributors

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

Concordia

About

Installation

pip install

Manual install

Devcontainer

Bring your own LLM

Example usage

Citing Concordia

Disclaimer

Owner

Citation (CITATION.bib)

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

proxy.golang.org: github.com/google-deepmind/concordia

Rankings

pypi.org: gdm-concordia

Rankings

Maintainers (2)

Dependencies

`pip` install