vrona/fhe.chess

Create an application that plays Chess against an AI oponent. Moves should be encrypted with FHE.

FHE.Chess

Overview

FHE.Chess is about an application that let you play Chess against an AI opponent. The moves are encrypted and then thanks to FHE, the AI infers on data that it cannot see.

Acknowledgement

This repo contains large files: training dataset.

• FHE.Chess project answers to Zama.ai's bounty and shows how to use Zama's Concrete-ML open-source library,
• The FHE.Chess app can be run under 3 modes:
  • clear: non-encryption context. Fast inferences.
  • simfhe: encrypted context thanks to simulation of FHE computations. Fast inferences.
  • deepfhe: encrypted context thanks to FHE. Very slow inferences (because model complexity + hardware)
• AI mainly starts its moves the same way, after several white & black moves its moves are relevant,
• Several minor bugs remain within the Chess_app itself, such as:
  • potential false positive authorized en-passant moves,
  • because of the dual chess developments: one from scratch, one from python-chess, the latter call potential "illegal" moves (this does not lead to crash the app.).
• To download wb_2000_300.csv training data, git lfs is required.

How to

Project flow is the ⭕ IMPORTANT ⭕ document and represents your Ariadne's wire to install, run or rebuilt FHE.Chess project.
As it contains details, explanations and links to other detailed docs, follow the inner steps it explains.

All documents are here docs.

Bibliography

All concept, benchmark modeling, code tutorial and libraries links are in bibliography.

Set up and Play

As the app is based on a client-server architecture, client is at local, server at remote instance.
(not to be confused with client-server architecture used when deploying models under the context of FHE).

Local

1. mkdir client_local directory on your local machine (macOS, Linux, Windows),
2. Create venv based on the /requirements.txt file and activate venv,
3. Download the content of client_local into your client_local local directory,
4. cd client_local

Remote instance

1. Create a remote instance that runs under Intel Ice Lake CPU. Name of instance in GCI: "n2-standard-8", in AWS: EC2 "M6i",
2. Run the remote instance and grab: public IP_address + port that enables to communicate with instance under firewall constrains (for eg.: GCI, port 3389),
3. Create an SSH connection due to another terminal to command your remote instance. (if you don't know how, see ¹)
   
4. Create venv based on the server_cloud/requirements.txt file and activate venv,
5. mkdir fhechess directory,
6. Download the content of server_cloud (without the mentioned large files) into fhechess directory.
7. cd fhechess.

At this step, you have 2 different terminals which are running simultaneously.
Then, run:

1st remote terminal: $ python3 server/server_all.py -i (or --inference) "clear" or "simfhe" or "deepfhe"
!! Wait until the server is connected !! (waiting time:"clear" and "deepfhe" < several seconds, "simfhe" between 2 and 7 mins)

2nd local terminal: $ python3 client_local/chess_env/main.py --server "IP_address" --port PORT
NB:

• --server: Required option and it enables "White AI" and "Black AI" modes, If you have mistyped your IP_Address or if you forgot to run your remote server, please answer to the prompt displayed by your Local Terminal.
• --port: Facultative if your value is the default value:3389. This is the ok firewall on GCI and AWS.

There is a "developer mode" called --devmode. Facultative if you are not interesting in:

• "Human vs Human" game,
• "AI vs AI"game.
  
  Its default value: False.
  To activate it, run $ python3 client_local/chess_env/main.py --devmode True --server "IP_address" --port PORT

Reset and kill

• to reset the game: press r,
• to kill: ctrl+C on local terminal or close the pygame window.
• in deepfhe mode, as it takes hours to predict (see. mode explanation Project Flow), kill the remote terminal.

Playing FHE.Chess

2 main modes:

• Game
  
  White or Black AI (vs Human as Black or White)
  3 modes:
  • clear
  • simfhe
  • deepfhe

• Developer Mode
  
  2 more choices added to the Game mode:
  
  • Human vs Human
  • AI vs AI (here to watch different type of behavior, you can play with the top best answers of each models. In your remote machine, then into server_all.py, change the parameters 5 and 3 of
    python reply = inference.predict(data, 5, 3). Recall that 5 is the 5 top answers of Source model. And for each of them, Target model keep the 3 top answers).

Footnotes

1. if needed, main steps to create ssh connection with GCI on Linux/Mac:

   • recall your USERNAME from GCI and think about a KEY_FILENAME,
   • create your keys: run the command ssh-keygen -t rsa -f ~/.ssh/KEY_FILENAME -C USERNAME -b 2048 (to see them ls .ssh),
   • then copy the private key (.pub is the public one)
   • Add private key + USERNAME into your instance's metadata (follow this process),
   • cd .ssh,
   • established ssh connection with your instance, run ssh -i KEY_FILENAME USERNAME@IP_address.
   ↩

fhe.chess's Issues

Private fork

Hello @MikeHatchi

Could you please allow me to fork privately the repo, so that reviewer from Zama could access the code?
Thanks.