Add needs-based village example: homeostatic agents with competing drives

[darraghmoran2025]

What this adds

A population of villagers on a Moore grid each manage four competing homeostatic needs — HUNGER, REST, SOCIAL, and SAFETY. Each step, each villager acts on whichever need is most urgent, moving toward the relevant resource or partner and satisfying it on arrival.

This demonstrates a needs-based (drive-reduction) decision-making architecture — a distinct paradigm from both the reactive agents (Schelling, WolfSheep) and BDI deliberation examples already in the repo.

New classes

Class	Role
NeedSpec	Dataclass configuring one homeostatic need (decay rate, threshold, satisfy amount)
NeedsAgent	Abstract CellAgent subclass: need decay, urgency ordering, preemption counting
VillagerAgent	Four-need concrete agent with greedy Manhattan movement
FoodSource	Regenerating food patch (finite, competitive resource)
HomePatch	Stationary rest site
ThreatAgent	Random-walk predator; spikes SAFETY need via perception
VillageModel	OrthogonalMooreGrid, DataCollector, Solara visualisation

Architecture contrast

Property	Reactive	BDI	NeedsAgent (this PR)
Decision driver	World state	Explicit goals (pull)	Internal drives (push)
Priority source	Rule conditions	Deliberation over desires	Urgency ordering of floats
Plan horizon	Single step	Multi-step intention queue	Single next action
Interruption	N/A	Plan invalidation	Continuous preemption on priority flip

Running

pip install -r requirements.txt
solara run app.py

Test plan

• solara run app.py opens and grid renders with colour-coded villagers
• Sliders update the model on reset
• Need level chart shows oscillation between HUNGER and REST
• Setting Threats = 0 runs without error
• from needs_village import VillageModel; m = VillageModel(); m.step() runs cleanly

Note: PR #432 also explores needs-based drives, but extends the existing Wolf-Sheep model with two drives (hunger, fear) and no shared base class. This PR takes a different approach: an original scenario, four competing needs including a perception-driven SAFETY need and a mutual SOCIAL need, and a reusable abstract NeedsAgent / NeedSpec architecture that any model could subclass.

[TomRodger]

Overall, the model logic is sound and runs without errors. The architecture is genuinely interesting, the NeedSpec dataclass, and NeedsAgent abstraction are clean and reusable, and the Pain Points documentation is well written and directly useful for the Behavioural Framework project.

[TomRodger]

FoodSource is a stationary environment object that never moves after placement. The Mesa convention for stationary agents is FixedAgent, rather than CellAgent (same as GrassPatch in Mesa's built-in Sugarscape example). Using CellAgent works but semantically, it is incorrect and could affect Mesa's internal agent tracking.

[darraghmoran2025]

Thanks for the feedback. I've updated both FoodSource and
HomePatch to inherit from FixedAgent instead of CellAgent.

You're right that CellAgent worked functionally, but the
semantics were wrong — both are environment objects placed
once at initialisation and never moved, which is exactly what
FixedAgent is designed for. Using CellAgent implied they were
mobile agents, which could cause issues with Mesa's internal
agent tracking down the line.

The fix mirrors the convention used in Mesa's own Sugarscape
example (GrassPatch inherits from FixedAgent), so it aligns
with the established pattern in the framework.

[TomRodger]

Same fix as FoodSource

[TomRodger]

SolaraViz on Mesa 3.5.1 expects a model instance rather than the class. Passing VillageModel directly causes the visualisation to fail with [AttributeError: type object 'VillageModel' has no attribute 'datacollector']. Fix: you instantiate the model first and then pass it in e.g. model = VillageModel(), then pass model to SolaraViz

[darraghmoran2025]

Good catch. I've updated app.py to instantiate VillageModel before passing it to SolaraViz:

model = VillageModel()

page = SolaraViz(
model,
components=[SpaceComponent, NeedsChart, ActiveNeedChart, PreemptionChart],
model_params=model_params,
name="Needs-Based Village",
)

Passing the class directly caused the AttributeError because SolaraViz in Mesa 3.5.1 immediately tries to access instance attributes like datacollector on whatever is passed in. The
interactive sliders in model_params still work — SolaraViz handles re-instantiation when parameters change.

[TomRodger]

mesa[viz]>=3.0 is unspecific. When running the Solara visualisation in Mesa 3.5.1 it crashes with an AttributeError in mesa_signals/core.py. The model logic itself runs cleanly. Naming a specific model or stricter constraints would help improve reproducibility.

[darraghmoran2025]

Agreed. I've tightened the constraint in requirements.txt to mesa[viz]>=3.5.1,<4.0.

The >=3.0 bound was too loose — any version in the 3.x range would satisfy it, but earlier releases hit the AttributeError in mesa_signals/core.py you flagged. Pinning to >=3.5.1
targets the version the example was developed and tested against, and <4.0 guards against breaking changes in a future major release.

[TomRodger]

The NeedSpec dataclass is a clean design choice here. Keeping need configuration separate from the agent logic will make it easy for someone to extend the code, only needing to touch one place when tweaking decay rates, or adding a fifth. It also makes VillagerAgent read much cleaner as a result.

[TomRodger]

Good pain points documentation, labelling the workarounds with numbers and connecting them to specific limitations is very useful evidence for the Behavioural Framework case.

[darraghmoran2025]

Hi Tom sorry for the inactivity on my end. College has been exceptionally busy. Hopefully with exams over soon I will have more time. I have responded to all of your queries and pushed the relevant changes. Hope that is acceptable. Thank you!