♟️ Chess Training — Magnus Carlsen Game Analyzer

AI-powered chess training app that analyzes Magnus Carlsen's games with Stockfish engine evaluation and LLM-generated natural language commentary on every move.

🚀 Features

• Interactive board — Navigate move-by-move through Carlsen's games
• Stockfish analysis — Every position evaluated with configurable depth
• AI commentary — Optional LLM (GPT-4o-mini) generates human-readable explanations of each move's strategy and tactics
• Game database — SQLite-backed, searchable, paginated
• Import from PGN — Bulk import games from PGN files or download directly via API
• Dark theme — Clean, chess-appropriate dark UI

🏗️ Architecture

Chess/
├── backend/              # FastAPI Python backend
│   ├── main.py          # API server
│   ├── analyzer.py      # Stockfish + LLM pipeline
│   ├── pgn_parser.py    # PGN file parsing
│   ├── database.py      # SQLite game database
│   ├── models.py        # Pydantic data models
│   ├── requirements.txt
│   └── .env.example
├── frontend/             # Next.js React frontend
│   ├── pages/           # Game list & detail pages
│   ├── styles/          # Tailwind CSS + custom styles
│   ├── package.json
│   └── next.config.js
├── scripts/
│   └── download_games.py  # Fetch games from Chess.com/Lichess APIs
├── data/pgn/              # Place PGN files here
├── setup.ps1              # Windows one-click setup script
└── README.md

🪟 Windows Setup

Prerequisites

Tool	Where to get it
Python 3.10+	python.org (check "Add to PATH")
Node.js 18+	nodejs.org
Stockfish	stockfishchess.org or winget install Stockfish.Stockfish

Option A: Quick Setup (recommended)

1. Clone the repo:

   git clone https://github.com/<YOUR_USERNAME>/Chess.git
   cd Chess

2. Run the setup script (as Administrator):

   .\setup.ps1

   This creates a Python venv, installs all dependencies, and sets up the .env file.

3. Set your OpenAI API key (optional — needed for LLM commentary):

   notepad backend\.env

   Replace sk-your-key-here with your key from platform.openai.com

Option B: Manual Setup

# Terminal 1 — Backend
cd Chess
python -m venv backend\.venv
.\backend\.venv\Scripts\Activate.ps1
pip install -r backend\requirements.txt
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

# Terminal 2 — Frontend
cd Chess\frontend
npm install
npm run dev

4. Download Carlsen's games

cd Chess
.\backend\.venv\Scripts\Activate.ps1
python scripts\download_games.py

Follow the prompts to choose a source (Chess.com / Lichess / both).

5. Import games into the app

After downloading PGN files, import them via the API:

curl -X POST "http://localhost:8000/api/import/pgn?filepath=data/pgn/carlsen_games_20260415.pgn"

Then open http://localhost:3000 to browse and analyze games.

🧠 Understanding the Analysis

Without LLM (Free, works offline)

When you click "Analyze" on a game, Stockfish evaluates every position. The UI shows:

• Evaluation bar — Red/white/black indicator of who's winning
• Move quality — Best move ✅, Mistake ❓, Blunder ❌❌
• Eval swing — How much the evaluation changed with each move

With LLM (requires API key)

After engine analysis, click "LLM Comment" to get natural-language explanations like:

"Carlsen played Nxd5 here, sacrificing a knight for two pawns and exposing the black king. Stockfish shows the eval swings from +0.2 to +1.1 — White gets a lasting initiative with the bishop pair and open files against the castled king. This is a classic Carlsen transformation: dynamic compensation over material."

📡 API Endpoints

Method	Endpoint	Description
GET	/api/games	List games (params: limit, offset, search, analyzed)
GET	/api/games/count	Total game count
GET	/api/games/{id}	Full game with moves and annotations
POST	/api/import/pgn	Import PGN file by path
POST	/api/analyze/position	Analyze a single FEN position
POST	/api/analyze/game/{id}	Run Stockfish on all moves
POST	/api/analyze/game/{id}/annotate	Add LLM commentary to analyzed game
GET	/api/health	Server health check

⚙️ Configuration

Edit backend/.env:

STOCKFISH_PATH=stockfish           # Path to Stockfish binary
ENGINE_DEPTH=18                    # Analysis depth (higher = slower but more accurate)
OPENAI_API_KEY=sk-...              # OpenAI key for LLM commentary
LLM_MODEL=gpt-4o-mini              # Model (gpt-4o-mini is fast/cheap)
LLM_BASE_URL=                      # Optional: for local LLMs (Ollama, llama.cpp)
HOST=0.0.0.0
PORT=8000

Using a Local LLM (free, no API key needed)

Set these in .env:

OPENAI_API_KEY=not-needed
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL=llama3.2

This works with Ollama, llama.cpp, or any OpenAI-compatible local server.

🛠️ Troubleshooting

Problem	Fix
Stockfish not found	Set full path in .env: STOCKFISH_PATH=C:\tools\stockfish\stockfish-windows-x86-64.exe
ModuleNotFoundError	Activate venv: .\backend\.venv\Scripts\Activate.ps1
Port 8000 in use	Change PORT=8001 in .env and update frontend/next.config.js proxy
Board not rendering	Ensure chess.js installed: cd frontend && npm install chess.js
API connection refused	Start backend first, then frontend

📄 License

MIT

---

Built with ♟️ by [Your Name]