Chess Tutor

This is an open-source project to help beginner player's imrpove their understanding of chess principles and develop basic chess vision.

It leverages an LLM (openai/gpt-4o) to analyze the position and provide feedback to the user and using another, separate system prompt to play against the user.

Features

• Multi-LLM: this project utilizes two LLMs, one as a coach and the other as an opponent
  • Coach: openai/gpt-4o because it's a pretty good all-around model
  • Opponent: openai/gpt-4o because it's a pretty good all-around model and plays pretty well when provided with the list of legal moves
    • *Note: previously the opponent was using openai/gpt-3.5-turbo-instruct because there's some anecdotal evidence that it's better at playing chess than other models - if it doesn't provide a valid move after 4 attempts we choose a random valid move for the Opponent; I've also tested openai/gpt-4o-mini, but it seems to play the almost the same moves every game and also makes reckless choices with it's queen early on
• Advice: the player can right click on a piece with valid moves to ask the Coach what it thinks about moving that piece
• Analysis: the Coach will provide an ongoing analysis after each player and Opponent move
• Undo: the player can undo and redo moves, checking the Coach's analysis and viewing the possible Opponent responses before finally committing to a move and allowing the Opponent to play
• View Opponent Moves: before committing to a move, the player can click on Opponent pieces to see their possible moves, allowing them to consider the Opponent's possible responses before committing to a move - they can also right click on a piece to ask the Coach about the relative strength of that opponent move
• Real-time Evaluation: the Stockfish evaluation of the position is displayed in real-time as you play, allowing you to see the impact that each move and opponent response has on your chances of winning

Development Info

This is a Next.js project bootstrapped with create-next-app.

Getting Started

Clone or download the repo:

git clone git@github.com:DVDAGames/chess-tutor.git

Change into the project directory:

cd chess-tutor

Install the dependencies:

npm install

Copy the .example.env file to .env and set your OpenAI API key as the API_KEY environment variable:

cp .example.env .env

Note: You can also set the BASE_URL environment variable if you want to use some other OpenAI-compatible endpoint. The tutor and opponent are currently optimized for the openai/gpt-4o model so you may need to tweak the prompts in src/lib/prompts.ts if you change the models used for the routes in the /src/app/api/bot directory.

Run the development server:

npm run dev

Open http://localhost:3000 with your browser interact with the chess tutor.

Note: There is currently a build warning error TP1001 new Worker("/engine/stockfish.wasm.js") is not statically analyse-able. Other folks have run into the same issue with Next.js and Stockfish, but things still seem to run locally, so it's not a priority right now.

Learn More

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.