examples: Add needs-based Wolf-Sheep exploring behavioral drive patterns

[DashamiJituri]

What this adds

A new example model extending Wolf-Sheep with explicit needs-based
behavioral drives (hunger, fear) instead of inline conditionals.

Motivation

While extending Wolf-Sheep to explore behavioral patterns for the
GSoC 2026 Behavioral Framework project, I noticed that all agent
decisions are checked every tick regardless of whether state changed.
This model restructures that logic using explicit drive states that
degrade over time and determine action priority.

Connection to Mesa discussions

• Behavioral Framework #2538
• Tasks / desire-based modelling #2526

Files added

• agents.py — NeedsBasedWolf and NeedsBasedSheep with CellAgent
  and drive state management
• model.py — model using OrthogonalMooreGrid and DataCollector
• README.md — explanation of behavioral difference

Testing

Runs cleanly for 100 steps. Population dynamics stable.
Mesa version: checked against current main branch.

[B2prakash]

Great to see a needs-based behavioral model — this is exactly the kind of pattern the Behavioral Framework project aims to explore.
A few thoughts after reviewing:

1. The drive-based approach is a good structural improvement over inline conditionals. Separating hunger and fear as explicit state variables that degrade over time and determine action priority makes the behavioral logic much clearer and more extensible.

2. Pre-commit CI is failing — you'll need to fix that before this can be merged. Check the failing checks to see what ruff or formatting issues need to be resolved.

3. Missing files: I don't see an app.py for SolaraViz visualization or a metadata.toml. Adding these would align with the direction discussed in Discussion #417 and #3272 for mesa-examples best practices.

4. README question: Does the README explain how the needs-based approach differs from the standard Wolf-Sheep model in terms of emergent behavior? For example, do the population dynamics change when agents prioritize fear over hunger?

5. CellAgent usage: Good to see this built on Mesa 4.0 API with OrthogonalMooreGrid and CellAgent rather than the deprecated MultiGrid.

6. GSoC checklist: I don't see the GSoC contributor checklist (context/motivation, what I learned, learning repo link, peer review). The GSoC contribution guidelines in issue #3536 require this for all GSoC PRs.

[DashamiJituri]

Great to see a needs-based behavioral model — this is exactly the kind of pattern the Behavioral Framework project aims to explore. A few thoughts after reviewing:

1. The drive-based approach is a good structural improvement over inline conditionals. Separating hunger and fear as explicit state variables that degrade over time and determine action priority makes the behavioral logic much clearer and more extensible.
2. Pre-commit CI is failing — you'll need to fix that before this can be merged. Check the failing checks to see what ruff or formatting issues need to be resolved.
3. Missing files: I don't see an app.py for SolaraViz visualization or a metadata.toml. Adding these would align with the direction discussed in Discussion Mesa-examples revival: vision & open questions #417 and #3272 for mesa-examples best practices.
4. README question: Does the README explain how the needs-based approach differs from the standard Wolf-Sheep model in terms of emergent behavior? For example, do the population dynamics change when agents prioritize fear over hunger?
5. CellAgent usage: Good to see this built on Mesa 4.0 API with OrthogonalMooreGrid and CellAgent rather than the deprecated MultiGrid.
6. GSoC checklist: I don't see the GSoC contributor checklist (context/motivation, what I learned, learning repo link, peer review). The GSoC contribution guidelines in issue #3536 require this for all GSoC PRs.

Thanks for the detailed review @B2prakash — really helpful feedback.

Here's what I've addressed:

1. Pre-commit CI — Fixed all ruff/SIM102 formatting errors. All checks passing now.
2. app.py — Added SolaraViz visualization with population plot and parameter sliders.
3. metadata.toml — Added following mesa-examples convention from Mesa-examples revival: vision & open questions #417 and #3272.
4. README — Added emergent behavior differences section. The cascade extinction from fear-suppressed eating is documented as an intentional finding — it's an emergent property of needs-based architecture that doesn't appear in standard Wolf-Sheep, which is exactly what makes this exploration relevant to #2538.
5. GSoC checklist — Adding to PR description per issue #3536.

Happy to make further changes if needed.