swarm-squad-ep1 0.1.8

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-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. 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/swarm_squad/main.py
   

📁 File Tree

📂Swarm-Squad-Ep1
 ┣ 📂lib                              // Supplementary materials
 ┃ ┣ 📂img                                // Readme Assets
 ┃ ┣ 📂old                                // Original old code
 ┃ ┣ 📄Li-paper.pdf                       // Original paper
 ┃ ┣ 📄Xing-paper1.pdf                    // Paper 1
 ┃ ┣ 📄Xing-paper2.pdf                    // Paper 2
 ┃ ┗ 📄Xing-ppt.pdf                       // Presentation
 ┣ 📂logs                             // Logs
 ┣ 📂src                              // Source Code
 ┃ ┗ 📦swarm_squad                        // 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
 ┣ 📄.pre-commit-msg_template.py
 ┣ 📄.python-version
 ┣ 📄LICENSE
 ┣ 📄README.md
 ┣ 📄pyproject.toml
 ┗ 📄uv.lock