Skip to content

feat(connectors): add lichess/clock-blunder, chess clocks and evaluations with a blunder question - #834

Open
SudeepGowda55 wants to merge 3 commits into
OpenTSLM:mainfrom
SudeepGowda55:feature/lichess-clock-blunder
Open

SudeepGowda55 wants to merge 3 commits into
OpenTSLM:mainfrom
SudeepGowda55:feature/lichess-clock-blunder

Conversation

@SudeepGowda55

Copy link
Copy Markdown

Description

Adds lichess/clock-blunder, a connector for real rated games from the Lichess open database (CC0).

  • Data: 60,358 windows from 15,205 games (48,055 train, 6,136 validation, 6,167 test). Each window holds three per-ply series: White's clock and Black's clock in seconds, and the Stockfish evaluation in pawns from White's view, all as recorded by Lichess in the game's PGN.
  • Task: each window ends just before one player's move, and a ClassificationTask asks whether that player blunders within their next three moves (22.8% of the train windows are a yes).

Why it matters:

  • TimeNet has no dataset from games or from human decisions under a clock. Here the series are a person's own time use and the swings of the position, and the question is about what they do next.
  • A time-series language model can be asked to call the blunder before it happens and say why, and every answer can be checked against the moves that were actually played.

Contributed as part of the TimeNet Online Hackathon (team Matcrypt).

Mapping

Record: one Record per window, at most 40 plies before the decision point, on an OrdinalAxis (one value per ply).

  • Sources: Clocks with the signals white_clock and black_clock (seconds; a clock keeps its last value between its owner's moves), and Engine with evaluation_pawns (clipped to ±10, so one mate does not dwarf the window).
  • Annotations: time_control, white_elo, black_elo, side_to_move, ply. The Lichess game id is in the record metadata. Player names are not kept.

Task: a ClassificationTask over the label set blunder_within_three_moves (no, yes).

  • Label: Lichess's own rule. A move is a blunder when it drops the mover's winning chances by 0.3 or more on the -1 to +1 scale, with winning chances 2 / (1 + exp(-0.00368208 * centipawns)) - 1 and a forced mate counted as +1 or -1. The label is computed from the evaluations; it is not read from the PGN's ?? glyphs, and the two differ on some moves.
  • Prompt: states the time control, both ratings and who is to move. It never contains the answer or anything from later plies.
  • Rationale: a template sentence written from the window's own numbers and the answer. It is generated supervision, tagged as such, not expert commentary.

Source and determinism

  • The connector reads a fixed byte range, the first 64 MiB of the April 2017 standard rated dump (3.5 GB in full), pinned by sha256, so every build sees the same games.
  • It keeps the complete games that have a clock and an evaluation on every ply. Up to four windows are drawn per game at plies chosen with a seed derived from the game id, from ply 12 on and always leaving room for the mover's next three moves.
  • The split is by game id (80/10/10), so no game appears in two splits.
  • requirements.txt adds zstandard (BSD-3-Clause) to decompress the dump.

Testing

  • 42 tests in tests/test_connector.py, none of which uses the network: synthetic PGN compressed with zstandard, including a mate evaluation, a berserk start, an increment control, a game without evaluations, a game cut off without a result and a game too short for a window, plus a round trip through the writer and reader.
  • make check, make test-connectors (all 13 connectors), ty check --python-version 3.11 and make license-check pass locally. I did not run make test, since the change adds a connector and touches no core code.
  • A real build with timenet-build build lichess/clock-blunder takes about a minute and produces the counts above.

SudeepGowda55 and others added 3 commits November 20, 2026 19:20
… API

Main changed the connector API. A label set carries its name as an
annotation, a Hugging Face connector passes its Hub settings as class
keywords and reads a mapping from part to path, BaseConnector names the
whole download result, and Annotation takes its value by keyword.

The dev group now lists zstandard, so ty finds it.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants