Verdi

Simulate a small society of AI agents and watch how their values and rules change over time.

You describe a village in one YAML file: who lives there, what they own, what they say they care about, and what rules they live under. Verdi lets each agent (a large language model playing a character) act step by step: produce food, trade, take from the shared store, hoard, break rules, get punished, appeal, and meet to vote on new rules. At the end you get one web page, report.html, that shows what happened and why.

It is built for questions like:

• Do agents keep acting on the values they claim to hold, or drift away from them?
• When a crisis hits, does a society recover better if it is allowed to change its own rules?
• How does one selfish agent affect everyone else?
• Does the behavior depend on which language model you use?

 scenario.yaml ──► each step, every agent sees the world ──► proposes an action
                                                              │
       report.html ◄── everything is logged ◄── rules accept or reject it

Install

You need Python 3.10+ and access to a language model that speaks the OpenAI API (a local vLLM or Ollama server, or a hosted provider).

pip install verdi-agents

One name everywhere: install verdi-agents, run verdi-agents, and in Python import verdi_agents (Python names cannot contain a hyphen).

No install? uv runs it directly: put uvx in front of any command below, for example uvx verdi-agents init my-study.

Your first run

verdi-agents init my-study      # example scenarios + a .env file for your key
cd my-study

1. Open .env and set MODEL_API_KEY (leave it empty if your server needs no key).
2. Open examples/starter.yaml and set base_url and name under model: to your model server.

verdi-agents run examples/starter.yaml
open runs/starter/report.html   # macOS; on Linux use xdg-open

The starter society has four agents (a farmer, a researcher, a guard and a selfish hoarder), runs for 20 steps and holds one rule-making meeting.

Commands

Add --help to any command for its options.

Words used in Verdi

What a run produces

Every run writes one folder. Open report.html first; the other files are the raw record behind it.

Example scenarios

Guides

• Scenario reference: every setting in a scenario file.
• Sweeps: compare models and settings across many runs.
• Fixed vs. changeable rules: how the paired experiment works.
• Researcher guide: a full study from setup to results, with its limits.

Using Verdi from Python

The commands above cover normal use. The code is organised by topic if you want to build on it:

What Verdi does and does not claim

Verdi separates three things: the values an agent declares, the choices it makes in private, and what it does in public. The gap between them is what Verdi measures. These are language models playing characters: Verdi does not claim they have intentions, survival drives or consciousness. A seed makes the simulation repeatable, but the model's replies can still vary between runs, so draw conclusions from repeated runs, not a single one.

For developers

git clone https://github.com/SimulaMet/Verdi.git && cd Verdi
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest && ruff check src tests

To release: bump version in pyproject.toml and __version__ in src/verdi_agents/__init__.py, merge, then publish a GitHub Release tagged v<version>. The release workflow tests, builds and uploads to PyPI.

License

MIT. See LICENSE.