Metadata-Version: 2.4
Name: chess-self-coach
Version: 0.4.17
Summary: Learn from your own chess mistakes: Stockfish analysis + spaced repetition training
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: berserk<1,>=0.14.0
Requires-Dist: chess-com<4,>=3.0.0
Requires-Dist: chess<2,>=1.11.0
Requires-Dist: fastapi<1,>=0.115.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: optuna>=4.8.0
Requires-Dist: python-dotenv<2,>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: scikit-learn>=1.5.0
Requires-Dist: sse-starlette>=3.3.3
Requires-Dist: uvicorn[standard]<1,>=0.34.0
Requires-Dist: xgboost>=2.0.0
Requires-Dist: zstandard>=0.23.0
Description-Content-Type: text/markdown

# Chess Self-Coach

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Learn from your own mistakes.** Chess Self-Coach fetches your games from Lichess and chess.com, finds your blunders with Stockfish and Lichess tablebases, drills you on the correct moves with spaced repetition, and provides chess.com-quality game review with eval bar, score chart, and move classifications.

**[Static demo](https://bobain.github.io/chess-self-coach/train/)** | **[Documentation](https://bobain.github.io/chess-self-coach/docs/)** | **[Landing page](https://bobain.github.io/chess-self-coach/)**

## How It Works

**Your games → Stockfish analysis → Training drills + Game review**

The PWA opens on a **game list** — your recent games from Lichess and chess.com. From there:

- **Select games** to analyze with Stockfish (checkboxes + batch analyze)
- **Click a game** for chess.com-style game review (eval bar, score chart, move classifications)
- **Train** on any analyzed game, or open full **Training** from the menu for spaced repetition drills across all your mistakes

### One command to start

```bash
chess-self-coach train --prepare    # fetch games + Stockfish analysis (~5 min)
chess-self-coach                    # open training in browser
```

### What you see

For each mistake in your games, the trainer shows:
- **Context**: "Middlegame, you had a slight advantage. Your move lost significant material."
- **The position** with material balance (captured pieces)
- **Your task**: find the better move by dragging a piece
- **Wrong move?** Stockfish shows how the opponent punishes it, then Retry
- **After answering**: explanation, best line (playable), link to the original game
- **Spaced repetition**: positions come back until mastered (intra-session + SM-2)
- **Give up**: permanently dismiss positions you don't want to review

### Mistake categories

| Category | Centipawn loss | Example |
|----------|--------------|---------|
| Blunder | >= 200 cp | Hanging a piece, allowing checkmate |
| Mistake | 100-199 cp | Missing a tactic, losing material |
| Inaccuracy | 50-99 cp | Passive move when active was better |

Endgame positions (≤ 7 pieces) are resolved by the [Lichess tablebase API](https://tablebase.lichess.ovh/) with mathematically exact Win/Draw/Loss verdicts — no Stockfish heuristics needed.

## Installation

### One-liner (recommended)

```bash
curl -fsSL https://raw.githubusercontent.com/Bobain/chess-self-coach/main/install.sh | bash
```

Installs Stockfish, Python, pipx, and chess-self-coach. Then run the setup wizard:

```bash
chess-self-coach setup
```

**Supported platforms**: macOS (Homebrew), Ubuntu/Debian (apt).

### Manual installation

```bash
# 1. Install Stockfish
sudo apt install stockfish  # or: brew install stockfish

# 2. Install chess-self-coach
pipx install chess-self-coach

# 3. Run the interactive setup wizard
chess-self-coach setup
```

### Update

```bash
chess-self-coach update
```

### Setup wizard

The `setup` command will:
1. Find Stockfish on your system
2. Guide you through **Lichess token creation** (step by step)
3. Ask for your **chess.com username** (for importing games)

## CLI Reference

### Training (main feature)

```bash
# Fetch your games and analyze with Stockfish
chess-self-coach train --prepare                    # 10 games, depth 18, parallel
chess-self-coach train --prepare --games 50         # more games
chess-self-coach train --prepare --depth 12         # faster analysis

# Open the training interface
chess-self-coach

# Check your stats
chess-self-coach train --stats
```

Incremental by default: only new games are analyzed. Existing positions and your SRS progress are preserved.

```bash
# Developer options
chess-self-coach train --prepare --fresh            # [dev] discard data, start from scratch
chess-self-coach train --refresh-explanations       # [dev] regenerate texts without Stockfish
```

### Other commands

```bash
chess-self-coach syzygy [download|status]  # manage Syzygy endgame tablebases
chess-self-coach setup                  # interactive configuration wizard
```

## Data & Privacy

- Your games are fetched from public APIs (Lichess, chess.com)
- `data/training_data.json` and `data/analysis_data.json` are stored locally (gitignored)
- Drill progress is in your browser's localStorage
- No server, no account, no tracking

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for code guidelines.

## License

[MIT](LICENSE)
