Add hierarchical organization meta-agent example (Mesa 3.x compatible)

[BittuAgarwal1237]

Overview

This example implements a three-level agent hierarchy:
Employees → Departments → Organization
The model avoids legacy scheduler APIs and instead uses explicit activation ordering to remain fully compatible with Mesa 3.x and future versions.

Motive

While working with mesa-examples in a clean environment, I noticed that:
Legacy scheduler usage is no longer applicable in Mesa 3.x
Activation semantics are not consistently illustrated
Visualization dependencies can be implicit
There are few examples demonstrating hierarchical/meta-agent patterns

This model aims to provide a clear, modern reference implementation for:
Explicit hierarchical activation
Meta-agent structuring
Solara-based visualization
Reproducible dependency declaration

Model Features

Hierarchical meta-agent structure
Adaptive performance threshold (scales with department size)
Damped workload adjustment (prevents oscillatory instability)
Additive policy intervention (avoids exponential morale growth)
External shock events with bounded impact
Workload clamping for stability
Parameter sliders for experimentation
Mesa 3.x compatible architecture

Stability Improvements (Compared to Initial Prototype)

The current version includes:
Damped feedback instead of abrupt threshold reactions
Additive (not multiplicative) policy adjustments
Bounded morale and workload dynamics
Controlled shock intensity
Adaptive performance targets
These changes were made to improve interpretability and prevent runaway oscillations.

Tested With

Mesa 3.3.x
Python 3.11

Happy to adjust structure, naming, or conventions based on maintainer feedback. Happy to learn from you.
Looking forward to your thoughts.

[tpike3]

The write up on this is overly AI generated heavy.

Meta-agents never existed in Mesa 2, so the Mesa 3 syntax focus is irrelevant.

What is the actual purpose of the model?
What is the model trying to show?
Why do meta-agents matter in this model?
What is the purpose of the "shock"?

[BittuAgarwal1237]

Hey @tpike3 , thanks for the feedback — fair points, let me answer each one.

1. The purpose of the model is to show how agents at different levels of a hierarchy depend on and influence each other. Employees affect departments, departments affect the organization, and the organization's response feeds back down to employees. The idea was to make that chain of dependency visible and explicit rather than just having a flat list of agents doing things independently.

2. What it's trying to show is that behavior in a structured system isn't just the sum of individual actions, it emerges from how each level responds to the one below it. When an employee's morale drops, it doesn't just affect their output in isolation, it ripples upward and eventually triggers a policy response that touches everyone. That feedback loop is what the model is really demonstrating.

3. The reason meta-agents matter here is that departments and the organization don't produce anything themselves, they only exist to observe and adjust. That's the whole point of making them agents rather than just functions. They have their own state, their own step, and they act based on what they see below them. Without that structure it would just be employees running in a loop with no real hierarchy.

4. The shock was added to stress-test the system. A hierarchy that only works under normal conditions isn't very interesting. The shock drops morale across all employees suddenly and forces the department and organization layers to actually do something meaningful, you can watch in the chart whether the system recovers or spirals. That's where the hierarchical feedback loops either prove themselves or don't.

Happy to address any other questions, fix anything that needs changing, or add features if that would help , just let me know. i will be happy .

[tpike3]

Hey @tpike3 , thanks for the feedback — fair points, let me answer each one.

1. The purpose of the model is to show how agents at different levels of a hierarchy depend on and influence each other. Employees affect departments, departments affect the organization, and the organization's response feeds back down to employees. The idea was to make that chain of dependency visible and explicit rather than just having a flat list of agents doing things independently.
2. What it's trying to show is that behavior in a structured system isn't just the sum of individual actions, it emerges from how each level responds to the one below it. When an employee's morale drops, it doesn't just affect their output in isolation, it ripples upward and eventually triggers a policy response that touches everyone. That feedback loop is what the model is really demonstrating.
3. The reason meta-agents matter here is that departments and the organization don't produce anything themselves, they only exist to observe and adjust. That's the whole point of making them agents rather than just functions. They have their own state, their own step, and they act based on what they see below them. Without that structure it would just be employees running in a loop with no real hierarchy.
4. The shock was added to stress-test the system. A hierarchy that only works under normal conditions isn't very interesting. The shock drops morale across all employees suddenly and forces the department and organization layers to actually do something meaningful, you can watch in the chart whether the system recovers or spirals. That's where the hierarchical feedback loops either prove themselves or don't.

Happy to address any other questions, fix anything that needs changing, or add features if that would help , just let me know. i will be happy .

@BittuAgarwal1237 Apologies I should have been more explicit, your readme should capture these ideas about the model. I would also get rid of the requirements.txt. All the requirement can be met with pip install mesa[rec] which can be annotated in the read. Also please update the repos README which has the menu of examples.

[BittuAgarwal1237]

Done! Removed requirements.txt, updated the README with pip install mesa[rec] and added the model to the repo index. Let me know if anything else needs changing. @tpike3

Also working on a SEIR epidemic model with a vaccination policy meta-agent as a follow-up contribution , will open a separate PR soon.

[BittuAgarwal1237]

@tpike3 can you also see the issue #350 . it will be very helpful for me :)