Skip to content

Latest commit

 

History

History
302 lines (230 loc) · 10 KB

README.md

File metadata and controls

302 lines (230 loc) · 10 KB

DebateForge: AI-Powered Structured Dialectical Debate Platform

Overview

DebateForge is an advanced AI-powered debate orchestration platform that generates intelligent personas and facilitates structured dialectical debates between AI agents on complex topics. It combines web research capabilities with multi-round debate mechanics to produce comprehensive, evidence-based arguments and strategic decision matrices.

The platform uses LangGraph for orchestration, LangChain for AI interactions, and Chroma for vector-based document retrieval to create a sophisticated debate workflow that explores both sides of controversial topics.

Key Features

1. Intelligent Persona Generation

  • Automatically generates two opposing AI personas based on the debate topic
  • Creates persona-specific system prompts with:
    • Core belief statements
    • Argumentation styles (data-driven, evidence-based)
    • Debate tactics and win conditions
    • Tool usage strategies for research support

2. Multi-Round Structured Debate

  • Configurable number of debate rounds
  • Clear role assignment (Proponent vs. Critic/Skeptic)
  • Progressive rebuttal structure:
    • Round 1: Opening statements with core evidence
    • Rounds 2-N: Targeted rebuttals and counter-arguments
    • Final Round: Closing arguments and summaries

3. Research Integration

  • Automatic Query Refinement: Breaks user queries into 5 focused sub-queries
  • Multi-Source Search: Integrates DuckDuckGo web search
  • Vector Store Retrieval: Chroma-based document embedding and retrieval (MMR search)
  • Context Management: Intelligent summarization to prevent token bloat

4. Debate Supervision

  • Lead Moderator: Enforces debate quality and prevents vague claims
  • Fact-Checking: Validates arguments using research tools
  • Flow Control: Manages speaker turns and round progression
  • Constraint Enforcement: Prevents argument repetition and ensures substantive rebuttals

5. Visual & Textual Reporting

  • Round Digests: Mermaid.js flowcharts mapping argument flows per round
  • Strategic Decision Matrix: Comprehensive final report with:
    • Executive summary
    • Agent-specific arguments and positions
    • Consensus points and unique perspectives
    • Round-by-round scorecard
    • Cited sources and references
  • Real-time Streaming: Live UI updates via Gradio

Architecture

Graph Structure

1. Research Graph

(research graph)

2. Forum Graph

(forum graph)

┌─────────────────────────────────────┐
│   Research Graph                    │
├─────────────────────────────────────┤
│ • Query Refiner                     │
│ • Web Search (Multi-source)         │
│ • Data Extraction & Analysis        │
│ • Vector Store Creation             │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│   Forum Graph (Main Debate Loop)    │
├─────────────────────────────────────┤
│ 1. Persona Creator                  │
│ 2. Debate Supervisor (Moderator)    │
│ 3. Persona Agent (Argument Engine)  │
│ 4. Round Digest (Visualization)     │
│ 5. Report Generator (Final Output)  │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│   Final Graph & Report Rendering    │
└─────────────────────────────────────┘

Core Components

Component File Purpose
Research Graph research_graph.py Web search & document embedding
Forum Graph forum_graph.py Debate orchestration & persona management
Final Graph final_graph.py Report generation & visualization
State Definitions graph_states.py Pydantic models for all graph states
Web UI main.py Gradio interface for user interaction

🚀 Getting Started

Prerequisites

  • Python 3.10+
  • OpenAI API key (GPT-4.5-nano with extended thinking)
  • Environment variables configured (.env file)

Installation

# Install dependencies using uv
uv sync

# Or using pip
pip install -r requirements.txt

Configuration

Create a .env file in the project root:

OPENAI_API_KEY=your-api-key-here

Running the Application

# Start the Gradio web interface
python main.py

Then navigate to http://localhost:7860 in your browser.

Usage Example

import asyncio
from forum_graph import create_forum_graph
from graph_states import ForumState

async def main():
    forum_graph = await create_forum_graph()
    
    initial_state = ForumState(
        query="Is AI investment in 2024 a bubble or undervalued opportunity?",
        max_rounds=3,
        current_round=1,
        vector_store="path/to/vector/store",
        messages=[],
        # ... other state fields
    )
    
    config = {"configurable": {"thread_id": "unique-thread-id"}}
    
    async for update in forum_graph.astream(initial_state, config=config):
        print(update)

asyncio.run(main())

📝 Workflow Details

1. Research Phase

  • Expands user query into 5 sub-queries covering different angles
  • Searches multiple sources simultaneously
  • Extracts and validates information
  • Builds vector store with embedded documents

2. Persona Generation

  • Analyzes query to identify opposing perspectives
  • Generates specialized system prompts for each persona
  • Configures persona strategies and debate tactics

3. Debate Execution (Multi-Round)

  • Supervisor rounds: Moderator gives instructions to next speaker
  • Agent rounds: Persona argues their position using research tools
  • Summarization: Compress conversation to prevent context overflow
  • Round digest: Visualize argument flow for this round

4. Report Generation

  • Synthesizes debate outcomes
  • Creates Markdown report with citations
  • Generates Mermaid visualizations
  • Compiles source references

🛠️ Configuration Options

Forum State Parameters

ForumState(
    query: str                    # Topic/question for debate
    max_rounds: int              # Number of debate rounds (default: 3)
    vector_store: str            # Path to Chroma vector store
    query_limit: int             # Max refined queries for research
    # ... additional tracking fields
)

Model Configuration

Models used (configured in source files):

  • Research: GPT-5-nano (minimal reasoning)
  • Forum: GPT-5-nano (low reasoning effort)
  • Embeddings: text-embedding-3-small

Output Artifacts

1. Chat History

  • Real-time debate messages with speaker attribution
  • Tool calls and data retrieval notifications

2. Round Digests

  • Mermaid flowcharts per round
  • Key arguments (pro/con) summary
  • Round winner determination

3. Final Report

  • Executive summary
  • Comprehensive argument lists per agent
  • Consensus and unique perspective identification
  • Source references with titles and URLs

4. Usage Analytics

  • Token count tracking (input/output)
  • Execution time
  • Round progression

🔧 Advanced Features

Token Management

  • Automatic summarization when approaching context limits
  • Message pruning after summarization
  • Efficient state management across rounds

Argument Quality Enforcement

  • Fact-checking via research tool calls
  • Preventing vague claims through supervisor instructions
  • Enforcing substantive rebuttals (no "agree to disagree")

Tool Integration

  • fetch_data: Retrieves from vector store (RAG)
  • debate_search: Real-time web search via DuckDuckGo
  • ToolNode: Async tool execution within graph

📚 Project Structure

agent/
├── forum_graph.py           # Debate orchestration
├── research_graph.py        # Web search & embedding
├── final_graph.py           # Report generation
├── graph_states.py          # Pydantic state models
├── main.py                  # Gradio UI
├── pyproject.toml           # Project metadata
├── uv.lock                  # Dependency lock file
└── README.md                # This file

AI Models & APIs

  • LLM: OpenAI GPT-5-nano
  • Embeddings: OpenAI text-embedding-3-small
  • Web Search: DuckDuckGo Search API
  • Vector Store: Chroma (Open-source)
  • Orchestration: LangGraph (LangChain ecosystem)

UI/UX Features

  • Real-time Chat Display: Live debate transcript
  • Round Counter: Visual progress tracking
  • Status Messages: Real-time operation status
  • Performance Metrics: Token usage and execution time
  • Input Controls: Query, refinement depth, round count

🔮 Future Enhancements

  • Support for additional LLM providers (Claude, Llama)

  • Multi-language debate support

  • Data fetching from more sources

  • Debate export (PDF, JSON)

  • Interactive persona editing pre-debate

  • Debate scoring rubrics

  • Audio/video debate playback

Acknowledgments

Built with:

Support & Contribution

For issues, questions, or contributions, please refer to the project repository.

DebateForge - Turning Complex Questions into Structured Insights through AI-Powered Dialectics