Debators

A small OpenAI SDK project where two LLM agents debate each other in a loop and save transcripts by day.

Features

• Two agents with distinct styles:
  • mild_polite
  • rude_violent_style
• Iterative debate prompt loop:
  • This is what you said
  • This is the other argument
  • Now prove the other wrong
• Daily transcript persistence to conversations/YYYY-MM-DD.jsonl
• Minimalist dark-mode retro web UI (early internet terminal feel)
• UI renders newest messages first

Requirements

• Python >=3.12
• uv (recommended) or pip
• OpenAI-compatible API credentials

Local Setup

uv sync
cp .env.example .env

Set environment values in .env:

OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4.1-mini
TTS_API_URL=https://your-tts-api/tts

Run Debate Agent

uv run python main.py

By default, it runs until stopped.

Common options:

uv run python main.py \
  --topic "Remote work reduces productivity" \
  --rounds 8 \
  --min-chars 120 \
  --max-chars 220 \
  --out-dir conversations

Run UI Frontend

uv run python ui_server.py --host 127.0.0.1 --port 8080

Open: http://127.0.0.1:8080

Optional:

uv run python ui_server.py --conversations-dir conversations --web-dir web

Run Both with Docker

Build:

docker build -t debators .

Run (UI on 0.0.0.0:9999):

docker run --rm -p 9999:9999 \
  -e OPENAI_API_KEY=your_api_key_here \
  -e OPENAI_BASE_URL=https://api.openai.com/v1 \
  -e OPENAI_MODEL=gpt-4.1-mini \
  -e TTS_API_URL=https://your-tts-api/tts \
  debators

Optional env vars:

• DEBATE_ARGS="--topic 'Remote work reduces productivity' --rounds 20"
• OUT_DIR=conversations

Run with Docker Compose

docker compose up --build

Open: http://localhost:9999

Compose uses these env vars (from shell or .env):

• OPENAI_API_KEY (required)
• OPENAI_BASE_URL (optional)
• OPENAI_MODEL (optional)
• TTS_API_URL (required for voice playback)
• DEBATE_ARGS (optional)
• OUT_DIR (optional)

Current docker-compose.yml uses env_file: .env for container runtime variables (no ${...} interpolation), so values come from .env instead of being overridden by your shell environment.

Project Structure

.
├── main.py
├── ui_server.py
├── web/
│   ├── index.html
│   ├── styles.css
│   └── app.js
├── conversations/
├── Dockerfile
├── docker-compose.yml
└── docker-entrypoint.sh