ChessMad Engine

ChessMad Engine is a local browser-playable chess engine built with Flask, python-chess, minimax search with alpha-beta pruning, and a small JSON-backed learning layer.

The app runs entirely on your computer after setup. There are no hosted services, API keys, accounts, or external chess engines required.

Features

• Browser chessboard with legal-move highlighting, move history, and replay.
• Engine play powered by minimax and alpha-beta pruning.
• Difficulty presets for easy, medium, and hard search behavior.
• Local weighted learning from completed games and self-play training.
• Offline piece artwork served from the repository.
• Flask JSON API with smoke tests.

Why Python

Python was chosen because python-chess provides complete offline chess rules: legal move generation, check, checkmate, stalemate, draw detection, SAN/FEN, and move validation. That lets this project focus on readable engine logic and local learning instead of reimplementing chess rules.

Requirements

• Python 3.11 or newer
• pip

Setup

git clone https://github.com/YOUR_USERNAME/chessmad-engine.git
cd chessmad-engine
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run Locally

python app.py

Open http://127.0.0.1:5000.

Optional environment variables:

FLASK_DEBUG=1 PORT=5000 python app.py

Run Tests

pytest

Project Structure

chessmad-engine/
  ai/                 # evaluator, minimax, learning, self-play training
  data/               # generated local learning JSON and example data
  engine/             # game orchestration and snapshots
  frontend/           # static HTML/CSS/JS browser UI
  server/             # Flask routes
  tests/              # API and engine tests
  app.py              # local server entrypoint
  requirements.txt    # runtime and test dependencies

How The Engine Works

• Legal moves and game-end detection come from python-chess.
• The AI searches moves with minimax and alpha-beta pruning.
• Static evaluation scores material, center control, development, checks, and piece safety.
• Difficulty controls search depth:
  • Easy: depth 1 with more randomness
  • Medium: depth 2
  • Hard: depth 3

How Learning Works

The learner stores local weights for each (position, move) pair in data/data.json.

• Engine win: moves from that game receive +1 reward.
• Engine loss: moves from that game receive -1 reward.
• Draw: moves receive 0 reward.
• Later moves receive a slightly larger update because they are usually closer to the final outcome.
• On future visits to the same position, the learned move weight is added as a small bias to the minimax score.

data/data.json is generated local state and is intentionally ignored by Git. Use data/example-data.json as the public shape of that file.

Train Mode

The Train Mode button runs a small batch of engine-vs-engine self-play games. Those games update the same local data/data.json file, so learning persists after the server restarts.

You can also train from the terminal with a progress bar:

python train.py 10
python train.py 50 --difficulty medium

The command accepts 1 to 50 games per run and writes to data/data.json by default.

API

Method	Path	Description
GET	/api/state	Current board, legal moves, result, and learning stats
POST	/api/new	Start a new game with humanColor and difficulty
POST	/api/move	Submit a UCI move like e2e4
POST	/api/train	Run local self-play training
GET	/api/learning	Return learning summary stats

Piece Artwork

Chess piece SVGs are stored locally in frontend/static/pieces/ and come from the Wikimedia Commons SVG chess pieces category, specifically the Cburnett transparent 45px chess piece set.

License

Code is released under the MIT License. See LICENSE.