AI Chess Battle

A terminal-based chess application where AI engines and LLMs play against each other. Watch Stockfish battle LLMs on a Unicode chess board with real-time move updates.

Game start & End game

Features

• Multiple engine types: Stockfish, Ollama LLMs, or Random
• Live display: Unicode chess board centered in terminal
• Move highlighting: Last move shown in green
• Material score: Real-time advantage tracking (e.g., "+3 material")
• Captured pieces: Displayed next to each player
• Adjustable Stockfish skill levels (0-20)
• Tournament mode with statistics
• PGN export for game analysis

Requirements

• Python 3.8+
• Stockfish (recommended) - for proper chess play
• Ollama (optional) - for LLM-based play

Installation

1. Clone/navigate to the project

cd ai_chess

2. Create and activate a virtual environment

# Create venv
python -m venv venv

# Activate (Linux/macOS)
source venv/bin/activate

# Activate (Windows)
venv\Scripts\activate

3. Install Python dependencies

pip install -r requirements.txt

4. Install Stockfish

# Arch Linux
sudo pacman -S stockfish

# Ubuntu/Debian
sudo apt install stockfish

# macOS
brew install stockfish

# Windows - download from https://stockfishchess.org/download/

5. (Optional) Set up Ollama for LLM play

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull models
ollama pull llama3
ollama pull mistral

# Start Ollama
ollama serve

Quick Start

# See all options
python -m src.main --help

# Default game: Stockfish (skill 10) vs Stockfish (skill 10)
python -m src.main

# Watch a mismatch: strong vs weak
python -m src.main --white-skill 15 --black-skill 3

Usage

Stockfish vs Stockfish (default)

# Equal skill match
python -m src.main

# Different skill levels (skill 0-20, higher = stronger)
python -m src.main --white-skill 15 --black-skill 5

LLM vs Stockfish

# LLM plays white against weak Stockfish
python -m src.main --white-engine llm --white-model llama3 --black-engine stockfish --black-skill 3

LLM vs LLM

python -m src.main --white-engine llm --white-model llama3 --black-engine llm --black-model mistral

Tournament mode

# 5-game tournament between Stockfish levels
python -m src.main --tournament --games 5 --white-skill 10 --black-skill 5

# Save all games to PGN
python -m src.main --tournament --games 10 --save-pgn

Quick test with random players

python -m src.main --white-engine random --black-engine random --delay 0.3

CLI Options

Engine Selection

Option	Default	Description
--white-engine	stockfish	Engine for white: stockfish, llm, or random
--black-engine	stockfish	Engine for black: stockfish, llm, or random

Stockfish Options

Option	Default	Description
--white-skill	10	Stockfish skill for white (0-20)
--black-skill	10	Stockfish skill for black (0-20)
--engine-path	auto	Path to Stockfish executable
--engine-time	1.0	Time per move in seconds
--engine-depth	-	Search depth (overrides time)

LLM Options

Option	Default	Description
--white-model	llama3	Ollama model for white
--black-model	llama3	Ollama model for black
--ollama-url	http://localhost:11434	Ollama API URL
--temperature	0.7	LLM temperature (0.0-1.0)

Game Options

Option	Default	Description
--delay	1.5	Delay between moves (seconds)
--games	1	Number of games to play
--tournament	false	Run tournament with stats
--save-pgn	false	Save games to PGN files
--list-models	false	List available Ollama models
-h, --help	-	Show help message and exit

Stockfish Skill Levels

Level	Approximate Rating	Description
0-3	800-1200	Beginner
4-7	1200-1600	Casual player
8-11	1600-2000	Club player
12-15	2000-2400	Advanced
16-19	2400-2800	Expert/Master
20	3000+	Full strength

Examples

# Beginner vs intermediate Stockfish
python -m src.main --white-skill 3 --black-skill 8

# Fast game with minimal delay
python -m src.main --delay 0.5 --engine-time 0.5

# Deep analysis mode (slower but stronger)
python -m src.main --engine-depth 20

# LLM trying to beat weak Stockfish
python -m src.main --white-engine llm --white-model llama3 --black-skill 1

# 10-game match, save results
python -m src.main --tournament --games 10 --save-pgn --white-skill 10 --black-skill 15

Display

The game displays a centered chess board with:

         ╭───────────── AI Chess Battle ──────────────╮
         │                                            │
         │    ♚  Stockfish (Skill 5)  (Black)         │
         │                                            │
         │         a   b   c   d   e   f   g   h      │
         │      8  ♜   ♞   ♝   ♛   ♚   ♝   ♞   ♜      │
         │      7  ♟   ♟   ♟   ♟   ♟   ♟   ♟   ♟      │
         │      ...                                   │
         │      2  ♙   ♙   ♙   ♙   ♙   ♙   ♙   ♙      │
         │      1  ♖   ♘   ♗   ♕   ♔   ♗   ♘   ♖      │
         │                                            │
         │    ♔  Stockfish (Skill 15)  (White)        │
         │         Captured: ♟ ♟ ♞                    │
         │                                            │
         │         Move 12  ♔ White to play           │
         │      ♔ Stockfish (Skill 15) leads by +4    │
         │                                            │
         ╰──────────── Powered by Ollama ─────────────╯

• Board colors: Tan/brown squares with high contrast pieces
• Highlighting: Last move shown in bright green
• Material score: Shows who's winning and by how much

Saved Games

PGN files are saved to the games/ directory:

games/20240115_143022_Stockfish_(Skill_10)_vs_Stockfish_(Skill_5).pgn

Project Structure

ai_chess/
├── README.md
├── requirements.txt
├── src/
│   ├── __init__.py
│   ├── main.py           # CLI entry point
│   ├── chess_game.py     # Game orchestration
│   ├── board_display.py  # Terminal rendering
│   ├── ai_player.py      # Ollama LLM integration
│   ├── engine_player.py  # Stockfish integration
│   ├── game_recorder.py  # PGN save/replay
│   └── utils.py          # Helper functions
├── games/                # Saved PGN files
└── tests/
    └── __init__.py

Troubleshooting

"Stockfish not found"

Install Stockfish for your system (see Installation), or specify the path:

python -m src.main --engine-path /path/to/stockfish

"Cannot connect to Ollama"

Only needed if using --white-engine llm or --black-engine llm:

ollama serve

LLM makes bad moves

This is expected - LLMs are not chess engines. They pattern-match rather than calculate. Use Stockfish for proper chess, or pit LLMs against low-skill Stockfish for entertainment.

License

MIT