swarm-squad-ep1 0.1.5

Swarm Squad Ep1: Surviving the jam

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

Supplementary Materials

Paper	Presentation

🚀 Getting Started

Get uv and create a virtual environment.

uv venv --python 3.10
source .venv/bin/activate
uv pip install swarm-squad-ep1

To run the application, simply type:

swarm-squad

🛠️ 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. Create a virtual environment:

   uv venv
   

4. Activate the virtual environment:

   # macOS/Linux
   source .venv/bin/activate
   

   # Windows
   .venv\Scripts\activate
   

5. Install the required packages:

   uv pip install -e .
   

👨‍💻 Development Setup

1. Install ruff and pre-commit:

   uv pip install ruff pre-commit
   

   • ruff is a super fast Python linter and formatter.
   • pre-commit helps maintain code quality by running automated checks before commits are made.

2. Install git hooks:

   pre-commit install --hook-type commit-msg --hook-type pre-commit --hook-type pre-push
   

   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

3. Code Linting:

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

4. Run the application:

   uv run src/main.py
   

📁 File Tree

 📂Swarm-Squad-Ep1
 ┣ 📂lib                                  // Supplementary materials
 ┃ ┣ 📂img                                   // Readme Assets
 ┃ ┗ 📂old                                   // Original old code
 ┣ 📂src
 ┃ ┣ 📦Swarm-Squad-Ep1                   // Source Code
 ┃ ┃ ┣ 📄main.py                            // Entry point
 ┃ ┃ ┣ 📄config.py                          // Configuration parameters
 ┃ ┃ ┣ 📄utils.py                           // Core utility functions
 ┃ ┃ ┣ 📄visualization.py                   // Visualization functions
 ┃ ┃ ┣ 📂models                         // Model components
 ┃ ┃ ┃ ┗ 📄swarm_state.py                   // Swarm state management
 ┃ ┃ ┣ 📂controllers                    // Controllers for swarm behavior
 ┃ ┃ ┃ ┣ 📄base_controller.py               // Base controller interface
 ┃ ┃ ┃ ┣ 📄communication_controller.py      // Communication-aware controller
 ┃ ┃ ┃ ┣ 📄behavior_controller.py           // Behavior-based controller
 ┃ ┃ ┃ ┣ 📄llm_controller.py                // LLM controller
 ┃ ┃ ┃ ┗ 📄controller_factory.py            // Controller management system
 ┃ ┃ ┣ 📂gui                            // GUI components
 ┃ ┃ ┗ ┗ 📄formation_control_gui.py         // GUI application
 ┣ 📄.gitignore
 ┣ 📄.pre-commit-msg_template.yaml
 ┣ 📄.pre-commit-config.yaml
 ┣ 📄.python-version
 ┣ 📄LICENSE
 ┣ 📄pyproject.toml
 ┣ 📄README.md
 ┗ 📄uv.lock