___________________________________ __    _____________________________ _______
___  __ )__  /___    |_  ____/__  //_/    ______  /__    |_  ____/__  //_/__  /
__  __  |_  / __  /| |  /    __  ,<       ___ _  /__  /| |  /    __  ,<  __  / 
_  /_/ /_  /___  ___ / /___  _  /| |      / /_/ / _  ___ / /___  _  /| |  /_/  
/_____/ /_____/_/  |_\____/  /_/ |_|      \____/  /_/  |_\____/  /_/ |_| (_)  

This codebase is a command-line blackjack game-engine/application where you can design your own neural network and train it to learn basic blackjack strategy.

There are 4 ways to use this Blackjack Engine without touching any code.

1. It can be used to play a text-based blackjack game, with the computer serving as dealer and scorekeeper.
2. It can advise you on how to play any given hand you're playing in real life based on basic-strategy.
3. It can simulate an arbitrary number of hands, using either a basic strategy model or a neural network.
4. It allows users to choose hyperparameters and train their own neural network, which they can then use in the simulator.

I developed this engine as an excuse to learn to build neural networks, and built up the other functionality along the way.

The easiest way to use the blackjack engine is to download the code, navigate to the directory you just downloaded, and type the following command in your terminal (with python and uv installed).

uv run main.py

(Note: The first time you run this code, it may take a few minutes to install torch, the python library that the program uses for the neural network functionality. Subsequent runs will be faster.)

If you're unsure where to start when training a neural network, some relatively reasonable default parameters are:

Layers: 8
Neurons per Layer: 128
Learning Rate: .02
Epochs: 10
Batch Size: 64

For those interested in digging deeper into the code, here's the basic outline:

• main.py is the user-friendly entry point, which coordinates between the different functions of the engine from the command line.
• game_logic.py is where the underlying logic of the game is defined. To make different game-modes (text-based play along, getting recommended moves, simulating thousands of hands) that use the same game logic, turn-structure, etc., the structure is built around the use of dependency injection, and calls different functions based on which functions are passed as arguments in the GameState and GameInterface objects.
• Those objects are defined in base.py, and a few common configurations are stored in config.py.
• Most of the functions for each game-mode, which are either passed into the main functions of game_logic.py or called by main.py, are defined in their own file. That's what text.py, basic_strategy.py, cheat.py, train_nn.py, and performance_tracker.py do.
• The csvdata/ directory houses the training and testing dataset as a csv file, which can be regenerated using some of the code in train_nn.py
• All neural network models are saved in the models/ directory.

It is not possible right now to customize the ruleset. The current rules are:

• doubling down is allowed,
• splitting is allowed,
• maximum 3 splits (4 hands),
• doubling down after splitting is allowed,
• if aces are split, only one card is dealt to each hand
• no insurance or surrender,
• dealer hits on a soft 17 (H17),

Ideas to build on this program further include, in rough order of priority:

• Allow users to use trained models in "cheat" mode.
• Calculate odds in different positions using the engine instead of relying on established basic-strategy rules.
• Go beyond basic strategy to include card-counting capabilities.
• Allow comparison of multiple models on the same decks/hands in simulation mode.
• Allow newer machines to use newer versions of pytorch/numpy and use their GPUs.
• Allow users to see the hyperparameters of their various models.
• Allow users to customize the activation functions used in their models.
• Allow the user to simulate different betting strategies.
• Make the ruleset more customizable.
• Switch from the current "imitation" model of training the neural network to a true RL framework.
• Build a database of hyperparameter combinations to map out the hyperparameter "loss landscape".
• Make a web-based version for less technical people.
• Build a GUI, either terminal based or not?

Source for basic-strategy: https://www.blackjackapprenticeship.com/blackjack-strategy-charts/

Source for blackjack rules: https://bicyclecards.com/how-to-play/blackjack

Distributed under the MIT License.