README.md

1# Restricted Lichess Bot API bridge
2
3Public source: `core.py`, `runtime.py`, `launch.py`, `test_bridge.py` and this
4README. Ship these with the tokenizer, verified `training_adapter` /
5`training_core`, `harness.py`, and `mate_override.py`. Do not ship runtime
6directories, tokens, local launch commands, credentials, model weights or
7personal configuration. No token or machine-specific path is embedded here.
8
9The bot uses the official https://lichess.org/api Bot API (not the human Board
10API). Credentials come only from the local file supplied to `--token-file`,
11remain in memory, and are never included in logs or exceptions. TLS verification
12stays enabled, redirects are rejected, and authenticated requests use only
13`https://lichess.org/api/...`. No upgrade/security-setting endpoints exist here.
14
15## Launch contract
16
17Use an existing compatible Python environment with torch, transformers, requests
18and python-chess. Set `CHESS_MODEL_PROJECT` to the directory containing the
19training adapter, then invoke `launch.py` with:
20
21```
22--token-file /private/path/to/token
23--checkpoint /private/path/to/checkpoint
24--checkpoint-sha256 VERIFIED_SHA256
25--bot-name YOUR_BOT
26--opponent ALLOWED_HUMAN
27--output /private/runtime-directory
28--session-minutes 90
29```
30
31No packages are installed. Checkpoint hash and GPU occupancy are checked before
32load; GPU 1 is used only when no compute process is present. The model loads in
33the existing spawned worker, warms up with a standard-start decision, and its
34BOT identity is checked through `/api/account`. Readiness is reported only after
35the event stream has opened, with the separately recorded `/api/users/status`
36online flag. `status.json` and `events.jsonl` are local operational artifacts.
37A file lock prevents two copies from using the same runtime directory.
38
39Only incoming challenges from the configured human to the configured BOT are
40accepted: casual, standard chess, standard start, at least 600 seconds and a
415-second increment. One game is active/reserved at a time. No matchmaking,
42outgoing challenges, chat posting, takeback acceptance or account changes.
43After the session deadline no new challenges are accepted; an active game is
44allowed to finish before shutdown. A newly opened event stream includes current
45games/challenges, allowing startup and reconnect recovery.
46
47## Gameplay and recovery
48
49Every server state is replayed from the standard start with python-chess; server
50FEN snapshots are not model prompts. King-to-rook castling UCI is normalized.
51The complete history goes to the existing legal full-move joint scorer. The
52reviewed three-ply AND/OR mate proof runs first and is independently labeled.
53There is no general engine evaluation or hidden search. When context is too
54long, the model fails, or the clock reserve is short, a deterministic lexical
55legal fallback is explicitly logged; history is never cropped. No probability
56is invented for a skipped/unavailable model.
57
58Per-turn inference budget is at most 8 seconds, adjusted for remaining clock,
59increment, queue age and first-move expiration. Tactical work uses at most one
60second and 50,000 nodes within that budget. Network writes have bounded 5-second
61connect/read timeouts. The server is authoritative for game status and results;
62the mate search retains the harness's conservative immediate draw-claim policy.
63The API's `claim-draw` means disconnected-opponent adjudication and is not used
64as a local fifty-move/repetition shortcut.
65
66Before sending, persist the decision and exact history key. Duplicate snapshots
67never cause another accepted move submission. A timed-out write is uncertain:
68reconnect, receive a fresh full state, and retry only that same move if the exact
69position remains unchanged (at least two seconds later, at most three attempts).
70If history advanced, never replay the old move. Each state writes a replayable
71PGN and journal; helper moves receive explicit PGN comments and full proofs in
72the journal. Accepted moves are awaited in server history before logging as
73actual PGN moves. No speculative moves enter a PGN.
74
75Streams reconnect with bounded exponential backoff; HTTP 429 waits at least
7660 seconds and 401/403 stops. Chat text is ignored, never interpreted as commands.
77Offline fixtures cover authorization gates, special moves, persistence, duplicate
78and uncertain submissions, clock budgets, helper bypass, fallback and PGN results.
79This is a restricted human-test bridge, not a production tournament service.
80