Chess Esca

The moves a Polyglot opening book holds for a position. Polyglot is the opening-book format whose 16-byte entries are keyed by a hash of the position, so a book written by any program that speaks it can be read here. No book is bundled: `book` names one of your own. Args: book: path to a `.bin` Polyglot book. fen: the position as FEN or EPD; the start position when omitted. moves: moves played from it, SAN or UCI. pgn: a whole game instead of `fen` and `moves`. variant: 'classic' or 'chess960'. limit: how many entries to return, heaviest first. Returns: dict: `book`, `entries_in_book`, `polyglot_key`, `fen`, `count`, `moves` — each `san`, `uci`, `weight`, `share`, `learn` — and `best`; or `error` when the book cannot be read.

The ending the material makes, what theory says it is, and how it is won. An ending is a position where neither side holds more than two pieces, a piece being anything that is neither a king nor a pawn; above that the class is `not_an_ending` and the signature still says what is on the board. The signature writes the stronger side first — `KRPvKR` — the class names the material alone, and the verdict names the colour it favours. The technique is the named method the ending is played by: the box method, the Lucena position, the opposition, the wrong bishop. The `evidence` holds the position-specific facts the verdict and the technique were read off, each behind the reason it belongs to. This is the books' answer for the material, adjusted by those facts. It is not a search, and it does not know whether this particular position is won. Args: fen: the position as FEN or EPD; the start position when omitted. moves: moves played from it, SAN or UCI. pgn: a whole game instead of `fen` and `moves`. variant: 'classic' or 'chess960'. Returns: dict: `fen`, `is_ending`, `signature`, `class`, `verdict` (`kind` and `colour`), `technique`, `evidence` (`pawn`, `bishops`, `opposition`) and `prose` — or `error`.

Whether one move is legal, and what it does or what forbids it. An illegal move answers with every reason that applies at once — no castling right, a rook that is not there, a king in check, an attacked or a blocked path, a pinned unit, an occupied destination, a promotion left unnamed — each carrying the squares it was read off. A legal move answers with what it changes: the capture, the check, the castling or en passant, the promotion, the position after it, and the draws either side could claim once it is played. Args: move: the move, SAN or UCI. fen: the position as FEN or EPD; the start position when omitted. moves: moves played from it, SAN or UCI. pgn: a whole game instead of `fen` and `moves`. variant: 'classic' or 'chess960'. Returns: dict: `legal`, `move`, `fen`, `prose`, and either `reasons` — a list of `reason`-and-evidence objects — with `legal_moves`, or the move's own text with `effects`, `after` and `claims_after`; or `error`.

The named facts esca reads off a position, group by group. Every fact is labelled by its own name, and a value that differs between the two sides is written `{"white": …, "black": …}`, so nothing has to be read against whose turn it is. A set of squares is the list of its square names in board order, a set of files the list of its letters, and a value that may be absent is `null`. Where a value is a run of eight or three, `field_notes` says once which end is which. The groups are `state`, `history`, `material`, `pawns`, `pieces`, `king`, `mobility`, `attacks`, `exchange`, `threats`, `tactics`, `endgame`, and the two that restate others, `placement` and `maps`. `esca://facts-catalogue` says what every field means. Args: fen: the position as FEN or EPD; the start position when omitted. moves: moves played from it, SAN or UCI. `history` needs them. pgn: a whole game instead of `fen` and `moves`. variant: 'classic' or 'chess960'. groups: the groups to read; all but `placement` and `maps` by default. Returns: dict: `fen`, `side_to_move`, `groups` keyed by group name, each holding `{field: value}`, `field_notes` for the fields whose value is a run of positions, `groups_available` and `prose` — or `error`.

Every legal move of a position, in SAN and in UCI. Each move carries what it does — the role that moves, whether it captures and what, whether it gives check, what it promotes to, and the static exchange it starts. With `categories`, the same moves are also grouped as captures, checks, castling, promotions, en passant and quiet. Args: fen: the position as FEN or EPD; the start position when omitted. moves: moves played from it, SAN or UCI. pgn: a whole game instead of `fen` and `moves`. variant: 'classic' or 'chess960'. categories: group the moves as well as listing them. Returns: dict: `fen`, `side_to_move`, `count`, `moves` — each `san`, `uci`, `kind`, `mover`, `capture`, `victim`, `promotion`, `gives_check`, `see` — and `by_category` when asked for; or `error`.

The ECO code and name of a position, and of the line that reached it. ECO is the Encyclopaedia of Chess Openings, whose volume letter and index name a known opening. The catalogue is keyed by position, so a line that transposes into a named position is named, and a line that has left the book keeps the last name it reached, which is what `reached` reports. Args: fen: the position as FEN or EPD; the start position when omitted. moves: moves played from it, SAN or UCI. `reached` needs them. pgn: a whole game instead of `fen` and `moves`. variant: 'classic' or 'chess960'. Returns: dict: `fen`, `at_position` (`eco` and `name`, or null), `reached`, `line`, `ply`, `named_positions_in_catalogue` — or `error`.

A PGN game read into its headers, its moves and where it ended up. PGN is Portable Game Notation, the text a game is saved and shared in. Comments, numeric glyphs and variation counts are kept where the source has them; the moves reported are the mainline. Args: text: the PGN source; it may hold more than one game. index: which game to read, counting from 0. Returns: dict: `games_in_source`, `index`, `headers`, `comment`, `result`, `variant`, `start_fen`, `moves` — each `san`, `uci`, `nags`, `comment_before`, `comment_after`, `variations` — `ply`, `final_fen`, `opening`, `status`; or `error`.

The whole state of a chess position, read by the rules. Answers in one call: whose turn it is, whether that side is in check and from where, whether the game is over and how, which draws are claimable and on what evidence, how many legal moves there are, the opening name if the position has one, the material on each side, both castlings of both colours with every obstacle at once, the en-passant capture on offer, the pins and skewers on the board, and the ending it is where the material makes one. `prose` gathers every sentence the answer carries. Args: fen: the position as FEN or EPD; the start position when omitted. moves: moves played from it, SAN or UCI. Repetition and fifty-move claims are only visible when the moves that led here are given. pgn: a whole game instead of `fen` and `moves`. variant: 'classic' or 'chess960'. Returns: dict: `fen`, `epd`, `variant`, `side_to_move`, `fullmove_number`, `halfmove_clock`, `ply`, `line`, `status`, `check`, `legal_move_count`, `opening`, `material`, `castling`, `en_passant`, `pins`, `skewers`, `ending` where the material is one, and `prose`, every sentence the answer carries — or `error` when the input names no position.

A list of moves written out as a PGN game. Args: moves: the moves, SAN or UCI. fen: the start position; the variant's own when omitted. variant: 'classic' or 'chess960'. headers: tag pairs to set on the game. result: the termination marker; read from the final position when omitted. Returns: dict: `pgn`, `final_fen`, `ply`, `result`, `opening` — or `error` when a move is not legal where it stands.