feat: add thematic coverage % to deck descriptions

Coverage = unique themes in sampled deck / unique themes in full ELO
tranche before filtering, computed at CSV generation time.

lichess_optimized_puzzles_datasets.py:
- report_theme_coverage() now returns a stats dict
  {selected, unique_themes_sample, unique_themes_tranche, coverage_pct}
  in addition to printing the existing report.
- extract_tranches() collects those dicts and writes puzzles_stats.json
  alongside the puzzle CSVs so build_apkg.py can read them.

build_apkg.py:
- Add _load_deck_stats(csv_dir) helper to read puzzles_stats.json.
- _build_description() accepts an optional coverage float and appends
  "(74.3% of tranche themes)" inline with the theme list when present.
- build_from_csvs() loads stats once and passes coverage_pct per deck.
- Move media path to module constant MEDIA_PATH to stay within pylint's
  20-local-variable limit (was 22 after new locals were added).

5 new tests cover coverage display, absence when None, and JSON loading.

https://claude.ai/code/session_01VAUnQCt5CM2TVpRbsQbSBL

Author: claude

build_apkg.py

@@ -13,16 +13,18 @@
 import argparse
 import csv
 import hashlib
+import json
 import os
 import shutil
 import zipfile
 from pathlib import Path
-from typing import List, Dict
+from typing import Dict, List, Optional
 
 import genanki
 
 DECK_PARENT = "♟️ Optimized Chess Puzzles"
 MODEL_NAME = "Chess Optimized Tactics"
+MEDIA_PATH = os.path.join("♟️_Optimized_Chess_Puzzles", "media", "_chess_merida_unicode.ttf")
 
 # Stable ID matching the reference deck (do not change — Anki uses it to
 # identify the note type when merging with existing collections).
@@ -174,12 +176,22 @@ def _row_to_note(row: Dict[str, str], model: genanki.Model) -> PuzzleNote:
     )
 
 
-def _build_description(rows: List[Dict[str, str]]) -> str:
+def _load_deck_stats(csv_dir: str) -> Dict[str, Dict]:
+    """Load per-tranche coverage stats written by lichess_optimized_puzzles_datasets."""
+    path = os.path.join(csv_dir, "puzzles_stats.json")
+    if not os.path.exists(path):
+        return {}
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _build_description(rows: List[Dict[str, str]], coverage: Optional[float] = None) -> str:
     """Build a plain-text deck description from a list of puzzle rows.
 
     Includes puzzle count, ELO range/average, popularity average, and the top
     themes sorted by frequency — mirroring what lichess_optimized_puzzles_datasets
-    reports at generation time.
+    reports at generation time.  When coverage is provided (ratio of unique themes
+    in the sample vs the full ELO tranche), it is shown inline with the theme list.
     """
     count = len(rows)
     if count == 0:
@@ -205,9 +217,10 @@ def _build_description(rows: List[Dict[str, str]]) -> str:
 
     if theme_counts:
         n_themes = len(theme_counts)
+        cov_label = f" ({coverage:.1f}% of tranche themes)" if coverage is not None else ""
         top = sorted(theme_counts.items(), key=lambda x: -x[1])[:15]
         lines.append(
-            f"\n{n_themes} theme{'s' if n_themes != 1 else ''}: "
+            f"\n{n_themes} theme{'s' if n_themes != 1 else ''}{cov_label}: "
             + " · ".join(f"{t} ({n})" for t, n in top)
         )
 
@@ -219,10 +232,7 @@ def build_from_csvs(csv_dir: str, output: str) -> None:
     front, back, css = _load_templates()
     model = _build_model(front, back, css)
 
-    media_path = os.path.join(
-        "♟️_Optimized_Chess_Puzzles", "media", "_chess_merida_unicode.ttf"
-    )
-
+    deck_stats = _load_deck_stats(csv_dir)
     decks: List[genanki.Deck] = []
     all_rows: List[Dict[str, str]] = []
     total_notes = 0
@@ -240,7 +250,10 @@ def build_from_csvs(csv_dir: str, output: str) -> None:
 
         all_rows.extend(rows)
         deck = genanki.Deck(
-            _deck_id(deck_name), deck_name, description=_build_description(rows)
+            _deck_id(deck_name), deck_name,
+            description=_build_description(
+                rows, (deck_stats.get(csv_filename) or {}).get("coverage_pct")
+            ),
         )
         for row in rows:
             deck.add_note(_row_to_note(row, model))
@@ -259,8 +272,8 @@ def build_from_csvs(csv_dir: str, output: str) -> None:
     decks.insert(0, parent_deck)
 
     package = genanki.Package(decks)
-    if os.path.exists(media_path):
-        package.media_files = [media_path]
+    if os.path.exists(MEDIA_PATH):
+        package.media_files = [MEDIA_PATH]
 
     package.write_to_file(output)
     _upgrade_to_anki21(output)

lichess_optimized_puzzles_datasets.py

@@ -32,11 +32,12 @@
 provide comprehensive coverage of tactical themes and opening patterns.
 """
 
+import json
 import os
 import re
 import subprocess
 from collections import defaultdict
-from typing import List, Tuple
+from typing import Dict, List, Tuple
 
 import chess
 import pandas
@@ -232,6 +233,8 @@ def extract_tranches(
 
     Creates separate CSV files for each ELO range with optimally selected puzzles.
     Ranges include: <1000, 1000-1100, 1100-1200, ..., 1700-1800, 1800+
+    Also writes puzzles_stats.json with per-tranche coverage stats consumed by
+    build_apkg.py when generating deck descriptions.
 
     Parameters
     ----------
@@ -245,6 +248,7 @@ def extract_tranches(
     dataframe = pandas.read_csv(csv_file)
     cols = ['PuzzleId', 'FEN', 'Moves', 'Rating', 'Popularity', 'Themes', 'OpeningTags']
     dataframe = dataframe[cols]
+    all_stats: Dict[str, Dict] = {}
 
     first_tranche = dataframe[dataframe['Rating'] < 1000]
     sampled_rows = sample_by_themes(
@@ -253,7 +257,9 @@ def extract_tranches(
         popularity_threshold=popularity_threshold
     )
     _write_csv_file(sampled_rows, "puzzles_1000minus.csv")
-    report_theme_coverage(sampled_rows, "puzzles_1000minus.csv", first_tranche)
+    all_stats["puzzles_1000minus.csv"] = report_theme_coverage(
+        sampled_rows, "puzzles_1000minus.csv", first_tranche
+    )
 
     for elo_start in range(1000, 1800, 100):
         elo_end = elo_start + 100
@@ -265,7 +271,7 @@ def extract_tranches(
         )
         out_file = f"puzzles_{elo_start}_{elo_end}.csv"
         _write_csv_file(sampled_rows, out_file)
-        report_theme_coverage(sampled_rows, out_file, tranche)
+        all_stats[out_file] = report_theme_coverage(sampled_rows, out_file, tranche)
 
     last_tranche = dataframe[dataframe['Rating'] >= 1800]
     sampled_rows = sample_by_themes(
@@ -274,7 +280,12 @@ def extract_tranches(
         popularity_threshold=popularity_threshold
     )
     _write_csv_file(sampled_rows, "puzzles_1800plus.csv")
-    report_theme_coverage(sampled_rows, "puzzles_1800plus.csv", last_tranche)
+    all_stats["puzzles_1800plus.csv"] = report_theme_coverage(
+        sampled_rows, "puzzles_1800plus.csv", last_tranche
+    )
+
+    with open("puzzles_stats.json", "w", encoding="utf-8") as stats_file:
+        json.dump(all_stats, stats_file, indent=2)
 
 
 def _write_csv_file(sampled_rows: List, filename) -> None:
@@ -325,7 +336,7 @@ def report_theme_coverage(
     sampled_rows: List,
     out_file: str,
     tranche: pandas.DataFrame,
-) -> None:
+) -> Dict:
     """
     Generate and display theme coverage statistics for the puzzle selection.
 
@@ -340,6 +351,13 @@ def report_theme_coverage(
         Output filename for context
     tranche : pandas.DataFrame
         Original tranche data for comparison
+
+    Returns
+    -------
+    dict
+        Stats dict with keys: selected, unique_themes_sample,
+        unique_themes_tranche, coverage_pct.  Consumed by build_apkg.py
+        to populate deck descriptions.
     """
     selected_themes: set = set()
     theme_freq: dict[str, int] = {}
@@ -376,6 +394,13 @@ def report_theme_coverage(
         print(f"  • {theme}: {freq} puzzles")
     print("—" * 35)
 
+    return {
+        "selected": len(sampled_rows),
+        "unique_themes_sample": len(selected_themes),
+        "unique_themes_tranche": len(tranche_themes),
+        "coverage_pct": round(percentage_coverage, 1),
+    }
+
 
 def main() -> None:
     """

tests/build_apkg_test.py

@@ -20,6 +20,7 @@
     _deck_id,
     _build_model,
     _build_description,
+    _load_deck_stats,
     _row_to_note,
     build_sample,
     ALL_DECKS,
@@ -242,3 +243,38 @@ def test_sample_cards_have_description(self):
         desc = _build_description(list(build_apkg.SAMPLE_CARDS))
         assert "3 puzzles" in desc
         assert "fork" in desc
+
+    def test_coverage_shown_when_provided(self):
+        rows = [_make_themed_row("p1", "fork pin")]
+        desc = _build_description(rows, coverage=74.3)
+        assert "74.3%" in desc
+        assert "of tranche themes" in desc
+
+    def test_coverage_absent_when_none(self):
+        rows = [_make_themed_row("p1", "fork pin")]
+        desc = _build_description(rows, coverage=None)
+        assert "tranche" not in desc
+
+    def test_coverage_100_percent(self):
+        rows = [_make_themed_row("p1", "fork")]
+        desc = _build_description(rows, coverage=100.0)
+        assert "100.0%" in desc
+
+
+class TestLoadDeckStats:
+    def test_returns_empty_dict_when_file_absent(self, tmp_path):
+        assert _load_deck_stats(str(tmp_path)) == {}
+
+    def test_loads_coverage_pct(self, tmp_path):
+        import json
+        stats = {
+            "puzzles_1000minus.csv": {
+                "selected": 847,
+                "unique_themes_sample": 23,
+                "unique_themes_tranche": 31,
+                "coverage_pct": 74.2,
+            }
+        }
+        (tmp_path / "puzzles_stats.json").write_text(json.dumps(stats))
+        loaded = _load_deck_stats(str(tmp_path))
+        assert loaded["puzzles_1000minus.csv"]["coverage_pct"] == 74.2