Contributing to Swarms

​

Why Contribute?

• Work on the Frontier of Agents: Shape the future of autonomous agent technology and help build a production-grade, open-source framework
• Join a Vibrant Community: Collaborate with a passionate and growing group of agent developers, researchers, and enthusiasts
• Make a Tangible Impact: Whether you’re fixing a bug, adding a new feature, or improving documentation, your work will be used in real-world applications
• Learn and Grow: Gain hands-on experience with advanced AI concepts and strengthen your software engineering skills

​

Areas Needing Contributions

​

Writing Tests

• Goal: Increase test coverage to ensure the library’s robustness
• Tasks:
  • Write unit tests for existing code in swarms/
  • Identify edge cases and potential failure points
  • Ensure tests are repeatable and independent
  • Add integration tests for swarm orchestration methods

​

Improving Documentation

• Goal: Maintain clear and comprehensive documentation for users and developers
• Tasks:
  • Update docstrings to reflect any changes
  • Add examples and tutorials in the examples/ directory
  • Improve or expand the content in the swarms-framework-docs repository
  • Create video tutorials and walkthroughs

​

Adding New Swarm Architectures

• Goal: Provide new multi-agent orchestration methods
• Current Architectures:
  • SequentialWorkflow
  • AgentRearrange
  • MixtureOfAgents
  • SpreadSheetSwarm
  • ForestSwarm
  • GraphWorkflow
  • GroupChat
  • SwarmRouter

​

Enhancing Agent Capabilities

• Goal: Improve existing agents and add new specialized agents
• Areas of Focus:
  • Financial analysis agents
  • Medical diagnosis agents
  • Code generation and review agents
  • Research and analysis agents
  • Creative content generation agents

​

Removing Defunct Code

• Goal: Clean up and remove bad code to improve maintainability
• Tasks:
  • Identify unused or deprecated code
  • Remove duplicate implementations
  • Simplify complex functions
  • Update outdated dependencies

​

How to Contribute

​

Reporting Issues

1. Search Existing Issues: Before opening a new issue, check if it has already been reported
2. Open a New Issue: If it hasn’t been reported, create a new issue and provide detailed information
   • Title: A concise summary in the WARP format, for example [FIX][SwarmRouter.run][Pass output_type to fallback swarms]
   • Description: Detailed description, steps to reproduce, expected behavior, and any relevant logs or screenshots
3. Label Appropriately: Use labels to categorize the issue (e.g., bug, enhancement, documentation)

• Bug Report
• Feature Request

​

Good First Issues

• Good First Issues
• Contributing Board - Participate in roadmap discussions!

​

Submitting Pull Requests

1. Fork the Repository: Create a personal fork of the repository on GitHub
2. Clone Your Fork: Clone your forked repository to your local machine and install it in editable mode
   git clone https://github.com/<your-username>/swarms.git
   cd swarms
   pip install -e .
   
3. Create a New Branch: Use a descriptive branch name
   git checkout -b feature/your-feature-name
   
4. Make Your Changes: Implement your code, ensuring it adheres to the coding standards
5. Add Tests: Write tests to cover your changes
6. Commit Your Changes: Write the commit message in the WARP format
   git commit -am "[FEAT][SwarmRouter][Add fallback_swarms]"
   
7. Push to Your Fork:
   git push origin feature/your-feature-name
   
8. Create a Pull Request:
   • Go to the original repository on GitHub
   • Click on “New Pull Request”
   • Select your branch and open the PR against master with a WARP title
   • Describe the problem it solves and link the issue (Fixes #1234)
9. Respond to Feedback: Be prepared to make changes based on code reviews

​

WARP git messages

[TYPE][Function/FileName][Short Description]

• TYPE: the kind of change, in capitals, for example FEAT, FIX, DOCS, REFACTOR, TEST, or CHORE.
• Function/FileName: the function, class, module, or file the change is about.
• Short Description: one imperative line saying what changed.

[FIX][Agent._run][Raise AgentLLMError after retry exhaustion]
[FEAT][MCPDeployer][Serve several agents as separate tools]
[DOCS][README][Add the MCPDeployer section]

​

Coding Standards

​

Type Annotations

• Mandatory: All functions and methods must have type annotations
• Example:
  def add_numbers(a: int, b: int) -> int:
      return a + b
  
• Benefits:
  • Improves code readability
  • Helps with static type checking tools

​

Docstrings and Documentation

• Docstrings: Every public class, function, and method must have a docstring following the Google Python Style Guide or NumPy Docstring Standard
• Content:
  • Description: Briefly describe what the function or class does
  • Args: List and describe each parameter
  • Returns: Describe the return value(s)
  • Raises: List any exceptions that are raised
• Example:
  def calculate_mean(values: List[float]) -> float:
      """
      Calculates the mean of a list of numbers.
  
      Args:
          values (List[float]): A list of numerical values.
  
      Returns:
          float: The mean of the input values.
  
      Raises:
          ValueError: If the input list is empty.
      """
      if not values:
          raise ValueError("The input list is empty.")
      return sum(values) / len(values)
  
• Documentation: Update or create documentation pages if your changes affect the public API

​

Testing

• Required: All new features and bug fixes must include appropriate unit tests
• Framework: Use unittest, pytest, or a similar testing framework
• Test Location: Place tests in the tests/ directory, mirroring the structure of swarms/
• Test Coverage: Aim for high test coverage to ensure code reliability
• Running Tests:
  pytest tests/
  

​

Code Style

• PEP 8 Compliance: Follow PEP 8 style guidelines
• Linting Tools: The CI lint gate runs black --check and ruff check . — run black . and ruff check . locally before submitting
• Consistency: Maintain consistency with the existing codebase
• No unrelated reformatting: Change only the lines you need to

​

Comments

• No multi-line comment blocks: no banners, section dividers, or multi-paragraph explanations
• No commented-out code; git history keeps it
• Don’t restate the code, such as # loop over agents above a for loop

# Bad: a block that restates the code and goes stale
# ------------------------------------------------------------
# This function takes a list of agents and runs each of them
# against the provided task, collecting the results into a
# list which is then returned to the caller.
# ------------------------------------------------------------
def run_all(agents: List[Agent], task: str) -> List[str]:
    return [agent.run(task) for agent in agents]


# Good: the docstring states the contract, a comment explains the surprise
def run_all(agents: List[Agent], task: str) -> List[str]:
    """Run task on each agent and return their outputs in order."""
    # Sequential on purpose: agents share a rate-limited client.
    return [agent.run(task) for agent in agents]

​

Development Resources

​

Documentation

• Official Documentation: docs.swarms.world
• Installation Guide: Installation
• Quickstart Guide: Get Started
• Agent Architecture: Agent Internal Mechanisms
• Agent API: Agent API

​

Examples and Tutorials

• Basic Examples: examples/
• Agent Examples: examples/single_agent/
• Multi-Agent Examples: examples/multi_agent/
• Tool Examples: examples/tools/

​

API Reference

• Core Classes: swarms/structs/
• Agent Implementations: swarms/agents/
• Tool Implementations: swarms/tools/
• Utility Functions: swarms/utils/

​

License

​

Get Help

• Open an issue on GitHub
• Join our Discord community
• Reach out to the maintainers
• Schedule an onboarding session