♟️ Chess Post-Game Analyst

A professional, production-ready chess game analysis tool with interactive web interface

Features • Quick Start • Installation • Documentation • Contributing

---

🎯 Features

Core Analysis

• ✨ Deep Game Analysis - Powered by Stockfish engine for accurate position evaluation
• 🎯 Move Classification - Identifies brilliant moves, blunders, mistakes, and inaccuracies
• 📊 Accuracy Metrics - Calculate player accuracy and performance ratings
• 🔍 Critical Moments - Highlight turning points and missed opportunities
• 📝 PGN Support - Parse and analyze standard PGN (Portable Game Notation) files

Interactive Web Interface

• ♟️ Interactive Chessboard - Replay games move-by-move with visual position display
• 📈 Evaluation Graph - See position evaluation change throughout the game
• 🧠 Coaching Tips - Get beginner-friendly explanations for every type of mistake
• 📋 Paste PGN - Analyze games directly from clipboard without file upload
• ⭐ Sample Games - Try analysis with pre-loaded famous games
• ⌨️ Keyboard Controls - Navigate with arrow keys for quick replay
• 📱 Responsive Design - Works seamlessly on desktop, tablet, and mobile

Output Formats

• 📄 JSON - Machine-readable format for integration
• 📝 Text - Human-readable analysis reports
• 🌐 HTML - Rich formatted reports with diagrams
• 📊 Statistics - Detailed game statistics and insights

Production Features

• 🐳 Docker Support - Easy deployment with Docker and docker-compose
• ⚡ Fast Performance - Optimized for analyzing multiple games
• 🔒 Error Handling - Robust error handling and logging
• ✅ Well Tested - Comprehensive unit and integration tests
• 📚 Documentation - Complete API and usage documentation

---

🚀 Quick Start for Beginners

Never analyzed a chess game before? No problem! Here's how to get started in 3 minutes:

1. Play a game on Chess.com or Lichess

2. Export your game as a PGN file:

   • On Chess.com: Archive → Click game → Share → Download PGN
   • On Lichess: Click game → Export → Download PGN

3. Visit Chess Analyst and upload your file

4. Review your analysis - see your mistakes, accuracy, and get tips to improve!

Or try instantly: Click "Try Sample" to analyze a famous game without uploading anything!

📚 New to chess analysis? Read our Complete Beginner's Guide

---

🚀 Installation

Prerequisites

• Python 3.8 or higher
• Stockfish chess engine (Download Here)

Quick Install

# Clone the repository
git clone https://github.com/lekhanpro/chess-post-game-analyst.git
cd chess-post-game-analyst

# Install dependencies
pip install -r requirements.txt

# Install the package
pip install -e .

Docker Installation

# Build and run with Docker Compose
docker-compose up -d

# Access web interface at http://localhost:5000

---

💡 Usage

Command Line Interface

Basic Analysis

# Analyze a single PGN file
chess-analyst analyze game.pgn

# Specify output format
chess-analyst analyze game.pgn --format json

# Save analysis to file
chess-analyst analyze game.pgn --output analysis.txt

Advanced Options

# Analyze with custom engine depth
chess-analyst analyze game.pgn --depth 20

# Show only blunders and mistakes
chess-analyst analyze game.pgn --threshold mistake

# Analyze multiple games
chess-analyst analyze games/*.pgn --output results/

Configuration

# Set Stockfish engine path
chess-analyst config --engine-path /usr/local/bin/stockfish

# View current configuration
chess-analyst config --show

Web Interface

# Start the web server
python web/app.py

# Or use the CLI command
chess-analyst serve --port 5000

Then open your browser to http://localhost:5000

Python API

from chess_analyst import GameAnalyzer, PGNParser

# Load a game
parser = PGNParser("game.pgn")
game = parser.load_game()

# Analyze the game
analyzer = GameAnalyzer(engine_path="/usr/local/bin/stockfish")
analysis = analyzer.analyze(game)

# Get results
for move_analysis in analysis.moves:
    print(f"Move {move_analysis.move_number}: {move_analysis.classification}")
    print(f"Evaluation: {move_analysis.evaluation}")

---

📊 Sample Output

CLI Output

♟️  Chess Game Analysis Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Game Information:
  White: Magnus Carlsen (2863)
  Black: Hikaru Nakamura (2829)
  Event: World Blitz Championship 2024
  Result: 1-0

Overall Statistics:
  White Accuracy: 94.2%
  Black Accuracy: 87.6%
  Total Moves: 42
  Critical Positions: 5

Move Analysis:
  ✨ Brilliant Moves: 2
  ✅ Good Moves: 35
  ⚠️  Inaccuracies: 3
  ❌ Mistakes: 1
  💥 Blunders: 1

Key Moments:
  Move 18: Black missed winning continuation (-3.2 → +0.5)
  Move 24: White found brilliant tactical shot (+0.8 → +4.1)
  Move 31: Black blunder lost the game (+2.1 → +8.4)

---

🛠️ Development

Setup Development Environment

# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=chess_analyst --cov-report=html

# Run specific test file
pytest tests/test_analyzer.py

Code Quality

# Format code
black chess_analyst/

# Lint code
flake8 chess_analyst/

# Type checking
mypy chess_analyst/

---

📚 Documentation

• API Documentation
• Contributing Guidelines
• Code of Conduct
• Changelog
• Architecture Overview

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Quick Start for Contributors

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• python-chess - Chess library for Python
• Stockfish - Powerful chess engine
• chessboard.js - JavaScript chessboard component
• The chess community for continuous inspiration

---

📧 Contact

Project Maintainer: @lekhanpro

Project Link: https://github.com/lekhanpro/chess-post-game-analyst

---

Made with ♟️ by chess enthusiasts, for chess enthusiasts

⭐ Star this repository if you find it helpful!