mesa / mesa/mesa-examples

Add dormant_alliances example demonstrating MetaAgent lifecycle features

Open
#459 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
252
Forks
279
Avg merge
8d 9h
Merged PRs (30d)
2

Description

## Summary
This proposes adding a new example `dormant_alliances` to demonstrate the new
MetaAgent lifecycle features being added in projectmesa/mesa#3684.

## What it models
Countries (agents) form alliances (MetaAgents). Each step, countries lose power
from attrition. When a country's power hits zero it is defeated and removed. If
an alliance loses more than half its founding members, it goes DORMANT — suspended
but not destroyed. Dormant alliances can reactivate if they recruit enough
unaffiliated countries to recover.

## Features demonstrated

| Feature | Where used |
|---|---|
| `MetaAgentState` (ACTIVE / DORMANT / DISSOLVED) | `Alliance.step()` |
| `deactivate()` | Triggered when >50% of founders are defeated |
| `activate()` | Triggered when dormant alliance recruits enough members |
| `on(signal, handler)` | Alliance registers `_on_member_defeated` |
| `emit(signal, ...)` | CountryAgent fires `"member_defeated"` on defeat |
| `cascade_step = True` | Alliance steps all members automatically |
| `to_dict()` | Used by DataCollector for structured logging |

## Files

examples/dormant_alliances/ contains __init__.py, agents.py (CountryAgent + Alliance), model.py (DormantAlliancesModel), app.py (Solara visualization), and README.md.

## Related
- Companion to projectmesa/mesa#3684

Contributor guide

Open the contributing guide

Research direction

Start with the files listed in examples/dormant_alliances/: agents.py, model.py, app.py, __init__.py, and README.md, and review projectmesa/mesa#3684 for the MetaAgent lifecycle API. Trace how CountryAgent and Alliance model defeat, dormancy, reactivation, signals, cascading steps, and structured logging. Done means the example runs, demonstrates the listed lifecycle features, and includes the Solara visualization and README.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.