🤖 AI Debates · Debatr

Two AIs. One topic. A video in minutes.

Debatr (the AI Debates studio) is a full-stack service that orchestrates structured debates between AI personas and turns them into content. Powered by OpenRouter, it lets you pit hundreds of LLMs against each other with custom roles, personalities and stances, watch the debate stream live, get a judge's verdict, and render a 16:9 YouTube video plus a 9:16 Short right in the browser.

Users sign up, receive welcome credits, buy more with Stripe, keep a library of their debates and can publish them to a public gallery with share links.

🚀 Live Demo Version is Coming Soon!

---

✨ Key Features

• 🧭 4-step wizard: topic → speakers (model, neural voice, persona per speaker) → voice engine, outputs and quality → review with a cost/length estimate.
• ⚔️ LLM vs LLM: Mix and match models. Have Claude debate GPT on philosophy while Gemini moderates.
• ⚡ Real-time streaming: watch the debate generate token-by-token, stop it at any moment.
• ⚖️ Structured verdict: the judge names a winner (or a draw), with per-debater feedback shown in the UI and on the video end card.
• 🎙️ Neural voices: ElevenLabs (premium, emotion tags) or free Edge voices with word timestamps, mixed MP3 and karaoke transcript.
• 🎬 Video in the browser: 16:9 episode and 9:16 Shorts (LLM-picked highlights with a hook) rendered with Remotion and WebCodecs — no server encoding.
• 👤 Accounts & credits: email sign-up with welcome credits, Stripe top-ups, a ledger of every charge, an optional personal OpenRouter key that bypasses credits.
• 📚 Library & gallery: drafts, filters, search; publish finished debates with a share link (/d/{slug}) and view counts.
• 🐳 Dockerized: Postgres, Redis, API, workers and a Caddy-served frontend.

🛠️ Tech Stack

Backend

• Framework: FastAPI (Python 3.12+, managed with uv)
• Database: PostgreSQL (async SQLAlchemy 2 + Alembic migrations)
• Queue: Redis & RQ (Redis Queue) for reliable task orchestration
• AI Integration: OpenRouter API (streaming, token & cost accounting)
• Voices & media: ElevenLabs / edge-tts, ffmpeg mixing, timeline contract for the browser renderer
• Accounts & payments: session cookie login (bcrypt), encrypted personal keys (Fernet), Stripe Checkout + webhooks
• Quality: ruff, pyright, pytest

Frontend

• Framework: React 19 + Vite 8 + TypeScript
• Styling: Tailwind CSS 4 with the Debatr design tokens (dark studio theme)
• State/Routing: React Router, Axios
• Streaming: Server-Sent Events (SSE)
• Video: Remotion Player + @remotion/web-renderer (MP4 encoded in the visitor's browser)

DevOps

• Containers: Docker Compose (Postgres, Redis, API, worker, Caddy)
• CI: GitHub Actions (lint, type-check, tests, build)

---

🚀 Getting Started

Follow these steps to get a copy up and running locally or on your server.

🐳 Quick start with Docker

1. Clone the repository

   git clone https://github.com/khoren93/ai-debates.git
   cd ai-debates

2. Configure environment

   cp .env.example .env

   For local testing you only need to set OPENROUTER_API_KEY. Keep DOMAIN_NAME=localhost. Set DEV_FAKE_PAYMENTS=true to top up credits instantly without Stripe while developing.

3. Run

   docker compose up -d --build

   Database migrations run automatically when the API container starts.

4. Open

   • Frontend: http://localhost
   • API docs: http://localhost/api/docs
   • Admin panel: http://localhost/api/admin (ADMIN_USER / ADMIN_PASSWORD)

💻 Local development (hot reload)

Prerequisites: uv, Node.js 20.19+ and Docker.

# 1. Infrastructure only (Postgres on :5432, Redis on :6379)
docker compose -f docker-compose.dev.yml up -d

# 2. Backend API (http://localhost:8000/api/docs)
cd backend
uv sync
uv run alembic upgrade head
uv run uvicorn app.main:app --reload

# 3. Worker (second terminal). SimpleWorker avoids fork issues on macOS.
cd backend
RQ_SIMPLE_WORKER=true uv run python -m app.worker

# 4. Frontend (third terminal, http://localhost:5173 — proxies /api to the backend)
cd frontend
npm install
npm run dev

Leave DATABASE_URL and REDIS_URL unset in .env: the defaults point at localhost, and docker compose injects the container addresses itself.

Checks

cd backend && uv run ruff check . && uv run pyright && uv run pytest
cd frontend && npm run check && npm run build

---

🌐 Server Deployment (Hetzner/VPS)

1. Point your domain (e.g., ai-debates.net) to your server IP in Cloudflare/DNS.
2. SSH into your server and install Docker:

   curl -fsSL https://get.docker.com | sh

3. Clone and Setup:

   git clone https://github.com/khoren93/ai-debates.git
   cd ai-debates
   cp .env.example .env

4. Edit .env:
   • Set DOMAIN_NAME=your-domain.com
   • Set ACME_EMAIL=your@email.com (for SSL)
   • Set OPENROUTER_API_KEY=...
   • Generate a strong POSTGRES_PASSWORD.
5. Start everything:

   ./deploy.sh

   deploy.sh pulls the latest code, rebuilds the containers (migrations run on start) and prunes old images. In production set ENVIRONMENT=production and replace every placeholder secret in .env (SECRET_KEY, ADMIN_PASSWORD, POSTGRES_PASSWORD).

---

📖 Usage

1. Open the web interface at https://your-domain.com (or http://localhost) and create an account (new accounts receive SIGNUP_BONUS_USD of credits).
2. Click "+ New debate" and walk through the wizard:
   • Topic: type a question or pick one from the library, choose language, rounds and reply length.
   • Speakers: a host plus two or more debaters, each with a model, a neural voice and a persona.
   • Voice & format: spoken or written style, free Edge or premium ElevenLabs voices, which outputs to produce (audio, 16:9 video, 9:16 Short) and the render quality.
   • Review: the estimate shows cost, length, turns and your credits after the run.
3. Hit Start the debate and watch it stream live. When it finishes the verdict is scored and the audio track is built automatically; open the debate to render the MP4s in your browser.
4. Share: publish the debate to the gallery and copy the share link.
5. Account: top up credits (Stripe), see this month's usage, store a personal OpenRouter key so paid models run on your own account instead of credits.

💳 Credits

• Every run charges the OpenRouter cost reported for the debate × CREDIT_MARKUP once it finishes.
• Premium voices on the system ElevenLabs key cost TTS_CREDIT_PRICE_PER_1K_CHARS per 1,000 characters.
• Free models and free Edge voices cost nothing; a personal OpenRouter key makes model usage free.
• Top-ups go through Stripe Checkout (STRIPE_SECRET_KEY, webhook /api/billing/webhook with the checkout.session.completed event and STRIPE_WEBHOOK_SECRET). Every movement is recorded in the credit_transactions ledger and visible on the Account page and in the admin panel.

---

🏗️ Architecture Overview

The system uses an event-driven architecture to handle long-running LLM generation tasks without blocking the UI.

1. API Layer: POST /api/debates validates the configuration and saves the debate with status queued. A user-supplied OpenRouter key is kept only in Redis for the lifetime of the debate, never in the database.
2. Queue (RQ): A chain of jobs runs in the worker: start → one job per turn → verdict → finish.
3. Scheduler: Every round starts with the moderator (introduction, then short transitions) followed by each debater. Debater turns are typed opening / rebuttal / closing; the moderator's model then delivers a structured verdict.
4. Worker: Builds role-specific prompts, streams the OpenRouter response, records token usage and cost per turn, and publishes events to Redis Pub/Sub. A debate can be stopped at any time from the UI.
5. Frontend: Subscribes to GET /api/debates/{id}/stream (SSE) and renders turns token-by-token. Finished debates are served straight from the database.
6. Verdict & billing: after the judge's turn a cheap model structures the verdict (winner, headline, feedback). At the terminal state the worker charges the owner's credits and, if the wizard asked for media, queues the audio build on the media queue.
7. Media: the media worker voices every turn (cached by content hash), mixes the track with ffmpeg, picks highlights for Shorts and writes timeline.json. The browser renders MP4s from that timeline.
8. Accounts: the login lives in the signed session cookie; personal OpenRouter keys are stored encrypted and only ever handed to the worker through Redis for the duration of a run.

Configuration (see .env.example): OPENROUTER_API_KEY, ELEVENLABS_API_KEY, ALLOWED_ORIGINS, SIGNUP_BONUS_USD, CREDIT_MARKUP, TTS_CREDIT_PRICE_PER_1K_CHARS, TOPUP_AMOUNTS_USD, STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET (or DEV_FAKE_PAYMENTS), DEBATE_CREATE_RATE_LIMIT, LOGIN_RATE_LIMIT, TURN_JOB_TIMEOUT, MEDIA_JOB_TIMEOUT, ADMIN_USER / ADMIN_PASSWORD, SECRET_KEY.

---

🗺️ Roadmap

• Voice Synthesis (TTS): Browser text-to-speech playback.
• Neural TTS: ElevenLabs / Edge voices with word timestamps, karaoke transcript and MP3 export.
• Video: 16:9 debate video and 9:16 shorts rendered in the browser (Remotion).
• User Voting: Let the audience decide the winner.
• Export Transcripts: Save debates as Markdown.
• Accounts & credits: sign-up, Stripe top-ups, ledger, personal OpenRouter key.
• Public gallery: publish debates with share links.
• PDF Export: Nicely formatted transcript downloads.
• Multiplayer Mode: Human vs AI debates.
• Local LLM Support: Integration with Ollama for offline debates.

---

🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
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

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

📬 Contact

Project Link: https://github.com/khoren93/ai-debates