[FEAT][DebateWithJudge]

docs/mkdocs.yml

@@ -271,6 +271,7 @@ nav:
         - Overview: "swarms/structs/overview.md"
         - Custom Multi Agent Architectures: "swarms/structs/custom_swarm.md"
         - Debate Multi-Agent Architectures: "swarms/structs/orchestration_methods.md"
+        - DebateWithJudge: "swarms/structs/debate_with_judge.md"
         - MajorityVoting: "swarms/structs/majorityvoting.md"
         - RoundRobin: "swarms/structs/round_robin_swarm.md"
         - Mixture of Agents: "swarms/structs/moa.md"

docs/swarms/structs/debate_with_judge.md

@@ -0,0 +1,677 @@
+# DebateWithJudge Module Documentation
+
+The `DebateWithJudge` module provides a sophisticated debate architecture with self-refinement through a judge agent. This system enables two agents (Pro and Con) to debate a topic, with a Judge agent evaluating their arguments and providing refined synthesis. The process repeats for N rounds to progressively refine the answer.
+
+## Architecture
+
+```mermaid
+graph TD
+    A[DebateWithJudge System] --> B[Initialize Pro, Con, and Judge Agents]
+    B --> C[Start with Initial Topic]
+    C --> D[Round Loop: max_rounds]
+    D --> E[Pro Agent Presents Argument]
+    E --> F[Con Agent Presents Counter-Argument]
+    F --> G[Judge Agent Evaluates Both]
+    G --> H[Judge Provides Synthesis]
+    H --> I{More Rounds?}
+    I -->|Yes| D
+    I -->|No| J[Format Final Output]
+    J --> K[Return Result]
+```
+
+### Key Concepts
+
+| Concept                  | Description                                                                                  |
+|--------------------------|----------------------------------------------------------------------------------------------|
+| Debate Architecture      | A structured process where two agents present opposing arguments on a topic                  |
+| Pro Agent                | The agent arguing in favor of a position                                                     |
+| Con Agent                | The agent arguing against a position                                                        |
+| Judge Agent              | An impartial evaluator that analyzes both arguments and provides synthesis                   |
+| Iterative Refinement     | The process repeats for multiple rounds, each round building upon the judge's previous synthesis |
+| Progressive Improvement  | Each round refines the answer by incorporating feedback and addressing weaknesses            |
+
+## Class Definition: `DebateWithJudge`
+
+```python
+class DebateWithJudge:
+    def __init__(
+        self,
+        pro_agent: Agent,
+        con_agent: Agent,
+        judge_agent: Agent,
+        max_rounds: int = 3,
+        output_type: str = "str-all-except-first",
+        verbose: bool = True,
+    ):
+```
+
+### Constructor Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `pro_agent` | `Agent` | Required | The agent arguing in favor (Pro position) |
+| `con_agent` | `Agent` | Required | The agent arguing against (Con position) |
+| `judge_agent` | `Agent` | Required | The judge agent that evaluates arguments and provides synthesis |
+| `max_rounds` | `int` | `3` | Maximum number of debate rounds to execute |
+| `output_type` | `str` | `"str-all-except-first"` | Format for the output conversation history |
+| `verbose` | `bool` | `True` | Whether to enable verbose logging |
+
+## API Reference
+
+### Core Methods
+
+#### `run(task: str) -> Union[str, List, dict]`
+
+Executes the debate with judge refinement process for a single task and returns the refined result.
+
+**Signature:**
+
+```python
+def run(self, task: str) -> Union[str, List, dict]
+```
+
+**Parameters:**
+
+- `task` (`str`): The initial topic or question to debate
+
+**Returns:**
+
+- `Union[str, List, dict]`: The formatted conversation history or final refined answer, depending on `output_type`
+
+**Process Flow:**
+
+1. **Task Validation**: Validates that the task is a non-empty string
+2. **Agent Initialization**: Initializes all three agents with their respective roles and the initial task context
+3. **Multi-Round Execution**: For each round (up to `max_rounds`):
+   - **Pro Argument**: Pro agent presents an argument in favor of the current topic
+   
+   - **Con Counter-Argument**: Con agent presents a counter-argument, addressing the Pro's points
+   
+   - **Judge Evaluation**: Judge agent evaluates both arguments, identifies strengths and weaknesses
+   
+   - **Synthesis Generation**: Judge provides a refined synthesis that incorporates the best elements from both sides
+   
+   - **Topic Refinement**: Judge's synthesis becomes the topic for the next round
+4. **Result Formatting**: Returns the final result formatted according to `output_type`
+
+**Example:**
+
+```python
+from swarms import Agent, DebateWithJudge
+
+# Create the Pro agent (arguing in favor)
+pro_agent = Agent(
+    agent_name="Pro-Agent",
+    system_prompt=(
+        "You are a skilled debater who argues in favor of positions. "
+        "You present well-reasoned arguments with evidence, examples, "
+        "and logical reasoning. You are persuasive and articulate."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the Con agent (arguing against)
+con_agent = Agent(
+    agent_name="Con-Agent",
+    system_prompt=(
+        "You are a skilled debater who argues against positions. "
+        "You present strong counter-arguments with evidence, examples, "
+        "and logical reasoning. You identify weaknesses in opposing "
+        "arguments and provide compelling alternatives."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the Judge agent (evaluates and synthesizes)
+judge_agent = Agent(
+    agent_name="Judge-Agent",
+    system_prompt=(
+        "You are an impartial judge who evaluates debates. "
+        "You carefully analyze arguments from both sides, identify "
+        "strengths and weaknesses, and provide balanced synthesis. "
+        "You may declare a winner or provide a refined answer that "
+        "incorporates the best elements from both arguments."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the DebateWithJudge system
+debate_system = DebateWithJudge(
+    pro_agent=pro_agent,
+    con_agent=con_agent,
+    judge_agent=judge_agent,
+    max_rounds=3,
+    output_type="str-all-except-first",
+    verbose=True,
+)
+
+# Define the debate topic
+topic = (
+    "Should artificial intelligence be regulated by governments? "
+    "Discuss the balance between innovation and safety."
+)
+
+# Run the debate
+result = debate_system.run(task=topic)
+print(result)
+```
+
+**Raises:**
+
+- `ValueError`: If task is None or empty, or if any required agents are None, or if max_rounds is less than 1
+
+---
+
+#### `batched_run(tasks: List[str]) -> List[str]`
+
+Executes the debate with judge refinement process for multiple tasks sequentially, processing each task through the complete multi-round debate process.
+
+**Signature:**
+
+```python
+def batched_run(self, tasks: List[str]) -> List[str]
+```
+
+**Parameters:**
+
+- `tasks` (`List[str]`): List of topics or questions to debate
+
+**Returns:**
+
+- `List[str]`: List of final refined answers, one for each input task
+
+**Process Flow:**
+
+1. **Sequential Processing**: Processes each task in the input list one by one
+2. **Independent Execution**: Each task runs through the complete multi-round debate process independently
+3. **Result Collection**: Collects and returns all results in the same order as input tasks
+
+**Example:**
+
+```python
+# Define multiple debate topics
+debate_topics = [
+    "Should remote work become the standard for knowledge workers?",
+    "Is cryptocurrency a viable alternative to traditional banking?",
+    "Should social media platforms be held accountable for content moderation?",
+    "Are electric vehicles the future of transportation?"
+]
+
+# Execute batch processing
+results = debate_system.batched_run(debate_topics)
+
+# Process results
+for topic, result in zip(debate_topics, results):
+    print(result)
+```
+
+**Performance Considerations:**
+
+| Consideration                               | Description                                                               |
+|---------------------------------------------|---------------------------------------------------------------------------|
+| Sequential Processing                      | Tasks are processed one after another, not in parallel                    |
+| Independent Conversation History           | Each task maintains its own conversation history                          |
+| Memory Usage                               | Scales with the number of tasks and the length of each conversation       |
+| Total Execution Time                       | Equals the sum of all individual task execution times                     |
+
+---
+
+### Helper Methods
+
+#### `get_conversation_history() -> List[dict]`
+
+Get the full conversation history from the debate.
+
+**Signature:**
+
+```python
+def get_conversation_history(self) -> List[dict]
+```
+
+**Returns:**
+
+- `List[dict]`: List of message dictionaries containing the conversation history
+
+**Example:**
+
+```python
+# Run a debate
+result = debate_system.run("Should AI be regulated?")
+
+# Get the full conversation history
+history = debate_system.get_conversation_history()
+print(history)
+```
+
+---
+
+#### `get_final_answer() -> str`
+
+Get the final refined answer from the judge.
+
+**Signature:**
+
+```python
+def get_final_answer(self) -> str
+```
+
+**Returns:**
+
+- `str`: The content of the final judge synthesis
+
+**Example:**
+
+```python
+# Run a debate
+result = debate_system.run("Should AI be regulated?")
+
+# Get just the final answer
+final_answer = debate_system.get_final_answer()
+print(final_answer)
+```
+
+---
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pro_agent` | `Agent` | The agent arguing in favor (Pro position) |
+| `con_agent` | `Agent` | The agent arguing against (Con position) |
+| `judge_agent` | `Agent` | The judge agent that evaluates arguments |
+| `max_rounds` | `int` | Maximum number of debate rounds |
+| `output_type` | `str` | Format for returned results |
+| `verbose` | `bool` | Whether verbose logging is enabled |
+| `conversation` | `Conversation` | Conversation history management object |
+
+## Output Types
+
+The `output_type` parameter controls how the conversation history is formatted:
+
+| `output_type` Value         | Description                                                  |
+|----------------------------|--------------------------------------------------------------|
+| `"str-all-except-first"`    | Returns a formatted string with all messages except the first (default) |
+| `"str"`                    | Returns all messages as a formatted string                   |
+| `"dict"`                   | Returns messages as a dictionary                            |
+| `"list"`                   | Returns messages as a list                                  |
+
+
+## Usage Patterns
+
+### Single Topic Debate
+
+For focused debate and refinement on a single complex topic:
+
+```python
+# Simple single topic execution
+result = debate_system.run("Should universal basic income be implemented?")
+
+# With custom output format
+debate_system.output_type = "dict"
+result = debate_system.run("Should universal basic income be implemented?")
+```
+
+### Batch Processing
+
+For processing multiple related topics sequentially:
+
+```python
+# Process multiple policy questions
+policy_topics = [
+    "Should healthcare be universal?",
+    "Should education be free?",
+    "Should carbon emissions be taxed?"
+]
+results = debate_system.batched_run(policy_topics)
+```
+
+### Custom Agent Configuration
+
+For specialized debate scenarios with custom agent prompts:
+
+```python
+# Create specialized agents for technical debates
+technical_pro = Agent(
+    agent_name="Technical-Pro",
+    system_prompt="You are a software engineering expert arguing for technical solutions...",
+    model_name="gpt-4",
+    max_loops=1,
+)
+
+technical_con = Agent(
+    agent_name="Technical-Con",
+    system_prompt="You are a software engineering expert arguing against technical solutions...",
+    model_name="gpt-4",
+    max_loops=1,
+)
+
+technical_judge = Agent(
+    agent_name="Technical-Judge",
+    system_prompt="You are a senior software architect evaluating technical arguments...",
+    model_name="gpt-4",
+    max_loops=1,
+)
+
+technical_debate = DebateWithJudge(
+    pro_agent=technical_pro,
+    con_agent=technical_con,
+    judge_agent=technical_judge,
+    max_rounds=5,  # More rounds for complex technical topics
+    verbose=True,
+)
+```
+
+## Usage Examples
+
+### Example 1: Policy Debate on AI Regulation
+
+This example demonstrates using `DebateWithJudge` for a comprehensive policy debate on AI regulation, with multiple rounds of refinement.
+
+```python
+from swarms import Agent, DebateWithJudge
+
+# Create the Pro agent (arguing in favor of AI regulation)
+pro_agent = Agent(
+    agent_name="Pro-Regulation-Agent",
+    system_prompt=(
+        "You are a policy expert specializing in technology regulation. "
+        "You argue in favor of government regulation of artificial intelligence. "
+        "You present well-reasoned arguments focusing on safety, ethics, "
+        "and public interest. You use evidence, examples, and logical reasoning. "
+        "You are persuasive and articulate, emphasizing the need for oversight "
+        "to prevent harm and ensure responsible AI development."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the Con agent (arguing against AI regulation)
+con_agent = Agent(
+    agent_name="Anti-Regulation-Agent",
+    system_prompt=(
+        "You are a technology policy expert specializing in innovation. "
+        "You argue against heavy government regulation of artificial intelligence. "
+        "You present strong counter-arguments focusing on innovation, economic growth, "
+        "and the risks of over-regulation. You identify weaknesses in regulatory "
+        "proposals and provide compelling alternatives such as industry self-regulation "
+        "and ethical guidelines. You emphasize the importance of maintaining "
+        "technological competitiveness."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the Judge agent (evaluates and synthesizes)
+judge_agent = Agent(
+    agent_name="Policy-Judge-Agent",
+    system_prompt=(
+        "You are an impartial policy analyst and judge who evaluates debates on "
+        "technology policy. You carefully analyze arguments from both sides, "
+        "identify strengths and weaknesses, and provide balanced synthesis. "
+        "You consider multiple perspectives including safety, innovation, economic impact, "
+        "and ethical considerations. You may declare a winner or provide a refined "
+        "answer that incorporates the best elements from both arguments, such as "
+        "balanced regulatory frameworks that protect public interest while fostering innovation."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the DebateWithJudge system
+debate_system = DebateWithJudge(
+    pro_agent=pro_agent,
+    con_agent=con_agent,
+    judge_agent=judge_agent,
+    max_rounds=3,
+    output_type="str-all-except-first",
+    verbose=True,
+)
+
+# Define the debate topic
+topic = (
+    "Should artificial intelligence be regulated by governments? "
+    "Discuss the balance between innovation and safety, considering "
+    "both the potential benefits of regulation (safety, ethics, public trust) "
+    "and the potential drawbacks (stifling innovation, economic impact, "
+    "regulatory capture). Provide a nuanced analysis."
+)
+
+# Run the debate
+result = debate_system.run(task=topic)
+print(result)
+
+# Get the final refined answer
+final_answer = debate_system.get_final_answer()
+print(final_answer)
+```
+
+### Example 2: Technical Architecture Debate with Batch Processing
+
+This example demonstrates using `batched_run` to process multiple technical architecture questions, comparing different approaches to system design.
+
+```python
+from swarms import Agent, DebateWithJudge
+
+# Create specialized technical agents
+pro_agent = Agent(
+    agent_name="Microservices-Pro",
+    system_prompt=(
+        "You are a software architecture expert advocating for microservices architecture. "
+        "You present arguments focusing on scalability, independent deployment, "
+        "technology diversity, and team autonomy. You use real-world examples and "
+        "case studies to support your position."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+con_agent = Agent(
+    agent_name="Monolith-Pro",
+    system_prompt=(
+        "You are a software architecture expert advocating for monolithic architecture. "
+        "You present counter-arguments focusing on simplicity, reduced complexity, "
+        "easier debugging, and lower operational overhead. You identify weaknesses "
+        "in microservices approaches and provide compelling alternatives."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+judge_agent = Agent(
+    agent_name="Architecture-Judge",
+    system_prompt=(
+        "You are a senior software architect evaluating architecture debates. "
+        "You analyze both arguments considering factors like team size, project scale, "
+        "complexity, operational capabilities, and long-term maintainability. "
+        "You provide balanced synthesis that considers context-specific trade-offs."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the debate system
+architecture_debate = DebateWithJudge(
+    pro_agent=pro_agent,
+    con_agent=con_agent,
+    judge_agent=judge_agent,
+    max_rounds=2,  # Fewer rounds for more focused technical debates
+    output_type="str-all-except-first",
+    verbose=True,
+)
+
+# Define multiple architecture questions
+architecture_questions = [
+    "Should a startup with 5 developers use microservices or monolithic architecture?",
+    "Is serverless architecture better than containerized deployments for event-driven systems?",
+    "Should a financial application use SQL or NoSQL databases for transaction processing?",
+    "Is event-driven architecture superior to request-response for real-time systems?",
+]
+
+# Execute batch processing
+results = architecture_debate.batched_run(architecture_questions)
+
+# Display results
+for result in results:
+    print(result)
+```
+
+### Example 3: Business Strategy Debate with Custom Configuration
+
+This example demonstrates a business strategy debate with custom agent configurations, multiple rounds, and accessing conversation history.
+
+```python
+from swarms import Agent, DebateWithJudge
+
+# Create business strategy agents with detailed expertise
+pro_agent = Agent(
+    agent_name="Growth-Strategy-Pro",
+    system_prompt=(
+        "You are a business strategy consultant specializing in aggressive growth strategies. "
+        "You argue in favor of rapid expansion, market penetration, and scaling. "
+        "You present arguments focusing on first-mover advantages, market share capture, "
+        "network effects, and competitive positioning. You use case studies from "
+        "successful companies like Amazon, Uber, and Airbnb to support your position."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+con_agent = Agent(
+    agent_name="Sustainable-Growth-Pro",
+    system_prompt=(
+        "You are a business strategy consultant specializing in sustainable, profitable growth. "
+        "You argue against aggressive expansion in favor of measured, sustainable growth. "
+        "You present counter-arguments focusing on profitability, unit economics, "
+        "sustainable competitive advantages, and avoiding overextension. You identify "
+        "weaknesses in 'growth at all costs' approaches and provide compelling alternatives "
+        "based on companies like Apple, Microsoft, and Berkshire Hathaway."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+judge_agent = Agent(
+    agent_name="Strategy-Judge",
+    system_prompt=(
+        "You are a seasoned business strategist and former CEO evaluating growth strategy debates. "
+        "You carefully analyze arguments from both sides, considering factors like: "
+        "- Market conditions and competitive landscape\n"
+        "- Company resources and capabilities\n"
+        "- Risk tolerance and financial position\n"
+        "- Long-term sustainability vs. short-term growth\n"
+        "- Industry-specific dynamics\n\n"
+        "You provide balanced synthesis that incorporates the best elements from both arguments, "
+        "considering context-specific factors. You may recommend a hybrid approach when appropriate."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the debate system with extended rounds for complex strategy discussions
+strategy_debate = DebateWithJudge(
+    pro_agent=pro_agent,
+    con_agent=con_agent,
+    judge_agent=judge_agent,
+    max_rounds=4,  # More rounds for complex strategic discussions
+    output_type="dict",  # Use dict format for structured analysis
+    verbose=True,
+)
+
+# Define a complex business strategy question
+strategy_question = (
+    "A SaaS startup with $2M ARR, 40% gross margins, and $500K in the bank "
+    "is considering two paths:\n"
+    "1. Aggressive growth: Raise $10M, hire 50 people, expand to 5 new markets\n"
+    "2. Sustainable growth: Focus on profitability, improve unit economics, "
+    "expand gradually with existing resources\n\n"
+    "Which strategy should they pursue? Consider market conditions, competitive "
+    "landscape, and long-term viability."
+)
+
+# Run the debate
+result = strategy_debate.run(task=strategy_question)
+print(result)
+
+# Get the full conversation history for detailed analysis
+history = strategy_debate.get_conversation_history()
+print(history)
+
+# Get the final refined answer
+final_answer = strategy_debate.get_final_answer()
+print(final_answer)
+```
+
+## Best Practices
+
+### Agent Configuration
+
+!!! tip "Agent Configuration Best Practices"
+    - **Pro Agent**: Should be configured with expertise in the topic area and strong argumentation skills
+    - **Con Agent**: Should be configured to identify weaknesses and provide compelling alternatives
+    - **Judge Agent**: Should be configured with broad expertise and impartial evaluation capabilities
+    - Use appropriate models for the complexity of the debate topic
+    - Consider using more powerful models for the Judge agent
+
+### Round Configuration
+
+!!! note "Round Configuration Tips"
+    - Use 2-3 rounds for most topics
+    - Use 4-5 rounds for complex, multi-faceted topics
+    - More rounds allow for deeper refinement but increase execution time
+    - Consider the trade-off between refinement quality and cost
+
+### Output Format Selection
+
+!!! info "Output Format Guidelines"
+    - Use `"str-all-except-first"` for readable summaries (default)
+    - Use `"dict"` for structured analysis and programmatic processing
+    - Use `"list"` for detailed conversation inspection
+    - Use `"str"` for complete conversation history as text
+
+### Performance Optimization
+
+!!! warning "Performance Considerations"
+    - Batch processing is sequential - consider parallel execution for large batches
+    - Each round requires 3 agent calls (Pro, Con, Judge)
+    - Memory usage scales with conversation history length
+    - Consider using lighter models for faster execution when appropriate
+
+## Troubleshooting
+
+### Common Issues
+
+!!! danger "Common Problems"
+    **Issue**: Agents not following their roles
+
+    **Solution**: Ensure system prompts clearly define each agent's role and expertise
+
+    ---
+
+    **Issue**: Judge synthesis not improving over rounds
+
+    **Solution**: Increase `max_rounds` or improve Judge agent's system prompt to emphasize refinement
+
+    ---
+
+    **Issue**: Debate results are too generic
+
+    **Solution**: Use more specific system prompts and provide detailed context in the task
+
+    ---
+
+    **Issue**: Execution time is too long
+
+    **Solution**: Reduce `max_rounds`, use faster models, or process fewer topics in batch
+
+## Contributing
+
+!!! success "Contributing"
+    Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+!!! info "License"
+    This project is licensed under the MIT License - see the LICENSE file for details.

examples/multi_agent/debate_examples/README.md

@@ -6,7 +6,49 @@ This directory contains examples demonstrating debate patterns for multi-agent s
 
 Debate patterns enable agents to engage in structured discussions, present arguments, and reach conclusions through discourse. This pattern is useful for exploring multiple perspectives on complex topics and arriving at well-reasoned decisions.
 
-## Note
+## Examples
 
-This directory is currently being populated with debate examples. Check back soon for implementations!
+### DebateWithJudge
+
+The `DebateWithJudge` architecture implements a debate system with self-refinement:
+
+- **Agent A (Pro)** and **Agent B (Con)** present opposing arguments
+- Both arguments are evaluated by a **Judge/Critic Agent**
+- The Judge provides a winner or synthesis → refined answer
+- The process repeats for N rounds to progressively improve the answer
+
+**Architecture Flow:**
+```
+Agent A (Pro) ↔ Agent B (Con)
+      │            │
+      ▼            ▼
+   Judge / Critic Agent
+      │
+      ▼
+Winner or synthesis → refined answer
+```
+
+**Example Usage:**
+```python
+from swarms import Agent
+from swarms.structs.debate_with_judge import DebateWithJudge
+
+# Create Pro, Con, and Judge agents
+pro_agent = Agent(agent_name="Pro-Agent", ...)
+con_agent = Agent(agent_name="Con-Agent", ...)
+judge_agent = Agent(agent_name="Judge-Agent", ...)
+
+# Create debate system
+debate = DebateWithJudge(
+    pro_agent=pro_agent,
+    con_agent=con_agent,
+    judge_agent=judge_agent,
+    max_rounds=3
+)
+
+# Run debate
+result = debate.run("Should AI be regulated?")
+```
+
+See [debate_with_judge_example.py](./debate_with_judge_example.py) for a complete example.
 

examples/multi_agent/debate_examples/business_strategy_debate_example.py

@@ -0,0 +1,87 @@
+"""
+Example 3: Business Strategy Debate with Custom Configuration
+
+This example demonstrates a business strategy debate with custom agent configurations,
+multiple rounds, and accessing conversation history.
+"""
+
+from swarms import Agent, DebateWithJudge
+
+# Create business strategy agents with detailed expertise
+pro_agent = Agent(
+    agent_name="Growth-Strategy-Pro",
+    system_prompt=(
+        "You are a business strategy consultant specializing in aggressive growth strategies. "
+        "You argue in favor of rapid expansion, market penetration, and scaling. "
+        "You present arguments focusing on first-mover advantages, market share capture, "
+        "network effects, and competitive positioning. You use case studies from "
+        "successful companies like Amazon, Uber, and Airbnb to support your position."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+con_agent = Agent(
+    agent_name="Sustainable-Growth-Pro",
+    system_prompt=(
+        "You are a business strategy consultant specializing in sustainable, profitable growth. "
+        "You argue against aggressive expansion in favor of measured, sustainable growth. "
+        "You present counter-arguments focusing on profitability, unit economics, "
+        "sustainable competitive advantages, and avoiding overextension. You identify "
+        "weaknesses in 'growth at all costs' approaches and provide compelling alternatives "
+        "based on companies like Apple, Microsoft, and Berkshire Hathaway."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+judge_agent = Agent(
+    agent_name="Strategy-Judge",
+    system_prompt=(
+        "You are a seasoned business strategist and former CEO evaluating growth strategy debates. "
+        "You carefully analyze arguments from both sides, considering factors like: "
+        "- Market conditions and competitive landscape\n"
+        "- Company resources and capabilities\n"
+        "- Risk tolerance and financial position\n"
+        "- Long-term sustainability vs. short-term growth\n"
+        "- Industry-specific dynamics\n\n"
+        "You provide balanced synthesis that incorporates the best elements from both arguments, "
+        "considering context-specific factors. You may recommend a hybrid approach when appropriate."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the debate system with extended rounds for complex strategy discussions
+strategy_debate = DebateWithJudge(
+    pro_agent=pro_agent,
+    con_agent=con_agent,
+    judge_agent=judge_agent,
+    max_rounds=4,  # More rounds for complex strategic discussions
+    output_type="dict",  # Use dict format for structured analysis
+    verbose=True,
+)
+
+# Define a complex business strategy question
+strategy_question = (
+    "A SaaS startup with $2M ARR, 40% gross margins, and $500K in the bank "
+    "is considering two paths:\n"
+    "1. Aggressive growth: Raise $10M, hire 50 people, expand to 5 new markets\n"
+    "2. Sustainable growth: Focus on profitability, improve unit economics, "
+    "expand gradually with existing resources\n\n"
+    "Which strategy should they pursue? Consider market conditions, competitive "
+    "landscape, and long-term viability."
+)
+
+# Run the debate
+result = strategy_debate.run(task=strategy_question)
+print(result)
+
+# Get the full conversation history for detailed analysis
+history = strategy_debate.get_conversation_history()
+print(history)
+
+# Get the final refined answer
+final_answer = strategy_debate.get_final_answer()
+print(final_answer)
+

examples/multi_agent/debate_examples/debate_with_judge_example.py

@@ -0,0 +1,61 @@
+from swarms import Agent, DebateWithJudge
+
+# Create the Pro agent (arguing in favor)
+pro_agent = Agent(
+    agent_name="Pro-Agent",
+    system_prompt=(
+        "You are a skilled debater who argues in favor of positions. "
+        "You present well-reasoned arguments with evidence, examples, "
+        "and logical reasoning. You are persuasive and articulate."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the Con agent (arguing against)
+con_agent = Agent(
+    agent_name="Con-Agent",
+    system_prompt=(
+        "You are a skilled debater who argues against positions. "
+        "You present strong counter-arguments with evidence, examples, "
+        "and logical reasoning. You identify weaknesses in opposing "
+        "arguments and provide compelling alternatives."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the Judge agent (evaluates and synthesizes)
+judge_agent = Agent(
+    agent_name="Judge-Agent",
+    system_prompt=(
+        "You are an impartial judge who evaluates debates. "
+        "You carefully analyze arguments from both sides, identify "
+        "strengths and weaknesses, and provide balanced synthesis. "
+        "You may declare a winner or provide a refined answer that "
+        "incorporates the best elements from both arguments."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the DebateWithJudge system
+debate_system = DebateWithJudge(
+    pro_agent=pro_agent,
+    con_agent=con_agent,
+    judge_agent=judge_agent,
+    max_rounds=3,  # Run 3 rounds of debate and refinement
+    output_type="str-all-except-first",  # Return as formatted string
+    verbose=True,  # Enable verbose logging
+)
+
+# Define the debate topic
+topic = (
+    "Should artificial intelligence be regulated by governments? "
+    "Discuss the balance between innovation and safety."
+)
+
+# Run the debate
+result = debate_system.run(task=topic)
+
+print(result)

examples/multi_agent/debate_examples/policy_debate_example.py

@@ -0,0 +1,83 @@
+"""
+Example 1: Policy Debate on AI Regulation
+
+This example demonstrates using DebateWithJudge for a comprehensive policy debate
+on AI regulation, with multiple rounds of refinement.
+"""
+
+from swarms import Agent, DebateWithJudge
+
+# Create the Pro agent (arguing in favor of AI regulation)
+pro_agent = Agent(
+    agent_name="Pro-Regulation-Agent",
+    system_prompt=(
+        "You are a policy expert specializing in technology regulation. "
+        "You argue in favor of government regulation of artificial intelligence. "
+        "You present well-reasoned arguments focusing on safety, ethics, "
+        "and public interest. You use evidence, examples, and logical reasoning. "
+        "You are persuasive and articulate, emphasizing the need for oversight "
+        "to prevent harm and ensure responsible AI development."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the Con agent (arguing against AI regulation)
+con_agent = Agent(
+    agent_name="Anti-Regulation-Agent",
+    system_prompt=(
+        "You are a technology policy expert specializing in innovation. "
+        "You argue against heavy government regulation of artificial intelligence. "
+        "You present strong counter-arguments focusing on innovation, economic growth, "
+        "and the risks of over-regulation. You identify weaknesses in regulatory "
+        "proposals and provide compelling alternatives such as industry self-regulation "
+        "and ethical guidelines. You emphasize the importance of maintaining "
+        "technological competitiveness."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the Judge agent (evaluates and synthesizes)
+judge_agent = Agent(
+    agent_name="Policy-Judge-Agent",
+    system_prompt=(
+        "You are an impartial policy analyst and judge who evaluates debates on "
+        "technology policy. You carefully analyze arguments from both sides, "
+        "identify strengths and weaknesses, and provide balanced synthesis. "
+        "You consider multiple perspectives including safety, innovation, economic impact, "
+        "and ethical considerations. You may declare a winner or provide a refined "
+        "answer that incorporates the best elements from both arguments, such as "
+        "balanced regulatory frameworks that protect public interest while fostering innovation."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the DebateWithJudge system
+debate_system = DebateWithJudge(
+    pro_agent=pro_agent,
+    con_agent=con_agent,
+    judge_agent=judge_agent,
+    max_rounds=3,
+    output_type="str-all-except-first",
+    verbose=True,
+)
+
+# Define the debate topic
+topic = (
+    "Should artificial intelligence be regulated by governments? "
+    "Discuss the balance between innovation and safety, considering "
+    "both the potential benefits of regulation (safety, ethics, public trust) "
+    "and the potential drawbacks (stifling innovation, economic impact, "
+    "regulatory capture). Provide a nuanced analysis."
+)
+
+# Run the debate
+result = debate_system.run(task=topic)
+print(result)
+
+# Get the final refined answer
+final_answer = debate_system.get_final_answer()
+print(final_answer)
+

examples/multi_agent/debate_examples/technical_architecture_debate_example.py

@@ -0,0 +1,71 @@
+"""
+Example 2: Technical Architecture Debate with Batch Processing
+
+This example demonstrates using batched_run to process multiple technical
+architecture questions, comparing different approaches to system design.
+"""
+
+from swarms import Agent, DebateWithJudge
+
+# Create specialized technical agents
+pro_agent = Agent(
+    agent_name="Microservices-Pro",
+    system_prompt=(
+        "You are a software architecture expert advocating for microservices architecture. "
+        "You present arguments focusing on scalability, independent deployment, "
+        "technology diversity, and team autonomy. You use real-world examples and "
+        "case studies to support your position."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+con_agent = Agent(
+    agent_name="Monolith-Pro",
+    system_prompt=(
+        "You are a software architecture expert advocating for monolithic architecture. "
+        "You present counter-arguments focusing on simplicity, reduced complexity, "
+        "easier debugging, and lower operational overhead. You identify weaknesses "
+        "in microservices approaches and provide compelling alternatives."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+judge_agent = Agent(
+    agent_name="Architecture-Judge",
+    system_prompt=(
+        "You are a senior software architect evaluating architecture debates. "
+        "You analyze both arguments considering factors like team size, project scale, "
+        "complexity, operational capabilities, and long-term maintainability. "
+        "You provide balanced synthesis that considers context-specific trade-offs."
+    ),
+    model_name="gpt-4o-mini",
+    max_loops=1,
+)
+
+# Create the debate system
+architecture_debate = DebateWithJudge(
+    pro_agent=pro_agent,
+    con_agent=con_agent,
+    judge_agent=judge_agent,
+    max_rounds=2,  # Fewer rounds for more focused technical debates
+    output_type="str-all-except-first",
+    verbose=True,
+)
+
+# Define multiple architecture questions
+architecture_questions = [
+    "Should a startup with 5 developers use microservices or monolithic architecture?",
+    "Is serverless architecture better than containerized deployments for event-driven systems?",
+    "Should a financial application use SQL or NoSQL databases for transaction processing?",
+    "Is event-driven architecture superior to request-response for real-time systems?",
+]
+
+# Execute batch processing
+results = architecture_debate.batched_run(architecture_questions)
+
+# Display results
+for result in results:
+    print(result)
+

examples/reasoning_agents/reasoning_agent_router_examples/ire_example.py

@@ -8,4 +8,3 @@ router = ReasoningAgentRouter(
 
 result = router.run("Explain photosynthesis in one sentence.")
 print(result)
-

swarms/structs/__init__.py

@@ -11,6 +11,7 @@ from swarms.structs.concurrent_workflow import ConcurrentWorkflow
 from swarms.structs.conversation import Conversation
 from swarms.structs.council_as_judge import CouncilAsAJudge
 from swarms.structs.cron_job import CronJob
+from swarms.structs.debate_with_judge import DebateWithJudge
 from swarms.structs.graph_workflow import (
     Edge,
     GraphWorkflow,
@@ -186,4 +187,5 @@ __all__ = [
     "BatchedGridWorkflow",
     "AOP",
     "SelfMoASeq",
+    "DebateWithJudge",
 ]

swarms/structs/debate_with_judge.py

@@ -0,0 +1,346 @@
+"""
+Debate/Self-Refinement with Judge Architecture
+
+This module implements a debate architecture where two agents (Pro and Con)
+debate a topic, and a Judge agent evaluates their arguments and provides
+refined synthesis. The process repeats for N rounds to progressively refine
+the answer.
+"""
+
+from typing import List, Union
+
+from loguru import logger
+
+from swarms.structs.agent import Agent
+from swarms.structs.conversation import Conversation
+from swarms.utils.history_output_formatter import (
+    history_output_formatter,
+)
+
+
+class DebateWithJudge:
+    """
+    A debate architecture with self-refinement through a judge agent.
+
+    This class implements a debate system where:
+    1. Agent A (Pro) and Agent B (Con) present opposing arguments
+    2. Both arguments are evaluated by a Judge/Critic Agent
+    3. The Judge provides a winner or synthesis → refined answer
+    4. The process repeats for N rounds to progressively improve the answer
+
+    Architecture:
+        Agent A (Pro) ↔ Agent B (Con)
+              │            │
+              ▼            ▼
+           Judge / Critic Agent
+              │
+              ▼
+        Winner or synthesis → refined answer
+
+    Attributes:
+        pro_agent (Agent): The agent arguing in favor (Pro position).
+        con_agent (Agent): The agent arguing against (Con position).
+        judge_agent (Agent): The judge agent that evaluates arguments and provides synthesis.
+        max_rounds (int): Maximum number of debate rounds to execute.
+        output_type (str): Format for the output conversation history.
+        verbose (bool): Whether to enable verbose logging.
+    """
+
+    def __init__(
+        self,
+        pro_agent: Agent,
+        con_agent: Agent,
+        judge_agent: Agent,
+        max_rounds: int = 3,
+        output_type: str = "str-all-except-first",
+        verbose: bool = True,
+    ):
+        """
+        Initialize the DebateWithJudge architecture.
+
+        Args:
+            pro_agent (Agent): The agent arguing in favor (Pro position).
+            con_agent (Agent): The agent arguing against (Con position).
+            judge_agent (Agent): The judge agent that evaluates arguments and provides synthesis.
+            max_rounds (int): Maximum number of debate rounds to execute. Defaults to 3.
+            output_type (str): Format for the output conversation history. Defaults to "str-all-except-first".
+            verbose (bool): Whether to enable verbose logging. Defaults to True.
+
+        Raises:
+            ValueError: If any of the required agents are None or if max_rounds is less than 1.
+        """
+        if pro_agent is None:
+            raise ValueError("pro_agent cannot be None")
+        if con_agent is None:
+            raise ValueError("con_agent cannot be None")
+        if judge_agent is None:
+            raise ValueError("judge_agent cannot be None")
+        if max_rounds < 1:
+            raise ValueError("max_rounds must be at least 1")
+
+        self.pro_agent = pro_agent
+        self.con_agent = con_agent
+        self.judge_agent = judge_agent
+        self.max_rounds = max_rounds
+        self.output_type = output_type
+        self.verbose = verbose
+
+        # Initialize conversation history
+        self.conversation = Conversation()
+
+        if self.verbose:
+            logger.info(
+                f"DebateWithJudge initialized with {max_rounds} rounds"
+            )
+
+    def run(self, task: str) -> Union[str, List, dict]:
+        """
+        Execute the debate with judge refinement process.
+
+        Args:
+            task (str): The initial topic or question to debate.
+
+        Returns:
+            Union[str, List, dict]: The formatted conversation history or final refined answer,
+                depending on output_type.
+
+        Raises:
+            ValueError: If task is None or empty.
+        """
+        if not task or not isinstance(task, str):
+            raise ValueError("Task must be a non-empty string")
+
+        # Initialize agents with their roles
+        self._initialize_agents(task)
+
+        # Start with the initial task
+        current_topic = task
+
+        if self.verbose:
+            logger.info(f"Starting debate on: {task}")
+
+        # Execute N rounds of debate and refinement
+        for round_num in range(self.max_rounds):
+            if self.verbose:
+                logger.info(
+                    f"Round {round_num + 1}/{self.max_rounds}"
+                )
+
+            # Step 1: Pro agent presents argument
+            pro_prompt = self._create_pro_prompt(
+                current_topic, round_num
+            )
+            pro_argument = self.pro_agent.run(task=pro_prompt)
+            self.conversation.add(
+                self.pro_agent.agent_name, pro_argument
+            )
+
+            if self.verbose:
+                logger.debug(f"Pro argument: {pro_argument[:100]}...")
+
+            # Step 2: Con agent presents counter-argument
+            con_prompt = self._create_con_prompt(
+                current_topic, pro_argument, round_num
+            )
+            con_argument = self.con_agent.run(task=con_prompt)
+            self.conversation.add(
+                self.con_agent.agent_name, con_argument
+            )
+
+            if self.verbose:
+                logger.debug(f"Con argument: {con_argument[:100]}...")
+
+            # Step 3: Judge evaluates both arguments and provides synthesis
+            judge_prompt = self._create_judge_prompt(
+                current_topic, pro_argument, con_argument, round_num
+            )
+            judge_synthesis = self.judge_agent.run(task=judge_prompt)
+            self.conversation.add(
+                self.judge_agent.agent_name, judge_synthesis
+            )
+
+            if self.verbose:
+                logger.debug(
+                    f"Judge synthesis: {judge_synthesis[:100]}..."
+                )
+
+            # Use judge's synthesis as input for next round
+            current_topic = judge_synthesis
+
+        # Return formatted output
+        return history_output_formatter(
+            conversation=self.conversation, type=self.output_type
+        )
+
+    def _initialize_agents(self, task: str) -> None:
+        """
+        Initialize agents with their respective roles and context.
+
+        Args:
+            task (str): The initial task/topic for context.
+        """
+        # Initialize Pro agent
+        pro_intro = (
+            f"You are {self.pro_agent.agent_name}, arguing in favor (Pro position) "
+            f"of the topic: {task}. Your role is to present strong, well-reasoned "
+            f"arguments supporting your position. You will debate against "
+            f"{self.con_agent.agent_name}, who will argue against your position. "
+            f"A judge ({self.judge_agent.agent_name}) will evaluate both arguments "
+            f"and provide synthesis. Present compelling evidence and reasoning."
+        )
+        self.pro_agent.run(task=pro_intro)
+
+        # Initialize Con agent
+        con_intro = (
+            f"You are {self.con_agent.agent_name}, arguing against (Con position) "
+            f"of the topic: {task}. Your role is to present strong, well-reasoned "
+            f"counter-arguments. You will debate against {self.pro_agent.agent_name}, "
+            f"who will argue in favor. A judge ({self.judge_agent.agent_name}) will "
+            f"evaluate both arguments and provide synthesis. Present compelling "
+            f"counter-evidence and reasoning."
+        )
+        self.con_agent.run(task=con_intro)
+
+        # Initialize Judge agent
+        judge_intro = (
+            f"You are {self.judge_agent.agent_name}, an impartial judge evaluating "
+            f"a debate between {self.pro_agent.agent_name} (Pro) and "
+            f"{self.con_agent.agent_name} (Con) on the topic: {task}. "
+            f"Your role is to carefully evaluate both arguments, identify strengths "
+            f"and weaknesses, and provide a refined synthesis that incorporates the "
+            f"best elements from both sides. You may declare a winner or provide a "
+            f"balanced synthesis. Your output will be used to refine the discussion "
+            f"in subsequent rounds."
+        )
+        self.judge_agent.run(task=judge_intro)
+
+    def _create_pro_prompt(self, topic: str, round_num: int) -> str:
+        """
+        Create the prompt for the Pro agent.
+
+        Args:
+            topic (str): The current topic or refined question.
+            round_num (int): The current round number (0-indexed).
+
+        Returns:
+            str: The prompt for the Pro agent.
+        """
+        if round_num == 0:
+            return (
+                f"Present your argument in favor of: {topic}\n\n"
+                f"Provide a strong, well-reasoned argument with evidence and examples."
+            )
+        else:
+            return (
+                f"Round {round_num + 1}: Based on the judge's previous evaluation, "
+                f"present an improved argument in favor of: {topic}\n\n"
+                f"Address any weaknesses identified and strengthen your position "
+                f"with additional evidence and reasoning."
+            )
+
+    def _create_con_prompt(
+        self, topic: str, pro_argument: str, round_num: int
+    ) -> str:
+        """
+        Create the prompt for the Con agent.
+
+        Args:
+            topic (str): The current topic or refined question.
+            pro_argument (str): The Pro agent's argument to counter.
+            round_num (int): The current round number (0-indexed).
+
+        Returns:
+            str: The prompt for the Con agent.
+        """
+        if round_num == 0:
+            return (
+                f"Present your counter-argument against: {topic}\n\n"
+                f"Pro's argument:\n{pro_argument}\n\n"
+                f"Provide a strong, well-reasoned counter-argument that addresses "
+                f"the Pro's points and presents evidence against the position."
+            )
+        else:
+            return (
+                f"Round {round_num + 1}: Based on the judge's previous evaluation, "
+                f"present an improved counter-argument against: {topic}\n\n"
+                f"Pro's current argument:\n{pro_argument}\n\n"
+                f"Address any weaknesses identified and strengthen your counter-position "
+                f"with additional evidence and reasoning."
+            )
+
+    def _create_judge_prompt(
+        self,
+        topic: str,
+        pro_argument: str,
+        con_argument: str,
+        round_num: int,
+    ) -> str:
+        """
+        Create the prompt for the Judge agent.
+
+        Args:
+            topic (str): The current topic or refined question.
+            pro_argument (str): The Pro agent's argument.
+            con_argument (str): The Con agent's argument.
+            round_num (int): The current round number (0-indexed).
+
+        Returns:
+            str: The prompt for the Judge agent.
+        """
+        is_final_round = round_num == self.max_rounds - 1
+
+        prompt = (
+            f"Round {round_num + 1}/{self.max_rounds}: Evaluate the debate on: {topic}\n\n"
+            f"Pro's argument ({self.pro_agent.agent_name}):\n{pro_argument}\n\n"
+            f"Con's argument ({self.con_agent.agent_name}):\n{con_argument}\n\n"
+        )
+
+        if is_final_round:
+            prompt += (
+                "This is the final round. Provide a comprehensive final evaluation:\n"
+                "- Identify the strongest points from both sides\n"
+                "- Determine a winner OR provide a balanced synthesis\n"
+                "- Present a refined, well-reasoned answer that incorporates the best "
+                "elements from both arguments\n"
+                "- This will be the final output of the debate"
+            )
+        else:
+            prompt += (
+                "Evaluate both arguments and provide:\n"
+                "- Assessment of strengths and weaknesses in each argument\n"
+                "- A refined synthesis that incorporates the best elements from both sides\n"
+                "- Specific feedback for improvement in the next round\n"
+                "- Your synthesis will be used as the topic for the next round"
+            )
+
+        return prompt
+
+    def get_conversation_history(self) -> List[dict]:
+        """
+        Get the full conversation history.
+
+        Returns:
+            List[dict]: List of message dictionaries containing the conversation history.
+        """
+        return self.conversation.return_messages_as_list()
+
+    def get_final_answer(self) -> str:
+        """
+        Get the final refined answer from the judge.
+
+        Returns:
+            str: The content of the final judge synthesis.
+        """
+        return self.conversation.get_final_message_content()
+    
+    def batched_run(self, tasks: List[str]) -> List[str]:
+        """
+        Run the debate with judge refinement process for a batch of tasks.
+
+        Args:
+            tasks (List[str]): The list of tasks to run the debate with judge refinement process for.
+
+        Returns:
+            List[str]: The list of final refined answers.
+        """
+        return [self.run(task) for task in tasks]