Module lab 

open-chess additions to the Lichess API, used by the chess training app:

• POST /api/board/game/{id}/assist: the app declares that its engine help was switched on or off during one of our games (ground truth for the fair-play model);
• GET /api/esl/position?fen=: the position dictionary — the deepest stored evaluation of a position, with win/draw/loss odds, and the deepest analysis a training app sent in (a hint);
• POST /api/esl/position: send in the app’s own analysis of a position;
• GET /api/esl/position/moves?fen=: every legal move with its value, where the dictionary knows it;
• POST /api/esl/recognise: read a board from a photo;
• POST /api/esl/photos/{id}/confirm: say what a photo kept for review showed.
• GET /api/esl/tablebase?fen=: the exact result of a position with up to seven pieces, from the tablebase server, kept once fetched.

Structs

ConfirmBody

HintBody

HintMove

One move’s value as the app sends it.

PhotoLabel

PhotoList

PositionQuery

RecogniseBody

Functions

assist

confirm_photo

POST /api/esl/photos/{id}/confirm: the player who sent a photo says what it showed (they picked the move it matched, or finished setting the position up in the editor). A label for training, marked as the player’s: a reviewer’s label always wins.

label_photo

POST /api/esl/photos/{id}/label (JSON {placement} or {unreadable: true}): a reviewer’s label, which replaces a player’s. The position joins the dictionary (each side to move: a photo doesn’t say).

photo_image

GET /api/esl/photos/{id}/image: a photo’s bytes.

photos

GET /api/esl/photos: board photos the reader wasn’t sure of, waiting for a person (?all=true: every photo), newest first, without the image bytes.

position

position_hint

POST /api/esl/position: the training app’s analysis of a position, a hint for others looking it up. One per player and position (the deepest kept); never mixed with the worker’s evaluations. Refused while you’re playing a game here.

position_key

The dictionary key for a position (see chess_analysis::dictionary).

position_moves

GET /api/esl/position/moves?fen=: every legal move, each with the best value the dictionary has for it, from the mover’s view, and White’s odds after it: the worker’s scoring of this position’s moves first, then the evaluation stored for the position the move leads to, then an app’s hint. null where nothing is known.

queue_photo_positions

Queue a confirmed photo’s position(s) in the dictionary for the fair-play worker to evaluate (counting the photos of each).

recognise

Read a board from a photo: with our board reader if there is one, asking the vision language model only when it isn’t sure (or there is no reader). A photo that wasn’t read for sure is kept for the Review page (photoId in the answer) unless CHESS_VISION_REVIEW is off.

tablebase

GET /api/esl/tablebase?fen=: Lichess’s tablebase answer (category, distance to zeroing and to mate, and every move’s result), cached. Like the position dictionary, refused while you’re playing here.