swarms/docs/contributors/environment_setup.md

Environment Setup Guide for Swarms Contributors

Welcome to the Swarms development environment setup guide! This comprehensive guide will walk you through setting up your development environment from scratch, whether you're a first-time contributor or an experienced developer.

!!! success "🚀 One-Click Setup (Recommended)" New! Use our automated setup script that handles everything: bash git clone https://github.com/kyegomez/swarms.git cd swarms chmod +x scripts/setup.sh ./scripts/setup.sh This script automatically installs Poetry, creates a virtual environment, installs all dependencies, sets up pre-commit hooks, and more!

!!! info "Manual Setup" Alternative: For manual control, install Python 3.10+, Git, and Poetry, then run: bash git clone https://github.com/kyegomez/swarms.git cd swarms poetry install --with dev

---

:material-list-status: Prerequisites

Before setting up your development environment, ensure you have the following installed:

System Requirements

Tool	Version	Purpose
Python	3.10+	Core runtime
Git	2.30+	Version control
Poetry	1.4+	Dependency management (recommended)
Node.js	16+	Documentation tools (optional)

Operating System Support

=== "macOS"

```bash
# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install prerequisites
brew install python@3.10 git poetry node
```

=== "Ubuntu/Debian"

```bash
# Update package list
sudo apt update

# Install Python 3.10 and pip
sudo apt install python3.10 python3.10-venv python3-pip git curl

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

# Add Poetry to PATH
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
```

=== "Windows"

1. **Install Python 3.10+** from [python.org](https://python.org/downloads/)
2. **Install Git** from [git-scm.com](https://git-scm.com/download/win)
3. **Install Poetry** using PowerShell:
```powershell
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
```

---

:material-auto-fix: Automated Setup (Recommended)

We provide a comprehensive setup script that automates the entire development environment setup process. This is the recommended approach for new contributors.

What the Setup Script Does

The scripts/setup.sh script automatically handles:

• ✅ Python Version Check: Verifies Python 3.10+ is installed
• ✅ Poetry Installation: Installs Poetry if not present
• ✅ Virtual Environment: Creates and configures a project-specific virtual environment
• ✅ Dependencies: Installs all main, development, lint, and test dependencies
• ✅ Pre-commit Hooks: Sets up and installs pre-commit hooks for code quality
• ✅ Environment Template: Creates a .env file template with common variables
• ✅ Verification: Runs initial setup verification checks
• ✅ Helpful Output: Provides colored output and next steps

Running the Automated Setup

# Clone the repository
git clone https://github.com/kyegomez/swarms.git
cd swarms

# Make the script executable and run it
chmod +x scripts/setup.sh
./scripts/setup.sh

Script Features

=== "🎯 Smart Detection" The script intelligently detects your system state: - Checks if Poetry is already installed - Verifies Python version compatibility - Detects existing virtual environments - Checks for Git repository status

=== "🔧 Comprehensive Setup" Installs everything you need: ```bash # All dependency groups poetry install --with dev,lint,test

# Pre-commit hooks
pre-commit install
pre-commit install --hook-type commit-msg

# Initial verification run
pre-commit run --all-files
```

=== "📋 Environment Template" Creates a starter .env file: bash # Generated .env template OPENAI_API_KEY=your_openai_api_key_here ANTHROPIC_API_KEY=your_anthropic_key_here LOG_LEVEL=INFO DEVELOPMENT=true

=== "💡 Helpful Guidance" Provides next steps and useful commands: - How to activate the virtual environment - Essential Poetry commands - Testing and development workflow - Troubleshooting tips

When to Use Manual Setup

Use the manual setup approach if you:

• Want full control over each step
• Have specific system requirements
• Are troubleshooting installation issues
• Prefer to understand each component

---

:material-git: Repository Setup

Step 1: Fork and Clone

1. Fork the repository on GitHub: github.com/kyegomez/swarms

2. Clone your fork:

git clone https://github.com/YOUR_USERNAME/swarms.git
cd swarms

3. Add upstream remote:

git remote add upstream https://github.com/kyegomez/swarms.git

4. Verify remotes:

git remote -v
# origin    https://github.com/YOUR_USERNAME/swarms.git (fetch)
# origin    https://github.com/YOUR_USERNAME/swarms.git (push)
# upstream  https://github.com/kyegomez/swarms.git (fetch)
# upstream  https://github.com/kyegomez/swarms.git (push)

---

:material-package-variant: Dependency Management

Choose your preferred method for managing dependencies:

=== "Poetry (Recommended)"

Poetry provides superior dependency resolution and virtual environment management.

### Installation

```bash
# Navigate to project directory
cd swarms

# Install all dependencies including development tools
poetry install --with dev,lint,test

# Activate the virtual environment
poetry shell
```

### Useful Poetry Commands

```bash
# Add a new dependency
poetry add package_name

# Add a development dependency
poetry add --group dev package_name

# Update dependencies
poetry update

# Show dependency tree
poetry show --tree

# Run commands in the virtual environment
poetry run python your_script.py
```

=== "pip + venv"

Traditional pip-based setup with virtual environments.

### Installation

```bash
# Navigate to project directory
cd swarms

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install core dependencies
pip install -r requirements.txt

# Install documentation dependencies (optional)
pip install -r docs/requirements.txt
```

---

:material-tools: Development Tools Setup

Code Quality Tools

Swarms uses several tools to maintain code quality:

=== "Formatting"

**Black** - Code formatter
```bash
# Format code
poetry run black swarms/
# or with pip:
black swarms/

# Check formatting without making changes
black swarms/ --check --diff
```

=== "Linting"

**Ruff** - Fast Python linter
```bash
# Run linter
poetry run ruff check swarms/
# or with pip:
ruff check swarms/

# Auto-fix issues
ruff check swarms/ --fix
```

=== "Type Checking"

**MyPy** - Static type checker
```bash
# Run type checking
poetry run mypy swarms/
# or with pip:
mypy swarms/
```

Pre-commit Hooks (Optional but Recommended)

Set up pre-commit hooks to automatically run quality checks:

# Install pre-commit
poetry add --group dev pre-commit
# or with pip:
pip install pre-commit

# Install git hooks
pre-commit install

# Run on all files
pre-commit run --all-files

The project uses the latest ruff-pre-commit configuration with separate hooks for linting and formatting:

• ruff-check: Runs the linter with automatic fixes (--fix flag)
• ruff-format: Runs the formatter for code styling
• types_or: [python, pyi]: Excludes Jupyter notebooks from processing

This configuration ensures consistent code quality and style across the project while avoiding conflicts with Jupyter notebook files.

---

:material-test-tube: Testing Setup

Running Tests

# Run all tests
poetry run pytest
# or with pip:
pytest

# Run tests with coverage
poetry run pytest --cov=swarms tests/

# Run specific test file
poetry run pytest tests/test_specific_file.py

# Run tests matching a pattern
poetry run pytest -k "test_agent"

Test Structure

The project uses pytest with the following structure:

tests/
├── agents/          # Agent-related tests
├── structs/         # Multi-agent structure tests
├── tools/           # Tool tests
├── utils/           # Utility tests
└── conftest.py      # Test configuration

Writing Tests

# Example test file: tests/test_example.py
import pytest
from swarms import Agent

def test_agent_creation():
    """Test that an agent can be created successfully."""
    agent = Agent(
        agent_name="test_agent",
        system_prompt="You are a helpful assistant"
    )
    assert agent.agent_name == "test_agent"

@pytest.mark.parametrize("input_val,expected", [
    ("hello", "HELLO"),
    ("world", "WORLD"),
])
def test_uppercase(input_val, expected):
    """Example parametrized test."""
    assert input_val.upper() == expected

---

:material-book-open-page-variant: Documentation Setup

Building Documentation Locally

# Install documentation dependencies
pip install -r docs/requirements.txt

# Navigate to docs directory
cd docs

# Serve documentation locally
mkdocs serve
# Documentation will be available at http://127.0.0.1:8000

Documentation Structure

docs/
├── index.md              # Homepage
├── mkdocs.yml           # MkDocs configuration
├── swarms/              # Core documentation
├── examples/            # Examples and tutorials
├── contributors/        # Contributor guides
└── assets/              # Images and static files

Writing Documentation

Use Markdown with MkDocs extensions:

# Page Title

!!! tip "Pro Tip"
    Use admonitions to highlight important information.

=== "Python"
    ```python
    from swarms import Agent
    agent = Agent()
    ```

=== "CLI"
    ```bash
    swarms create-agent --name myagent
    ```

---

:material-application-variable: Environment Variables

Create a .env file for local development:

# Copy example environment file
cp .env.example .env  # if it exists

# Or create your own .env file
touch .env

Common environment variables:

# .env file
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
GROQ_API_KEY=your_groq_api_key_here

# Development settings
DEBUG=true
LOG_LEVEL=INFO

# Optional: Database settings
DATABASE_URL=sqlite:///swarms.db

---

:material-check-circle: Verification Steps

!!! tip "Automated Verification" If you used the automated setup script (./scripts/setup.sh), most verification steps are handled automatically. The script runs verification checks and reports any issues.

For manual setups, verify your setup is working correctly:

1. Basic Import Test

poetry run python -c "from swarms import Agent; print('✅ Import successful')"

2. Run a Simple Agent

# test_setup.py
from swarms import Agent

agent = Agent(
    agent_name="setup_test",
    system_prompt="You are a helpful assistant for testing setup.",
    max_loops=1
)

response = agent.run("Say hello!")
print(f"✅ Agent response: {response}")

3. Code Quality Check

# Run all quality checks
poetry run black swarms/ --check
poetry run ruff check swarms/
poetry run pytest tests/ -x

4. Documentation Build

cd docs
mkdocs build
echo "✅ Documentation built successfully"

---

:material-rocket-launch: Development Workflow

Creating a Feature Branch

# Sync with upstream
git fetch upstream
git checkout master
git rebase upstream/master

# Create feature branch
git checkout -b feature/your-feature-name

# Make your changes...
# Add and commit
git add .
git commit -m "feat: add your feature description"

# Push to your fork
git push origin feature/your-feature-name

Daily Development Commands

# Start development session
cd swarms
poetry shell  # or source venv/bin/activate

# Pull latest changes
git fetch upstream
git rebase upstream/master

# Run tests during development
poetry run pytest tests/ -v

# Format and lint before committing
poetry run black swarms/
poetry run ruff check swarms/ --fix

# Run a quick smoke test
poetry run python -c "from swarms import Agent; print('✅ All good')"

---

:material-bug: Troubleshooting

!!! tip "First Step: Try the Automated Setup" If you're experiencing setup issues, try running our automated setup script first: bash chmod +x scripts/setup.sh ./scripts/setup.sh This script handles most common setup problems automatically and provides helpful error messages.

Common Issues and Solutions

=== "Poetry Issues"

**Problem**: Poetry command not found
```bash
# Solution: Add Poetry to PATH
export PATH="$HOME/.local/bin:$PATH"
# Add to your shell profile (.bashrc, .zshrc, etc.)
```

**Problem**: Poetry install fails
```bash
# Solution: Clear cache and reinstall
poetry cache clear --all pypi
poetry install --with dev
```

=== "Python Version Issues"

**Problem**: Wrong Python version
```bash
# Check Python version
python --version

# Use pyenv to manage Python versions
curl https://pyenv.run | bash
pyenv install 3.10.12
pyenv local 3.10.12
```

=== "Import Errors"

**Problem**: Cannot import swarms modules
```bash
# Ensure you're in the virtual environment
poetry shell
# or
source venv/bin/activate

# Install in development mode
poetry install --with dev
# or
pip install -e .
```

=== "Test Failures"

**Problem**: Tests fail due to missing dependencies
```bash
# Install test dependencies
poetry install --with test
# or
pip install pytest pytest-cov pytest-mock
```

Getting Help

If you encounter issues:

1. Check the FAQ in the main documentation
2. Search existing issues on GitHub
3. Ask in the Discord community: discord.gg/jM3Z6M9uMq
4. Create a GitHub issue with:
   • Your operating system
   • Python version
   • Error messages
   • Steps to reproduce

---

:material-next-step: Next Steps

Now that your environment is set up:

1. Read the Contributing Guide: contributors/main.md
2. Explore the Codebase: Start with swarms/structs/agent.py
3. Run Examples: Check out examples/ directory
4. Pick an Issue: Look for good-first-issue labels on GitHub
5. Join the Community: Discord, Twitter, and GitHub discussions

!!! success "You're Ready!" Your Swarms development environment is now set up! You're ready to contribute to the most important technology for multi-agent collaboration.

---

:material-bookmark-outline: Quick Reference

Essential Commands

# Setup (choose one)
./scripts/setup.sh                   # Automated setup (recommended)
poetry install --with dev            # Manual dependency install

# Daily workflow
poetry shell                          # Activate environment
poetry run pytest                    # Run tests
poetry run black swarms/             # Format code
poetry run ruff check swarms/        # Lint code

# Git workflow
git fetch upstream                    # Get latest changes
git rebase upstream/master           # Update your branch
git checkout -b feature/name         # Create feature branch
git push origin feature/name         # Push your changes

# Documentation
cd docs && mkdocs serve              # Serve docs locally
mkdocs build                         # Build docs

Project Structure

swarms/
├── swarms/              # Core package
│   ├── agents/         # Agent implementations
│   ├── structs/        # Multi-agent structures
│   ├── tools/          # Agent tools
│   └── utils/          # Utilities
├── examples/           # Usage examples
├── tests/              # Test suite
├── docs/               # Documentation
├── pyproject.toml      # Poetry configuration
└── requirements.txt    # Pip dependencies

Happy coding! 🚀