FairChess

FairChess és una eina experimental desenvolupada en Python per a l’anàlisi preliminar de possibles patrons de joc assistit en partides d’escacs digitals. El sistema processa fitxers PGN i combina indicadors de precisió i indicadors temporals amb mecanismes bàsics de preservació d’evidències, amb finalitats docents i d’anàlisi exploratòria.

Aquest repositori conté una versió neta i funcional del prototip utilitzat en el Treball Final de Grau.

---

Característiques principals

• Anàlisi jugada a jugada mitjançant un motor UCI (Stockfish).
• Indicadors de precisió (MM, CV, AE).
• Indicadors temporals (T1, T2, T3) basats en informació de rellotge del PGN.
• Síntesi de risc per jugador mitjançant una estratègia conservadora.
• Generació automàtica de registres i evidències (PGN preservat, JSON, PDF, logs i empremtes hash).
• Execució per línia d’ordres, sense dependència d’entorns gràfics.

---

Requisits del sistema

• Python 3.10 o superior
• Sistema operatiu: Linux, macOS o Windows
• Motor Stockfish accessible al sistema
• Dependències Python indicades a requirements.txt

Es recomana l’ús d’un entorn virtual (venv).

---

Instal·lació

Clonar el repositori:

git clone https://github.com/msoldevila/fairchess-test.git
cd fairchess-test

Crear i activar un entorn virtual:

python3 -m venv venv
source venv/bin/activate

Instal·lar dependències:

pip install -r requirements.txt

---

Execució bàsica

Executar l’anàlisi d’una partida PGN:

python src/main.py ruta/a/partida.pgn

L’eina genera una carpeta de sessió amb els resultats, que inclou:

• una còpia preservada del fitxer PGN analitzat,
• fitxers JSON amb els indicadors calculats i metadades de sessió,
• registres d’execució (logs),
• empremtes hash per a verificació d’integritat,
• un informe en format PDF.

---

Configuració

FairChess pot utilitzar un fitxer opcional config.json per ajustar paràmetres del motor i de l’anàlisi.
Si aquest fitxer no existeix, el sistema funciona amb valors interns per defecte.

Per motius de seguretat i portabilitat, el fitxer config.json inclòs al repositori conté una configuració genèrica d’exemple, que pot ser adaptada segons l’entorn d’execució.

---

Limitacions

FairChess no és una eina de detecció professional ni ofereix diagnòstics concloents.
Els resultats obtinguts són indicadors orientatius i han de ser interpretats amb cautela, especialment fora de contextos docents o exploratoris.

---

Llicència

Aquest projecte es distribueix sota llicència MIT amb finalitats educatives i de recerca.