Building a Chess Game with Python and OpenAI

I enjoy coding small, silly things whenever I have some free time over the weekend. One such idea turned into a command-line chess game where you can play against OpenAI. I called it "SkakiBot," inspired by "Skaki," the Greek word for chess.

The excellent python-chess library takes care of all the chess mechanics. The goal isn’t to build a chess engine from scratch but to demonstrate how easily OpenAI can be integrated into a project like this.

Let’s delve into the code and see how it all comes together!

The Entry Point

We’ll start by setting up a basic game loop that takes user input and prepares the foundation for the chess logic.

def main():
    while True:
        user_input = input("Enter your next move: ").strip()

        if user_input.lower() == 'exit':
            print("Thanks for playing SkakiBot. Goodbye!")
            break

        if not user_input:
            print("Move cannot be empty. Please try again.")
            continue

        print(f"You entered: {user_input}")

At this point, the code doesn't do much. It just prompts the user for input, validates it, and prints it:

Enter your next move: e2e4
You entered: e2e4
Enter your next move: exit
Thanks for playing SkakiBot. Goodbye!

Adding the Chess Library

Next, we bring in python-chess, which will handle board management, move validation, and game-ending scenarios.

pip install chess

With the library installed, we can initialize a chessboard and print it before prompting for user input:

import chess

def main():
    board = chess.Board()

    while not board.is_game_over():
        print(board)

        user_input = input("Enter your next move (e.g., e2e4): ").strip()

        if user_input.lower() == 'exit':
            print("Thanks for playing SkakiBot. Goodbye!")
            break

Adding Move Validation

To make the game functional, we need to validate user input and apply legal moves to the board. UCI (Universal Chess Interface) format is used for moves, where you specify the starting and ending square (e.g., e2e4).

def main():
    board = chess.Board()

    while not board.is_game_over():
        # ...

        try:
            move = chess.Move.from_uci(user_input)
            if move in board.legal_moves:
                board.push(move)
                print(f"Move '{user_input}' played.")
            else:
                print("Invalid move. Please enter a valid move.")
        except ValueError:
            print("Invalid move format. Use UCI format like 'e2e4'.")

Handling Endgames

We can now handle game-ending scenarios like checkmate or stalemate:

def main():
    board = chess.Board()

    while not board.is_game_over():
        # ...

    if board.is_checkmate():
        print("Checkmate! The game is over.")
    elif board.is_stalemate():
        print("Stalemate! The game is a draw.")
    elif board.is_insufficient_material():
        print("Draw due to insufficient material.")
    elif board.is_seventyfive_moves():
        print("Draw due to the seventy-five-move rule.")
    else:
        print("Game ended.")

At this stage, you play for both sides. You can test it out by attempting Fool's Mate with the following moves in UCI format:

• f2f3
• e7e5
• g2g4
• d8h4

This results in a quick checkmate.

Integrating OpenAI

Now it’s time to let AI take over one side. OpenAI will evaluate the state of the board and suggest the best move.

Fetching the OpenAI Key

We start by fetching the OpenAI API key from the environment:

# config.py

import os

def get_openai_key() -> str:
    key = os.getenv("OPENAI_API_KEY")
    if not key:
        raise EnvironmentError("OpenAI API key is not set. Please set 'OPENAI_API_KEY' in the environment.")
    return key

AI Move Generation

Next, we write a function to send the board state - in Forsyth-Edwards Notation (FEN) format - to OpenAI and retrieve a suggested move:

def get_openai_move(board):
    import openai
    openai.api_key = get_openai_key()
    board_fen = board.fen()

    response = openai.ChatCompletion.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "system", "content": (
                "You are an expert chess player and assistant. Your task is to "
                "analyse chess positions and suggest the best move in UCI format."
            )},
            {"role": "user", "content": (
                "The current chess board is given in FEN notation:\n"
                f"{board_fen}\n\n"
                "Analyse the position and suggest the best possible move. Respond "
                "with a single UCI move, such as 'e2e4'. Do not provide any explanations."
            )}
        ])

    suggested_move = response.choices[0].message.content.strip()
    return suggested_move

The prompt is simple, but it works well to generate valid moves. It provides enough context for OpenAI to understand the board state and respond with a legal move in UCI format.

The board state is sent in FEN format, which gives a complete snapshot of the game, including piece positions, whose turn it is, castling rights, and other details. This is ideal because OpenAI's API is stateless and doesn’t retain information between requests, so each request must include all necessary context.

For now, the model is hardcoded as gpt-3.5-turbo for simplicity, but it would be better to fetch it from the environment, as we did for the API key. This would make it easier to update or test with different models later.

The Final Game Loop

Finally, we can integrate the AI into the main game loop. The AI evaluates the board after each user move and plays its response.

def main():
    board = chess.Board()

    while not board.is_game_over():
        clear_display()
        print(board)

        user_input = input("Enter your next move (e.g., e2e4): ").strip()

        if user_input.lower() == 'exit':
            print("Thanks for playing SkakiBot. Goodbye!")
            break

        try:
            move = chess.Move.from_uci(user_input)
            if move in board.legal_moves:
                board.push(move)
                print(f"Move '{user_input}' played.")
            else:
                print("Invalid move. Please enter a valid move.")
                continue
        except ValueError:
            print("Invalid move format. Use UCI format like 'e2e4'.")
            continue

        if not board.is_game_over():
            try:
                ai_move_uci = get_openai_move(board)
                ai_move = chess.Move.from_uci(ai_move_uci)
            except Exception as e:
                print(f"Error with OpenAI: {str(e)}")
                break

            if ai_move in board.legal_moves:
                board.push(ai_move)
                print(f"OpenAI played '{ai_move_uci}'.")
            else:
                print(f"OpenAI suggested an invalid move: '{ai_move_uci}'.")
                break

---

That’s it! You now have a functional chess game where you can play against OpenAI. There’s plenty of room for improvement in the code, but it’s already playable. A fun next step would be to pit two AIs against each other and let them battle it out.

The code is available at GitHub. Have fun experimenting!