🤖 Lichess-MakeChessBetter

📖 Table of Contents

1. Introduction
2. Project Goal
3. Architecture & Workflow
4. Core Features
5. Prerequisites & System Requirements
6. Installation Blueprint
7. Environement Configuration
8. Deployed Bot
9. Advanced Usage Framework

---

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-3.0.1.post1-py3-none-any.whl

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

tar -xvf MakeChessBetter-3.0.0.post1.tar.gz
cd MakeChessBetter-3.0.1.post1
pip install -r requirements.txt

Tip

To set up your environment and bot, go directly to ./scripts/README.md for setup guide, or download our binaries mentioned in our Releases tab.

7. 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"
  variants: "./fairy-stockfish"

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

LICHESS_TOKEN=lip_yourtoken

8. 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!

9. 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 &.

pipeline refresh