chessvision-py 0.1.0__tar.gz

chessvision_py-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: chessvision-py
+Version: 0.1.0
+Summary: Computational chess performance analysis — ML-powered insights from personal PGN archives
+Author-email: Rakkshet Singhaal <rakkshetsinghaal99@gmail.com>
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/chesslens-project/chessvision-py
+Project-URL: Repository, https://github.com/chesslens-project/chessvision-py
+Keywords: chess,machine-learning,performance-analysis,stockfish,pgn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Games/Entertainment :: Board Games
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: chess>=1.10.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pyarrow>=12.0.0
+Requires-Dist: zstandard>=0.21.0
+Requires-Dist: gensim>=4.3.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: tqdm>=4.65.0
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: joblib>=1.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+
+# chessvision-py
+
+A Python library for computational chess performance analysis. Takes your PGN game files and runs machine learning on them to tell you what kind of mistakes you make and how to improve.
+
+## What it does
+
+- Parses PGN files from chess.com, lichess, or OTB tournaments
+- Evaluates every position with Stockfish (cached, resumable)
+- Clusters your errors into 5 distinct archetypes
+- Embeds your playing style into a vector space trained on 29.3M elite games
+- Forecasts ELO trajectory using a model trained on 67,115 elite players
+- Generates a personalized weekly training plan
+
+## Installation
+
+```bash
+pip install chessvision-py
+```
+
+Requires Stockfish:
+```bash
+brew install stockfish   # Mac
+apt install stockfish    # Linux
+```
+
+## Quick start
+
+```python
+import chessvision as cv
+
+cv.download_models()
+
+report = cv.analyze("my_games.pgn", player_name="YourUsername")
+```
+
+Or step by step:
+
+```python
+games, moves = cv.parse_pgn("my_games.pgn")
+moves  = cv.evaluate_games(moves)
+moves  = cv.engineer_features(games, moves)
+errors = cv.run_archetype_analysis(moves)
+report = cv.analyze_player(moves, games, errors, "YourUsername")
+```
+
+## Pre-trained models
+
+Models are hosted on Hugging Face at `rakkshet/chessvision-models` and download automatically on first use:
+
+```python
+cv.download_models()
+```
+
+## License
+
+GPL-3.0

chessvision_py-0.1.0/README.md

@@ -0,0 +1,56 @@
+# chessvision-py
+
+A Python library for computational chess performance analysis. Takes your PGN game files and runs machine learning on them to tell you what kind of mistakes you make and how to improve.
+
+## What it does
+
+- Parses PGN files from chess.com, lichess, or OTB tournaments
+- Evaluates every position with Stockfish (cached, resumable)
+- Clusters your errors into 5 distinct archetypes
+- Embeds your playing style into a vector space trained on 29.3M elite games
+- Forecasts ELO trajectory using a model trained on 67,115 elite players
+- Generates a personalized weekly training plan
+
+## Installation
+
+```bash
+pip install chessvision-py
+```
+
+Requires Stockfish:
+```bash
+brew install stockfish   # Mac
+apt install stockfish    # Linux
+```
+
+## Quick start
+
+```python
+import chessvision as cv
+
+cv.download_models()
+
+report = cv.analyze("my_games.pgn", player_name="YourUsername")
+```
+
+Or step by step:
+
+```python
+games, moves = cv.parse_pgn("my_games.pgn")
+moves  = cv.evaluate_games(moves)
+moves  = cv.engineer_features(games, moves)
+errors = cv.run_archetype_analysis(moves)
+report = cv.analyze_player(moves, games, errors, "YourUsername")
+```
+
+## Pre-trained models
+
+Models are hosted on Hugging Face at `rakkshet/chessvision-models` and download automatically on first use:
+
+```python
+cv.download_models()
+```
+
+## License
+
+GPL-3.0

chessvision_py-0.1.0/chessvision/__init__.py

@@ -0,0 +1,33 @@
+from .analyze   import analyze
+from .parser    import parse_pgn
+from .evaluator import evaluate_games
+from .features  import engineer_features, feature_summary
+from .archetypes import run_archetype_analysis, player_archetype_profile
+from .recommender import (
+    build_player_profile,
+    generate_recommendations,
+    analyze_player,
+)
+from .models import (
+    download_models,
+    register_local_models,
+    list_models,
+    is_downloaded,
+)
+
+try:
+    from .elo_forecast import (
+        build_game_features,
+        train_elo_model,
+        train_win_classifier,
+        train_population_lstm,
+        fine_tune_on_personal,
+        predict_elo_trajectory,
+        load_model,
+    )
+except ImportError:
+    pass
+
+__version__ = "0.1.0"
+__author__  = "Rakkshet Singhaal"
+__email__   = "rakkshet.singhaal@kellogg.northwestern.edu"

chessvision_py-0.1.0/chessvision/analyze.py

@@ -0,0 +1,124 @@
+"""
+analyze.py
+
+Main entry point for chessvision.
+One function call produces the full analysis report.
+"""
+
+import pandas as pd
+from pathlib import Path
+from typing import Optional, Union
+
+from .parser    import parse_pgn
+from .evaluator import evaluate_games
+from .features  import engineer_features
+from .archetypes import run_archetype_analysis
+from .recommender import analyze_player
+from .models    import get_cached_path
+
+
+def analyze(
+    pgn_path:    Union[str, Path],
+    player_name: Optional[str] = None,
+    stockfish_path: str = "stockfish",
+    depth:       int   = 15,
+    output_path: Optional[Union[str, Path]] = None,
+    verbose:     bool  = True,
+) -> dict:
+    """
+    Full chessvision analysis pipeline — one function call.
+
+    Takes a PGN file (or folder of PGN files) and returns a
+    comprehensive training report with error archetypes, style
+    profile, and personalized recommendations.
+
+    Parameters
+    ----------
+    pgn_path      : path to .pgn file or folder of .pgn files
+    player_name   : name of the player to analyze
+                    (auto-detected if only one player appears frequently)
+    stockfish_path: path to Stockfish binary (default: 'stockfish' on PATH)
+    depth         : Stockfish search depth (default: 15)
+    output_path   : if set, saves JSON report here
+    verbose       : print progress and report
+
+    Returns
+    -------
+    dict with full analysis results
+
+    Example
+    -------
+    >>> import chessvision as cv
+    >>> report = cv.analyze("my_games.pgn", player_name="MyUsername")
+    """
+    pgn_path = Path(pgn_path)
+
+    if verbose:
+        print("=" * 60)
+        print("  ChessVision Analysis Pipeline")
+        print("=" * 60)
+        print()
+
+    # ── Step 1: Parse ────────────────────────────────────────────
+    if verbose:
+        print("[1/5] Parsing PGN files...")
+    games_df, moves_df = parse_pgn(pgn_path)
+
+    # Auto-detect player name
+    if player_name is None:
+        player_name = _detect_player(games_df)
+        if verbose:
+            print(f"  Auto-detected player: {player_name}")
+
+    # ── Step 2: Evaluate ─────────────────────────────────────────
+    if verbose:
+        print("\n[2/5] Evaluating positions with Stockfish...")
+        print("  (This step is cached — safe to stop and restart)")
+    moves_df = evaluate_games(
+        moves_df,
+        stockfish_path = stockfish_path,
+        depth          = depth,
+        cache          = True,
+    )
+
+    # ── Step 3: Feature engineering ──────────────────────────────
+    if verbose:
+        print("\n[3/5] Engineering behavioral features...")
+    moves_df = engineer_features(games_df, moves_df)
+
+    # ── Step 4: Error archetypes ──────────────────────────────────
+    if verbose:
+        print("\n[4/5] Discovering error archetypes...")
+
+    # Use pre-trained model if available
+    get_cached_path("error_archetypes", "hdbscan_model.joblib")
+    error_df = run_archetype_analysis(
+        moves_df,
+        min_cluster_size = 200,
+        min_samples      = 50,
+    )
+
+    # ── Step 5: Recommendations ──────────────────────────────────
+    if verbose:
+        print("\n[5/5] Generating personalized recommendations...")
+
+    chess2vec_path = get_cached_path(
+        "chess2vec", "chess2vec.wordvectors"
+    )
+
+    report = analyze_player(
+        moves_df       = moves_df,
+        games_df       = games_df,
+        error_df       = error_df,
+        player_name    = player_name,
+        chess2vec_path = chess2vec_path,
+        output_path    = Path(output_path) if output_path else None,
+    )
+
+    return report
+
+
+def _detect_player(games_df: pd.DataFrame) -> str:
+    """Auto-detect the focal player — the one who appears most often."""
+    all_players = pd.concat([games_df["white"], games_df["black"]])
+    return all_players.value_counts().index[0]

chessvision_py-0.1.0/chessvision/archetypes.py

@@ -0,0 +1,393 @@
+"""
+archetypes.py
+
+Unsupervised error archetype discovery using HDBSCAN.
+
+Takes the evaluated move dataframe and clusters error moves
+into behaviorally distinct groups — replacing the naive
+blunder/mistake/inaccuracy taxonomy with a data-driven one.
+
+Expected archetypes:
+    - Tactical blindspot   : sharp positions, sudden CPL spike
+    - Strategic drift      : cumulative small losses, passive pieces
+    - Time pressure        : low clock, CPL spikes regardless of position
+    - Endgame failure      : winning positions lost in low material
+    - Preparation boundary : CPL spike at specific opening move number
+    - Positional confusion : complex pawn structures, gradual CPL creep
+"""
+
+import numpy as np
+import pandas as pd
+import joblib
+from pathlib import Path
+from typing import Optional
+
+try:
+    import hdbscan
+except ImportError:
+    raise ImportError("Install hdbscan: pip3 install hdbscan")
+
+try:
+    import umap
+except ImportError:
+    raise ImportError("Install umap-learn: pip3 install umap-learn")
+
+
+ARCHETYPE_LABELS = {
+    -1: "noise",
+    0:  "tactical_blindspot",
+    1:  "strategic_drift",
+    2:  "time_pressure_collapse",
+    3:  "endgame_failure",
+    4:  "preparation_boundary",
+    5:  "positional_confusion",
+    6:  "other",
+}
+
+
+def build_error_features(moves_df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Build the feature matrix for error clustering.
+    Filters to error moves only (CPL >= 50).
+
+    Features per move:
+        cpl_norm             : normalized centipawn loss [0,1]
+        eval_before_norm     : normalized position evaluation
+        clock_pressure_index : time remaining fraction
+        complexity           : position complexity score
+        mobility_ratio       : own vs opponent mobility
+        phase_encoded        : opening=0, middlegame=1, endgame=2
+        move_number_norm     : normalized move number
+        is_capture           : binary — was it a capture?
+        cumulative_cpl_norm  : running total CPL in game (normalized)
+
+    Returns
+    -------
+    error_df : filtered + feature-enriched dataframe
+    """
+    df = moves_df.copy()
+
+    # Filter to errors only
+    error_df = df[df["cpl"] >= 50].copy()
+    print(f"Error moves (CPL >= 50): {len(error_df):,} of {len(df):,} total")
+
+    # Normalize CPL (clip at 1000 to handle mate scores)
+    error_df["cpl_norm"] = (
+        error_df["cpl"].clip(upper=1000) / 1000.0
+    )
+
+    # Normalize eval_before (clip at ±1000 centipawns)
+    error_df["eval_before_norm"] = (
+        error_df["eval_before"].clip(-1000, 1000) / 1000.0
+    )
+
+    # Phase encoding
+    phase_map = {"opening": 0.0, "middlegame": 0.5, "endgame": 1.0}
+    error_df["phase_encoded"] = error_df["phase"].map(phase_map).fillna(0.5)
+
+    # Normalize move number (cap at 80)
+    error_df["move_number_norm"] = (
+        error_df["move_number"].clip(upper=80) / 80.0
+    )
+
+    # Is capture — detect from SAN notation
+    error_df["is_capture"] = error_df["san"].str.contains(
+        "x", na=False
+    ).astype(float)
+
+    # Cumulative CPL per game (normalized)
+    error_df["cumulative_cpl"] = (
+        df.groupby("game_id")["cpl"]
+        .transform(lambda x: x.fillna(0).cumsum())
+        .loc[error_df.index]
+    )
+    error_df["cumulative_cpl_norm"] = (
+        error_df["cumulative_cpl"].clip(upper=3000) / 3000.0
+    )
+
+    # Fill missing values
+    error_df["clock_pressure_index"] = (
+        error_df["clock_pressure_index"].fillna(0.5)
+    )
+    error_df["position_complexity_score"] = (
+        error_df["position_complexity_score"].fillna(0.5)
+    )
+    error_df["mobility_ratio"] = (
+        error_df["mobility_ratio"].fillna(1.0).clip(0.1, 5.0)
+    )
+    error_df["mobility_ratio_norm"] = (
+        (error_df["mobility_ratio"] - 0.1) / (5.0 - 0.1)
+    )
+
+    return error_df
+
+
+def get_feature_matrix(error_df: pd.DataFrame) -> np.ndarray:
+    """Extract the numeric feature columns as a numpy array."""
+    feature_cols = [
+        "cpl_norm",
+        "eval_before_norm",
+        "clock_pressure_index",
+        "position_complexity_score",
+        "mobility_ratio_norm",
+        "phase_encoded",
+        "move_number_norm",
+        "is_capture",
+        "cumulative_cpl_norm",
+    ]
+    missing = [c for c in feature_cols if c not in error_df.columns]
+    if missing:
+        raise ValueError(f"Missing feature columns: {missing}")
+
+    X = error_df[feature_cols].values.astype(np.float32)
+    print(f"Feature matrix shape: {X.shape}")
+    return X
+
+
+def reduce_dimensions(
+    X: np.ndarray,
+    n_components: int = 10,
+    random_state: int = 42,
+) -> np.ndarray:
+    """
+    Reduce feature dimensions with UMAP before clustering.
+    HDBSCAN degrades in high dimensions — UMAP first improves results.
+    """
+    print(f"Reducing {X.shape[1]}D → {n_components}D with UMAP...")
+    reducer = umap.UMAP(
+        n_components  = n_components,
+        n_neighbors   = 30,
+        min_dist      = 0.0,
+        metric        = "euclidean",
+        random_state  = random_state,
+    )
+    X_reduced = reducer.fit_transform(X)
+    print(f"Reduction complete. Shape: {X_reduced.shape}")
+    return X_reduced, reducer
+
+
+def cluster_errors(
+    X_reduced: np.ndarray,
+    min_cluster_size: int = 200,
+    min_samples: int = 50,
+) -> np.ndarray:
+    """
+    Run HDBSCAN on the UMAP-reduced feature matrix.
+
+    min_cluster_size : minimum moves to form a cluster
+    min_samples      : controls how conservative clustering is
+                       (higher = fewer, denser clusters)
+    """
+    print(f"Running HDBSCAN "
+          f"(min_cluster_size={min_cluster_size}, "
+          f"min_samples={min_samples})...")
+
+    clusterer = hdbscan.HDBSCAN(
+        min_cluster_size  = min_cluster_size,
+        min_samples       = min_samples,
+        metric            = "euclidean",
+        cluster_selection_method = "eom",
+        prediction_data   = True,
+    )
+    labels = clusterer.fit_predict(X_reduced)
+
+    n_clusters = len(set(labels)) - (1 if -1 in labels else 0)
+    n_noise    = (labels == -1).sum()
+    print(f"Found {n_clusters} clusters, {n_noise:,} noise points "
+          f"({n_noise/len(labels)*100:.1f}%)")
+
+    return labels, clusterer
+
+
+def label_archetypes(
+    error_df: pd.DataFrame,
+    labels: np.ndarray,
+) -> pd.DataFrame:
+    """
+    Assign archetype labels to clusters by inspecting
+    the mean feature profile of each cluster.
+
+    Labeling rules (in priority order):
+        time_pressure_collapse : mean clock_pressure_index < 0.2
+        endgame_failure        : mean phase_encoded > 0.8
+        preparation_boundary   : mean move_number_norm < 0.2
+        tactical_blindspot     : high cpl_norm + high complexity
+        positional_confusion   : low cpl_norm + high cumulative_cpl
+        strategic_drift        : middlegame + low complexity + high cumul
+        other                  : everything else
+    """
+    df = error_df.copy()
+    df["cluster"]   = labels
+    df["archetype"] = "noise"
+
+    cluster_ids = [c for c in sorted(df["cluster"].unique()) if c != -1]
+    archetype_map = {}
+
+    print("\nCluster profiles:")
+    print(f"{'Cluster':>8} {'N':>7} {'CPL':>6} {'Clock':>6} "
+          f"{'Phase':>6} {'Complexity':>10} {'MoveN':>6}  Archetype")
+    print("-" * 75)
+
+    for cid in cluster_ids:
+        mask = df["cluster"] == cid
+        sub  = df[mask]
+        n    = len(sub)
+
+        mean_cpl        = sub["cpl_norm"].mean()
+        mean_clock      = sub["clock_pressure_index"].mean()
+        mean_phase      = sub["phase_encoded"].mean()
+        mean_complexity = sub["position_complexity_score"].mean()
+        mean_move       = sub["move_number_norm"].mean()
+        mean_cumul      = sub["cumulative_cpl_norm"].mean()
+
+        # Assign archetype by feature signature
+        if mean_clock < 0.2:
+            archetype = "time_pressure_collapse"
+        elif mean_phase > 0.75:
+            archetype = "endgame_failure"
+        elif mean_move < 0.2:
+            archetype = "preparation_boundary"
+        elif mean_cpl > 0.5 and mean_complexity > 0.6:
+            archetype = "tactical_blindspot"
+        elif mean_cumul > 0.5 and mean_complexity < 0.4:
+            archetype = "strategic_drift"
+        elif mean_cumul > 0.4 and mean_complexity > 0.4:
+            archetype = "positional_confusion"
+        else:
+            archetype = "other"
+
+        archetype_map[cid] = archetype
+        print(f"{cid:>8} {n:>7,} {mean_cpl:>6.3f} {mean_clock:>6.3f} "
+              f"{mean_phase:>6.3f} {mean_complexity:>10.3f} "
+              f"{mean_move:>6.3f}  {archetype}")
+
+    df["archetype"] = df["cluster"].map(archetype_map).fillna("noise")
+    return df, archetype_map
+
+
+def run_archetype_analysis(
+    moves_df: pd.DataFrame,
+    min_cluster_size: int = 200,
+    min_samples: int = 50,
+    umap_components: int = 10,
+    output_dir: Optional[Path] = None,
+) -> pd.DataFrame:
+    """
+    Full pipeline: features → UMAP → HDBSCAN → archetypes.
+
+    Parameters
+    ----------
+    moves_df         : evaluated move dataframe
+    min_cluster_size : HDBSCAN minimum cluster size
+    min_samples      : HDBSCAN minimum samples
+    umap_components  : UMAP output dimensions
+    output_dir       : if set, saves model and results here
+
+    Returns
+    -------
+    error_df with cluster and archetype columns added
+    """
+    print("=" * 60)
+    print("Phase 3B — Error Archetype Analysis")
+    print("=" * 60)
+
+    # Check input
+    required = ["cpl", "phase", "move_number", "clock_pressure_index",
+                "position_complexity_score", "mobility_ratio"]
+    missing = [c for c in required if c not in moves_df.columns]
+    if missing:
+        raise ValueError(
+            f"Missing columns: {missing}. "
+            f"Run evaluate_games() and engineer_features() first."
+        )
+
+    evaluated = moves_df["cpl"].notna().sum()
+    if evaluated == 0:
+        raise ValueError("No evaluated moves found. Run evaluate_games() first.")
+
+    print(f"\nInput: {len(moves_df):,} moves, {evaluated:,} evaluated")
+
+    # Step 1: build features
+    print("\n[1/4] Building error features...")
+    error_df = build_error_features(moves_df)
+
+    # Step 2: feature matrix
+    print("\n[2/4] Extracting feature matrix...")
+    X = get_feature_matrix(error_df)
+
+    # Step 3: UMAP reduction
+    print("\n[3/4] Dimensionality reduction...")
+    X_reduced, reducer = reduce_dimensions(X, n_components=umap_components)
+
+    # Step 4: clustering
+    print("\n[4/4] Clustering...")
+    labels, clusterer = cluster_errors(
+        X_reduced, min_cluster_size, min_samples
+    )
+
+    # Label archetypes
+    error_df, archetype_map = label_archetypes(error_df, labels)
+
+    # Summary
+    print("\nArchetype distribution:")
+    arch_counts = error_df["archetype"].value_counts()
+    for arch, count in arch_counts.items():
+        pct = count / len(error_df) * 100
+        print(f"  {arch:<28} : {count:>6,}  ({pct:.1f}%)")
+
+    # Save if requested
+    if output_dir:
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        joblib.dump(clusterer, output_dir / "hdbscan_model.joblib")
+        joblib.dump(reducer,   output_dir / "umap_reducer.joblib")
+
+        error_df.to_parquet(output_dir / "error_archetypes.parquet",
+                            index=False)
+
+        import json
+        with open(output_dir / "archetype_map.json", "w") as f:
+            json.dump({str(k): v for k, v in archetype_map.items()}, f,
+                      indent=2)
+
+        print(f"\nSaved to {output_dir}")
+
+    return error_df
+
+
+def player_archetype_profile(
+    error_df: pd.DataFrame,
+    player_name: str,
+    games_df: Optional[pd.DataFrame] = None,
+) -> pd.DataFrame:
+    """
+    Compute archetype distribution for a specific player.
+    Returns a dataframe with archetype counts and percentages.
+    """
+    if games_df is not None:
+        player_games = games_df[
+            (games_df["white"] == player_name) |
+            (games_df["black"] == player_name)
+        ]["game_id"].tolist()
+        player_errors = error_df[error_df["game_id"].isin(player_games)]
+    else:
+        player_errors = error_df
+
+    if len(player_errors) == 0:
+        print(f"No error moves found for player: {player_name}")
+        return pd.DataFrame()
+
+    profile = (
+        player_errors["archetype"]
+        .value_counts()
+        .reset_index()
+    )
+    profile.columns = ["archetype", "count"]
+    profile["pct"]  = (profile["count"] / len(player_errors) * 100).round(1)
+
+    print(f"\nError archetype profile for {player_name}:")
+    print(f"Total error moves: {len(player_errors):,}")
+    print(profile.to_string(index=False))
+
+    return profile