A real-time chess platform with an AlphaZero-style AI engine and live LLM coaching — all running in the browser.
Looking for the original version? The classic Chess Gang (Django + Redis multiplayer) is available on the
masterbranch. This branch (main) contains the upgraded AI + coaching version.
- AlphaZero-style engine — Neural network + MCTS running entirely in-browser via ONNX Runtime Web
- Three difficulty levels — Beginner (50 sims), Intermediate (150), Advanced (400)
- Zero server load — AI runs as a Web Worker on the client
- Per-move evaluation — Every move gets classified: ★ Brilliant, ✓ Good, OK, ?! Inaccuracy, ? Mistake, ?? Blunder
- Stockfish-powered analysis — Accurate centipawn evaluation via Stockfish.js (depth 12)
- Live LLM coaching — Natural language tips after each move using Llama 3.3 70B (Groq free tier)
- Eval bar — Visual evaluation bar showing position advantage
- Score tracking — Cumulative score based on move quality
- WebSocket-based — Instant move synchronization via Django Channels + Redis
- Public & private games — Create open lobbies or invite specific opponents
- Connection handling — Auto-reconnect with opponent online/offline status
- Bootstrap 5.3 dark theme across all pages
- Responsive design — Works on desktop and mobile
- 9 redesigned templates — Lobby, game, create, ongoing, completed, login, signup
- Python 3.11+
- Redis (for multiplayer —
docker run -p 6379:6379 -d redis:5) - Groq API key (free — for coaching feature)
# Clone and install
git clone https://github.com/your-username/chess.git
cd chess
pipenv install
# Configure environment
echo "GROQ_API_KEY=your_key_here" > .env
# Run server
python manage.py runserverVisit http://127.0.0.1:8000/ — no account needed to browse, register to play.
The single player mode with AI coaching works without Redis. Just start the server and navigate to Single Player.
See ARCHITECTURE.md for the full system diagram and component breakdown.
Key components:
- Browser: Chess.js + Chessboard.js (UI), Engine Worker (MCTS + ONNX), Stockfish Worker (eval)
- Server: Django 5.2 + Daphne (ASGI), Channels (WebSocket), Groq (LLM)
- Training: PyTorch → ONNX export, supervised + self-play pipeline
Browser (Client) Server (Django)
┌──────────────────────┐ ┌──────────────┐
│ Engine Worker (ONNX) │ │ /api/coach/ │──→ Groq LLM
│ Stockfish Worker │──HTTP POST──→ │ /api/analyze/│
│ Chess UI (Board.js) │ │ WebSocket │──→ Redis
└──────────────────────┘ └──────────────┘
See DESIGN_DECISIONS.md for detailed rationale on:
- Why AI runs in-browser (zero server cost)
- Dual worker architecture (neural net + Stockfish)
- Supervised pre-training vs pure self-play
- ONNX INT8 quantization (43 MB → 10.9 MB)
- Groq free tier for coaching
- Queue-based eval system (race condition fix)
See training.md for the full training pipeline documentation.
# Supervised pre-training on master games (~30 min on GPU)
python -m training.supervised \
--pgn data/lichess_elite_2025-01.pgn \
--max-games 50000 --epochs 15 --export
# Export to ONNX for browser
python -m training.export_onnx --quantizeModel specs: 6 residual blocks, 128 filters, ~11.4M parameters, AlphaZero 8×8×73 move encoding.
| Component | Technology |
|---|---|
| Backend | Django 5.2 + Daphne 4.2 (ASGI) |
| WebSocket | Django Channels 4.3 + Redis |
| AI Engine | PyTorch → ONNX Runtime Web (WASM) |
| Position Eval | Stockfish.js v10 |
| LLM Coaching | Groq (Llama 3.3 70B) |
| UI | Bootstrap 5.3 + Chessboard.js 1.0 |
| Chess Logic | Chess.js 0.10 / python-chess 1.11 |
See the render branch for full deployment instructions including environment variables, build configuration, and architecture diagram.
Quick start:
- Create a Web Service on Render pointing to the
renderbranch - Set up a Neon PostgreSQL database (free tier)
- Set environment variables:
DATABASE_URL,SECRET_KEY,GROQ_API_KEY,ALLOWED_HOSTS,CSRF_TRUSTED_ORIGINS - Build:
sh build.sh| Start:daphne pychess.asgi:application --bind 0.0.0.0 --port $PORT -v2
MIT