Swarm Squad

A simulation framework for multi-agent systems.

     

---

✨ Key Features

• 🤖 Agent Simulation: Simulates multiple agents in a shared environment.
• 📈 Scalability: Handles large-scale agent simulations efficiently.
• ✅ Behavior Specs: Define and test agent behavior against expected outcomes.
• 🌍 Environment Modeling: Build and manage physical or virtual environments.
• 📊 Analytics: Collect metrics on speed, coordination, and performance.
• ⚙️ Customizable: Easily extend agents, environments, and evaluation logic.
• 🗺️ Visualization: Real-time views and post-run reports of simulations.
• 🧰 Tool Integration: Connect with RL libraries, protocols, or visual tools.
• 🚘 Versatile Agents: Supports robots, drones, and autonomous vehicles.

---

🚀 Getting Started

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

uv pip install swarm-squad

To run the application, simply type:

swarm-squad
# or
swarm-squad --help

---

👨‍💻 Development Setup

1. Clone the repository and navigate to project folder:

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

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 .

4. Set up environment variables:

   # Copy the example environment file
   cp .env.example .env

   • You can get a MAPBOX_ACCESS_TOKEN by signing up at https://www.mapbox.com/
   • Update the OLLAMA_API_URL if your Ollama instance is running on a different address
   • Update the DATABASE_PATH if you want to use a custom database file

5. 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.

6. 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

7. Code Linting & Formatting:

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

8. Run the application:

   uv run src/swarm_squad/app.py

---

📝 File Structure

📂Swarm Squad
 ┣ 📂src                         // Source Code
 ┃ ┗ 📦swarm_squad                  //
 ┃ ┃ ┣ 📂assets                     // Static assets (CSS, images, favicon, etc.)
 ┃ ┃ ┃ ┣ 📂css                      // CSS files
 ┃ ┃ ┃ ┣ 📂js                       // JavaScript files
 ┃ ┃ ┃ ┣ 📂models                   // Model files
 ┃ ┃ ┃ ┣ 📄favicon.ico              // Favicon
 ┃ ┃ ┃ ┗ 📄favicon.png              // Favicon
 ┃ ┃ ┣ 📂cli                        // CLI commands
 ┃ ┃ ┣ 📂components                 // Reusable UI components
 ┃ ┃ ┣ 📂data                       // Database files
 ┃ ┃ ┣ 📂pages                      // Page components and routing
 ┃ ┃ ┣ 📂scripts                    // Simulation and algorithm scripts
 ┃ ┃ ┣ 📂utils                      // Utility functions and helpers
 ┃ ┃ ┣ 📂cli                        // CLI commands
 ┃ ┃ ┣ 📄app.py                     // Entry point
 ┃ ┃ ┗ 📄core.py                    // Dash app core
 ┣ 📄.env.example                // Template for environment variables
 ┣ 📄.gitignore                  // Git ignore patterns (env, cache, database)
 ┣ 📄.pre-commit-config.yaml     // Pre-commit hooks (ruff, commit message)
 ┣ 📄.python-version             // Python version
 ┣ 📄LICENSE                     // MIT License
 ┣ 📄README.md                   // Project documentation
 ┣ 📄pyproject.toml              // Project configuration
 ┗ 📄uv.lock                     // Lock file