Caissa - Chess Weakness Analyzer

Analyze your Lichess games to identify recurring weakness patterns and get coaching insights.

Prerequisites

• Python 3.13+
• Stockfish chess engine (install via brew install stockfish on macOS)
• uv package manager (recommended) or pip

Setup

Option A: Using uv (Recommended)

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the project in development mode
uv pip install -e .

Option B: Using pip/venv

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the project in development mode
pip install -e .

Quick Start

1. Initialize

# Run initialization (creates config, database, downloads opening book)
caissa init

# View configuration
caissa config show

# Set your Lichess username
caissa config set lichess.username YOUR_USERNAME

2. Fetch Games

# Fetch your last 100 games
caissa fetch games YOUR_USERNAME

# Fetch with options
caissa fetch games YOUR_USERNAME --max 50 --time-control rapid --since 2024-01-01

# Fetch a single game by ID
caissa fetch game GAME_ID

3. Analyze Games

# Analyze all fetched games with Stockfish (detects patterns automatically)
caissa analyze

# Analyze a specific game
caissa analyze game GAME_ID --depth 18

# Re-analyze already analyzed games
caissa analyze --force

# Re-run pattern detection on already analyzed games (no Stockfish needed)
caissa analyze patterns

4. View Reports

# Show weakness pattern summary across all games
caissa report summary

# Show detailed report for a single game
caissa report game GAME_ID

# Export as JSON for further analysis
caissa report game GAME_ID --format json
caissa report summary --format json

Pattern Categories

Caissa detects the following weakness patterns:

Pattern	Description
Missed Tactic	Generic tactical miss with high centipawn loss
Missed Mate	Had a winning checkmate but missed it
Missed Fork	Best move was a fork attacking 2+ pieces
Missed Pin	Best move created an absolute pin
Missed Skewer	Best move was a skewer
Hanging Piece	Left a piece undefended
Time Trouble Blunder	Blunder with < 30s on clock
Premature Move	Moved too quickly (< 3s) and made an error
Opening/Middlegame/Endgame Error	Phase-specific errors (fallback category)

CLI Reference

# Setup
caissa init                              # Initialize: download book, init DB, configure
caissa config show                       # Show configuration
caissa config set <key> <value>          # Set config value

# Fetch games
caissa fetch games [USERNAME]            # Fetch games from Lichess
  --since DATE                           # Games after date (YYYY-MM-DD)
  --max N                                # Max games to fetch (default: 100)
  --time-control TC                      # bullet|blitz|rapid|classical|all
  --rated/--all-games                    # Rated only (default) or all
caissa fetch game <GAME_ID>              # Fetch single game by ID

# Analysis
caissa analyze                           # Analyze fetched games with Stockfish
  --depth N                              # Stockfish depth (default: 18)
  --force                                # Re-analyze already analyzed games
  --max N                                # Max games to analyze
  --username USER                        # Analyze specific user's games
caissa analyze game <GAME_ID>            # Analyze a single game
caissa analyze patterns                  # Re-run pattern detection only
  --username USER                        # For specific user
  --force                                # Clear and re-detect

# Reports
caissa report summary                    # Pattern summary across all games
  --top N                                # Show top N patterns (default: 10)
  --format rich|json                     # Output format
  --username USER                        # For specific user
caissa report game <GAME_ID>             # Detailed single game report
  --format rich|json                     # Output format
  --all                                  # Show all moves, not just mistakes

Example Output

Pattern Summary

                            Top 10 Patterns
┏━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ #  ┃ Pattern          ┃ Count ┃ Avg CP Loss ┃ Total CP Loss ┃ Impact ┃
┡━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ 1  │ Missed Tactic    │   292 │        2598 │        758581 │ 758581 │
│ 2  │ Missed Mate      │    16 │        8626 │        138020 │ 138020 │
│ 3  │ Hanging Piece    │   141 │         952 │        134170 │ 134170 │
│ ...                                                                   │
└────┴──────────────────┴───────┴─────────────┴───────────────┴────────┘

Game Report

╭───────────────────────────────── Game Info ──────────────────────────────────╮
│ ID: 9TqS7N66                                                                 │
│ URL: https://lichess.org/9TqS7N66                                            │
│ Player: username (white)                                                     │
│ Result: loss (0-1)                                                           │
╰──────────────────────────────────────────────────────────────────────────────╯

17. Ne3 ?!
    Best move: Nxf6+
    Eval drop: 86 cp
    Phase: middlegame
    Pattern: Missed Fork
    Tactic: fork
    Targets: bishop, king

Development

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src/caissa

# Linting
ruff check src/caissa

Project Structure

caissa/
├── src/caissa/
│   ├── cli/          # Command-line interface (Typer)
│   ├── core/         # Config and data models
│   ├── ingestion/    # Lichess API client
│   ├── extraction/   # PGN parsing, phase detection
│   ├── analysis/     # Stockfish evaluation, opening book
│   ├── patterns/     # Pattern detection (tactical, time trouble)
│   ├── synthesis/    # LLM prompt generation (coming soon)
│   └── persistence/  # SQLite database
├── docs/             # Documentation
├── tests/
├── PLAN.md           # Implementation roadmap
└── README.md

User data is stored in ~/.local/share/caissa/:

• caissa.db - SQLite database with games, positions, mistakes, patterns
• books/gm2600.bin - Opening book (auto-downloaded)

Configuration

Configuration is stored at ~/.config/caissa/config.toml:

[lichess]
username = "your_username"
default_time_controls = ["blitz", "rapid"]

[stockfish]
path = ""  # Auto-detected if empty
depth = 18

[analysis]
inaccuracy_threshold = 50   # centipawns
mistake_threshold = 100
blunder_threshold = 200
time_trouble_seconds = 30

Implementation Status

• Phase 1: Foundation (config, database, CLI skeleton)
• Phase 2: Ingestion (Lichess API client, fetch command)
• Phase 3: Extraction (PGN parsing, phase detection)
• Phase 4: Analysis (Stockfish evaluation)
• Phase 5: Pattern Detection (tactical, time trouble, phase-based)
• Phase 6: Reporting (summary, game reports) - partial, LLM prompts pending
• Phase 7: TUI (Post-MVP)

See PLAN.md for detailed implementation phases.