Stefan
3afc75f78d
- Add tactical recognition system documentation - Update to 9 AI personalities (was 3) - Improve Quick Start section with Docker Compose as primary method - Document automated Docker builds via GitHub Actions - Add detailed tactical detection feature explanation - Update game flow to mention tactical feedback - Reorganize deployment sections for clarity
293 lines
11 KiB
Markdown
293 lines
11 KiB
Markdown
# AI Chess Tutor
|
|
|
|
## The Story
|
|
I always wanted to implement an AI-based chess tutor because I like playing chess, although to be honest, I actually suck at it. I didn't find the existing tutors or big apps useful enough for my needs, so I decided to build my own approach.
|
|
|
|
This application was built using **Antigravity by Google**. I like to work with it, though sometimes it just runs away. Still, I found the end result to be quite fun to play, which is why I'm sharing it here.
|
|
|
|
## How It Works
|
|
|
|
**AI Chess Tutor** is an interactive chess learning application where you play against an AI opponent powered by Stockfish while receiving real-time coaching feedback from a Large Language Model (LLM).
|
|
|
|
### Typical Game Flow
|
|
|
|
1. **Choose Your Personality**: Select from 9 unique AI coaching personalities, each with their own teaching style and character
|
|
2. **Play Chess**: Make your moves on the board while the Stockfish engine plays against you
|
|
3. **Get Real-Time Feedback**: After each move exchange, your AI tutor analyzes the position and provides personalized feedback based on:
|
|
- Move quality and alternatives
|
|
- Position evaluation changes
|
|
- **Missed tactical opportunities** (pins, forks, skewers, checks, hanging pieces, material captures)
|
|
- Opening theory (when applicable)
|
|
- Strategic and positional considerations
|
|
4. **Chat with Your Tutor**: Ask questions anytime using the integrated chat feature - your tutor will answer in character
|
|
5. **Post-Game Analysis**: When the game ends, review a comprehensive analysis showing:
|
|
- All your mistakes and inaccuracies
|
|
- Missed tactical opportunities throughout the game
|
|
- Learning opportunities and improvement suggestions
|
|
|
|
|
|
*Screenshot placeholder: Main game interface with board, evaluation bar, and chat*
|
|
|
|
## Features
|
|
|
|
### Core Features
|
|
- **Stockfish Engine**: Powerful chess engine for move analysis and opponent play
|
|
- **Tactical Recognition**: Automatically detects missed tactical opportunities (pins, forks, skewers, checks, hanging pieces, material captures)
|
|
- **Opening Database**: Comprehensive database of chess openings with metadata and theory
|
|
- **Real-Time Evaluation**: Live position evaluation with visual evaluation bar
|
|
- **Move Analysis**: Detailed feedback on every move you make with tactical insights
|
|
- **Interactive Chat**: Ask your AI tutor questions and get personalized answers
|
|
- **Post-Game Analysis**: Review all your mistakes and missed opportunities after each game
|
|
- **Multi-Language Support**: Available in English, German, French, and Italian
|
|
- **FEN/PGN Import**: Import positions or games with automatic format detection
|
|
- **Move History**: Visual move history table with evaluation changes
|
|
|
|
### AI Personalities
|
|
|
|
Choose from **9 distinct coaching personalities**, each offering a unique learning experience:
|
|
|
|
#### 📘 Opening Professor
|
|
*"This is a very instructive structure..."*
|
|
|
|
A calm, deeply knowledgeable educator who loves turning openings into understandable stories with history, plans, and model structures. Perfect for learning opening theory and understanding positional concepts.
|
|
|
|
#### 👨🏫 Professional Coach
|
|
*"Let's analyze the structure of this position"*
|
|
|
|
A strict, analytical, and straightforward chess coach focused on your improvement. Expect objective analysis, clear explanations based on chess principles, and professional teaching methods.
|
|
|
|
#### 🥃 Drunk Russian GM
|
|
*"Ach... life is pain, my boy"*
|
|
|
|
A bitter, fatalistic, but brilliant Grandmaster who has seen it all. Expect brutally honest feedback delivered with dark humor and existential commentary. This personality combines deep chess knowledge with a Dostoevsky-like atmosphere.
|
|
|
|
#### 🎧 Hype Streamer
|
|
*"BRO! THAT MOVE WAS INSANE!"*
|
|
|
|
An energetic, loud, and entertaining chess streamer who makes every game exciting. Expect dramatic reactions, Gen-Z slang, and over-the-top commentary that keeps you engaged and motivated.
|
|
|
|
#### 🧙♂️ Gandalf the Chess Wizard
|
|
*"A move is never late, nor is it early..."*
|
|
|
|
A wise and mystical chess wizard who speaks in riddles and metaphors. Combines chess wisdom with magical references and philosophical insights.
|
|
|
|
#### 🤖 Stockfish (Literal)
|
|
*"Evaluation: +0.7. Best continuation: Nf3, d5, c4..."*
|
|
|
|
The engine itself, speaking in pure chess notation and evaluations. No personality, just raw analysis and computer-like precision.
|
|
|
|
#### 😤 Toxic Gamer
|
|
*"Are you even trying? That's the worst move I've seen all day!"*
|
|
|
|
An abrasive, confrontational personality that roasts your mistakes mercilessly. Not for the faint of heart, but some players find the challenge motivating.
|
|
|
|
#### 🎭 Shakespearean Bard
|
|
*"To castle or not to castle, that is the question..."*
|
|
|
|
A theatrical personality that delivers chess analysis in Shakespearean verse and dramatic monologues. Makes every game feel like a stage performance.
|
|
|
|
#### 🧘 Zen Master
|
|
*"The board is empty, yet full of possibilities..."*
|
|
|
|
A calm, meditative personality that approaches chess as a spiritual practice. Focuses on mindfulness, patience, and finding harmony in the position.
|
|
|
|
### Tactical Recognition System
|
|
|
|
One of the standout features is the **automatic tactical pattern detection** that runs after every move:
|
|
|
|
**What it detects:**
|
|
- **Material Captures**: Safe captures of pieces and pawns (with recapture analysis)
|
|
- **Pins**: Pieces pinned to the king or more valuable pieces
|
|
- **Forks**: Pieces attacking multiple valuable targets simultaneously
|
|
- **Skewers**: Attacks forcing a valuable piece to move, exposing another
|
|
- **Checks**: Moves that give check to the opponent's king
|
|
- **Hanging Pieces**: Undefended pieces that could be captured
|
|
|
|
**How it works:**
|
|
1. After each move, the system compares your move to the engine's best move
|
|
2. If there's a significant evaluation difference, it analyzes what tactical opportunities were missed
|
|
3. The AI tutor receives this information and explains it in real-time in their characteristic style
|
|
4. All missed tactics are also shown in the post-game analysis
|
|
|
|
**Conservative approach:**
|
|
- The system uses multiple filters to avoid false positives
|
|
- Only reports tactics when there's a clear advantage
|
|
- Checks for piece safety (e.g., won't report a "capture" if the piece can be immediately recaptured)
|
|
|
|
This feature helps you learn tactical patterns naturally during gameplay, rather than just through puzzle training.
|
|
|
|
## Quick Start
|
|
|
|
### Option 1: Docker Compose (Recommended - Easiest!)
|
|
|
|
The fastest way to get started is using our pre-built Docker image from GitHub Container Registry:
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/stefan-kp/chess_tutor.git
|
|
cd chess_tutor
|
|
|
|
# (Optional) Create .env file with your API key
|
|
echo "NEXT_PUBLIC_GEMINI_API_KEY=your_api_key_here" > .env
|
|
|
|
# Start the application
|
|
docker-compose up -d
|
|
|
|
# View logs
|
|
docker-compose logs -f
|
|
```
|
|
|
|
The application will be available at `http://localhost:3050`
|
|
|
|
**What happens:**
|
|
- Docker Compose automatically pulls the latest pre-built image from `ghcr.io/stefan-kp/chess-tutor:latest`
|
|
- No build step required - the image is built automatically on every push to main via GitHub Actions
|
|
- The container starts with health checks and auto-restart enabled
|
|
|
|
### Option 2: Local Development
|
|
|
|
If you want to run the application locally for development:
|
|
|
|
#### Prerequisites
|
|
- Node.js 18+ installed
|
|
- A free Google Gemini API key
|
|
|
|
#### Steps
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/stefan-kp/chess_tutor.git
|
|
cd chess_tutor
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Create .env file (optional)
|
|
echo "NEXT_PUBLIC_GEMINI_API_KEY=your_api_key_here" > .env
|
|
|
|
# Run development server
|
|
npm run dev
|
|
|
|
# Or build and run production
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
The application will be available at `http://localhost:3050`
|
|
|
|
### Getting Your Gemini API Key
|
|
|
|
1. Visit [Google AI Studio](https://aistudio.google.com/app/apikey)
|
|
2. Sign in with your Google account
|
|
3. Click "Create API Key"
|
|
4. Copy your API key
|
|
|
|
### API Key Configuration
|
|
|
|
You have two options for providing your Gemini API key:
|
|
|
|
#### Option 1: Environment Variable (Recommended for Docker/Server)
|
|
1. Create a `.env` file in the project root
|
|
2. Add your API key:
|
|
```
|
|
NEXT_PUBLIC_GEMINI_API_KEY=your_api_key_here
|
|
```
|
|
3. The application will automatically use this key
|
|
|
|
#### Option 2: Browser Storage (Fallback)
|
|
1. Run the application without an API key
|
|
2. When prompted, enter your API key in the modal dialog
|
|
3. The key will be stored in your browser's localStorage
|
|
|
|
> [!NOTE]
|
|
> You can update your API key anytime by clicking the key icon in the bottom-right corner of the application.
|
|
|
|
## Advanced Deployment
|
|
|
|
### Automated Docker Builds
|
|
|
|
This project uses GitHub Actions to automatically build and publish Docker images to GitHub Container Registry (GHCR) on every push to the `main` branch.
|
|
|
|
**What this means:**
|
|
- Every commit to `main` triggers an automatic Docker build
|
|
- The latest image is always available at `ghcr.io/stefan-kp/chess-tutor:latest`
|
|
- Each build is also tagged with the commit SHA for version tracking
|
|
- No need to build locally - just pull and run!
|
|
|
|
### Using Pre-Built Images
|
|
|
|
The `docker-compose.yml` file is already configured to use the pre-built image:
|
|
|
|
```yaml
|
|
services:
|
|
chess-tutor:
|
|
image: ghcr.io/stefan-kp/chess-tutor:latest
|
|
# ... rest of configuration
|
|
```
|
|
|
|
This means you can deploy anywhere with just:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
### Manual Docker Build (Optional)
|
|
|
|
If you prefer to build the image yourself:
|
|
|
|
```bash
|
|
# Build the image
|
|
docker build -t chess-tutor:latest .
|
|
|
|
# Run the container
|
|
docker run -d \
|
|
--name chess-tutor \
|
|
-p 3050:3050 \
|
|
-e NEXT_PUBLIC_GEMINI_API_KEY=your_api_key_here \
|
|
--restart unless-stopped \
|
|
chess-tutor:latest
|
|
```
|
|
|
|
### Nginx Reverse Proxy
|
|
|
|
For production deployment behind nginx, use the provided `nginx.conf.example`:
|
|
|
|
```bash
|
|
# Copy the example configuration
|
|
sudo cp nginx.conf.example /etc/nginx/sites-available/chess-tutor
|
|
|
|
# Edit the configuration
|
|
sudo nano /etc/nginx/sites-available/chess-tutor
|
|
# Update: server_name, SSL certificates (if using HTTPS)
|
|
|
|
# Enable the site
|
|
sudo ln -s /etc/nginx/sites-available/chess-tutor /etc/nginx/sites-enabled/
|
|
|
|
# Test nginx configuration
|
|
sudo nginx -t
|
|
|
|
# Reload nginx
|
|
sudo systemctl reload nginx
|
|
```
|
|
|
|
## Configuration
|
|
|
|
You can configure the application using environment variables in your `.env` file or Docker Compose configuration:
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `NEXT_PUBLIC_GEMINI_API_KEY` | Google Gemini API Key for AI features | (Required for AI) |
|
|
| `IMPRINT_URL` | External URL for the Imprint link in the footer. If not set, an internal page is used. | Internal Page |
|
|
| `DATA_PRIVACY_RESPONSIBLE_PERSON` | Name of the person responsible for data privacy (shown on /privacy page). | Placeholder |
|
|
|
|
## License
|
|
|
|
This project is licensed under the GNU General Public License v3.0 (GPLv3) - see the [LICENSE](LICENSE) file for details.
|
|
|
|
This application uses [Stockfish](https://stockfishchess.org/), which is licensed under the GPLv3.
|
|
|
|
## Credits
|
|
- Opening collection originally by [ragizaki/ChessOpeningsRecommender](https://github.com/ragizaki/ChessOpeningsRecommender)
|
|
- Chess engine: [Stockfish](https://stockfishchess.org/) (GPLv3)
|
|
- LLM: [Google Gemini](https://ai.google.dev/)
|
|
|