🤖 Lichess-MakeChessBetter

📖 Table of Contents

1. Introduction
2. Project Goal
3. Architecture & Workflow
4. Core Features
5. Prerequisites & System Requirements
6. Installation Blueprint
7. Setup Guide
8. Environement Configuration
9. Deployed Bot
10. Advanced Usage Framework
11. API & Programmatic Reference
12. Troubleshooting & Diagnostics
13. Performance Fine-Tuning
14. Future Roadmap

---

1. Introduction

Lichess-MakeChessBetter is an open-source, fully automated chess execution engine designed to interface natively with the lichess.org Bot API. Constructed using modern Python workflows, the bot acts as a bridge between asynchronous web streaming loops and local command-line chess engine binaries, processing matches across classical formats and alternative variants flawlessly.

2. Project Goal

The ultimate core focus of the project is to build an Adaptive Chess Partner that dynamically matches an opponent's real-time playing prowess. By calculating performance on a per-move basis, the framework prevents games from feeling stagnant, creating a flexible environment that tests tactical accuracy dynamically throughout the match lifecycles.

3. Architecture & Workflow

The system reads gameplay states continuously via streaming long-lived TCP connections, estimating performance using a specialized rolling calculation matrix:

   Game Starts
   │
   ├── [1. Default State]
   │     └── Bot initializes at default ELO 1320
   │
   ├── [2. Live Tracking Loop]
   │     ├── Monitors opponent moves continuously
   │     └── Calculates rolling average Centipawn Loss (CPL)
   │
   ├── [3. Dynamic Mapping Phase]
   │     ├── CPL ≤ 15   ➔ ELO 2200 (Master)
   │     ├── CPL ≤ 25   ➔ ELO 2000 (Expert)
   │     ├── CPL ≤ 40   ➔ ELO 1800 (Strong Club)
   │     ├── CPL ≤ 60   ➔ ELO 1600 (Intermediate)
   │     ├── CPL ≤ 90   ➔ ELO 1400 (Casual)
   │     ├── CPL ≤ 130  ➔ ELO 1200 (Beginner)
   │     └── CPL > 130  ➔ ELO 1000 (Newcomer)
   │
   └── [4. Lock-In Phase]
         └── Enforces calculated target ELO for remaining game matrix

4. Core Features

• Live CPL Scaling: Real-time optimization updates that dynamically scale difficulty setting attributes.
• Variant Integration: Full execution compatibility with all variants supported by Fairy-Stockfish.
• Smart Draw Strategy: Rejects draw queries when holding advantages; accepts when under heavy strain.
• Predictive Resignations: Instantly detects unpreventable forced checkmates in 3 moves or fewer.
• Concurrent Scaling: Handles multiple asynchronous platform matches running at once.

5. Prerequisites & System Requirements

• Runtime Core: Python 3.10 or newer (configured along with local virtual environments).
• Engines: Local system execution paths pointing to standard Stockfish or Fairy-Stockfish binaries.
• Platform Constraints: A dedicated, unplayed Lichess profile upgraded strictly to a BOT status.

6. Installation Blueprint

To deploy using the pre-compiled Python distribution packaging wheels, run the installation sequence directly through your tool terminal:

pip install MakeChessBetter-2.0.1-py3-none-any.whl

To run directly from the raw source code compression archive, unpack the package components manually:

tar -xvf MakeChessBetter-2.0.1.tar.gz
cd MakeChessBetter-2.0.1
pip install -r requirements.txt

7. Setup Guide

To set up your environment and bot, go directly to ./scripts/README.md for setup guide.

8. Environment Configuration

The application consumes standard credentials through an active .env configuration template or a localized configuration layout. Create a config.yml block in your workspace path:

token: "lip_YOUR_SECURE_LICHESS_API_TOKEN"
engine:
  path: "./stockfish-windows-x86-64-avx2.exe"
  variants: "./fairy-stockfish-largeboard_x86-64.exe"

Alternatively, apply configuration rules directly using a root .env template parameter configuration:

LICHESS_TOKEN=lip_yourtoken

9. Deployed Bot

The backend server is live on Render: Live Server Status

How to Play / Interact: Since this is a backend Lichess bot, you don't interact with the Render link directly. Instead:

1. Go to Lichess.org.
2. Search for the bot's username: MakeChessBetter.
3. Challenge the bot to a game or send it a message to see it in action!

10. Advanced Usage Framework

Launch the tool package command interface execution entry point natively via the active console window:

MakeChessBetter

For deep application tracing or to enforce active execution visibility without immediate background detachment, run the raw script modules via:

python -m src.bot

• Silent Mode Execution (Windows): Suppress the command console pop-up layer by utilizing pythonw bot.py.
• Detached Runtime (Linux/Mac): Maintain long-term execution after dropping SSH sessions via nohup python bot.py &.

11. API & Programmatic Reference

The internal handlers parse data properties streaming from Lichess's public development entry channels:

• GET /api/stream/event: Establishes the real-time event pipeline to intercept Incoming game challenges.
• POST /api/bot/game/{gameId}/move/{move}: Ships calculated chess engine calculations back to the board matrix.
• POST /api/bot/game/{gameId}/chat: Emits automated status alerts directly to the in-game log panel.

12. Troubleshooting & Diagnostics

• Flashing Window/Instant Exit: Avoid clicking raw module paths directly from the explorer window. Launch the module commands manually from an already open terminal window to capture active error flags.
• 401 Authentication Validation Errors: Confirm your token features the authorized bot:play permission configuration.
• Engine Connection Timeout: Ensure path variables in config.py point directly to legitimate engine instances.

13. Performance Fine-Tuning

Optimize your engine properties for low-latency calculations:

• Core Distribution: Align the calculation process properties explicitly with actual machine CPU core limitations.
• Hash Optimization: Raise local allocation ceilings (e.g., to 2048MB) within your script configuration values to accelerate high-depth searches.

pipeline refresh