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

TermsBody

Constants

PHOTO_TERMS

The photo licence’s version (docs/photo-licence.md). A photo is kept for review, and trained on, only under terms its sender accepted.

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}): what I say the photo shows. Anyone signed in may answer; two agreeing answers label it. An admin’s or manager’s answer is the label at once, whatever others said. A labelled 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.

photo_terms

GET /api/esl/photo-terms: the photo licence, and whether I accepted it.

photos

GET /api/esl/photos: board photos waiting for people to say what they show, for anyone signed in: not their own, not ones they’ve answered, not ones already settled (two agreeing, or an admin), newest first, without the image bytes. Admins and managers see disputed photos first, and with ?all=true every photo.

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.

set_photo_terms

POST /api/esl/photo-terms (JSON {accept, public}): accept (or withdraw from) the photo licence for photos I send from now on, and whether they’re also CC0.

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.