Chesscetera

Chesscetera is a Swift‑based chess‑coaching tool that fetches recent games from Lichess, evaluates every half‑move with Stockfish, stores the full analysis as JSON, and optionally generates LLM‑driven coaching reports.

---

Architecture

Lichess
 ↓
ChessKit
 ↓
Stockfish (depth 15, 4 threads, 128 MiB hash)
 ↓
JSON store (data/analysis/*.json)
 ↓
Aggregators / LLM (on‑demand)

• Lichess – public API pulls the latest games for the user kirti587.
• ChessKit – parses PGN files and provides board representations.
• Stockfish – runs with the parameters defined in project/engine_config.md to produce centipawn evaluations, best moves and principal variations.
• JSON store – each analyzed game is persisted under data/analysis/<gameId>.json. The file contains full move information, CPL, classification (Best, Excellent, Good, Inaccuracy, Mistake, Blunder) and engine best moves.
• Aggregators / LLM – separate command‑line tools read the JSON files to compute overall ACPL, per‑opening statistics, mistake‑pattern detection, and generate concise coaching reports via a local Ollama model.

---

Installation

1. Swift – ensure Swift 6.2 or newer is installed (comes with Xcode 15 or can be installed via swift.org).
2. Stockfish – install the engine:

   brew install stockfish

3. Ollama – for LLM‑driven explanations. Follow the official guide at https://ollama.com and pull a compact model, e.g.:

   ollama pull qwen3:0.6b

4. Clone & build:

   git clone https://github.com/<your‑username>/Chesscetera.git
   cd Chesscetera/Chesscetera
   swift build

---

Usage

1️⃣ Fetch & analyze the latest Lichess game

# Pull the most recent finished game for user kirti587
curl -s -H "Accept: application/x-ndjson" \
     "https://lichess.org/api/games/user/kirti587?max=1&moves=true&pgnInJson=true" \
| head -n1 \
| python3 -c "import sys, json, pathlib; data=json.loads(sys.stdin.read()); pathlib.Path('sample.pgn').write_text(data['pgn'])"

# Run the analysis (Stockfish evaluation + JSON persistence)
swift run Chesscetera

The analysis creates data/analysis/<gameId>.json and prints a brief console summary.

2️⃣ Aggregate statistics (Phase 2A)

swift run Aggregator

Produces an overall ACPL, counts of blunders/mistakes/inaccuracies, and per‑opening win‑rates. The summary is saved to data/summary.json.

3️⃣ Generate a weekly coaching report (Phase 2E)

swift run Chesscetera weekly-report

A single LLM call produces a concise coach note with strengths, weaknesses, training suggestions and a motivational sentence.

4️⃣ Opening explorer (Phase 2C)

swift run Chesscetera opening-report "London System"

Shows games count, win‑rate, ACPL and the most common mistakes for the specified opening.

---

License

This project is released under the MIT License. See the LICENSE file for details.

---

Contributing

• Fork the repository and create a feature branch.
• Run swift test (if you add tests) and swift build locally.
• Keep the .gitignore up‑to‑date – analysis data (data/analysis/, data/summary.json) should never be committed.
• Submit a pull request with a clear description of the change.

Happy analyzing! 🚀