🎭 AI Debate Arena

Watch two AI personalities argue about any topic you choose — powered by Gradio.

Features

• 5 debate personalities — Classic Debate, Professor vs Student, Politician vs Journalist, Comedian vs Critic, Lawyer vs Judge
• 6 category lenses — Politics, Philosophy, Entertainment, Science, Ethics, General
• Streaming conversation — responses appear in real time
• Configurable rounds & token limits — tune depth and length
• Per-session voting — rate each debater independently
• Export — download the full transcript as a .txt file

---

Project Structure

debate-arena/
├── pyproject.toml              # uv project metadata & dependencies
├── .python-version             # pinned Python version
├── .env                        # your secrets (gitignored)
├── .env.example                # template — copy and fill in
├── .gitignore
├── README.md
└── src/
    └── debate_arena/
        ├── __init__.py
        ├── main.py             # entrypoint: env loading + app launch
        ├── config.py           # all constants (personalities, categories, models)
        ├── llm_client.py       # unified Groq query wrapper
        ├── conversation.py     # debate orchestration generator
        ├── voting.py           # per-session VoteTracker dataclass
        ├── export.py           # HTML → plain text + download link
        └── ui/
            ├── __init__.py
            ├── layout.py       # Gradio Blocks layout + event wiring
            └── handlers.py     # Gradio event-handler callbacks

---

Setup

Prerequisites

• uv installed
• A Groq API key

Install

# 1. Clone / navigate to the project
cd debate-arena

# 2. Create the virtual environment and install dependencies
uv sync

# 3. Configure secrets
cp .env.example .env
# Open .env and set GROQ_API_KEY=<your key>

Run

uv run debate-arena

The app will open automatically in your browser at http://localhost:7860.

Development extras

# Install dev dependencies (ruff, pytest)
uv sync --all-extras

# Lint
uv run ruff check src/

# Format
uv run ruff format src/

# Tests
uv run pytest

---

Configuration

All tuneable constants live in src/debate_arena/config.py:

Constant	Default	Description
LLM1_MODEL	openai/gpt-oss-120b	Model for debater 1
LLM2_MODEL	openai/gpt-oss-20b	Model for debater 2
DEFAULT_MAX_TOKENS	300	Tokens per response
DEFAULT_TURNS	2	Default debate rounds
DEFAULT_TIMER_SECONDS	30	Timer slider default

To add a new personality or debate category, edit the AI_PERSONALITIES and DEBATE_CATEGORIES dicts in config.py — no other files need to change.

---

Environment Variables

Variable	Required	Description
GROQ_API_KEY	✅	Your Groq API key

---

Architecture Notes

• llm_client.py — One query_llm() function replaces the original duplicated query_llm1 / query_llm2. Model, API key, and system prompt are passed as parameters.
• VoteTracker — Instantiated per Gradio session via gr.State() so concurrent users get isolated vote counts.
• export.py — Uses urllib.parse.quote for safe data-URI encoding instead of raw string embedding.
• main.py — Validates env vars before importing Gradio so error messages are clear and fast.