CI-DEV
2 weeks ago
committed by
GitHub
parent
2ce93a37f0
commit
ba5c7d1630
@ -0,0 +1,880 @@
|
||||
# ElectionSwarm
|
||||
|
||||
The `ElectionSwarm` is a sophisticated multi-agent orchestrator selection system that implements AGENTSNET communication protocols for democratic decision-making. It enables agent voters to elect the best orchestrator candidate through various coordination algorithms, providing a structured approach to leadership selection in multi-agent workflows.
|
||||
|
||||
## Overview
|
||||
|
||||
The ElectionSwarm follows a democratic election workflow pattern:
|
||||
|
||||
1. **Task Reception**: User provides an election task to the swarm
|
||||
2. **Voter Registration**: Agent voters are registered with their preferences and expertise
|
||||
3. **Candidate Presentation**: Orchestrator candidates present their platforms and capabilities
|
||||
4. **Message Passing**: Voters communicate with neighbors using AGENTSNET protocols
|
||||
5. **Voting Process**: Voters cast structured votes with detailed reasoning
|
||||
6. **Result Determination**: Election algorithms determine the winning orchestrator
|
||||
7. **Context Preservation**: All conversation history and voting records are maintained
|
||||
|
||||
## Architecture
|
||||
|
||||
```mermaid
|
||||
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]
|
||||
```
|
||||
|
||||
## Key Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **AGENTSNET Protocols** | Implements distributed computing algorithms for coordination |
|
||||
| **Message Passing** | Synchronous neighbor-to-neighbor communication in rounds |
|
||||
| **Structured Voting** | Voters provide detailed reasoning, confidence, and candidate rankings |
|
||||
| **Multiple Algorithms** | Consensus, Leader Election, Matching, Coloring, Vertex Cover |
|
||||
| **Cost Tracking** | Budget management and token usage monitoring |
|
||||
| **Caching System** | Response caching to avoid redundant LLM calls |
|
||||
| **Lazy Loading** | Agents instantiated only when needed |
|
||||
| **Parallel Execution** | Concurrent agent operations for efficiency |
|
||||
| **Comprehensive Logging** | Detailed logging for debugging and monitoring |
|
||||
| **Flexible Configuration** | Configurable election parameters and algorithms |
|
||||
| **Voter Tool Calls** | Optional tool calls for detailed voting explanations |
|
||||
|
||||
## ElectionSwarm Constructor
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `name` | `str` | `"ElectionSwarm"` | Name of the election swarm |
|
||||
| `description` | `str` | `"Orchestrator selection with AGENTSNET algorithms"` | Description of the swarm purpose |
|
||||
| `voters` | `List[VoterProfile]` | `None` | List of agent voters (defaults created if None) |
|
||||
| `candidates` | `List[CandidateProfile]` | `None` | List of orchestrator candidates (defaults created if None) |
|
||||
| `election_config` | `ElectionConfig` | `None` | Election configuration settings |
|
||||
| `max_loops` | `int` | `1` | Maximum number of election loops |
|
||||
| `output_type` | `OutputType` | `"dict-all-except-first"` | Output format type |
|
||||
| `verbose` | `bool` | `False` | Enable verbose logging |
|
||||
| `enable_lazy_loading` | `bool` | `True` | Enable lazy agent loading |
|
||||
| `enable_caching` | `bool` | `True` | Enable response caching |
|
||||
| `batch_size` | `int` | `25` | Batch size for parallel operations |
|
||||
| `budget_limit` | `float` | `200.0` | Budget limit for cost tracking |
|
||||
| `*args` | `Any` | - | Additional positional arguments |
|
||||
| `**kwargs` | `Any` | - | Additional keyword arguments |
|
||||
|
||||
## Core Components
|
||||
|
||||
### VoterProfile
|
||||
|
||||
Represents an agent voter in the orchestrator selection system.
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class VoterProfile:
|
||||
voter_id: str
|
||||
name: str
|
||||
voter_type: VoterType
|
||||
preferences: Dict[str, Any] = field(default_factory=dict)
|
||||
expertise_areas: List[str] = field(default_factory=list)
|
||||
voting_weight: float = 1.0
|
||||
agent: Optional[Agent] = None
|
||||
is_loaded: bool = False
|
||||
demographics: Dict[str, Any] = field(default_factory=dict)
|
||||
past_voting_history: List[Dict[str, Any]] = field(default_factory=list)
|
||||
neighbors: List[str] = field(default_factory=list)
|
||||
coordination_style: str = "collaborative"
|
||||
leadership_preferences: Dict[str, float] = field(default_factory=dict)
|
||||
```
|
||||
|
||||
### VoterType
|
||||
|
||||
Enumeration of voter types in the election system.
|
||||
|
||||
```python
|
||||
class VoterType(str, Enum):
|
||||
INDIVIDUAL = "individual"
|
||||
GROUP = "group"
|
||||
EXPERT = "expert"
|
||||
DELEGATE = "delegate"
|
||||
```
|
||||
|
||||
### CandidateProfile
|
||||
|
||||
Represents an orchestrator candidate in the selection system.
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class CandidateProfile:
|
||||
candidate_id: str
|
||||
name: str
|
||||
candidate_type: CandidateType
|
||||
party_affiliation: Optional[str] = None
|
||||
policy_positions: Dict[str, Any] = field(default_factory=dict)
|
||||
campaign_promises: List[str] = field(default_factory=list)
|
||||
experience: List[str] = field(default_factory=list)
|
||||
agent: Optional[Agent] = None
|
||||
is_loaded: bool = False
|
||||
support_base: Dict[str, float] = field(default_factory=dict)
|
||||
campaign_strategy: Dict[str, Any] = field(default_factory=dict)
|
||||
leadership_style: str = "collaborative"
|
||||
coordination_approach: Dict[str, Any] = field(default_factory=dict)
|
||||
technical_expertise: List[str] = field(default_factory=list)
|
||||
```
|
||||
|
||||
### CandidateType
|
||||
|
||||
Enumeration of candidate types in the election system.
|
||||
|
||||
```python
|
||||
class CandidateType(str, Enum):
|
||||
INDIVIDUAL = "individual"
|
||||
COALITION = "coalition"
|
||||
PARTY = "party"
|
||||
MOVEMENT = "movement"
|
||||
```
|
||||
|
||||
### ElectionAlgorithm
|
||||
|
||||
AGENTSNET algorithms for coordination.
|
||||
|
||||
```python
|
||||
class ElectionAlgorithm(str, Enum):
|
||||
CONSENSUS = "consensus"
|
||||
LEADER_ELECTION = "leader_election"
|
||||
MATCHING = "matching"
|
||||
COLORING = "coloring"
|
||||
VERTEX_COVER = "vertex_cover"
|
||||
```
|
||||
|
||||
### VoterDecision
|
||||
|
||||
Structured output from voter agents.
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class VoterDecision:
|
||||
voter_id: str
|
||||
rationality: str
|
||||
vote: VoteResult
|
||||
confidence: float = 0.0
|
||||
reasoning_factors: List[str] = field(default_factory=list)
|
||||
candidate_rankings: Dict[str, int] = field(default_factory=dict)
|
||||
tool_call_explanation: Optional[str] = None
|
||||
timestamp: datetime = field(default_factory=datetime.now)
|
||||
```
|
||||
|
||||
### VoteResult
|
||||
|
||||
Possible vote results.
|
||||
|
||||
```python
|
||||
class VoteResult(str, Enum):
|
||||
FOR = "for"
|
||||
AGAINST = "against"
|
||||
ABSTAIN = "abstain"
|
||||
INVALID = "invalid"
|
||||
```
|
||||
|
||||
### ElectionResult
|
||||
|
||||
Results of an election.
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class ElectionResult:
|
||||
election_id: str
|
||||
algorithm_used: ElectionAlgorithm
|
||||
total_voters: int
|
||||
total_candidates: int
|
||||
votes_cast: int
|
||||
winner: Optional[str] = None
|
||||
vote_distribution: Dict[str, int] = field(default_factory=dict)
|
||||
voter_decisions: List[VoterDecision] = field(default_factory=list)
|
||||
consensus_reached: bool = False
|
||||
rounds_to_consensus: int = 0
|
||||
timestamp: datetime = field(default_factory=datetime.now)
|
||||
```
|
||||
|
||||
### MessagePassingProtocol
|
||||
|
||||
AGENTSNET-inspired message-passing protocol.
|
||||
|
||||
```python
|
||||
class MessagePassingProtocol:
|
||||
def __init__(self, rounds: int = 5, synchronous: bool = True):
|
||||
self.rounds = rounds
|
||||
self.synchronous = synchronous
|
||||
self.current_round = 0
|
||||
self.message_history: List[Dict[str, Any]] = []
|
||||
```
|
||||
|
||||
### CostTracker
|
||||
|
||||
Track costs and usage for budget management.
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class CostTracker:
|
||||
total_tokens_used: int = 0
|
||||
total_cost_estimate: float = 0.0
|
||||
budget_limit: float = DEFAULT_BUDGET_LIMIT
|
||||
token_cost_per_1m: float = 0.15
|
||||
requests_made: int = 0
|
||||
cache_hits: int = 0
|
||||
```
|
||||
|
||||
## Voter Tool Calls
|
||||
|
||||
The ElectionSwarm supports optional tool calls that allow voter agents to provide detailed explanations of their voting decisions. When enabled, each voter agent will make a tool call to `explain_voting_decision` before casting their vote.
|
||||
|
||||
### Tool Call Features
|
||||
|
||||
- **Detailed Explanations**: Voters provide comprehensive reasoning for their choices
|
||||
- **Structured Data**: Tool calls include voter name, ID, chosen candidate, and reasoning
|
||||
- **Confidence Levels**: Voters specify their confidence in their decision
|
||||
- **Alternative Considerations**: Voters explain why other candidates were not chosen
|
||||
- **Key Factors**: Voters list the most important factors influencing their decision
|
||||
|
||||
### Tool Call Structure
|
||||
|
||||
```python
|
||||
{
|
||||
"voter_name": "Alice Johnson",
|
||||
"voter_id": "voter_001",
|
||||
"chosen_candidate": "John Progressive",
|
||||
"voting_reasoning": "Detailed explanation of why this candidate was chosen",
|
||||
"key_factors": ["healthcare policy", "environmental stance", "experience"],
|
||||
"confidence_level": 0.85,
|
||||
"alternative_considerations": "Considered Sarah Conservative but disagreed on healthcare"
|
||||
}
|
||||
```
|
||||
|
||||
### Enabling Tool Calls
|
||||
|
||||
```python
|
||||
# Enable voter tool calls in configuration
|
||||
config = ElectionConfig(
|
||||
config_data={
|
||||
"enable_voter_tool_calls": True,
|
||||
# ... other config options
|
||||
}
|
||||
)
|
||||
|
||||
election = ElectionSwarm(
|
||||
election_config=config,
|
||||
# ... other parameters
|
||||
)
|
||||
```
|
||||
|
||||
## AGENTSNET Communication Protocols
|
||||
|
||||
### Message Passing Protocol
|
||||
|
||||
The ElectionSwarm implements AGENTSNET-inspired message-passing for distributed coordination:
|
||||
|
||||
- **Synchronous Communication**: Agents communicate in discrete rounds
|
||||
- **Neighbor-Only Messaging**: Agents can only communicate with immediate neighbors
|
||||
- **JSON Message Format**: Structured message exchange
|
||||
- **Multi-Round Process**: Multiple rounds for information propagation
|
||||
- **Final Decision**: Agents make final decisions after communication rounds
|
||||
|
||||
### Communication Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant V1 as Voter 1
|
||||
participant V2 as Voter 2
|
||||
participant V3 as Voter 3
|
||||
participant ES as ElectionSwarm
|
||||
|
||||
Note over ES: Round 1: Initial Communication
|
||||
V1->>V2: Share candidate preferences
|
||||
V2->>V1: Share candidate preferences
|
||||
V2->>V3: Share candidate preferences
|
||||
V3->>V2: Share candidate preferences
|
||||
|
||||
Note over ES: Round 2: Information Exchange
|
||||
V1->>V2: Discuss reasoning factors
|
||||
V2->>V1: Discuss reasoning factors
|
||||
V2->>V3: Discuss reasoning factors
|
||||
V3->>V2: Discuss reasoning factors
|
||||
|
||||
Note over ES: Round 3: Final Consensus
|
||||
V1->>ES: Final vote with reasoning
|
||||
V2->>ES: Final vote with reasoning
|
||||
V3->>ES: Final vote with reasoning
|
||||
```
|
||||
|
||||
## Election Algorithms
|
||||
|
||||
The ElectionSwarm implements five AGENTSNET-inspired algorithms for orchestrator selection. Each algorithm is designed for different coordination scenarios and communication patterns.
|
||||
|
||||
### 1. Consensus Algorithm
|
||||
|
||||
All agents must agree on a single orchestrator candidate through multiple rounds of communication.
|
||||
|
||||
- **Purpose**: Achieve unanimous agreement on orchestrator selection
|
||||
- **Process**: Multiple rounds until consensus threshold is reached
|
||||
- **Threshold**: Configurable consensus threshold (default: 60%)
|
||||
- **Fallback**: Majority vote if consensus not reached
|
||||
- **Implementation**: `_conduct_consensus_election()` method
|
||||
- **Use Case**: When unanimous agreement is required
|
||||
|
||||
### 2. Leader Election Algorithm
|
||||
|
||||
Select a single leader orchestrator through distributed voting.
|
||||
|
||||
- **Purpose**: Elect one orchestrator to lead the multi-agent workflow
|
||||
- **Process**: Direct voting with winner-takes-all mechanism
|
||||
- **Complexity**: O(D) rounds where D is network diameter
|
||||
- **Implementation**: `_conduct_leader_election()` method
|
||||
- **Use Case**: When clear leadership hierarchy is needed
|
||||
|
||||
### 3. Matching Algorithm
|
||||
|
||||
Pair voters with compatible orchestrator candidates using maximal matching.
|
||||
|
||||
- **Purpose**: Create optimal voter-candidate pairings
|
||||
- **Process**: Maximal matching to avoid conflicts
|
||||
- **Complexity**: O(log* n) rounds
|
||||
- **Implementation**: `_conduct_matching_election()` method
|
||||
- **Use Case**: When specialized orchestrator-voter relationships are important
|
||||
|
||||
### 4. Coloring Algorithm
|
||||
|
||||
Group voters and candidates into compatible categories using graph coloring.
|
||||
|
||||
- **Purpose**: Assign roles such that neighbors have different roles
|
||||
- **Process**: (Δ+1)-coloring where Δ is maximum node degree
|
||||
- **Complexity**: O(log* n) rounds
|
||||
- **Implementation**: `_conduct_coloring_election()` method
|
||||
- **Use Case**: Role assignment with conflict avoidance
|
||||
|
||||
### 5. Vertex Cover Algorithm
|
||||
|
||||
Select minimal set of coordinator agents to cover all voters.
|
||||
|
||||
- **Purpose**: Choose minimal set of orchestrators to cover all voters
|
||||
- **Process**: Minimal vertex cover selection
|
||||
- **Complexity**: O(log* n) rounds
|
||||
- **Implementation**: `_conduct_vertex_cover_election()` method
|
||||
- **Use Case**: When resource-efficient coordination is needed
|
||||
|
||||
### Algorithm Selection
|
||||
|
||||
Choose the appropriate algorithm based on your coordination needs:
|
||||
|
||||
```python
|
||||
# For unanimous decisions
|
||||
ElectionAlgorithm.CONSENSUS
|
||||
|
||||
# For clear leadership
|
||||
ElectionAlgorithm.LEADER_ELECTION
|
||||
|
||||
# For optimal pairings
|
||||
ElectionAlgorithm.MATCHING
|
||||
|
||||
# For role assignment
|
||||
ElectionAlgorithm.COLORING
|
||||
|
||||
# For minimal coordination
|
||||
ElectionAlgorithm.VERTEX_COVER
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Election Setup
|
||||
|
||||
```python
|
||||
from swarms.structs.election_swarm import (
|
||||
ElectionSwarm,
|
||||
VoterProfile,
|
||||
CandidateProfile,
|
||||
VoterType,
|
||||
CandidateType,
|
||||
ElectionAlgorithm
|
||||
)
|
||||
|
||||
# Create agent voters
|
||||
voters = [
|
||||
VoterProfile(
|
||||
voter_id="agent_001",
|
||||
name="Data Analysis Agent",
|
||||
voter_type=VoterType.EXPERT,
|
||||
preferences={
|
||||
"technical_leadership": 0.9,
|
||||
"data_processing": 0.8,
|
||||
"workflow_efficiency": 0.6
|
||||
},
|
||||
expertise_areas=["data_science", "machine_learning"],
|
||||
neighbors=["Research Agent", "Backend Agent"]
|
||||
),
|
||||
# ... more voters
|
||||
]
|
||||
|
||||
# Create orchestrator candidates
|
||||
candidates = [
|
||||
CandidateProfile(
|
||||
candidate_id="orchestrator_001",
|
||||
name="Technical Lead Orchestrator",
|
||||
candidate_type=CandidateType.INDIVIDUAL,
|
||||
policy_positions={
|
||||
"technical_leadership": "Focus on code quality and architecture",
|
||||
"team_coordination": "Agile methodologies with clear planning"
|
||||
},
|
||||
campaign_promises=[
|
||||
"Implement comprehensive code review processes",
|
||||
"Establish automated testing pipelines"
|
||||
],
|
||||
leadership_style="transformational",
|
||||
technical_expertise=["software_architecture", "devops"]
|
||||
),
|
||||
# ... more candidates
|
||||
]
|
||||
|
||||
# Create election swarm
|
||||
election = ElectionSwarm(
|
||||
name="Multi-Agent Orchestrator Election",
|
||||
voters=voters,
|
||||
candidates=candidates,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
### Running Elections
|
||||
|
||||
```python
|
||||
# Run consensus election
|
||||
result = election.run(
|
||||
task="Select the best orchestrator for our multi-agent workflow",
|
||||
election_type=ElectionAlgorithm.CONSENSUS,
|
||||
max_rounds=5
|
||||
)
|
||||
|
||||
# Run leader election
|
||||
result = election.run(
|
||||
task="Elect a leader to coordinate our development team",
|
||||
election_type=ElectionAlgorithm.LEADER_ELECTION
|
||||
)
|
||||
|
||||
# Run matching election
|
||||
result = election.run(
|
||||
task="Match voters with compatible orchestrator candidates",
|
||||
election_type=ElectionAlgorithm.MATCHING
|
||||
)
|
||||
|
||||
# Run election session with comprehensive analysis
|
||||
session_result = election.run_election_session(
|
||||
election_type=ElectionAlgorithm.CONSENSUS,
|
||||
max_rounds=5
|
||||
)
|
||||
|
||||
# Access detailed results
|
||||
election_result = session_result["election_result"]
|
||||
analysis = session_result["analysis"]
|
||||
cost_stats = session_result["cost_statistics"]
|
||||
```
|
||||
|
||||
### Board CEO Election Example
|
||||
|
||||
```python
|
||||
# Create board of directors as voters
|
||||
board_members = [
|
||||
VoterProfile(
|
||||
voter_id="director_001",
|
||||
name="Sarah Chen - Technology Director",
|
||||
voter_type=VoterType.EXPERT,
|
||||
preferences={
|
||||
"innovation": 0.9,
|
||||
"technical_excellence": 0.8,
|
||||
"digital_transformation": 0.7
|
||||
},
|
||||
expertise_areas=["technology", "innovation"],
|
||||
coordination_style="data_driven",
|
||||
leadership_preferences={
|
||||
"technical_leadership": 0.9,
|
||||
"innovation": 0.8
|
||||
}
|
||||
),
|
||||
# ... more board members
|
||||
]
|
||||
|
||||
# Create CEO candidates with diverse approaches
|
||||
ceo_candidates = [
|
||||
CandidateProfile(
|
||||
candidate_id="ceo_001",
|
||||
name="Alexandra Martinez - Innovation CEO",
|
||||
candidate_type=CandidateType.INDIVIDUAL,
|
||||
policy_positions={
|
||||
"innovation_leadership": "Aggressive digital transformation",
|
||||
"growth_strategy": "Rapid expansion with high-risk investments"
|
||||
},
|
||||
leadership_style="transformational",
|
||||
coordination_approach={"innovation": 0.9, "risk_taking": 0.8}
|
||||
),
|
||||
# ... more CEO candidates
|
||||
]
|
||||
|
||||
# Create board CEO election
|
||||
ceo_election = ElectionSwarm(
|
||||
name="Board of Directors CEO Election",
|
||||
voters=board_members,
|
||||
candidates=ceo_candidates,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Run the election
|
||||
result = ceo_election.run(
|
||||
task="Elect the best CEO to lead our company",
|
||||
election_type=ElectionAlgorithm.CONSENSUS
|
||||
)
|
||||
|
||||
# Get comprehensive statistics
|
||||
stats = ceo_election.get_election_statistics()
|
||||
print(f"Election statistics: {stats}")
|
||||
|
||||
# Get swarm status
|
||||
status = ceo_election.get_swarm_status()
|
||||
print(f"Swarm status: {status}")
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Election Configuration
|
||||
|
||||
The ElectionSwarm uses a comprehensive configuration system with Pydantic validation.
|
||||
|
||||
```python
|
||||
from swarms.structs.election_swarm import ElectionConfig, ElectionConfigModel
|
||||
|
||||
# Create configuration with validation
|
||||
config = ElectionConfig(
|
||||
config_data={
|
||||
"election_type": "orchestrator_selection",
|
||||
"max_candidates": 5,
|
||||
"max_voters": 50,
|
||||
"enable_consensus": True,
|
||||
"enable_leader_election": True,
|
||||
"enable_matching": True,
|
||||
"enable_coloring": True,
|
||||
"enable_vertex_cover": True,
|
||||
"enable_caching": True,
|
||||
"enable_voter_tool_calls": True,
|
||||
"batch_size": 10,
|
||||
"max_workers": 5,
|
||||
"budget_limit": 100.0,
|
||||
"default_model": "gpt-4o-mini",
|
||||
"verbose_logging": True
|
||||
}
|
||||
)
|
||||
|
||||
# Validate configuration
|
||||
errors = config.validate_config()
|
||||
if errors:
|
||||
print(f"Configuration errors: {errors}")
|
||||
|
||||
# Save configuration to file
|
||||
config.save_config("election_config.yaml")
|
||||
|
||||
election = ElectionSwarm(
|
||||
name="Advanced Election",
|
||||
election_config=config,
|
||||
voters=voters,
|
||||
candidates=candidates
|
||||
)
|
||||
```
|
||||
|
||||
### ElectionConfigModel
|
||||
|
||||
The configuration model with validation constraints:
|
||||
|
||||
```python
|
||||
class ElectionConfigModel(BaseModel):
|
||||
election_type: str = Field(default="orchestrator_selection")
|
||||
max_candidates: int = Field(default=5, ge=1, le=20)
|
||||
max_voters: int = Field(default=100, ge=1, le=1000)
|
||||
enable_consensus: bool = Field(default=True)
|
||||
enable_leader_election: bool = Field(default=True)
|
||||
enable_matching: bool = Field(default=True)
|
||||
enable_coloring: bool = Field(default=True)
|
||||
enable_vertex_cover: bool = Field(default=True)
|
||||
enable_caching: bool = Field(default=True)
|
||||
enable_voter_tool_calls: bool = Field(default=True)
|
||||
batch_size: int = Field(default=25, ge=1, le=100)
|
||||
max_workers: int = Field(default=10, ge=1, le=50)
|
||||
budget_limit: float = Field(default=200.0, ge=0.0)
|
||||
default_model: str = Field(default="gpt-4o-mini")
|
||||
verbose_logging: bool = Field(default=False)
|
||||
```
|
||||
|
||||
### Cost Tracking and Budget Management
|
||||
|
||||
```python
|
||||
# Monitor election costs
|
||||
election = ElectionSwarm(
|
||||
budget_limit=50.0,
|
||||
enable_caching=True
|
||||
)
|
||||
|
||||
# Run election with cost monitoring
|
||||
result = election.run(task="Select orchestrator")
|
||||
|
||||
# Get cost statistics
|
||||
stats = election.get_election_statistics()
|
||||
print(f"Total cost: ${stats['cost_statistics']['total_cost']:.2f}")
|
||||
print(f"Cache hit rate: {stats['cost_statistics']['cache_hit_rate']:.1%}")
|
||||
```
|
||||
|
||||
## Core Methods
|
||||
|
||||
### Step Method
|
||||
|
||||
Execute a single step of the ElectionSwarm.
|
||||
|
||||
```python
|
||||
# Execute a single election step
|
||||
result = election.step(
|
||||
task="Select the best orchestrator for our team",
|
||||
election_type=ElectionAlgorithm.CONSENSUS,
|
||||
max_rounds=5
|
||||
)
|
||||
```
|
||||
|
||||
### Run Method
|
||||
|
||||
Run the ElectionSwarm for the specified number of loops.
|
||||
|
||||
```python
|
||||
# Run multiple election loops
|
||||
result = election.run(
|
||||
task="Elect a leader for our development team",
|
||||
election_type=ElectionAlgorithm.LEADER_ELECTION,
|
||||
max_rounds=3
|
||||
)
|
||||
```
|
||||
|
||||
### Conduct Election
|
||||
|
||||
Conduct an election using the specified algorithm.
|
||||
|
||||
```python
|
||||
# Conduct election directly
|
||||
result = election.conduct_election(
|
||||
election_type=ElectionAlgorithm.CONSENSUS,
|
||||
max_rounds=5
|
||||
)
|
||||
```
|
||||
|
||||
### Run Election Session
|
||||
|
||||
Run a complete election session with comprehensive analysis.
|
||||
|
||||
```python
|
||||
# Run election session with detailed analysis
|
||||
session_result = election.run_election_session(
|
||||
election_type=ElectionAlgorithm.CONSENSUS,
|
||||
max_rounds=5
|
||||
)
|
||||
|
||||
# Access results
|
||||
election_result = session_result["election_result"]
|
||||
analysis = session_result["analysis"]
|
||||
cost_statistics = session_result["cost_statistics"]
|
||||
```
|
||||
|
||||
## Swarm Management Methods
|
||||
|
||||
### Adding and Removing Participants
|
||||
|
||||
```python
|
||||
# Add new voter
|
||||
new_voter = VoterProfile(
|
||||
voter_id="agent_007",
|
||||
name="New Agent",
|
||||
voter_type=VoterType.EXPERT
|
||||
)
|
||||
election.add_voter(new_voter)
|
||||
|
||||
# Add new candidate
|
||||
new_candidate = CandidateProfile(
|
||||
candidate_id="orchestrator_004",
|
||||
name="New Orchestrator",
|
||||
candidate_type=CandidateType.INDIVIDUAL
|
||||
)
|
||||
election.add_candidate(new_candidate)
|
||||
|
||||
# Remove participants
|
||||
election.remove_voter("agent_007")
|
||||
election.remove_candidate("orchestrator_004")
|
||||
```
|
||||
|
||||
### Swarm Status and Statistics
|
||||
|
||||
```python
|
||||
# Get swarm information
|
||||
status = election.get_swarm_status()
|
||||
print(f"Total participants: {status['total_participants']}")
|
||||
print(f"Voters: {status['voters']}")
|
||||
print(f"Candidates: {status['candidates']}")
|
||||
print(f"Budget remaining: ${status['budget_remaining']:.2f}")
|
||||
|
||||
# Get comprehensive statistics
|
||||
stats = election.get_election_statistics()
|
||||
print(f"Swarm name: {stats['swarm_info']['name']}")
|
||||
print(f"Cache size: {stats['cache_stats']['cache_size']}")
|
||||
|
||||
# Get swarm size
|
||||
swarm_size = election.get_swarm_size()
|
||||
print(f"Total swarm size: {swarm_size}")
|
||||
|
||||
# Get specific voter or candidate
|
||||
voter = election.get_voter("voter_001")
|
||||
candidate = election.get_candidate("candidate_001")
|
||||
```
|
||||
|
||||
### Reset and Cleanup
|
||||
|
||||
```python
|
||||
# Reset election swarm to initial state
|
||||
election.reset()
|
||||
|
||||
# This clears:
|
||||
# - Conversation history
|
||||
# - Cost tracking
|
||||
# - Message protocol
|
||||
# - Cache
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Voter Design
|
||||
|
||||
- **Diverse Expertise**: Include voters with different specializations
|
||||
- **Balanced Preferences**: Ensure varied preference profiles
|
||||
- **Neighbor Connections**: Create meaningful neighbor relationships
|
||||
- **Realistic Demographics**: Use realistic agent characteristics
|
||||
|
||||
### 2. Candidate Design
|
||||
|
||||
- **Clear Platforms**: Define distinct policy positions
|
||||
- **Compelling Promises**: Create realistic campaign promises
|
||||
- **Relevant Experience**: Include pertinent background experience
|
||||
- **Leadership Styles**: Vary leadership and coordination approaches
|
||||
|
||||
### 3. Election Configuration
|
||||
|
||||
- **Appropriate Algorithms**: Choose algorithms matching your use case
|
||||
- **Budget Management**: Set realistic budget limits
|
||||
- **Caching Strategy**: Enable caching for repeated elections
|
||||
- **Logging Level**: Use verbose logging for debugging
|
||||
|
||||
### 4. Performance Optimization
|
||||
|
||||
- **Lazy Loading**: Enable lazy loading for large swarms
|
||||
- **Batch Processing**: Use appropriate batch sizes
|
||||
- **Parallel Execution**: Leverage concurrent operations
|
||||
- **Cost Monitoring**: Track and optimize token usage
|
||||
|
||||
## Error Handling
|
||||
|
||||
The ElectionSwarm includes comprehensive error handling:
|
||||
|
||||
```python
|
||||
try:
|
||||
result = election.run(
|
||||
task="Select orchestrator",
|
||||
election_type=ElectionAlgorithm.CONSENSUS
|
||||
)
|
||||
except ValueError as e:
|
||||
print(f"Configuration error: {e}")
|
||||
except Exception as e:
|
||||
print(f"Election failed: {e}")
|
||||
```
|
||||
|
||||
Common error scenarios:
|
||||
|
||||
- **No voters or candidates**: Ensure at least one participant
|
||||
- **Invalid algorithm**: Use supported ElectionAlgorithm values
|
||||
- **Budget exceeded**: Monitor and adjust budget limits
|
||||
- **Agent loading failures**: Check agent configurations
|
||||
|
||||
## Integration with Other Swarms
|
||||
|
||||
The ElectionSwarm can be integrated with other Swarms architectures:
|
||||
|
||||
```python
|
||||
# Use with BoardOfDirectorsSwarm
|
||||
from swarms.structs.board_of_directors_swarm import BoardOfDirectorsSwarm
|
||||
|
||||
# Create board election
|
||||
board_election = ElectionSwarm(
|
||||
name="Board CEO Election",
|
||||
voters=board_members,
|
||||
candidates=ceo_candidates
|
||||
)
|
||||
|
||||
# Elect CEO
|
||||
ceo_result = board_election.run(
|
||||
task="Elect CEO for board governance",
|
||||
election_type=ElectionAlgorithm.CONSENSUS
|
||||
)
|
||||
|
||||
# Use elected CEO with BoardOfDirectorsSwarm
|
||||
board = BoardOfDirectorsSwarm(
|
||||
chairman=ceo_result.winner,
|
||||
# ... other board configuration
|
||||
)
|
||||
```
|
||||
|
||||
## Utility Functions
|
||||
|
||||
### Create Default Configuration
|
||||
|
||||
Create a default election configuration file.
|
||||
|
||||
```python
|
||||
from swarms.structs.election_swarm import create_default_election_config
|
||||
|
||||
# Create default configuration file
|
||||
create_default_election_config("my_election_config.yaml")
|
||||
```
|
||||
|
||||
### Default Constants
|
||||
|
||||
The ElectionSwarm uses several default constants:
|
||||
|
||||
```python
|
||||
DEFAULT_BUDGET_LIMIT = 200.0
|
||||
DEFAULT_CONSENSUS_THRESHOLD = 0.6
|
||||
DEFAULT_MAX_WORKERS = 10
|
||||
DEFAULT_MAX_ROUNDS = 5
|
||||
DEFAULT_BATCH_SIZE = 25
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
The ElectionSwarm provides a robust, scalable solution for orchestrator selection in multi-agent systems. By implementing AGENTSNET communication protocols and multiple election algorithms, it enables sophisticated democratic decision-making processes that can adapt to various coordination requirements and communication complexities.
|
||||
|
||||
Key advantages:
|
||||
|
||||
- **Distributed Coordination**: Implements proven distributed computing algorithms
|
||||
- **Flexible Architecture**: Supports various election types and configurations
|
||||
- **Production Ready**: Includes cost tracking, caching, and comprehensive error handling
|
||||
- **Swarms Integration**: Seamlessly integrates with other Swarms architectures
|
||||
- **Real-world Applications**: Suitable for corporate governance, team leadership, and workflow orchestration
|
||||
|
||||
The ElectionSwarm represents a significant advancement in multi-agent coordination, providing the tools necessary for sophisticated democratic decision-making in complex agent-based systems.
|
||||
Loading…
Reference in new issue