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
