chess-post-analyst 1.0.1
A professional chess post-game analysis tool with CLI and web interfaces
Requires Python: >=3.8
Keywords: chess analysis stockfish pgn game-analysis chess-engine

# ♟️ Chess Post-Game Analyst

<div align="center">

![Chess Analyst Banner](https://img.shields.io/badge/Chess-Post--Game%20Analyst-success?style=for-the-badge&logo=chess&logoColor=white)

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

**A professional, production-ready chess game analysis tool with interactive web interface**

[![Try Live Demo](https://img.shields.io/badge/🎮_Try_Live_Demo-Click_Here-success?style=for-the-badge)](https://lekhanpro.github.io/chess-post-game-analyst)
[![📚 Documentation](https://img.shields.io/badge/📚_Complete_Guide-For_Beginners-blue?style=for-the-badge)](https://lekhanpro.github.io/chess-post-game-analyst/docs)

![Interactive Analysis](https://img.shields.io/badge/✨_Interactive_Board-✓-green) ![Evaluation Graph](https://img.shields.io/badge/📊_Evaluation_Graph-✓-green) ![Coaching Tips](https://img.shields.io/badge/🧠_Coaching_Tips-✓-green)

[Features](#-features) • [Quick Start](#-quickstart-for-beginners) • [Installation](#-installation) • [Documentation](#-documentation) • [Contributing](#-contributing)

</div>

---

## 🎯 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](https://chess.com) or [Lichess](https://lichess.org)

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](https://lekhanpro.github.io/chess-post-game-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](https://lekhanpro.github.io/chess-post-game-analyst/docs/getting-started.html)

---

## 🚀 Installation

### Prerequisites

- Python 3.8 or higher
- Stockfish chess engine ([Download Here](https://stockfishchess.org/download/))

### Quick Install

```bash
# 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

```bash
# Build and run with Docker Compose
docker-compose up -d

# Access web interface at http://localhost:5000
```

---

## 💡 Usage

### Command Line Interface

#### Basic Analysis

```bash
# 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

```bash
# 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

```bash
# Set Stockfish engine path
chess-analyst config --engine-path /usr/local/bin/stockfish

# View current configuration
chess-analyst config --show
```

### Web Interface

```bash
# 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

```python
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

```bash
# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install
```

### Running Tests

```bash
# 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

```bash
# Format code
black chess_analyst/

# Lint code
flake8 chess_analyst/

# Type checking
mypy chess_analyst/
```

---

## 📚 Documentation

- [API Documentation](docs/API.md)
- [Contributing Guidelines](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Changelog](CHANGELOG.md)
- [Architecture Overview](docs/ARCHITECTURE.md)

---

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) 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](LICENSE) file for details.

---

## 🙏 Acknowledgments

- [python-chess](https://python-chess.readthedocs.io/) - Chess library for Python
- [Stockfish](https://stockfishchess.org/) - Powerful chess engine
- [chessboard.js](https://chessboardjs.com/) - JavaScript chessboard component
- The chess community for continuous inspiration

---

## 📧 Contact

**Project Maintainer**: [@lekhanpro](https://github.com/lekhanpro)

**Project Link**: [https://github.com/lekhanpro/chess-post-game-analyst](https://github.com/lekhanpro/chess-post-game-analyst)

---

<div align="center">

**Made with ♟️ by chess enthusiasts, for chess enthusiasts**

⭐ Star this repository if you find it helpful!

</div>