[FEAT-STRUCT][Finished off Election swarm, based on arxiv research paper and past projects]

[IlumCI]

Description

This PR introduces ElectionSwarm, a sophisticated multi-agent orchestrator selection system that implements democratic decision-making protocols for leadership selection in multi-agent workflows. The system enables agent voters to elect the best orchestrator candidate through various coordination algorithms, providing a structured approach to leadership selection.

Key Features Added:

1. ElectionSwarm Core System (swarms/structs/election_swarm.py):

   • Democratic election workflow with voter registration and candidate presentation
   • Multiple election algorithms: Leader Election, Consensus Building, Director-CEO Matching
   • AGENTSNET-inspired message passing protocols for voter coordination
   • Structured voting with detailed reasoning, confidence scores, and candidate rankings
   • Vote counting system with dedicated vote counter role
   • Comprehensive election result tracking and presentation

2. Vote Counter Integration:

   • New VoteCounterProfile dataclass for dedicated vote counting agents
   • VoteCountingResult dataclass for detailed vote analysis
   • Enhanced ElectionResult to include vote counting information
   • Automated vote counting and result presentation

3. Real-World Example (examples/multi_agent/election_swarm/real_world_election.py):

   • Complete CEO election simulation with board of directors
   • Multiple candidate profiles with different leadership styles
   • Vote counter integration for transparent results
   • Elected CEO task execution with renewable energy market expansion
   • Silent operation with no print statements

4. Documentation (docs/swarms/structs/election_swarm.md):

   • Comprehensive documentation with architecture diagrams
   • Usage examples and API reference
   • Quick start guide with import instructions

5. Package Integration:

   • Added ElectionSwarm to swarms/structs/__init__.py exports
   • Proper module structure for public API access

Architecture:

graph TD
    A[User Task] --> B[ElectionSwarm]
    B --> C[Voter Registration]
    B --> D[Candidate Registration]
    C --> E[Agent Voters]
    D --> F[Orchestrator Candidates]
    E --> G[Message Passing Protocol]
    F --> G
    G --> H[AGENTSNET Communication]
    H --> I[Voting Process]
    I --> J[Election Algorithms]
    J --> K[Consensus Building]
    J --> L[Leader Election]
    J --> M[Matching Algorithm]
    J --> N[Coloring Algorithm]
    J --> O[Vertex Cover]
    K --> P[Election Result]
    L --> P
    M --> P
    N --> P
    O --> P
    P --> Q[Selected Orchestrator]

Loading

Technical Implementation:

• Robust JSON Parsing: Handles LLM agent responses with multiple fallback strategies
• Error Handling: Comprehensive exception handling for election processes
• Type Safety: Full type annotations with Pydantic validation
• Modular Design: Clean separation of concerns with dedicated roles
• Extensible Architecture: Easy to add new election algorithms and voting methods

Issue

#957

Dependencies

• No new external dependencies required
• Uses existing Swarms framework components
• Compatible with current Swarms architecture

Tag Maintainer

@kyegomez

Twitter Handle

x.com/IlumTheProtogen

Testing

The implementation includes:

• Comprehensive error handling and validation
• Real-world example demonstrating full workflow
• Silent operation for production use
• Type safety with Pydantic validation

Files Changed

• swarms/structs/election_swarm.py - Core ElectionSwarm implementation
• examples/multi_agent/election_swarm/real_world_election.py - Real-world CEO election example
• docs/swarms/structs/election_swarm.md - Comprehensive documentation
• swarms/structs/__init__.py - Added ElectionSwarm to exports
• examples/multi_agent/election_swarm/basic_usage.py - Basic Usage example
• examples/multi_agent/election_swarm/specialized_session.py - advanced(more complex) example
• docs/mkdocs.yml - added election_swarm under advanced workflows

Usage Example

from swarms.structs import ElectionSwarm

# Create election swarm with voters and candidates
election = ElectionSwarm(
    voters=[voter1, voter2, voter3],
    candidates=[candidate1, candidate2],
    vote_counter=vote_counter
)

# Run election
result = election.run(
    task="Elect the best CEO for our company",
    election_type=ElectionAlgorithm.LEADER_ELECTION,
    max_rounds=3
)

# Get elected leader
winner = result.election_result.winner

This PR significantly enhances the Swarms framework with democratic decision-making capabilities, enabling more sophisticated multi-agent coordination and leadership selection.

---

📚 Documentation preview 📚: https://swarms--1095.org.readthedocs.build/en/1095/