LLM-Chess Hybrid

This repository demonstrates how to build a hybrid neural network — how to integrate a local LLM with other specialized networks that enable it to play chess far better than the original LLM.

A detailed explanation is provided in a series of articles, starting with this one.

1. Clone the repository with submodules (or update them if already cloned):

   git submodule update --recursive --init

2. Install the required Python modules:

   pip install -r requirements.txt

3. Download a suitable LLM (e.g., Llama-3.2-1B-instruct) in Hugging Face format.
   Registration may be required. Other compatible models should also work:

   hf download meta-llama/Llama-3.2-1B-instruct --local-dir pathToLlama

4. Download the Stockfish binary for your platform and unpack it.

• python ChessAugmentedModel.py

  to chat with the enhanced LLM that includes improved chess-playing abilities.

• python chatNoChess.py

  to chat with the original LLM for comparison.

Both scripts will ask for the LLM folder and the Stockfish executable path, then store them in settings.json so you won’t have to enter them again.

The ChessAugmentedModel class combines several components to create a chess-capable system:

1. On launch, the downloaded LLM spends a few seconds training a LogisticRegression model to recognize when the user wants to play chess, regardless of language.
   (See train_chess_detector().)
2. When the user sends input, the model performs a single forward pass. The logistic regression decides whether the user is in a chess context.
   (See is_chess_context(self, prompt).)
   This approach works with any LLM and is fast.
   Possible optimization: cache the training results on disk.
3. If a new chess game starts, chess mode is activated. Tokens like A1, b2, etc. are interpreted as board positions and sent to:
4. ChessBoardNN — a neural network that maintains the current board state based on textual moves.
5. If the user input does not contain board positions, it is processed by the LLM normally.
6. Additional regressions are trained to detect game endings (when requested by the user) and restarts.
7. The NNUE network from Stockfish is used to evaluate board positions.

The following parts are still implemented in Python/C++ rather than neural form:

1. Interface logic between networks — can be replaced with direct neural connections, but is left as-is for simplicity.
   This may change in production if code obfuscation is desired.
2. Enumerating legal moves — not trivial but straightforward for human-designed networks like ChessBoardNN.
3. Building a graph of board states to choose the best move — the most complex task of the three.

In engines such as Google AlphaZero or Stockfish, the last task is handled by traditional C++ code.
At first glance, it may seem poorly suited for neural architectures — however, it is possible.

The human brain uses the hippocampus for this type of task. It has been extensively studied, and many models exist — from biologically detailed ones used in neuroprosthetics to high-level conceptual models.
For our purposes, we’ll use a relatively simple but suitable model for the chess domain.

The hippocampus links separate memories and activates them in sequence. This mechanism can connect player moves and board states, create references to subsequent configurations, and traverse them — including backward navigation to parent states.

To store board state evaluations, we use numerical emotions attached to hippocampal memories.

The plan is to move this logic into a neural framework based on hippocampal modeling, which will be covered in a future article.