From 1e2e03eaac142251b9b9dc0c330e1e1af2a62b95 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9mi=20Louf?= <remi@thetypicalset.com>
Date: Tue, 28 Nov 2023 11:16:08 +0100
Subject: [PATCH] Add models playing chess example

---
 docs/examples/index.md                |  1 +
 docs/examples/models_playing_chess.md | 80 +++++++++++++++++++++++++++
 mkdocs.yml                            |  1 +
 3 files changed, 82 insertions(+)
 create mode 100644 docs/examples/models_playing_chess.md

diff --git a/docs/examples/index.md b/docs/examples/index.md
index 91682c611..c9a303d59 100644
--- a/docs/examples/index.md
+++ b/docs/examples/index.md
@@ -2,3 +2,4 @@
 
 - [Dating Profile](dating_profiles.md): Build dating profiles from descriptions using prompt templating and JSON-guided generation.
 - [Chain Of Density](chain_of_density.md): Summarize documents using chain of density prompting and JSON-guided generation.
+- [Playing Chess](models_playing_chess.md): Make Mistral-7B play chess against itself using regex-guided generation.
diff --git a/docs/examples/models_playing_chess.md b/docs/examples/models_playing_chess.md
new file mode 100644
index 000000000..2a1e21bfc
--- /dev/null
+++ b/docs/examples/models_playing_chess.md
@@ -0,0 +1,80 @@
+# Large language models playing chess
+
+In this example we will make a quantized version of Mistral-7B play chess against itself. On its own the model easily generates invalid move, so we will give it a little help. At each step we will generate a regex that only matches valid move, and use it to help the model only generating valid moves.
+
+## The chessboard
+
+The game will be played on a standard checkboard. We will use the `chess` [library](https://github.com/niklasf/python-chess) to track the opponents' moves, and check that the moves are valid.
+
+```python
+import chess
+
+board = chess.Board("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1")
+```
+
+## The opponents
+
+Mistral-7B quantized will be playing against itself:
+
+```python
+from outlines import models
+
+board_state = models.transformers("TheBloke/Mistral-7B-OpenOrca-AWQ", device="cuda")
+```
+
+## A little help for the language model
+
+To make sure Mistral-7B generates valid chess moves we will use Outline's regex-guided generation. We define a function that takes the current state of the board and returns a regex that matches all possible legal moves:
+
+```python
+import re
+
+def legal_moves_regex(board):
+    """Build a regex that only matches valid moves."""
+    legal_moves = list(board.legal_moves)
+    legal_modes_str = [board.san(move) for move in legal_moves]
+    legal_modes_str = [re.sub(r"[+#]", "", move) for move in legal_modes_str]
+    regex_pattern = "|".join(re.escape(move) for move in legal_modes_str)
+    regex_pattern = f"{regex_pattern}"
+    return regex_pattern
+```
+
+## Prompting the language model
+
+The prompt corresponds to the current state of the board, so we start with:
+
+```python
+prompt = "Score: 1-0 WhiteElo: 1600 BlackElo: 1600 Timecontrol: 1800+0 Moves: 1."
+```
+
+We update the prompt at each step so it reflects the state of the board after the previous move.
+
+## Let's play!
+
+
+```python
+from outlines import generate
+
+
+turn_number = 0
+while not board.is_game_over():
+    regex_pattern = legal_moves_regex(board)
+    guided = generate.regex(model, regex_pattern)(board_state)
+    move = board.parse_san(guided)
+
+    if turn_number % 2 == 0 :  # It's White's turn
+        board_state += board.san(move) + " "
+    else:
+        board_state += board.san(move) + " " + str(turn_number) + "."
+
+    turn_number += 1
+
+    board.push(move)
+
+    print(board_state)
+```
+
+It turns out Mistal-7B (quantized) is not very good at playing chess: the game systematically ends because of the threefold repetition rule.
+
+
+*This example was originally authored by [@903124S](@903124S) in [this gist](https://gist.github.com/903124/cfbefa24da95e2316e0d5e8ef8ed360d).*
diff --git a/mkdocs.yml b/mkdocs.yml
index d1c1873f0..702117078 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -108,6 +108,7 @@ nav:
       - examples/index.md
       - Synthetic dating Profile: examples/dating_profiles.md
       - Chain of density prompting: examples/chain_of_density.md
+      - Playing chess: examples/models_playing_chess.md
   - Reference:
     - reference/index.md
     - Prompting: reference/prompting.md