Merge pull request #1237 from IlumCI/agenbtjudge

[FEAT-SWARM[Updated Swarm_router with DebateWithJudge swarm]

docs/swarms/structs/swarm_router.md

@@ -125,6 +125,7 @@ The `SwarmRouter` supports many various multi-agent architectures for various ap
 | `HeavySwarm` | Heavy swarm architecture with question and worker agents |
 | `BatchedGridWorkflow` | Batched grid workflow for parallel task processing |
 | `LLMCouncil` | Council of specialized LLM agents with peer review and synthesis |
+| `DebateWithJudge` | Debate architecture with Pro/Con agents and a Judge for self-refinement |
 | `auto` | Automatically selects best swarm type via embedding search |
 
 ## Basic Usage
@@ -482,6 +483,64 @@ LLMCouncil creates a council of specialized agents (GPT-5.1, Gemini, Claude, Gro
 
 The council automatically tracks all messages in a conversation object and supports flexible output formats. Note: LLMCouncil uses default council members and doesn't require the `agents` parameter.
 
+### DebateWithJudge
+
+Use Case: Structured debate architecture where two agents (Pro and Con) present opposing arguments, and a Judge agent evaluates and synthesizes the arguments over multiple rounds to progressively refine the answer.
+
+```python
+from swarms import Agent, SwarmRouter
+
+# Create three specialized agents for the debate
+pro_agent = Agent(
+    agent_name="Pro-Agent",
+    system_prompt="You are an expert at presenting strong, well-reasoned arguments in favor of positions. "
+                  "You provide compelling evidence and logical reasoning to support your stance.",
+    model_name="gpt-4.1",
+    max_loops=1,
+)
+
+con_agent = Agent(
+    agent_name="Con-Agent",
+    system_prompt="You are an expert at presenting strong, well-reasoned counter-arguments. "
+                  "You identify weaknesses in opposing arguments and present compelling evidence against positions.",
+    model_name="gpt-4.1",
+    max_loops=1,
+)
+
+judge_agent = Agent(
+    agent_name="Judge-Agent",
+    system_prompt="You are an impartial judge evaluating debates. You carefully assess both arguments, "
+                  "identify strengths and weaknesses, and provide refined synthesis that incorporates "
+                  "the best elements from both sides.",
+    model_name="gpt-4.1",
+    max_loops=1,
+)
+
+# Initialize the SwarmRouter with DebateWithJudge
+debate_router = SwarmRouter(
+    name="DebateWithJudge",
+    description="Structured debate with Pro/Con agents and Judge for self-refinement",
+    swarm_type="DebateWithJudge",
+    agents=[pro_agent, con_agent, judge_agent],  # Must be exactly 3 agents
+    max_loops=3,  # Number of debate rounds
+    output_type="str-all-except-first",  # Output format
+    verbose=True  # Show progress and intermediate results
+)
+
+# Run a debate on a topic
+result = debate_router.run(
+    "Should artificial intelligence development be regulated by governments?"
+)
+```
+
+DebateWithJudge implements a multi-round debate system where:
+1. **Pro Agent** presents arguments in favor of the topic
+2. **Con Agent** presents counter-arguments against the topic
+3. **Judge Agent** evaluates both arguments and provides synthesis
+4. The process repeats for N rounds (specified by `max_loops`), with each round refining the discussion based on the judge's feedback
+
+The architecture progressively improves the answer through iterative refinement, making it ideal for complex topics requiring thorough analysis from multiple perspectives. Note: DebateWithJudge requires exactly 3 agents (pro_agent, con_agent, judge_agent) in that order.
+
 ## Advanced Features
 
 ### Processing Documents

swarms/structs/swarm_router.py

@@ -23,9 +23,10 @@ from swarms.structs.agent_rearrange import AgentRearrange
 from swarms.structs.batched_grid_workflow import BatchedGridWorkflow
 from swarms.structs.concurrent_workflow import ConcurrentWorkflow
 from swarms.structs.council_as_judge import CouncilAsAJudge
+from swarms.structs.debate_with_judge import DebateWithJudge
 from swarms.structs.groupchat import GroupChat
 from swarms.structs.heavy_swarm import HeavySwarm
-from swarms.structs.hiearchical_swarm import HierarchicalSwarm
+from swarms.structs.hierarchical_swarm import HierarchicalSwarm
 from swarms.structs.interactive_groupchat import InteractiveGroupChat
 from swarms.structs.ma_utils import list_all_agents
 from swarms.structs.majority_voting import MajorityVoting
@@ -49,7 +50,7 @@ SwarmType = Literal[
     "GroupChat",
     "MultiAgentRouter",
     "AutoSwarmBuilder",
-    "HiearchicalSwarm",
+    "HierarchicalSwarm",
     "auto",
     "MajorityVoting",
     "MALT",
@@ -58,6 +59,7 @@ SwarmType = Literal[
     "HeavySwarm",
     "BatchedGridWorkflow",
     "LLMCouncil",
+    "DebateWithJudge",
 ]
 
 
@@ -306,12 +308,23 @@ class SwarmRouter:
 
             if (
                 self.swarm_type != "HeavySwarm"
+                and self.swarm_type != "DebateWithJudge"
                 and self.agents is None
             ):
                 raise SwarmRouterConfigError(
                     "SwarmRouter: No agents provided for the swarm. Check the docs to learn of required parameters. https://docs.swarms.world/en/latest/swarms/structs/agent/"
                 )
 
+            if self.swarm_type == "DebateWithJudge":
+                if self.agents is None or len(self.agents) != 3:
+                    raise SwarmRouterConfigError(
+                        "SwarmRouter: DebateWithJudge requires exactly 3 agents: "
+                        "pro_agent (arguing in favor), con_agent (arguing against), "
+                        "and judge_agent (evaluating and synthesizing). "
+                        f"Provided {len(self.agents) if self.agents else 0} agent(s). "
+                        "Check the docs: https://docs.swarms.world/en/latest/swarms/structs/swarm_router/"
+                    )
+
             if (
                 self.swarm_type == "AgentRearrange"
                 and self.rearrange_flow is None
@@ -421,7 +434,7 @@ class SwarmRouter:
             "MALT": self._create_malt,
             "CouncilAsAJudge": self._create_council_as_judge,
             "InteractiveGroupChat": self._create_interactive_group_chat,
-            "HiearchicalSwarm": self._create_hierarchical_swarm,
+            "HierarchicalSwarm": self._create_hierarchical_swarm,
             "MixtureOfAgents": self._create_mixture_of_agents,
             "MajorityVoting": self._create_majority_voting,
             "GroupChat": self._create_group_chat,
@@ -430,6 +443,7 @@ class SwarmRouter:
             "ConcurrentWorkflow": self._create_concurrent_workflow,
             "BatchedGridWorkflow": self._create_batched_grid_workflow,
             "LLMCouncil": self._create_llm_council,
+            "DebateWithJudge": self._create_debate_with_judge,
         }
 
     def _create_heavy_swarm(self, *args, **kwargs):
@@ -457,6 +471,17 @@ class SwarmRouter:
             chairman_model=self.chairman_model,
         )
 
+    def _create_debate_with_judge(self, *args, **kwargs):
+        """Factory function for DebateWithJudge."""
+        return DebateWithJudge(
+            pro_agent=self.agents[0],
+            con_agent=self.agents[1],
+            judge_agent=self.agents[2],
+            max_rounds=self.max_loops,
+            output_type=self.output_type,
+            verbose=self.verbose,
+        )
+
     def _create_agent_rearrange(self, *args, **kwargs):
         """Factory function for AgentRearrange."""
         return AgentRearrange(