Add: climate negotiation multi-agent LLM example

[BhoomiAgrawal12]

Summary

Adds a new LLM example under llm/climate_negotiation/, a multi-agent simulation of international climate treaty negotiations. Six country agents (USA, EU, China, India, Brazil, Russia), each driven by an LLM, negotiate on a shared emissions-reduction target over multiple rounds until a 2/3 majority treaty is reached.

References issue #454

What makes this different from existing examples

The existing mesa-examples cover classic ABM patterns (opinion dynamic, resource competition, spatial movement). This is llm/ directory that uses LLM agents for structured multi-party
negotiation and a qualitatively different use-case where:

• Agents hold persistent negotiating positions (pledge %, coalitions, acceptance state) that evolve across rounds through LLM decisions.
• There is a shared global outcome (the treaty) that emerges only when agents reach consensus and not just individual behaviour.
• Agents use targeted inter-agent communication (speak_to) and domain-specific tools rather than generic actions.

The closest existing example is deffuant_weisbuch (opinion convergence without LLMs). This model demonstrates how LLM reasoning produces qualitatively richer convergence: coalition-building, diplomatic counters, and conditional acceptance behaviours that rule-based agents cannot replicate.

Mesa-LLM features demonstrated

Feature	How it appears
STLTMemory	Short-term stores recent proposals; long-term consolidates committed positions across rounds
ReActReasoning	Agents reason about economic interests before acting
speak_to (inbuilt tool)	Targeted diplomatic messaging between specific countries
Custom @tool functions	make_proposal, accept_proposal, form_coalition, reject_and_counter
vision=-1	Full-room awareness as every agent observes all others and no spatial grid needed
DataCollector	Tracks TotalProposals, AveragePledge, LargestCoalitionSize, TreatyReached per round

Features

Two LLM hallucination failure modes are explicitly guarded:

• Phantom agent IDs in form_coalition - partner_ids are filtered against the live agent set; invalid IDs are dropped and logged as WARNING.
• Invalid proposer_id in accept_proposal - the ID is validated before recording; if wrong, an error listing valid IDs is returned to the LLM for self-correction.

Every agent's step prompt also includes an explicit VALID COUNTRY IDs block to reduce hallucination at the source.

Visualisation (Solara)

• Pledge bar chart - bars turn green when a country accepts the treaty
• Coalition status panel - live table of pledge, acceptance, coalition members
• Pledge trajectories - line chart across rounds
• Time-series plots - TotalProposals, AveragePledge, LargestCoalitionSize

Supported LLMs

Works with any LiteLLM-compatible model string. Tested with openai/gpt-4o (best emergent behaviour), gemini/gemini-2.0-flash (default), openai/gpt-4o-mini, anthropic/claude-haiku-4-5-20251001, and ollama/llama3.2.

File Structure

llm/climate_negotiation/
├── app.py # Solara visualisation entry point
├── README.md
└── climate_negotiation/
├── init.py # triggers tool registration on import
├── agents.py # CountryAgent + negotiation history helper
├── tools.py # four custom @tool negotiation functions
└── model.py # ClimateNegotiationModel + countries configs

To Try

• pip install mesa-llm mesa solara python-dotenv rich
• Set a valid API key in llm/climate_negotiation/.env
• python -m climate_negotiation.model - confirm rounds print and treaty is reached within ~6 rounds with gpt-4o
• solara run app.py - confirm all four visualisation panels render and update per round