@intrastellar/kairos

Predict next-move think-time quantiles for chess positions.

Kairos accepts a pre-move chess record and returns estimated p10, p25, p50, p75, and p90 think times in seconds. It is a timing model, not a chess engine or move-selection tool.

Install

npm install @intrastellar/kairos

Usage

import model from "@intrastellar/kairos/model.json" with { type: "json" };
import { predictThinkTime } from "@intrastellar/kairos";

const prediction = predictThinkTime({
  fen_before_move: "rnbqkbnr/ppp2ppp/3p4/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 0 3",
  previous_move: "g1f3",
  opponent_move: "d7d6",
  elo: 1736,
  opponent_elo: 1719,
  time_left: 1195
}, model);

console.log(prediction);
// {
//   p10: 1.0697561367900401,
//   p25: 1.7381294936487353,
//   p50: 3.005793364295652,
//   p75: 5.490549115431874,
//   p90: 10.120121412227668
// }

API

predictThinkTime(record, model)

Returns five ordered quantiles in seconds: p10, p25, p50, p75, and p90. Values are non-negative and capped at record.time_left.

| Field | Type | Description | | --- | --- | --- | | fen_before_move | string | Full six-field FEN before the predicted move. | | previous_move | string \| null | Previous UCI move, such as g1f3; use null for the first move. | | opponent_move | string \| null | Most recent opponent UCI move; use null when unavailable. | | elo | number | Rating of the player whose think time is predicted. | | opponent_elo | number | Opponent rating. | | time_left | number | Player's pre-move clock in seconds. |

UCI moves may include a promotion suffix, for example e7e8q.

Browser use

predictThinkTime has no runtime dependencies. Load the bundled model with fetch, then pass the parsed object to the function:

import { loadModelFromUrl, predictThinkTime } from "@intrastellar/kairos";

const model = await loadModelFromUrl("/assets/kairos-model.json");
const prediction = predictThinkTime(record, model);

Userscripts

For userscript managers, load the classic-script model bundle with a bare @require directive. It exposes the parsed model as globalThis.DLPKairosModel; use it with your own inference implementation.

// @require https://unpkg.com/@intrastellar/[email protected]/model.js

Model scope

The bundled model was trained on historical 1200+0 standard-rated Lichess games from April 2017. It estimates how long a player may take for a move; it does not evaluate position quality, recommend moves, or account for player-specific history beyond the supplied record.

Data source and license

Training data came from the April 2017 Lichess standard-rated database export. Lichess database exports are released under CC0.

This package, including its inference code and bundled model, is licensed under the MIT License.