Swarm Squad: Episode I – Surviving the Jam

A hybrid control architecture combining behavior-based formation control with LLM-powered decision making for autonomous multi-agent systems.

#Unmanned Aerial Vehicles   #Multi-agent Systems   #LLM Integration
#Behavior-based Control   #Communication-aware   #Formation Control

🔬 Research Evolution

This project builds upon our previous research in formation control and swarm intelligence:

• 🚗 Low-Level Controller: Vehicle agents equipped with behavior-based and communication-aware formation control
  
• 🤖 High-Level Controller: LLM agents processing simulation data to provide strategic guidance
  
• 🎯 Goal: Enable swarm resilience and mission completion in challenging environments with jamming/obstacles

🚀 Getting Started

It is recommended to use uv to create a virtual environment and install the following package.

uv pip install swarm-squad-ep1

To run the application, simply type:

swarm-squad-ep1
# or
swarm-squad-ep1 --help

🛠️ Development Installation

1. Clone the repository and navigate to project folder:

   git clone https://github.com/Sang-Buster/Swarm-Squad-Ep1
   cd Swarm-Squad-Ep1

2. Install uv first:

   # macOS/Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh

   # Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Install the required packages: Option 1 (recommended): Synchronizes environment with dependencies in pyproject.toml and uv.lock

   uv sync
   source .venv/bin/activate # .venv\Scripts\activate for Windows

   Option 2 (manual): Manual editable installation without referencing lockfile

   uv venv --python 3.10 # Create virtual environment
   source .venv/bin/activate # .venv\Scripts\activate for Windows
   uv pip install -e .

👨‍💻 Development Setup

1. Install git hooks:

   pre-commit install --install-hooks

   These hooks perform different checks at various stages:

   • commit-msg: Ensures commit messages follow the conventional format
   • pre-commit: Runs Ruff linting and formatting checks before each commit
   • pre-push: Performs final validation before pushing to remote

2. Code Linting & Formatting:

   ruff check --fix
   ruff check --select I --fix
   ruff format

3. Run the application:

   uv run src/swarm_squad_ep1/main.py

📁 File Tree

📂Swarm-Squad-Ep1
 ┣ 📂lib                              // Supplementary materials
 ┃ ┣ 📂img                                // Readme Assets
 ┃ ┣ 📂old                                // Original old code
 ┃ ┣ 📄demo.mp4                           // Demo Video
 ┃ ┣ 📄paper.pdf                          // Paper
 ┃ ┗ 📄ppt.pdf                            // Presentation
 ┣ 📂logs                             // SimulationLogs
 ┣ 📂src                              // Source Code
 ┃ ┗ 📦swarm_squad_ep1                    // Python package
 ┃ ┃ ┣ 📂controllers                         // Controllers for swarm behavior
 ┃ ┃ ┃ ┣ 📄base_controller.py                   // Base controller interface
 ┃ ┃ ┃ ┣ 📄behavior_controller.py               // Behavior-based controller
 ┃ ┃ ┃ ┣ 📄controller_factory.py                // Controller management system
 ┃ ┃ ┃ ┣ 📄formation_controller.py              // Formation control
 ┃ ┃ ┃ ┗ 📄llm_controller.py                    // LLM controller
 ┃ ┃ ┣ 📂gui                                 // GUI components
 ┃ ┃ ┃ ┗ 📄formation_control_gui.py             // GUI application
 ┃ ┃ ┣ 📂models                              // Model components
 ┃ ┃ ┃ ┗ 📄swarm_state.py                       // Swarm state management
 ┃ ┃ ┣ 📂tests                               // Test cases
 ┃ ┃ ┃ ┗ 📄test_ollama.py                       // Test for Ollama
 ┃ ┃ ┣ 📄config.py                           // Configuration parameters
 ┃ ┃ ┣ 📄main.py                             // Entry point
 ┃ ┃ ┣ 📄utils.py                            // Core utility functions
 ┃ ┃ ┗ 📄visualization.py                    // Visualization functions
 ┣ 📄.gitignore
 ┣ 📄.pre-commit-config.yaml
 ┣ 📄.python-version
 ┣ 📄LICENSE
 ┣ 📄README.md
 ┣ 📄pyproject.toml
 ┗ 📄uv.lock