Add dormant_alliances example demonstrating MetaAgent lifecycle features
- 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
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