gabm 0.2.18

GABM is a flexible, extensible Python framework for developing agent-based models that use large language models (LLMs) as agent reasoning engines. It supports use of multiple LLM providers and implements persistent response caching.

Features

• Flexible, extensible agent-based modeling with LLMs
• Multi-provider LLM support
• Persistent response caching

API Keys

You need a data/api_key.csv file with your API keys. This file is not included in the repository for security reasons.

Create data/api_key.csv yourself in the following CSV format:

You must sign up with each LLM provider to obtain an API key:

• OpenAI: Go to platform.openai.com/signup and create an account. After logging in, visit API Keys to generate a key. Use openai as the API name.
• DeepSeek: Register at deepseek.com and follow their documentation to obtain an API key. Use deepseek as the API name.
• Gemini (Google): Go to Google AI Studio and sign in with your Google account. Create a new API key for the Gemini API. Use genai as the API name. This key is required for the new google-genai package.
• PublicAI (Apertus): Sign up at publicai.co to get your API key. Use publicai as the API name.

You can also add your Hugging Face token for downloading private or gated models:

Installation

pip install gabm

Run the Main Program

Running GABM: Example and Survey Modes

You can run GABM in different modes using a command-line argument. The default mode is the original Agent-Based Model (ABM) simulation ("example" mode). A new "survey" mode is also available, which will run a survey to change agent opinions (see below).

Run from the command line

• To run the example simulation (default):

  python3 -m gabm
  # or explicitly
  python3 -m gabm --mode example
  

• To run the survey example:

  python3 -m gabm --mode survey
  

Run using the Makefile

The Makefile provides a run-local target for convenience. You can pass arguments to the program using the ARGS variable:

• To run the example simulation (default):

  make run-local
  # or explicitly
  make run-local ARGS="--mode example"
  

• To run the survey example:

  make run-local ARGS="--mode survey"
  

When you run GABM (e.g., with python3 -m gabm), the default behavior is to execute an Agent-Based Model (ABM) simulation. Here’s what happens:

Agent Groups and Opinions

• The simulation creates three groups of agents: Negative, Positive, and Neutral.
• You can configure the number of agents in each group by editing variables at the top of the main script.
• Negative agents start with an opinion of -1.0, Positive agents with 1.0, and Neutral agents with 0.0.

Communication Rounds

• The simulation runs for several rounds (configurable).
• In each round, agents from the Negative and Positive groups communicate with randomly selected Neutral agents.
• When a Neutral agent communicates, both the Neutral agent and the other agent update their opinions to the average of their current opinions. This models opinion mixing and convergence.

Output and Visualization

• The simulation logs the state of the environment and the average opinion after each round to data/logs/run_main.log.
• After the simulation, a separate boxplot is generated for each opinion topic (negative, neutral, positive), showing the distribution of agent opinions at each round. These plots are saved as opinions_negative.png, opinions_neutral.png, and opinions_positive.png in data/output.
• The boxplots help visualize how opinions change and converge over time for each topic. You should see positive and negative opinions mix and converge, while neutral opinions may behave differently depending on the communication rules.
• The data/logs directory should contain run_main.log.

Customization

• You can change the number of agents in each group, the number of rounds, and other parameters by editing the main script.
• The random seed is set for reproducibility, so results are consistent across runs unless you change the seed.

This ABM demonstration is a starting point, it does not show how LLMs can be used in an ABM yet!

Documentation

Full documentation: https://compolis.github.io/GABM/

Acknowledgements

This project was developed with significant assistance from GitHub Copilot for code generation, refactoring, and documentation improvements.

We gratefully acknowledge support from the University of Leeds. Funding for this project comes from a UKRI Future Leaders Fellowship awarded to Professor Viktoria Spaiser (grant reference: UKRI2043).