ChessInsightAI is a chess analysis and training project focused on importing games, enriching them with engine and tactical signals, building machine-learning datasets, and preparing recommendation workflows for future coaching features.
- Main README - Project overview, setup, roadmap, and documentation hub
- Changelog - Project version history and release notes
- Version Base - Quick start and condensed project summary
- Technical Roadmap - Current roadmap and implementation phases
- Tests Guide - Test runner usage and test-suite structure
- Architecture Notes - Source-level architecture overview
- MLflow PostgreSQL Integration - Theory and implementation map for experiment tracking with PostgreSQL
- Reliable Chess Predictions - Prediction pipeline concepts, current modules, and future serving work
- ELO Standardization Guide - Rating normalization design and implementation references
- Issue #21 Completion Report - Project-level summary of the rating standardization milestone
- Docker Development Strategy - Container workflow, services, and environment responsibilities
- Datasets Volumes Config - Theoretical storage layout for datasets, artifacts, and shared volumes
- Git LFS Setup Guide - Guidance for handling large assets and model artifacts
- ML Theoretical Framework - Core ML concepts applied to chess data in this repository
- ML Current State Analysis - What exists today versus what is still planned
- Frontend: React, TypeScript, Vite, Material UI
- Backend: FastAPI, PostgreSQL, Alembic
- ML and analysis: Python, MLflow, Stockfish, notebook-based experimentation
- AI coaching direction: LangChain, local LLM workflows, retrieval and orchestration modules
- Import games from external sources and local PGN collections
- Analyze positions with Stockfish-oriented feature extraction
- Label tactical or error-oriented training signals
- Build machine-learning datasets and supporting exports
- Track model experiments and supporting ML utilities
- Provide a base for future coaching, recommendation, and explainability features
| Area | Purpose | Current status |
|---|---|---|
src/frontend/ |
React frontend and chess UI work | Implemented |
src/api/ |
FastAPI backend and API-facing services | Implemented |
src/modules/ |
PGN parsing, feature engineering, tagging, reporting, and utility modules | Implemented |
src/scripts/ |
Operational scripts for downloads, feature generation, training data, and CLI workflows | Implemented |
src/ml/ |
MLflow setup, ELO standardization, dataset analysis, training utilities, and prediction helpers | Implemented |
src/services/ |
Service wrappers for uploads, studies, and integration logic | Implemented |
src/ai_coach/ |
Coaching-oriented package structure and orchestration work | Partial / evolving |
docs/ |
Technical and theoretical documentation | Implemented and expanding |
tests/ |
Automated tests and test runner utilities | Implemented, environment-dependent |
.\build_up_clean_all.ps1This script builds and starts the main application environment and related development services.
docker-compose build
docker-compose up -d# Frontend
cd src/frontend
npm install
npm run dev
# Backend
cd src/api
python -m uvicorn main:app --reload --port 8000The repository workflow in .github/workflows/test.yml installs requirements.txt and runs:
pytest tests/Some tests assume project-specific import paths and runtime services. In this workspace, a baseline run currently fails during collection because modules is not available on the default PYTHONPATH.
Chess games are represented primarily through PGN move sequences and derived engine features. From those inputs, the project can build datasets that capture:
- openings and move sequences
- tactical opportunities and tactical mistakes
- engine score differences and error labels
- rating context and player strength normalization
- game outcomes and quality signals
From a theoretical point of view, the repository supports several ML problem families:
- classification for error labels or tactical pattern categories
- regression for score-based or quality-based estimations
- clustering for player-style or dataset-segmentation studies
- recommendation for future training and coaching flows
Relevant implementation references include src/modules/ml_preprocessing.py, src/modules/feature_engineering.py, src/modules/predict_error_label.py, src/ml/train_error_model.py, and src/ml/chess_error_predictor.py.
| Topic | Status | Notes |
|---|---|---|
| PGN ingestion and dataset preparation | Implemented | Covered by modules and scripts under src/modules/ and src/scripts/ |
| Tactical and feature extraction | Implemented | Stockfish- and tactics-related scripts already exist |
| ELO standardization | Implemented | See src/ml/elo_standardization.py and related utilities |
| MLflow tracking support | Implemented | PostgreSQL setup and utilities are present in src/ml/ |
| Real-time prediction serving | Partial | Predictor modules exist, but production API integration remains future work |
| Explainability and coaching orchestration | Planned | Mentioned by docs and package layout, not fully implemented yet |
Developed by cmessoftware as part of practical work connected to a data-science learning path.