🤖 Lichess-Inappropriate_BOT

📖 Table of Contents

1. Introduction
2. Project Goal
3. Architecture & Workflow
4. Core Features
5. Prerequisites & System Requirements
6. Installation Blueprint
7. Environment Configuration
8. Comprehensive Directory Mapping
9. Detailed Module Breakdown
10. Advanced Usage Framework
11. API & Programmatic Reference
12. Troubleshooting & Diagnostics
13. Performance Fine-Tuning
14. Contributing Lifecycle
15. License Agreements
16. Credits and Badges
17. Future Roadmap

---

1. Introduction

Lichess-Inappropriate_BOT 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 1200
   │
   ├── [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 inappropriate_bot-1.0.0-py3-none-any.whl

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

tar -xvf inappropriate_bot-1.0.0.tar.gz
cd inappropriate_bot-1.0.0
pip install -r requirements.txt

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-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

8. Comprehensive Directory Mapping

Lichess-Inappropriate_BOT/
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   └── bug_report.md
│   └── workflows/
│       ├── bot-ci.yml
│       └── lint-and-test.yml
├── assets/
│   └── books/
│       └── gm2001.bin
├── src/
│   ├── __init__.py
│   ├── bot.py
│   ├── game_handler.py
│   └── skill_estimator.py
├── dist/
│   ├── inappropriate_bot-1.0.0-py3-none-any.whl
│   └── inappropriate_bot-1.0.0.tar.gz
├── pyproject.toml
├── config.py
├── config.yml.default
├── requirements.txt
└── LICENSE

9. Detailed Module Breakdown

• src/bot.py: Boots the foundational framework runtime, sets up thread pools, and listens to event pipes.
• src/game_handler.py: Implements state rules, reads board steps, and processes challenge transactions.
• src/skill_estimator.py: Tracks analytical evaluation metrics to map centipawn metrics directly onto target ratings.

10. Advanced Usage Framework

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

inappropriate_bot

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 interceptIncoming 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.

14. Contributing Lifecycle

We welcome pull requests and enhancements. Review the comprehensive style standards, pipeline conditions, and branch submission structures maintained in our CONTRIBUTING.md configuration layout.

15. License Agreements

This codebase is entirely open-source software distributed under the terms of the MIT License. For complete copyright parameters, review the root LICENSE text asset. This framework acts as a bridge reference derived from the original engine systems managed under the AGPL open-source guidelines.

16. Credits and Badges

• Developed utilizing foundational structural wrappers provided by the lichess-bot-devs community team.
• Core engine operations run via official Stockfish and Fairy-Stockfish projects.
• Object representations managed inside Python using the open-source python-chess runtime package library.

17. Future Roadmap

• Integrate native web dashboard interfaces to keep track of active match histories.
• Support customized cloud hosting integration setups for true 24/7 uptime.
• Automate opening database selections according to opponent account configurations.