How louisguichard/llm-chess-arena works
Project type and purpose
• This is a full-stack web application built with Flask (Python) on the backend and plain HTML/JavaScript on the frontend.
• Purpose: let users pick two LLMs to play chess against each other, stream moves in real time, compute and display ELO ratings, and persist game history to Google Cloud Storage (GCS).
File structure
• Top-level Python modules:
• app.py – Flask server + SSE endpoint
• client.py – OpenRouter API client wrapper
• prompts.py – LLM prompt templates for chess moves
• match.py – Game orchestration: turn loop, validation
• ratings.py – ELO rating calculation & update logic
• gcp.py – GCS read/write: PGN files & ratings.json
• utils.py, logger.py – support utilities/logging
• Config/data:
• models.txt – list of model IDs to load at startup
• requirements.txt
• .env for API key & GCS_BUCKET_NAME
• Frontend:
• templates/*.html – Jinja templates (index, battle, leaderboard, etc.)
• static/js/*.js – battle.js (SSE client), stockfish.js (move validation), wasm
• static/pieces – chess piece images
• No traditional RDBMS: persistence layer is GCS.
README for additional insights
• Architecture is monolithic but layered (API-client, game logic, persistence, UI).
• Uses SSE to stream moves from server to browser.
• External dependencies: OpenRouter (OpenAI SDK), Google Cloud Storage.
a. Main components:
1. Browser (User Interface)
– HTML/CSS, JS (battle.js & stockfish.js), SSE client
2. Flask App (Backend)
– Endpoints:
• GET / → index page
• GET /battle → battle page
• GET /stream → SSE stream of moves
• GET /leaderboard → ratings page
3. Match Engine
– match.py orchestrates move requests
– uses prompts.py to generate LLM prompts
4. LLM API Client
– client.py calls OpenRouter API
5. Rating Service
– ratings.py computes ELO
6. Persistence (Google Cloud Storage)
– gcp.py reads/writes PGN & ratings JSON
7. Configuration & Data
– models.txt, .env variables
b. Relationships & data flow
1. User selects two models → Browser sends request to Flask.
2. Flask invokes Match Engine → iterates moves:
a. For each move, prompts.py builds prompt.
b. client.py calls OpenRouter → receives move.
c. match.py validates via stockfish.js (if used client-side) or via server logic.
d. match.py emits move via SSE to browser.
3. At match end:
a. ratings.py computes new ELO.
b. gcp.py writes PGN & rating updates to GCS.
4. Leaderboard endpoint reads ratings.json from GCS via gcp.py.
c. Architectural patterns & design principles
• Layered architecture: presentation (templates/js), application logic (Flask routes + match/rating), infrastructure (OpenRouter client, GCS).
• Streaming (Server-Sent Events) for real-time updates.
• Single monolithic codebase: no microservices, but components are modularized by function.
d. Key technologies/frameworks/libraries
• Flask for web server & SSE
• OpenAI SDK (via OpenRouter)
• Google Cloud Storage Python client
• stockfish.wasm for move validation in browser
• Jinja2 templating
• ELO algorithm implementation in Python