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.

[tpike3]

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.

@quaquel Sorry for the delay, I was visiting some family over the holiday

However, I made a bunch of updates to ideally allow more user options. Below I walk through each one, and I think that address your points you outline excepted for function to method, which I will change probably tomorrow since we are getting weather.

First - Based on @EwoutH comments I created MetaAgents as stand alone, this allows users to explicitly create meta_agents of the desired type.

Example use case I am thinking is an autonomous systems in a warehouse. So it has parts like wheels, FLIR sensors, computer etc, now it can have a meta agent that calls the unique attributes and methods of each of its subagents.

Second - I added multi-level agents as a stand alone and separate function. This is like the alliance formation and dynamically adds new agent classes MetaAgents at increasing hierarchies.

I also added the use of itertools.combinations and associated functions, but I still locked down the multi-level agents just because of the exponential growth of combinatorics. Going above into higher numbers of combinations (e.g. combinations of 10 vs 2), quickly overwhelms the model

Example use case is the provided example which is a more pure instantiation of the bilateral shapely value, but to your point an individual agent may now join a level 3 agent as it position changed. This, however, would be dependent on the example model but the multi_level agent code does allow for it by changing the logical of the multi-level alliance formation model.

Finally multi-level agents does allow for adding the sub agents attributes and methods. The thought behind this is unlike the first example that is explicit, this can allow for recombination and emergent agents.

Example use case and just to keep with with alliance: I once did a tribal affiliation model of the Libyan civil war. In this case some tribes may be coming with control of road networks and certain attributes and methods for dealing with that, while another tribe may come with control of oil fields and likewise have unique functions and attributes, this would allow for a singular agent who has leaders managing both assets as well as subgroups managing their respective territory. I concede this is an arguable feature.

The hard question to me, which ideally by dabbling in this unique and difficult landscape will help inspire the community to explore, is how one can assess how well the groups have coalesced together and what is their chances for descending into infighting and how do you manage that computationally. In one sense this expands experimental to not only do great Mesa improvements (like agentset, propertylayer, continuous space etc) but also to try some novel and questionable features to ideally get a larger community to explore the space and push the whole ABM field forward.

Let me know what you think. Thanks again for the review!

In the end I really only did an example 2 but in future pull requests could add examples for 1 and 3.

Let me know what you think.

[tpike3]

@quaquel and @EwoutH ready for review

[EwoutH]

Sorry for the delay, I was visiting some family over the holiday

Let’s stop apologizing for this stuff, we’re all doing this in our free time. Thanks for working on it!

I will try to review the ContiniousSpace soon, and then the PR hopefully later this week.

Exciting to have so much serious work going on!