Meta agents

[tpike3]

Summary

This PR is useful for creating meta-agents that represent groups of agents with interdependent characteristics.

New meta-agent classes are created dynamically using the provided name, attributes and functions of sub agents, and unique attributes and functions.

supersedes #2561

Motive

This method is for dynamically creating new agents (meta-agents).

Meta-agents are defined as agents composed of existing agents.

Meta-agents are created dynamically with a pointer to the model, name of the meta-agent,
iterable of agents to belong to the new meta-agents, any new functions for the meta-agent,
any new attributes for the meta-agent, whether to retain sub-agent functions,
whether to retain sub-agent attributes.

Examples of meta-agents:

• An autonomous car where the subagents are the wheels, sensors,
  battery, computer etc. and the meta-agent is the car itself.
• A company where the subagents are employees, departments, buildings, etc.
• A city where the subagents are people, buildings, streets, etc.

Currently meta-agents are restricted to one parent agent for each subagent/
one meta-agent per subagent.

Goal is to assess usage and expand functionality.

Implementation

Method has three paths of execution:

1. Add agents to existing metaagent
2. Create new meta-agent instance of existing metaagent class
3. Create new meta-agent class

Added meta_agents.py in experimental
Added tests in test-agent.py
Added alliance formation model in basic examples

Usage Examples

I added a basic example of alliance formation using the bilateral shapley value

Step 0- 50 Agents:

Step 8 - 17 Agents of increasing hierarchy added dynamically during code execution:

Additional Notes

Currently restricted to one parent agent and one meta-agent per agent. Goal is to assess usage and expand functionality.

[github-actions]

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 -3.6% [-5.2%, -1.9%]	🔵 +0.4% [+0.3%, +0.6%]
BoltzmannWealth	large	🔵 -0.2% [-1.7%, +0.7%]	🔵 -0.3% [-0.6%, +0.1%]
Schelling	small	🔵 -0.2% [-0.4%, +0.1%]	🔵 +0.1% [+0.0%, +0.2%]
Schelling	large	🔵 +0.1% [-0.3%, +0.5%]	🔵 -0.4% [-0.9%, +0.1%]
WolfSheep	small	🔵 +0.5% [+0.0%, +1.0%]	🔵 -1.4% [-6.2%, +3.6%]
WolfSheep	large	🔵 +0.8% [-0.4%, +1.6%]	🔵 -1.6% [-2.6%, -0.7%]
BoidFlockers	small	🔵 +1.3% [+0.9%, +1.9%]	🔵 -0.6% [-1.4%, +0.2%]
BoidFlockers	large	🔵 +1.8% [+0.8%, +2.7%]	🔵 -0.5% [-1.1%, +0.1%]

[EwoutH]

Did you consider incorporating the AgentSet into Meta-agents one way or another (inheritance, composition or otherwise)?

[tpike3]

Did you consider incorporating the AgentSet into Meta-agents one way or another (inheritance, composition or otherwise)?

I did, however just to get meta-agents started and integrated I avoided it since it will add a layer of complications and I was worried about collisions and MRO issues -- Ways forward in no particular order are add AgentSet so each meta-agent has the AgentSet functionality, integrate threading so meta-agents can be on their own thread in 3.13 forward, allow for greater combinatorics (e.g. agents can be in multiple meta-agents)

[EwoutH]

Cool, I will try to dive in and do a proper review tomorrow or Monday.

[jackiekazil]

I am playing catch-up on this. This is interesting. I do not have strong opinions on the setup, and I feel like @EwoutH and @quaquel have it covered.

Question for everyone regarding adding an example in the core examples folder: If memory serves me correctly -- we were adamant about only having five examples with ones that build off of those for maintenance purposes. In what cases do we justify an additional example to the core folder as opposed to the examples folder? (I ask because our original examples folder grew to the maintenance issue that it is because we were trying to demonstrate all the functionality we had in at least one location).

[tpike3]

I am playing catch-up on this. This is interesting. I do not have strong opinions on the setup, and I feel like @EwoutH and @quaquel have it covered.

Question for everyone regarding adding an example in the core examples folder: If memory serves me correctly -- we were adamant about only having five examples with ones that build off of those for maintenance purposes. In what cases do we justify an additional example to the core folder as opposed to the examples folder? (I ask because our original examples folder grew to the maintenance issue that it is because we were trying to demonstrate all the functionality we had in at least one location).

Well clearly I am going to have a bias on this, however, I did consider the challenge of an excess of core examples and the reason I built in basic examples as an exception is because as far I know this would be a unique capability of Mesa compared to NetLogo, MASON etc. Putting it in the basic examples would make it more prominent and easier for users to see, ideally further increasing Mesa's competitiveness as the ABM library of choice.

A second option would be putting it in mesa-examples and then adding some documentation in getting started.

Or I could just put it in Mesa-examples.

I am good with whatever the group decides, just let me know.

[EwoutH]

Let's focus on the functionality first and then work out the details on the examples.

[quaquel]

For various experimental features, I added some examples into the folder with the new experimental code. Once the API started to stabilize, I removed those examples. That might be a good middle ground here as well. The example helps clarify the experimental feature.

[EwoutH]

I have some initial thoughts, mainly on the conceptual and API design.

Our AgentSet provides already a lot of the capabilities needed by MetaAgents, so I would think as a MetaAgents as an AgentSet that can also perform things on their own. This would allow us to leverage existing functionality while making the API more consistent and intuitive.

Here's how we could redesign this:

class MetaAgent(mesa.Agent):
    """An agent that is composed of other agents and can act as a unit."""
    
    def __init__(self, model, components=None):
        super().__init__(model)
        # Use AgentSet to manage components - inheriting all its powerful features
        self._components = AgentSet(components or [], random=model.random)
        
    @property
    def components(self):
        """Read-only access to components as an AgentSet."""
        return self._components

    # Component management
    def add_component(self, agent):
        self._components.add(agent)
        
    def remove_component(self, agent):
        self._components.discard(agent)

This gives us several benefits:

1. All AgentSet methods (select, sort, do, map, agg, etc.) are available on the components
2. Consistent with how Mesa already manages agents
3. Automatic handling of weak references and agent lifecycle
4. Easy aggregation of component properties

For example, here's how your alliance formation could look using this approach:

class Alliance(MetaAgent):
    def __init__(self, model, components=None):
        super().__init__(model, components)
        # Compute alliance properties from components using AgentSet methods
        self.power = self.components.agg("power", sum) * 1.1  # With synergy bonus
        self.position = self.components.agg("position", np.mean)
        
    @classmethod
    def evaluate_potential(cls, agents: AgentSet) -> float:
        """Evaluate if these agents would make a good alliance using AgentSet methods."""
        total_power = agents.agg("power", sum)
        positions = agents.get("position")
        position_spread = max(positions) - min(positions)
        return total_power * (1 - position_spread)

We could even add some convenience methods to AgentSet to support meta-agent operations:

class AgentSet:
    def to_meta_agent(self, meta_agent_class, **kwargs):
        """Convert this AgentSet into a MetaAgent of the specified class."""
        return meta_agent_class(self.model, components=self, **kwargs)
    
    def find_combinations(self, size_range=(2,5), evaluation_func=None, min_value=None):
        """Find valuable combinations of agents in this set."""
        combinations = []
        for size in range(*size_range):
            for candidate_group in itertools.combinations(self, size):
                group_set = AgentSet(candidate_group, random=self.random)
                if evaluation_func:
                    value = evaluation_func(group_set)
                    if min_value is None or value >= min_value:
                        combinations.append((group_set, value))
        return combinations

Then alliance formation becomes very natural:

def step(self):
    # Find potential alliances among base agents
    base_agents = self.agents.select(agent_type=BaseAgent)
    potential_alliances = base_agents.find_combinations(
        evaluation_func=Alliance.evaluate_potential,
        min_value=10
    )
    
    # Form some alliances
    for agents, value in potential_alliances:
        if self.random.random() < 0.3:  # Some formation probability
            alliance = agents.to_meta_agent(Alliance)

Some open questions to consider:

1. Should we allow agents to be part of multiple meta-agents? The current PR restricts this but it might be unnecessarily limiting.
2. How should we handle property updates when components change? Should meta-agents recompute their properties automatically?
3. Should we add specific support in the Model class for tracking meta-agents separately from base agents?

I think this approach would make the feature more intuitive and maintainable while preserving all the functionality of the current implementation. It would also make it easier to extend with new capabilities in the future.

What do you think about moving in this direction? Happy to elaborate on any of these points.

Edit: I can also help with the implementation if you'd like.

[quaquel]

Just some quick thoughts:

1. I agree with @EwoutH suggestion to use composition. So let MetaAgent extend Agent, and let it have an AgentSet attribute. Not sure about the components label. Since it is a MetaAgent, something like constituting_agents would be better (but is too long). components to me is to vague. Likewise, I would simplify add_component to add_agent etc. Also, you can just do self.random instead of model.random.
2. I don't think the default MetaAgent class should make a choice on how to handle property updates. This is very case-specific. With the sketched functionality, you can do whatever you want in your own custom subclass.
3. There is no need for extra support in Model, since you can just use agents_by_type to get the MetaAgent instances.
4. I would not add meta agent specific methods to AgentSet to create MetaAgents. First, MetaAgent is still experimental. Second, in my view, it violates the separation of concern. If you want something like that, it might make more sense to a factory method to MetaAgent, so you can do MetaAgent.from_agentset.

[tpike3]

Thanks @EwoutH and @quaquel I appreciate the time you are spending on this, which came out unexpectedly.

So for expanding the MetaAgent to have AgentSet, that works for me. On the attribute name maybe nodes or subagents, but I am not sure I like any of those. I have no disagreements with any of @quaquel other concerns.

For practical way forward:
@EwoutH I believe code is sharing knowledge and ideas so feel free to edit my PR as you see fit or improve it in a new better PR. My only concern is how are you passing new meta agent functions or making a sub agent function now the meta-agent function?

There is some more nuance to the bilateral shapley value where you do not want to do mass aggregation and strictly speaking I am not doing it exactly right, but that is off topic. However, it leads to the larger conceptualization of meta-agents, which you can read or not at your leisure.

For less practical off the top of my head considerations
How do we deal with the diversity of use cases:

• One use would be similar to the alliance formation, where user wants the meta-agent to have the alliance formation function on its own so it can use its meta attributes to assess formation with other metaagents, which to keep it clean means it needs its own version of the function.
• Another path would be like the smart car example where different parts, at the desired level of granularity, would have their attributes and functions, FLIR sensor, turning mechanism, battery etc but the car metaagent would have functions to manage and control the subcomponents.
• Stretch goal would be at some point we would add the functionality for the subcomponents to create emergent functions from the constituent parts, thinking with RL and generative AI right now

Let me know you thoughts.

[EwoutH]

@tpike3 I created an initial implementation on the meta_agents_2 branch in EwoutH@377fb3d. If you want, you can continue from there (or use part of it, whatever works for you).

[tpike3]

@classmethod

Thanks @EwoutH! -- merging the code right now and yaaa I should have totally integrated AgentSet from the beginning

[tpike3]

Status Update

So I realized we are looking at the problem in different not necessarily mutually exclusive ways. So what I am working on is this---

From @EwoutH a base MetaAgent optimizes use of AgentSet

From me the ability to dynamically create multiple agent types

Things to do --

• update syntax to dynamically create agent types
• update tests
• add single level alliance formation model

Let me more if you have more thoughts

[quaquel]

I finally had time to take another look at this. Based on #2538, my understanding is that meta agents are composed of agents and have their own behavior and state which might be based on the behavior and state of its constituting agents. I think the ideas here are very interesting, but also hard to get right (which is why I don't know of any other ABM library that has something similar).

I am, however, a bit confused, about create_multi_levels.

First, add_attributes wil just add the value of the last agent in agents. See the code below. If you have multiple agents of the same type, meta_attributes[name] = value will just refer to the value of the last agent in agent, so what's the point of this?

if retain_subagent_attributes:
    for agent in agents:
        for name, value in agent.__dict__.items():
            if not callable(value):
                meta_attributes[name] = value

for key, value in meta_attributes.items():
    setattr(meta_agent_instance, key, value)

Second, add_functions. As an aside, this inner function is misnamed, and should be add_methods. Basically, this dynamically adds all methods from the constituting agents to the MetaAgent. Again, I am not sure about the conceptual motivation for this. Take the alliance example, the alliance has behavior that is uniquely its own but is collective over the alliance members. Second, it might trigger specific behavior in the alliance members. Now, some behavior might indeed be shared. E.g., individual agents can form into an alliance and alliances can form into larger alliances. Although, I would argue that the way in which an individual agent agrees to join an alliance is different from how an existing alliance agrees to join into a larger alliance. In the first case, the individual can decide itself, in the second case either all individual members decide themselves, or there is some voting procedure. Regardless, the logic of the behavior is not the same for individuals and for groups.