Tarot Bot

A four-player French Tarot table with a Rust rules engine, reinforcement-learning agents, and a React interface. The taker is selected before each deal; bidding and contract bonuses are outside the current scope.

Play in the browser

Requirements: a recent Rust toolchain and Node.js.

cd web
npm install
npm run build
cd ..
cargo run --bin tarot-bot

Open http://127.0.0.1:8000, choose the dealer and taker, then select a mode:

• Voir une donne favorable finds a deal whose predicted margin is positive before the dog is revealed. This uses the model's prediction, not the final result, so success is not guaranteed.
• Joueurs entraînés runs the supplied trained taker and defense on an arbitrary deal.
• Joueurs aléatoires uses random legal actions.
• Jouer à quatre lets four people share the screen and play manually.

An automatic deal pauses on the taker's initial 18 cards. Découvrir le chien reveals the six-card dog before play begins. During the game, the page shows the taker's hand, discard, dog, predicted final points out of 91, and predicted margin over the required threshold. The delay between cards is configurable, and play can be paused or advanced one card at a time.

The supplied agent is loaded automatically. TAROT_MODEL_PREFIX can select another model prefix, and TAROT_PORT can change the server port:

TAROT_MODEL_PREFIX=results/rl_agent_new TAROT_PORT=18000 cargo run --bin tarot-bot

For frontend development, run npm run dev inside web/ and open http://127.0.0.1:5173. Vite proxies /api requests to the Rust server on port 8000. Run npm run build after frontend changes to update the version served by Rust.

Supplied agent

The repository includes results/rl_agent_10min_attack.bin and results/rl_agent_10min_defense.bin. The pair was trained through self-play for 2,080,000 deals in about ten minutes on an RTX 4090.

Results on 10,000 unseen deals with seed 20260926:

Evaluation	Result
Trained taker success rate against random defense	29.3%
Fully random taker success rate	19.6%
Trained defense success rate against a random taker	89.9%
Initial point-estimate RMSE	7.09 points
Initial margin-estimate RMSE	9.60 points

The taker is imposed on every deal, including hands that a real player would pass. These success rates therefore do not represent auction play.

Rules engine and terminal version

cargo run --bin terminal
cargo test

The reusable rules engine is in src/lib.rs, the local server in src/main.rs, and the React interface in web/src/main.jsx. Card values are stored as integer half-points. The engine implements the dog and discard, legal-card constraints, trick resolution, the Excuse, and final card-point counting. It does not implement bidding, contract scoring, or bonuses.

Rules reference: Fédération Française de Tarot.

Reinforcement learning

The rl binary trains two actor-critic networks with Burn: one network for the taker and one shared by all three defenders. The taker network selects the six-card discard and plays the tricks.

Before seeing the dog, the taker network receives only its 18 initial cards and estimates its final points and margin. During the discard it receives the 24-card hand, dog, and cards already selected. During play, each network observes its hand, the dog, the ordered history of completed tricks, and the current trick. The taker also sees its discard. No network sees an opponent's hand.

Each observation contains 695 values. The network has two fully connected hidden layers of 128 units with ReLU activations, followed by a 78-action policy head, a margin-value head, and a final-points head. Each network has 115,920 parameters.

The terminal reward is the taker's final margin over the threshold determined by the number of oudlers captured; the defenders receive its negative. Training samples actions from the policy, while evaluation and the web table choose the highest-scoring legal action.

CUDA setup

burn-tch 0.21 and tch 0.22 require LibTorch 2.9. The cuda feature downloads the matching CUDA 12.8 build on its first compilation, which is approximately 3.6 GB. A recent NVIDIA driver compatible with CUDA 12.8 is required.

export TORCH_CUDA_VERSION=cu128
cargo run --release --features cuda --bin rl -- \
  train 50000 20261002 results/rl_agent_new
cargo run --release --features cuda --bin rl -- \
  eval results/rl_agent_new 10000 20261001

Training uses the first CUDA GPU and batches 512 games per update. The web server uses the CPU ndarray backend and does not require CUDA or LibTorch.

Linear card-value experiment

cargo run --release --bin analyze -- 100000 20260923 results

The analyzer simulates random legal play, fits a ridge regression from the taker's initial 18 cards to its final points, and writes aggregate validation metrics to results/summary.txt. Four out of five deals are used for fitting and one out of five for validation. An optional fourth argument controls the worker count; the default uses up to 16 available CPU threads.

License

This project is available under the MIT License.