debatecore

An asynchronous multi-agent debate engine built with LangGraph, FastAPI, and Google Gemini.

Overview

debatecore simulates a structured, formal debate between two autonomous AI agents (PRO and CON) on a user-provided topic. The debate follows a strict chronological sequence managed by a moderator node. Throughout the process, an LLM-based claim review mechanism fact-checks each statement, initiating self-correction/retries if inaccuracies are detected and penalizing agents who fail multiple checks. At the end of the debate, an AI judge reviews the complete transcript to deliver a structured verdict.

The system is accessible via a CLI tool or a FastAPI backend, enabling developers to run simulations locally or integrate the engine into web/mobile applications.

Note

The claim review system uses Google Gemini's internal knowledge to spot numerical inconsistencies or unsupported citations. It does not perform real-time external web search verification.

---

Key Features

• Mandatory User Topics: No automated/hardcoded topic generation; the debate is grounded in the user's specific inputs.
• Context Grounding: Supports optional context to focus agent arguments on a specific situation or target audience.
• Structured Stages: Follows a formal debate structure: Opening (PRO opening, CON rebuttal), Counter (PRO counter), and Closing (CON final argument).
• Claim Review & Retry Logic: Automatically parses statements for numbers or citations and requests correction if they are flagged as inaccurate.
• Configurable Limits & Settings: Exposes constraints through Pydantic schemas, enabling control over:
  • Language of the debate (default: English)
  • Maximum argument word length (100–1000 words)
  • Maximum allowed fact-checking retries (0–5 attempts)
  • Toggle to enable/disable claim reviews
  • Toggle to enable/disable final judging
• FastAPI Engine: Serves the graph as a concurrency-safe web service returning structured JSON responses (without exposing raw internal LangGraph/LangChain objects).
• Interactive CLI: Preserves a text-based terminal interface with interactive topic prompting.

---

Architecture

The workflow is orchestrated using LangGraph command-based routing. The chart below details the execution flow:

flowchart TD
    Start([Start]) --> Input[User topic + optional context & config]
    Input --> Entry{Entry Point}
    
    Entry --> PRO_Node[PRO Debater Node]
    PRO_Node --> FC_Node[Fact Checker Node]
    
    CON_Node[CON Debater Node] --> FC_Node
    
    FC_Node --> FC_Router{Fact Check Router}
    
    FC_Router -- Failed check & limit reached --> Early_End[Moderator Disqualification Msg]
    Early_End --> End([End])
    
    FC_Router -- Failed check & retry allowed --> PRO_Node
    FC_Router -- Failed check & retry allowed --> CON_Node
    
    FC_Router -- Validated / Fact check disabled --> Mod_Node[Debate Moderator Node]
    
    Mod_Node -- Opening statement done --> CON_Node
    Mod_Node -- Rebuttal done --> PRO_Node
    Mod_Node -- Counterargument done --> CON_Node
    Mod_Node -- Final arguments completed & Judge enabled --> Judge_Node[Judge Node]
    Mod_Node -- Final arguments completed & Judge disabled --> End
    
    Judge_Node --> End

Loading

---

Installation & Setup

Prerequisites

• Python 3.10 or higher
• Google Gemini API Key

1. Clone the repository

git clone https://github.com/Vedanshdhingra/debatecore.git
cd debatecore

2. Configure Virtual Environment & Install Dependencies

Create a virtual environment and install the required packages:

# On Windows
python -m venv venv
venv\Scripts\pip install -r requirements.txt

# On macOS/Linux
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Setup Environment Variables

Create a .env file in the root directory:

GEMINI_API_KEY=your_gemini_api_key_here

---

Execution Instructions

Run via CLI

To start an interactive debate session:

# Runs interactive CLI
venv\Scripts\python main.py

# Runs CLI directly with custom topic and context ,example:
venv\Scripts\python main.py --topic "Should AI coding assistants be used by beginner programmers?" --context "The users are first-year computer science students learning Python."

Run via FastAPI Backend

To start the REST API server:

venv\Scripts\python -m uvicorn api.main:app --port 8000

Once the server starts, you can access:

• Interactive API Documentation (Swagger UI): http://127.0.0.1:8000/docs
• ReDoc documentation: http://127.0.0.1:8000/redoc

---

API Documentation

1. Health Status

• Endpoint: GET /health
• Description: Verifies if the service is running and checking if GEMINI_API_KEY is loaded.
• Example Response:

{
  "status": "healthy",
  "service": "debatecore-api",
  "model_configured": true
}

2. Run Debate Workflow

• Endpoint: POST /api/v1/debates
• Description: Runs a real debate session with custom constraints.
• Request Body:

{
  "topic": "Should startups prioritize shipping fast over writing clean scalable code?",
  "context": "The startup has four developers, six months of runway, and no validated product-market fit.",
  "config": {
    "max_fact_check_retries": 3,
    "max_argument_words": 500,
    "language": "English",
    "include_fact_checks": true,
    "judge_enabled": true
  }
}

• Example Response:

{
  "debate_id": "4b76dfad-e837-4cbe-ba95-d2dfc2cf27d1",
  "topic": "Should startups prioritize shipping fast over writing clean scalable code?",
  "context": "The startup has four developers, six months of runway, and no validated product-market fit.",
  "config": {
    "max_fact_check_retries": 3,
    "max_argument_words": 500,
    "language": "English",
    "include_fact_checks": true,
    "judge_enabled": true
  },
  "messages": [
    {
      "speaker": "pro",
      "content": "... argument content ...",
      "validated": true,
      "stage": "opening"
    }
  ],
  "judge_verdict": {
    "winner": "pro",
    "justification": "... analysis of rhetorical delivery ..."
  },
  "status": "completed"
}

3. Retrieve Historical Debate

• Endpoint: GET /api/v1/debates/{debate_id}
• Description: Retrieves the complete session state of a completed debate run. Note that the backend maintains this state in memory; restarting the server clears historical debates.

4. Detailed Endpoints

• GET /api/v1/debates/{debate_id}/messages: Returns a structured chronological list of messages.
• GET /api/v1/debates/{debate_id}/fact-checks: Returns the structured claims reviewed during the debate.
• GET /api/v1/debates/{debate_id}/logs: Returns the list of operational server logs for the specific run.

---

Testing

To run the suite of unit tests:

venv\Scripts\pytest

---

Contributing

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