lichess-org / lila-tablebase

Tablebase server

lila-tablebase

Tablebase server for lichess.org, based on shakmaty-syzygy.

Usage

lila-tablebase

USAGE:
    lila-tablebase [OPTIONS]

OPTIONS:
        --standard <STANDARD>...      Directory with tablebase files for standard chess
        --antichess <ANTICHESS>...    Directory with tablebase files for antichess
        --atomic <ATOMIC>...          Directory with tablebase files for atomic chess
        --gaviota <GAVIOTA>...        Directory with Gaviota tablebase files
        --bind <BIND>                 Listen on this socket address [default: 127.0.0.1:9000]
    -h, --help                        Print help information

HTTP API

GET /standard

curl http://tablebase.lichess.ovh/standard?fen=4k3/6KP/8/8/8/8/7p/8_w_-_-_0_1

name	type	default	description
fen	string	required	FEN of the position. Underscores allowed.

{
  "dtz": 1, // dtz50'' with rounding or null if unknown
  "precise_dtz": 1, // dtz50'' (only if guaranteed to be not rounded) or null if unknown
  "dtm": 17, // depth to mate or null if unknown
  "checkmate": false,
  "stalemate": false,
  "variant_win": false, // only in chess variants (atomic, antichess)
  "variant_loss": false, // only in chess variants
  "insufficient_material": false,
  "category": "win", // win, unknown, maybe-win, cursed-win, draw, blessed-loss, maybe-loss, loss
  "moves": [ // information about legal moves, best first
    {
      "uci": "h7h8q",
      "san": "h8=Q+",
      "dtz": -2,
      "precise_dtz": -2,
      "dtm": -16,
      "zeroing": true,
      "checkmate": false,
      "stalemate": false,
      "variant_win": false,
      "variant_loss": false,
      "insufficient_material": false,
      "category": "loss" // loss, unknown, maybe-loss, blessed-loss, draw, cursed-win, maybe-win, win
    },
    // ...
  ]
}

GET /standard/mainline

curl http://tablebase.lichess.ovh/standard/mainline?fen=4k3/6KP/8/8/8/8/7p/8_w_-_-_0_1

name	type	default	description
fen	string	required	FEN of the position. Underscores allowed.

{
  "dtz": 1,
  "mainline": [ // dtz mainline or empty if drawn
    { "uci": "h7h8q", "san": "h8=Q+", "dtz": -2 },
    { "uci": "e8d7", "san": "Kd7", "dtz": 1 },
    { "uci": "h8h2", "san": "Qxh2", "dtz": -14 },
    { "uci": "d7c6", "san": "Kc6", "dtz": 13 },
    { "uci": "h2e5", "san": "Qe5", "dtz": -12 },
    { "uci": "c6b6", "san": "Kb6", "dtz": 11 },
    { "uci": "g7f6", "san": "Kf6", "dtz": -10 },
    { "uci": "b6a6", "san": "Ka6", "dtz": 9 },
    { "uci": "e5b2", "san": "Qb2", "dtz": -8 },
    { "uci": "a6a5", "san": "Ka5", "dtz": 7 },
    { "uci": "f6e5", "san": "Ke5", "dtz": -6 },
    { "uci": "a5a4", "san": "Ka4", "dtz": 5 },
    { "uci": "e5d4", "san": "Kd4", "dtz": -4 },
    { "uci": "a4a5", "san": "Ka5", "dtz": 3 },
    { "uci": "d4c5", "san": "Kc5", "dtz": -2 },
    { "uci": "a5a4", "san": "Ka4", "dtz": 1 },
    { "uci": "b2a2", "san": "Qa2#", "dtz": -1 }
  ],
  "winner": "w" // (w) white, (b) black, (null) draw
}

Claims draw by 50-move rule as soon as possible and ends the mainline. Error 404 if not a tablebase position or required tables not present.

GET /atomic

GET /antichess

Acknowledgements

Thanks to Ronald de Man for his Syzygy endgame tables. Thanks to Bojun Guo for generating and sharing 7-piece tables.

License

lila-tablebase is licensed under the GNU Affero General Public License 3.0 (or any later version at your option). See the COPYING file for the full license text.

lila-tablebase's Issues

Problems with connection to tablebaseserver

Hello,
I have problems with connecting to the tabelbase on following URI:

http://tablebase.lichess.ovh/standard?fen=4k3/6KP/8/8/8/8/7p/8_w_-_-_0_1

It seems like the Server is down or not available.
There is also a report that the Lichess-Client also can't connect.
https://lichess.org/forum/lichess-feedback/cannot-open-tablebase
I tested the connection via Postman to validate my problems.

This was the response:

GET http://tablebase.lichess.ovh/standard?fen=4k3/6KP/8/8/8/8/7p/8_w_-_-_0_1: {
  "Error": "connect ECONNREFUSED 54.37.255.147:80",
  "Request Headers": {
    "user-agent": "PostmanRuntime/7.33.0",
    "accept": "*/*",
    "postman-token": "8ac11b1d-73a6-4163-ba18-e8ed75d9fb1c",
    "host": "tablebase.lichess.ovh",
    "accept-encoding": "gzip, deflate, br",
    "connection": "keep-alive"
  }
}

Please check if the server is down or is in any trouble. I hope I could help.

Consistency between /standard and /standard/mainline endpoints

I'm using the API for the Reddit bot and people just reported it provided a wrong continuation line so I'm trying to examine it further.

Here is the FEN: 7k/8/1R6/R7/8/8/8/4K3 w - - 0 1

Now, http://tablebase.lichess.ovh/standard?fen=7k/8/1R6/R7/8/8/8/4K3_w_-_-_0_1 says that the best move is Ra7 and indeed it is, but mainline returned by http://tablebase.lichess.ovh/standard/mainline?fen=7k/8/1R6/R7/8/8/8/4K3_w_-_-_0_1 starts with Rg5 which is obviously not the best move (still a win but not the quickest one).

I'm basing the bot's internal logic on the assumption that if the /standard endpoint returns dtm different than null then /standard/mainline returns mainline leading to mate with the given dtm. Now I'm wondering if this assumption is even valid?

feature request

Hi many, many thanks for all your great work.
One tiny suggestion :-) As a problem composer, most of the interaction I have with the board is seeing what the change would be if I shift a piece to a new square. However, if that shift happens to randomly correspond to a legal move, then the player to move will be flipped. This is really disconcerting.
I am wondering if you could have two modes "Play" and "Explore". "Play" is what you have right now, but "Explore" only changes the player to move if you select the move from the menu on the right (or change the player to move explicitly at the top.

What's the rate limit for `/standard` endpoint?

I'm integrating an option for my bot to use the online tablebase and would like to know what's the rate limit for the /standard endpoint in order to configure a proper retry (exponential backoff) policy.

I already figured out it's way less strict than /standard/mainline one (confirmed in #61), but would love get some numbers.

Atomic Tablebases Incorrectly Assessing Insufficient Mating Material

I know this is the wrong place to post this, but hopefully someone else knows where it should be posted.

At the end of the game, it was a mate in seven, despite the tablebase saying it was a draw. There are likely other issues as well, so it might be worth someone else going through and double checking, since there's not really much point in having a tablebase if it's not accurate.
https://lichess.org/zM5LfgKL

`maybe-win` and `maybe-loss` categories

Positions that should return maybe-win ("8/6B1/6B1/8/2K2n2/4k3/8/8 w - - 1 2", here) and maybe-loss ("K7/2k5/3n4/8/2b5/8/8/8 w - - 97 128"), here according to the tests don't seem to return it in the prod endpoint.

Are those categories still in use?
If that's the case, when do positions get assigned those categories? Any chance some real examples could be provided to better understand and handle them?

Thanks!

HTTP 429 when requesting /standard/mainline endpoint

I just started working on adding the tablebase to u/chessvision-ai-bot/ bot on Reddit and this API looks like an awesome resource I could use. The bot tries to give the best continuation line so the GET /standard/mainline endpoint is quite useful. When I'm testing the requests to the API locally I get 429 Too Many Requests quite often. I'm sending a normal request with a unique User-Agent describing the bot. Is there any way to avoid the 429? In the production, the bot uses queuing to process Reddit submissions so that there is always at least a 30-60s interval between processing two submissions. Could this 429 be a problem?

Feature Request -> Multiple positions with one request

It would be nice if there is an option to request multiple positions at one time, for speed reasons.

So my chess engine uses a 5 peace tablebase (since 1 gig can fit in an raspberry pi ram), but it would be nice if my engine can request (around 30) endgame positions, in witch an 8 peace position may result to.

So the engine can decide witch peace to capture to get into an winning tablebase position.