Chess Game Report

Generate comprehensive, narrative-style chess game analysis using Stockfish and AI.

This tool operationalizes the approach described in Narrative AI Game Analysis. Instead of drowning in engine evaluation numbers (+0.73, -0.42), you get human-readable analysis that explains why moves were made and what the strategic themes were. See the MyAnalysis.txt file in this repo for an example of what an output report might look like.

Features

• Stockfish Analysis: Evaluates every position in your game
• Descriptive Labels: Converts numeric evals to human language ("slightly better for White", "winning advantage")
• Chapter-Based Analysis: Automatically breaks games into logical phases (opening, middlegame battles, endgame technique)
• AI-Powered Insights: Uses Google Gemini to generate narrative analysis with:
  • The Big Picture: Strategic narrative of each phase
  • Key Learning Points: Practical takeaways you can apply
  • Deeper Analysis: Technical details on critical decisions, pawn structure, and piece coordination
• Handles Complex PGNs: Properly processes variations, comments, and annotations (analyzes main line only)

Requirements

• Python 3.8+
• Stockfish chess engine
• Google Gemini API key

Installation

1. Install Python dependencies:

   pip install python-chess

2. Install Stockfish:

   • Linux: sudo apt install stockfish or download from Stockfish
   • macOS: brew install stockfish
   • Windows: Download from Stockfish

3. Get a Gemini API key:

   • Visit Google AI Studio
   • Sign in and click "Get API key"
   • Create or select a project
   • Copy your API key

Usage

Quick Start (Test Game)

export GEMINI_API_KEY='your-api-key-here'
python run_test.py

This analyzes the embedded test game (Dutch Defense) and outputs to GameAnalysis_Output.txt.

Analyze Your Own Games

# Basic usage
python chess_analyzer.py mygame.pgn -o analysis.txt

# With custom settings
python chess_analyzer.py tournament.pgn \
    --depth 20 \
    --threads 2 \
    --hash 512 \
    --time 1000 \
    --perspective White \
    -o my_analysis.txt

# Generate prompt only (for testing or custom API usage)
python chess_analyzer.py mygame.pgn --prompt-only --prompt-output my_prompt.txt

Command-Line Options

Option	Description	Default
--api-key	Gemini API key	GEMINI_API_KEY env var
--model	Gemini model to use	gemini-2.5-flash-lite
--perspective	Analyze from "White" or "Black" view	White
--depth	Stockfish search depth	18
--time	Time per move (milliseconds)	500
--threads	CPU threads for Stockfish	1
--hash	Hash table size (MB)	256
-o, --output	Output file path	stdout
--prompt-only	Generate prompt without calling API	False
--prompt-output	Output file for prompt	prompt.txt

Configuration

Edit the top of chess_analyzer.py to set defaults:

# Stockfish path
STOCKFISH_PATH = os.path.expanduser("~/.local/bin/stockfish")

# Stockfish settings
STOCKFISH_DEPTH = 18
STOCKFISH_TIME_PER_MOVE = 500
STOCKFISH_THREADS = 1
STOCKFISH_HASH = 256

# Gemini API
GEMINI_API_KEY = ""  # Or set via environment variable
GEMINI_MODEL = "gemini-2.5-flash-lite"

Example Output

The analysis is structured into chapters, each with three sections:

Dutch Defense Opening Phase

1. d4 f5 2. Nc3 Nf6 3. Bf4 e6 ...

The Big Picture

In this opening sequence, White responds to Black's Dutch Defense with a solid 
development plan, establishing central control while preparing for kingside castling...

Key Learning Points

   1. Central Tension Management: White demonstrates good timing with the e4 advance...

   2. Bishop Pair Handling: The early Bxd6 exchange damages Black's pawn structure...

Deeper Analysis

Critical Decision Points:
    • The early Bf4 development prepares for control of e5...
    • The decision to exchange on d6 is strategically sound...

Pawn Structure Considerations: White has a clean structure while Black has doubled d-pawns...

Piece Coordination: White's pieces are harmoniously placed...

How It Works

1. PGN Parsing: Reads your game file, handling variations and comments
2. Stockfish Analysis: Evaluates each position (configurable depth/time)
3. Evaluation Conversion: Translates numbers to descriptive labels
4. Chapter Detection: Identifies natural game phases based on eval shifts and move count
5. AI Analysis: Sends structured prompt to Gemini with all context
6. Output: Generates readable analysis report

Cost

• Stockfish: Free (open source)
• Gemini API: Free tier available (~15 requests/minute, 1M tokens/day)
• Typical game analysis costs ~10,000-50,000 tokens depending on game length

License

MIT License - see LICENSE file

Acknowledgments

Methodology based on the approach described at MattPlaysChess.