feat: Add Swarm Minefield Mapper (Dynamic Agent Role management and co-operation)

[apfine]

Description

This PR introduces the Swarm Minefield navigator, a deterministic, production-oriented spatial navigation model. It simulates a heterogeneous drone swarm (1 Leader, 3 Followers) tasked with mapping a strict 1-meter safe corridor through a dense, dynamically generated minefield under partial observability.

I built this model to establish a mathematically rigorous spatial baseline in preparation for a GSoC 2026 proposal.

Key Technical Implementations:

• Strict A Verification:* The final path extraction requires a cell and all 8 of its Moore neighbors to be explicitly scanned and safe.
• Dynamic Leadership Handoff: If the Leader drone is trapped, a Follower with better forward (Y-axis) progress automatically assumes the Leader role, triggering the swarm to rally to the new coordinates.
• Macro-Node DFS Backtracking: The Leader actively drops Checkpoints at fully safe intersections. If it detects a soft-deadlock (via a frustration timer), it retreats and explicitly paints the abandoned branch as a DEAD_END in the global mesh network.
• Airborne Regrouping: Followers utilize a distinct behavioral state to temporarily bypass ground hazards (ignoring safety buffers) when rallying to a retreating Leader.

(Note: Please see the attached GIFs/Screenshots below demonstrating the trap-escape and dynamic handoff logic.)

The swarm can be seen navigating a minefield with 450 mines in 100 X 100 grid .

You can read Readme of the project to know about all other configurations.

Motivation

The goal of this deterministic expert system is to serve as the foundation for an LLM-integration project. For GSoC, I plan to propose using the mesa-llm module to replace these hardcoded state machines (like the frustration timer and U-trap detection) with local LLM-driven spatial reasoning and semantic memory.

Checklist

• Code follows PEP8 formatting guidelines.
• Includes README.md with instructions and architecture details.
• Includes requirements.txt (only requires mesa).
• Unit tests provided in tests/test_model.py.

[apfine]

pre-commit.ci autofix

[apfine]

pre-commit.ci autofix