AI Debate Competition Platform

Built with Ralph Loop Methodology — A project demonstrating iterative, promise-driven development.

🔄 Ralph Loop Methodology

This project is developed using the Ralph Loop approach — an iterative development methodology that emphasizes:

• Promise-driven development: Clear commitments (<promise>COMPLETE</promise>) for each task
• Incremental delivery: Tasks completed and verified one by one
• Continuous validation: Each task is tested before moving to the next
• Transparent progress: All progress tracked in progress.txt

Ralph Loop Verification

This project serves as a proof of concept for the Ralph Loop methodology:

Ralph Loop Principle	Implementation in This Project
Task Breakdown	6 well-defined tasks from initialization to completion
Promise Tracking	Each task marked with <promise>COMPLETE</promise>
Iterative Progress	Sequential task completion with verification
Self-Documentation	Progress tracked in progress.txt
Full Delivery	All promised features delivered and working

Result: ✅ Ralph Loop methodology verified — All 6 tasks completed successfully with a fully functional application.

🎯 Features

• 📋 Debate Configuration: Customize debate topics, select AI models, set number of debaters
• 🤖 AI Debaters: Simulate AI models conducting debates (opening statements, rebuttals, free debate, closing statements)
• 👨‍⚖️ Judge Scoring: Multi-dimensional scoring system (logic, expression, rebuttal, teamwork)
• 📊 Results Display: Real-time score statistics, visual comparison, winner announcement
• 🏆 Traditional Format: Supports standard debate competition format

🛠️ Tech Stack

Frontend

• React 18 + TypeScript
• Material-UI (MUI) + Bootstrap
• React Router
• Vite

Backend

• Node.js + Express
• RESTful API
• CORS support

🚀 Quick Start

Prerequisites

• Node.js 18+ installed
• Qwen Code CLI (qwen command) installed and configured
• API keys configured in ~/.qwen/settings.json

Installation

cd debate-app

# Install dependencies
npm install

Start Services

# Terminal 1: Start backend server
npm run server

# Terminal 2: Start frontend dev server
npm run dev

Access the Application

• Frontend: http://localhost:5173
• Backend API: http://localhost:3001

📖 Usage Guide

1. Home Page: Click "Start Debate Configuration"
2. Configuration Page:
   • Enter the debate topic
   • Select AI models for both sides (Proposition & Opposition)
   • Set number of debaters (1-4 per side)
   • Set number of judges (1-5)
3. Debate Page:
   • Click "Start Debate" to begin AI debate
   • View debate content in real-time
   • Switch to "Judge Scoring" tab
   • Each judge submits their scores
4. Results Page: View final scores and winner

📡 API Endpoints

Method	Endpoint	Description
GET	/api/health	Health check
GET	/api/models	Get available AI models
GET	/api/rules	Get debate rules
POST	/api/debate/speak	Generate debate speech
POST	/api/debate/score	Get judge scores

Example: Generate Speech

POST /api/debate/speak
Content-Type: application/json

{
  "topic": "AI will benefit humanity",
  "side": "proposition",
  "round": "opening",
  "position": 1,
  "context": []
}

🏗️ Project Structure

debate/
├── PRD.md                 # Product Requirements Document
├── progress.txt           # Ralph Loop progress tracking
├── README.md              # This file
└── debate-app/
    ├── src/
    │   ├── components/    # React components
    │   │   └── JudgePanel.tsx
    │   ├── pages/         # Page components
    │   │   ├── Home.tsx
    │   │   ├── Config.tsx
    │   │   ├── Debate.tsx
    │   │   └── Result.tsx
    │   ├── services/      # API services
    │   │   └── api.ts
    │   ├── types/         # TypeScript types
    │   │   └── index.ts
    │   ├── App.tsx
    │   └── main.tsx
    ├── server/            # Backend server
    │   ├── index.js
    │   ├── package.json
    │   └── models.allowed.json
    ├── package.json
    └── README.md

📊 Scoring Dimensions

Dimension	Weight	Description
Logic	30%	Sound reasoning and logical arguments
Expression	25%	Clear and fluent language
Rebuttal	25%	Effective counter-arguments
Teamwork	20%	Coordination and overall coherence

✅ Ralph Loop Task Completion

Task	Status	Description
Task 1	✅	Project initialization and architecture
Task 2	✅	Debate configuration page
Task 3	✅	Debate display page UI
Task 4	✅	AI debater integration
Task 5	✅	Judge scoring system
Task 6	✅	Complete flow and optimization

Final Promise: <promise>COMPLETE</promise> — All tasks delivered and verified.

📝 Scripts

Command	Description
npm run dev	Start frontend development server
npm run build	Build for production
npm run server	Start backend server
npm run lint	Run ESLint
npm run preview	Preview production build

🔧 Configuration

Allowed Models

The backend reads allowed models from server/models.allowed.json. You can override this using environment variables:

• DEBATE_ALLOWED_MODEL_IDS: Comma-separated list of model IDs
• DEBATE_ALLOWED_MODELS_JSON: JSON array of model configurations

Environment Variables

Ensure the following are configured before running:

• ~/.qwen/settings.json: Qwen Code CLI configuration
• Required API keys (e.g., BAILIAN_CODING_PLAN_API_KEY)

📄 License

MIT

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

Ralph Loop Methodology Verified ✅

This project demonstrates that the Ralph Loop approach can successfully deliver a complete, functional web application through promise-driven, iterative development.