examples: Add needs-based Wolf-Sheep for behavioral framework exploration

Author: DashamiJituri

examples/needs_based_wolf_sheep/README.md

@@ -0,0 +1,44 @@
+# Needs-Based Wolf-Sheep
+
+An extension of the classic Wolf-Sheep predation model that
+explores **needs-based behavioral architecture** from Mesa
+discussion [#2538](https://github.com/projectmesa/mesa/discussions/2538).
+
+## What's different from standard Wolf-Sheep
+
+In the standard model, every agent checks all conditions every
+tick — energy thresholds, reproduction probability, nearby prey —
+regardless of whether anything changed.
+
+This model restructures that logic using **explicit internal drive
+states** that degrade over time and determine action priority:
+
+| Drive | Agent | Behaviour when urgent |
+|-------|-------|-----------------------|
+| `hunger` | Wolf, Sheep | Prioritise eating |
+| `fear` | Sheep | Suppress eating, flee |
+
+## Key behavioral difference
+```python
+# Standard Wolf-Sheep — all checked every tick
+if self.energy > 20:
+    if random() < p_reproduce:
+        self.reproduce()
+
+# Needs-based — action only fires when drive is urgent
+if self.hunger > 0.6:     # only when actually hungry
+    self._eat_nearest_prey()
+```
+
+## Connection to Mesa discussions
+
+- [#2538 Behavioral Framework](https://github.com/projectmesa/mesa/discussions/2538)
+  — State system, drive-based decision making
+- [#2526 Tasks](https://github.com/projectmesa/mesa/discussions/2526)
+  — Desire-based modelling, internal states
+
+## Running the model
+```bash
+pip install mesa
+python model.py
+```

examples/needs_based_wolf_sheep/agents.py

@@ -0,0 +1,85 @@
+import mesa
+from mesa.discrete_space import CellAgent
+
+
+class NeedsBasedAnimal(CellAgent):
+    """Base class with explicit internal drive states.
+    Connects to Mesa discussion #2538 State Management component.
+    """
+
+    def __init__(self, model, energy):
+        super().__init__(model)
+        self.energy = energy
+        self.hunger = 0.0
+        self.fear = 0.0
+
+    def update_drives(self):
+        self.hunger = min(1.0, self.hunger + 0.08)
+        self.fear = max(0.0, self.fear - 0.1)
+
+    def move(self):
+        self.cell = self.random.choice(
+            list(self.cell.connections.values())
+        )
+
+
+class NeedsBasedWolf(NeedsBasedAnimal):
+
+    def step(self):
+        self.move()
+        self.energy -= 1
+        self.update_drives()
+
+        if self.energy <= 0:
+            self.remove()
+            return
+
+        if self.hunger > 0.6:
+            sheep = [
+                a for a in self.cell.agents
+                if isinstance(a, NeedsBasedSheep)
+            ]
+            if sheep:
+                prey = self.random.choice(sheep)
+                self.energy += 4
+                self.hunger = 0.0
+                prey.remove()
+                return
+
+        if (self.energy > 20 and self.fear < 0.3
+                and self.hunger < 0.4):
+            if self.random.random() < self.model.wolf_reproduce:
+                self.energy //= 2
+                NeedsBasedWolf(self.model, self.energy)
+
+
+class NeedsBasedSheep(NeedsBasedAnimal):
+
+    def step(self):
+        self.move()
+        self.energy -= 1
+        self.update_drives()
+
+        wolves_nearby = sum(
+            1 for a in self.cell.agents
+            if isinstance(a, NeedsBasedWolf)
+        )
+        if wolves_nearby > 0:
+            self.fear = min(1.0, self.fear + 0.5)
+
+        if self.energy <= 0:
+            self.remove()
+            return
+
+        if self.hunger > 0.5 and self.fear < 0.7:
+            if self.cell.grass:
+                self.energy += 4
+                self.hunger = 0.0
+                self.cell.grass = False
+                return
+
+        if (self.energy > 6 and self.fear < 0.2
+                and self.hunger < 0.3):
+            if self.random.random() < self.model.sheep_reproduce:
+                self.energy //= 2
+                NeedsBasedSheep(self.model, self.energy)

examples/needs_based_wolf_sheep/model.py

@@ -0,0 +1,86 @@
+import mesa
+from mesa.discrete_space import OrthogonalMooreGrid
+from agents import NeedsBasedWolf, NeedsBasedSheep
+
+
+class GrassPatch(mesa.Agent):
+    def __init__(self, model, fully_grown):
+        super().__init__(model)
+        self.grass = fully_grown
+
+    def step(self):
+        if not self.grass:
+            if self.random.random() < self.model.grass_regrowth_rate:
+                self.grass = True
+
+
+class NeedsBasedWolfSheep(mesa.Model):
+    """Wolf-Sheep with needs-based behavioral drives.
+    Explores behavioral framework patterns from #2538 and #2526.
+    """
+
+    def __init__(
+        self,
+        width=20,
+        height=20,
+        initial_sheep=100,
+        initial_wolves=25,
+        sheep_reproduce=0.04,
+        wolf_reproduce=0.05,
+        grass_regrowth_rate=0.03,
+        rng=None,
+    ):
+        super().__init__(rng=rng)
+        self.sheep_reproduce = sheep_reproduce
+        self.wolf_reproduce = wolf_reproduce
+        self.grass_regrowth_rate = grass_regrowth_rate
+
+        self.grid = OrthogonalMooreGrid(
+            (width, height), torus=True, capacity=None,
+            random=self.random
+        )
+
+        # Place grass patches
+        for cell in self.grid.all_cells:
+            patch = GrassPatch(self, self.random.random() < 0.5)
+            patch.cell = cell
+
+        # Place sheep
+        for _ in range(initial_sheep):
+            cell = self.grid.all_cells.select_random_cell()
+            sheep = NeedsBasedSheep(self, self.random.randint(1, 6))
+            sheep.cell = cell
+
+        # Place wolves
+        for _ in range(initial_wolves):
+            cell = self.grid.all_cells.select_random_cell()
+            wolf = NeedsBasedWolf(self, self.random.randint(5, 15))
+            wolf.cell = cell
+
+        self.datacollector = mesa.DataCollector(
+            model_reporters={
+                "Wolves": lambda m: len(
+                    m.agents_by_type[NeedsBasedWolf]
+                ),
+                "Sheep": lambda m: len(
+                    m.agents_by_type[NeedsBasedSheep]
+                ),
+            }
+        )
+
+    def step(self):
+        self.agents.shuffle_do("step")
+        self.datacollector.collect(self)
+
+
+if __name__ == "__main__":
+    model = NeedsBasedWolfSheep()
+    for i in range(100):
+        model.step()
+        data = model.datacollector.get_model_vars_dataframe()
+        print(
+            f"Step {i+1:3d}: "
+            f"Wolves={int(data['Wolves'].iloc[-1]):3d}, "
+            f"Sheep={int(data['Sheep'].iloc[-1]):3d}"
+        )
+    print("Done — model ran 100 steps successfully.")

examples/needs_based_wolf_sheep/requirements.txt

@@ -0,0 +1 @@
+mesa