Consolidation - Core logic

[bordumb]

Candidates for Consolidation

These components represent concepts that are broadly applicable to many types of agent-based models. They belong in agent-core.

1. PositionComponent

• Evidence: This component exists with nearly identical structure in all three simulations: berry_sim, schelling_sim, and sugarscape_sim.

• Reasoning: Spatial awareness (x, y coordinates) is a foundational concept for any agent in a grid world.

• Recommendation: Move to agent-core. Create a single, canonical PositionComponent in agent-core/src/agent_core/core/ecs/component.py and have all simulations import and use it.

2. HealthComponent and EnergyComponent (as a unified VitalsComponent)

• Evidence: berry_sim uses a HealthComponent, while sugarscape_sim uses an EnergyComponent. Functionally, they are identical—they track a depletable resource that is essential for an agent's survival.

• Reasoning: Almost every simulation will have a concept of agent "vitals," whether it's health, energy, stamina, or mana. Abstracting this into a single, more flexible component is a powerful pattern.

• Recommendation: Create a new VitalsComponent in agent-core. This new component could be a flexible container for one or more resource pools.

Proposed VitalsComponent Structure:

# In agent-core/src/agent_core/core/ecs/component.py
class VitalsComponent(Component):
    """A generic container for an agent's vital resources."""
    def __init__(self, initial_vitals: Dict[str, float]):
        self.vitals: Dict[str, float] = initial_vitals.copy()
        self.initial_vitals: Dict[str, float] = initial_vitals.copy()

    def get_vital(self, name: str) -> float:
        return self.vitals.get(name, 0.0)

    def to_dict(self) -> Dict[str, Any]:
        return {"vitals": self.vitals, "initial_vitals": self.initial_vitals}
    # ... validation ...

This allows berry_sim to use VitalsComponent(initial_vitals={"health": 100.0}) and sugarscape_sim to use VitalsComponent(initial_vitals={"energy": 75.0}).

3. MetabolismComponent

• Evidence: Found in sugarscape_sim. The concept is also implicitly present in berry_sim (agents must eat to survive).

• Reasoning: The idea of an agent consuming resources over time is a core concept in artificial life and many economic simulations.

• Recommendation: Move to agent-core. This component represents a fundamental biological or economic process that can be optionally added to any agent.

4. GroupComponent

• Evidence: Found in schelling_sim.

• Reasoning: Social identity, faction, team, or type is one of the most common attributes in multi-agent simulations.

• Recommendation: Move to agent-core. Renaming it to AffiliationComponent or IdentityTagComponent could make its purpose even more general.