pol-agents

pol-agents is a simulation for studying how political beliefs may shift through repeated LLM-mediated conversations on a network.

Agents start with beliefs on a topic, connect through different network topologies, and then engage in multi-turn persuasion dialogues. The simulation logs belief changes over time and can export data for both static plots and an interactive D3 dashboard.

What’s included

• A configurable agent-based simulation driven from the command line.
• Network generation for topologies such as small-world, dense, scale-free, random, and community graphs.
• Pluggable LLM providers: mock, OpenAI, Anthropic, and Ollama.
• Structured outputs for analysis and visualization.
• A browser dashboard for exploring runs interactively.

Project Layout

• main.py - CLI entry point for running simulations, generating plots, and serving the dashboard.
• config.yaml - Default simulation, agent, network, and LLM settings.
• src/agents.py - Agent state, beliefs, openness, and personality traits.
• src/network.py - Network topology generation.
• src/llm.py - LLM provider abstraction and prompt handling.
• src/conversation.py - Multi-turn conversation logic between agents.
• src/simulation.py - Main simulation loop.
• src/logging.py - CSV/JSON logging and dashboard export.
• src/visualization.py - Static matplotlib visualizations.
• dashboard/ - Interactive D3 dashboard.
• outputs/ - Generated run artifacts.

Requirements

• Python 3.10 or newer is recommended.
• An API key is only needed if you use a real LLM provider such as OpenAI or Anthropic.

Installation

Create and activate a virtual environment, then install dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

If you plan to use OpenAI or Anthropic, set the relevant environment variable before running:

export OPENAI_API_KEY=your_key_here
export ANTHROPIC_API_KEY=your_key_here

Run a Simulation

The default configuration lives in config.yaml.

python main.py run

Common overrides:

python main.py run --mock
python main.py run --network random --n 25 --topic climate_change --timesteps 100 --turns 5

Useful flags:

• --mock forces the deterministic mock LLM provider and avoids API calls.
• --network overrides the network type.
• --n overrides the number of agents.
• --topic overrides the debate topic.
• --timesteps overrides the simulation length.
• --turns overrides the number of turns per interaction.

Outputs

By default, results are written to outputs/latest/:

• simulation_data.json - Dashboard-ready data file.
• conversations.jsonl - Raw conversation log.
• belief_trajectory.csv - Time series of beliefs per agent.
• summary.json - Final run metrics.
• viz/ - Static visualization images generated by the plotting command.

The dashboard command also copies simulation_data.json into the dashboard/ directory so the browser app can load it locally.

Visualize Results

Generate static matplotlib plots from a completed run:

python main.py visualize --run-dir outputs/latest

Interactive Dashboard

Serve the dashboard locally:

python main.py dashboard --run-dir outputs/latest --port 8000

Then open the printed localhost URL in your browser.

Configuration

Edit config.yaml to change the default behavior.

• network controls topology type and network-specific parameters.
• agents controls belief initialization, openness, and personality pools.
• simulation controls timestep count, turns per interaction, and seed.
• llm controls the provider, model, temperature, and retry behavior.
• output controls where logs and plots are written.

Environment variables can be referenced in the config with ${VAR_NAME} syntax.

Notes

• The project is designed to work with mock mode out of the box.
• Real LLM providers are loaded lazily, so you only need the packages and API keys for the backend you actually use.
• The dashboard expects the JSON structure produced by simulation_data.json.