ChessPersona

ChessPersona adalah aplikasi desktop lokal untuk membuat bot catur yang meniru kecenderungan bermain akun Chess.com tertentu.

Aplikasi mengambil game publik dari Chess.com, menganalisis pola bermain, memakai Stockfish untuk kandidat langkah legal, lalu membuat persona yang bisa kamu lawan langsung di GUI.

Status: v0.2.0-local-mvp
Platform utama: Windows 10/11
Bahasa: Python 3.12 + PySide6
Target: local desktop app, dijalankan dari VS Code / PowerShell

---

Fitur MVP

• Create / Update persona dari username Chess.com.
• Mode Rapid dan Blitz.
• Pipeline otomatis dari GUI:
  • download games;
  • behavioral analysis;
  • move quality analysis dengan Stockfish;
  • complete persona build;
  • Direct Ranker training;
  • release gate / runtime readiness check;
  • safe fallback kalau advanced ML belum siap.
• Bot bisa dimainkan dari GUI.
• Evaluation bar.
• Move history.
• Penjelasan keputusan persona.
• Promotion dialog.
• Resign.
• Export PGN.
• Board theme dan piece set.
• Local smoke test runner.
• Stockfish auto-recover jika engine process mati setelah workload berat.

---

Status runtime

ChessPersona punya beberapa level runtime:

Status	Arti
Runtime READY	Advanced runtime siap dipakai oleh UI.
needs_more_evidence	Persona sudah playable, tapi advanced ML belum cukup evidence. UI akan fallback aman.
Statistical selector	Mode aman default. Bot tetap bisa dimainkan.

needs_more_evidence bukan crash. Itu berarti data/evidence belum cukup untuk unlock advanced ML, tetapi persona tetap bisa dimainkan dengan Statistical selector.

---

Preset analisis

Preset	Target game	Kegunaan
Quick	100 game	Test cepat, smoke test, persona awal.
Standard	300 game	Kualitas lebih baik tanpa terlalu berat.
Full	500 game	Profil paling lengkap dari data yang tersedia.

Quick sering menghasilkan needs_more_evidence. Itu normal.

---

Rekomendasi lokasi project

Disarankan menjalankan project dari disk yang lega, misalnya:

D:\Projects\ChessPersona

Data besar akan tersimpan relatif terhadap folder project:

data\datasets
data\personas
data\analysis
data\ml

Kalau project dijalankan dari D:\Projects\ChessPersona, maka data tersebut masuk ke disk D.

---

Persyaratan

• Windows 10/11.
• Python 3.12.
• Git.
• Stockfish executable.
• Koneksi internet saat Create / Update persona.
• Akun Chess.com target harus punya game publik.

Setelah persona dibuat, game bisa dimainkan lokal tanpa koneksi internet.

---

Setup dari PowerShell

Masuk ke folder project:

cd D:\Projects\ChessPersona

Buat virtual environment jika belum ada:

py -3.12 -m venv .venv

Aktifkan virtual environment:

.\.venv\Scripts\Activate.ps1

Jika PowerShell menolak aktivasi:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1

Install dependency:

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

if (Test-Path .\requirements-dev.txt) {
    python -m pip install -r requirements-dev.txt
}

if (Test-Path .\requirements-ml.txt) {
    python -m pip install -r requirements-ml.txt
}

---

Stockfish

Path default:

engines\stockfish\stockfish.exe

Cek:

Test-Path .\engines\stockfish\stockfish.exe

Output yang benar:

True

Kalau Stockfish masih ada di folder lain, copy ke path default:

New-Item -ItemType Directory -Force .\engines\stockfish

Copy-Item C:\Users\user\stockfish\stockfish-windows-x86-64-avx2.exe `
    .\engines\stockfish\stockfish.exe

---

Menjalankan aplikasi

python .\app.py

Cara pakai GUI:

1. Masukkan username Chess.com.
2. Pilih Rapid atau Blitz.
3. Pilih preset Quick / Standard / Full.
4. Klik Create / Update.
5. Tunggu pipeline selesai.
6. Kalau muncul needs_more_evidence, itu aman.
7. Persona akan dimuat dan bot bisa dimainkan.

---

Local smoke test

Sebelum merge, release, atau tag stabil, jalankan:

python .\run_local_smoke_tests.py

Setelah semua perubahan sudah committed, bisa pakai mode strict:

python .\run_local_smoke_tests.py --strict-release-check

Checker khusus release candidate:

python .\check_release_candidate.py `
    --engine-path engines\stockfish\stockfish.exe

Runtime readiness untuk persona tertentu:

python .\check_runtime_readiness.py `
    --username jiqy `
    --time-class blitz `
    --engine-path engines\stockfish\stockfish.exe

---

Git hygiene

Jangan commit data generated lokal:

data\datasets
data\personas
data\analysis
data\ml

Yang boleh tracked hanya placeholder .gitkeep, jika ada.

Sebelum commit:

git status --short
git diff --cached --name-only

Kalau muncul file di folder data\..., jangan stage file itu.

---

Struktur folder penting

ChessPersona/
├── app.py
├── run_full_persona_pipeline.py
├── check_runtime_readiness.py
├── check_release_candidate.py
├── run_local_smoke_tests.py
├── assets/
├── data/
│   ├── datasets/
│   ├── personas/
│   ├── analysis/
│   └── ml/
├── engines/
│   └── stockfish/
│       └── stockfish.exe
├── exports/
├── src/
│   ├── api/
│   ├── bot/
│   ├── engine/
│   ├── ml/
│   ├── persona/
│   ├── runtime/
│   └── ui/
└── tests/

---

Troubleshooting

Stockfish tidak ditemukan

Pastikan file ini ada:

engines\stockfish\stockfish.exe

Jalankan aplikasi dari root project, bukan dari folder src.

Bot error engine event loop dead

Versi MVP ini sudah punya Stockfish auto-recover. Kalau masih terjadi:

Get-Process stockfish -ErrorAction SilentlyContinue |
    Stop-Process -Force

Lalu buka ulang app:

python .\app.py

Disk penuh

Pipeline menyimpan data dan model di folder data\.... Jalankan project dari disk yang lega, misalnya D.

Cek drive:

Get-PSDrive D

Persona ready tapi advanced ML belum ready

Kalau hasilnya needs_more_evidence, itu normal untuk Quick atau dataset kecil. Bot tetap playable dengan Statistical selector.

---

Batasan MVP

• Fokus Windows lokal.
• Belum ada installer .exe.
• Belum ada cloud deploy.
• Rapid dan Blitz adalah fokus utama.
• Kualitas persona bergantung pada jumlah dan variasi game publik.
• Bot meniru kecenderungan statistik, bukan menyalin pemain secara sempurna.

---

Target release

Target stabil saat ini:

v0.2.0 — Local MVP Stable

Definisi done untuk MVP:

1. App bisa dibuka dari PowerShell / VS Code.
2. User bisa Create / Update persona.
3. Persona bisa dimainkan.
4. Runtime fallback aman jika advanced ML belum ready.
5. Smoke test lokal hijau.
6. Data generated tidak ikut commit.

---

Credits

Lihat CREDITS.md untuk sumber dan atribusi asset.

ChessPersona bukan produk resmi dan tidak berafiliasi dengan Chess.com maupun Stockfish.

---

License

Lisensi project belum ditetapkan. Tambahkan file LICENSE sebelum distribusi publik.