Overview

BotLi is a bot for Lichess. Strongly inspired by ShailChoksi/lichess-bot. It extends its features with a matchmaking mode where the bot automatically challenges other bots with similar ratings.

How to install

• NOTE: Only Python 3.10 or later is supported!
• Download the repo into BotLi directory: git clone https://github.com/Torom/BotLi.git
• Navigate to the directory in cmd/Terminal: cd BotLi
• Copy config.yml.default to config.yml

Install all requirements:

python -m pip install -r requirements.txt

• Customize the config.yml according to your needs.

Lichess OAuth

• Create an account for your bot on Lichess.org.
• NOTE: If you have previously played games on an existing account, you will not be able to use it as a bot account.
• Once your account has been created and you are logged in, create a personal OAuth2 token with the "Play games with the bot API" ('bot:play') scope selected and a description added.
• A token will be displayed. Store this in the config.yml file as the token field.
• NOTE: You won't see this token again on Lichess, so do save it.

Setup Engine

Within the file config.yml:

• Enter the directory containing the engine executable in the engine: dir field.
• Enter the executable name in the engine: name field.
• You need to adjust the settings in engine: uci_options depending on your system.

Setup opening book

To use an opening book, you have to enter a name of your choice and the path to the book at the end of the config in the books section.

In the upper engine: opening_books: books section you only have to enter the name you just chose. In addition, different books can be used for white, black and chess960. If no specific book is defined, the standard books are used.

For example, the books section could look like this:

books:
  Goi: "./engines/Goi.bin"
  Perfect: "/home/Books/Perfect2021.bin"
  Cerebellum: "Cerebellum.bin"

A corresponding engine: opening_books: section could look like this:

  opening_books:
    enabled: true
    books:
      white:
        - "Perfect"
        - "Goi"
#     black:
#       - "BlackBook"
      standard:
        - "Cerebellum" 
#     chess960:
#       - "Chess960Book"
    selection: "weighted_random"

How to control

Interactive mode

In this mode the bot is controlled by commands entered into the console.

Start

To start the bot, type:

python user_interface.py

The bot automatically accepts challenges. Which challenges are accepted is defined in the config in the section challenge.

To see all commands, type:

help

Matchmaking

To challenge other players with similar ratings, type:

matchmaking

Change the settings in matchmaking in the config to change how this bot challenges other players. The bot will pause matchmaking for incoming challenges. To exit the matchmaking mode type:

stop

To exit the bot completely, type:

quit

The bot will always wait until the current game is finished.

Non interactive mode

In this mode, the bot is controlled by flags that are set at the start. This is useful when the bot is running as a service or on Heroku.

Start

To start the bot in the non interactive mode, type:

python user_interface.py --non_interactive

The bot automatically accepts challenges. Which challenges are accepted is defined in the config in the section challenge.

Matchmaking

To let the bot challenge other bots in non interactive mode, start it like this:

python user_interface.py --non_interactive --matchmaking

CAUTION: Lichess will rate limit you if you let matchmaking run for too long.

Upgrade to Bot account

When the bot is running in interactive mode it will ask for an account upgrade if necessary.

In non interactive mode the --upgrade flag must be set at start.

python user_interface.py --non_interactive --upgrade

The account cannot have played any game before becoming a Bot account. The upgrade is irreversible. The account will only be able to play as a Bot.

How to deploy to Heroku

For Heroku, any config change must be made in config.yml.default. Do NOT rename it to config.yml!

• Fork this repository.
• Create a new heroku app.
• Go to Account Settings on Heroku, scroll down to API Key and copy it.
• In your fork go to Settings -> Secrets and create a New repository secret. Name is HEROKU_API_KEY and value is the api key from Heroku.
• Create another New repository secret. Name is HEROKU_EMAIL and value is the email address you use for Heroku.
• Go to Settings tab on Heroku and create a variable, set LICHESS_BOT_TOKEN as key and your Lichess token as value.
• Go to the Actions tab on your fork and enable them.
• Insert your app name into the .github/workflows/main.yml of your fork and commit it.

Now the docker container gets deployed. This may take a moment. After the successful deployment, the worker needs to be activated in the Resources tab on Heroku.

Your bot is now online and ready to play.

Customize your bot

By default, the Dockerfile loads the latest Stockfish version from abrok.

If you want another engine or additional files like opening books to be downloaded you have to add this in the Dockerfile. Remember to modify your config.yml.default accordingly.

To start the matchmaking mode just add the --matchmaking flag to the CMD line in the Dockerfile.

Acknowledgements

Thanks to the Lichess team, especially T. Alexander Lystad and Thibault Duplessis for working with the LeelaChessZero team to get this API up. Thanks to the Niklas Fiekas and his python-chess code which allows engine communication seamlessly. In addition, the idea of this bot is based on ShailChoksi/lichess-bot.

License

BotLi is licensed under the AGPLv3 (or any later version at your option). Check out the LICENSE file for the full text.