An experiment in building an end-to-end chess experience that spans an iOS board, data collection from Chess.com, and (eventually) a self-improving engine. The project is currently in a prototyping phase: we now have a SwiftUI board with a basic rule engine, Python tooling to generate supervised datasets, and a mock AI server so the client can be exercised while the real model is under construction.
- SwiftUI board (
ChessAI/) – a native iOS app that lets you play as white against an AI operator. Legal move generation has been fleshed out for all pieces and simple SAN parsing is supported for AI moves. - Data tooling (
scripts/,main.ipynb) – reproducible pipeline that pulls your public Chess.com games and emits prompt/completion pairs for fine-tuning language models. - Mock inference server (
server/mock_ai_server.py) – a Flask service that usespython-chessto return random legal moves, unblocking UI development until a stronger model is available. - Supervised dataset (
sft_data.jsonl) – sample output generated from the notebook/script. Keep regenerating as your game archive grows.
.
├── ChessAI/ # SwiftUI front-end
├── ChessAI.xcodeproj/
├── ChessAITests/, ChessAIUITests/ # Xcode test targets (placeholders for now)
├── scripts/
│ └── generate_chess_sft_dataset.py
├── server/
│ └── mock_ai_server.py
├── main.ipynb # Exploratory notebook that informed the script
├── sft_data.jsonl # Example supervised dataset
├── requirements.txt # Python dependencies for scripts/server
├── requirements-dev.txt # Development extras (pytest, etc.)
├── tests/ # Python unit tests for the data tooling
└── README.md
python -m venv .env
source .env/bin/activate
pip install -r requirements-dev.txt # includes runtime + pytest for testsIf you only need the runtime dependencies (no tests), install with -r requirements.txt.
python scripts/generate_chess_sft_dataset.py <chess.com-username> --drop-abandonedThis mirrors the notebook workflow but is now reproducible. It writes a
JSONL file (default sft_data.jsonl) in the repository root.
python server/mock_ai_server.pyThe Swift client polls http://localhost:5000/health on launch and posts board
state to /ai-move. The mock server responds with random legal SAN moves.
Open ChessAI.xcodeproj in Xcode (17+) and run the ChessAI scheme on an
iOS 17 simulator or device. Ensure the mock server is running for AI moves.
pytestThe suite currently covers the Chess.com dataset pipeline, guarding against regressions in move history alignment and JSONL generation.
- Engine quality – replace the mock server with a staffed engine that uses the generated datasets (minimax baseline → policy/value networks → RL).
- Evaluation loop – automate self-play, rating tracking, and regression testing against prior checkpoints.
- UX polish – richer move annotations, game history, difficulty settings, and cross-platform support.
Refer to scripts/ and server/ for current scaffolding; everything is
intentionally modular to support incremental upgrades.