Document logits to move decoding

README.md

@@ -88,6 +88,54 @@ bin_logits = session.run(["bin_logits"], {"bin_moves": bin_moves})[0]
 The ONNX artifact uses the `bin_logits_v1` interface: `bin_moves` input with
 shape `[batch, time]` and `bin_logits` output with shape `[batch, 65536]`.
 
+## Converting Logits To Moves
+
+The model predicts move tokens, not SAN strings. Do not take an unconstrained
+argmax over the full vocabulary. Score the legal moves in the current board
+position and choose from that legal set.
+
+For PyTorch, logits are over the native output tokenizer vocabulary:
+
+```python
+from chess_autocomplete.chess_utils import Board
+
+board = Board()
+# Apply any moves already played:
+# board.push(chess.Move.from_uci("e2e4"))
+
+next_logits = logits[0, -1]
+legal = []
+for move in board.board.legal_moves:
+    raw_bin_word = board.encode(move)
+    token_id = loaded.output_tokenizer.encode(raw_bin_word)
+    legal.append((float(next_logits[token_id]), move))
+
+score, best_move = max(legal, key=lambda item: item[0])
+print(best_move.uci())
+```
+
+For ONNX `bin_logits_v1`, logits are already indexed by raw 16-bit move word:
+
+```python
+from chess_autocomplete.chess_utils import Board
+
+board = Board()
+# Apply any moves already played:
+# board.push(chess.Move.from_uci("e2e4"))
+
+next_logits = bin_logits[0]
+legal = []
+for move in board.board.legal_moves:
+    raw_bin_word = board.encode(move)
+    legal.append((float(next_logits[raw_bin_word]), move))
+
+score, best_move = max(legal, key=lambda item: item[0])
+print(best_move.uci())
+```
+
+Call `board.push(best_move)` after selecting a move so the next prediction is
+decoded against the updated legal move set.
+
 ## Validation
 
 | Artifact | Validation | Status | Backend | Sample shape |