Downloads · 30 days
8
7% of all-time downloads
quintana42/gang-of-four-neural
gang-of-four-neural is a other model from quintana42. Use it for the other task on the model card, and read the license before you ship it in a product. It is set up for pytorch. The card lists the license as mit.
A neural network model for playing the Gang of Four card game (Chinese climbing game).
Downloads · 30 days
8
7% of all-time downloads
All-time downloads
108
Public
Parameters
946K
26.6 MB on disk
Likes
0
Public
Click a slice to open those files.
.pt11.4 MB · 43%
From the Hugging Face model README
A neural network model for playing the Gang of Four card game (Chinese climbing game).
This model predicts optimal card plays through imitation learning from expert strategy demonstrations. It uses a custom architecture with card attention mechanisms to capture relationships between different card regions.
| Range | Description |
|---|---|
| 0-63 | Player's hand cards (64 card slots) |
| 64-127 | Cards played this game |
| 128-191 | Current trick cards to beat |
| 192-255 | Opponent card estimates |
| 256-295 | Action mask (40 valid actions) |
| 296-327 | Context features (scores, positions, etc.) |
from huggingface_hub import hf_hub_download
import torch
import sys
# Download all necessary files
for filename in ["modeling_gangoffour.py", "game_utils.py", "rules.py", "config.json", "model.safetensors"]:
hf_hub_download(repo_id="quintana42/gang-of-four-neural", filename=filename, local_dir="./model")
sys.path.insert(0, "./model")
from modeling_gangoffour import GangOfFourNet
from game_utils import Card, GameEncoder, decode_action
# Load model
model = GangOfFourNet.from_pretrained("./model")
model.eval()
# Parse your hand from string notation
hand = Card.parse_hand("1G 3R 5Y 7G 10R Dragon")
print(f"Hand: {[str(c) for c in hand]}")
# Define valid plays (in a real game, comes from game rules)
valid_plays = [
[], # Pass
[hand[0]], # Play 1G
[hand[1]], # Play 3R
[hand[2]], # Play 5Y
]
# Encode the game state
encoder = GameEncoder()
state, ordered_plays = encoder.encode_simple(
hand=hand,
valid_plays=valid_plays,
is_leading=True, # We're leading (no trick to beat)
)
# Run inference
state_tensor = torch.tensor(state).unsqueeze(0)
mask_tensor = torch.tensor(state[256:296]).unsqueeze(0)
with torch.no_grad():
logits, declare_prob = model(state_tensor, mask_tensor)
# Decode the result
action_idx = logits.argmax(dim=1).item()
chosen_play = decode_action(action_idx, ordered_plays)
if chosen_play is None:
print("Model chose: PASS")
else:
print(f"Model chose: {[str(c) for c in chosen_play]}")
print(f"Declare last card probability: {declare_prob.item():.3f}")
Parse cards using simple string notation:
from game_utils import Card
# Single cards
card = Card.parse("5G") # 5 Green
card = Card.parse("10R") # 10 Red
card = Card.parse("1M") # Multi-colored 1
card = Card.parse("Dragon") # Dragon
card = Card.parse("PhoenixG") # Phoenix Green
# Multiple cards
hand = Card.parse_hand("1G 3R 5Y Dragon PhoenixY")
The 64 cards are mapped to indices 0-63:
| Index | Card |
|---|---|
| 0-1 | 1 Green (2 copies) |
| 2-3 | 1 Yellow (2 copies) |
| 4-5 | 1 Red (2 copies) |
| 6-7 | 2 Green (2 copies) |
| ... | ... |
| 58-59 | 10 Red (2 copies) |
| 60 | Multi-colored 1 |
| 61 | Phoenix Green |
| 62 | Phoenix Yellow |
| 63 | Dragon |
Formula for numbered cards: (rank - 1) * 6 + color_idx * 2 + copy
where color_idx: GREEN=0, YELLOW=1, RED=2
Actions are encoded dynamically based on valid plays:
The ordered_plays list returned by the encoder maps action indices to actual plays.
Use rules.py to generate valid plays according to game rules:
from game_utils import Card
from rules import get_valid_plays, get_combination_type, can_beat
# Your hand and the trick to beat
hand = Card.parse_hand("4G 4Y 4R 4G 7R 7Y 10G")
trick = Card.parse_hand("6G 6R") # Pair of 6s
# Get all legal plays
valid_plays = get_valid_plays(hand, trick_to_beat=trick)
for play in valid_plays:
if play:
combo_type = get_combination_type(play)
print(f"{combo_type}: {[str(c) for c in play]}")
else:
print("PASS")
# Output:
# pair: ['7R', '7Y']
# gang_of_four: ['4G', '4Y', '4R', '4G'] # Gang beats anything!
# PASS
# Check if a specific play beats a trick
play = Card.parse_hand("8G 8Y")
print(can_beat(play, trick)) # True
Key functions in rules.py:
get_valid_plays(hand, trick_to_beat) - Get all legal playsget_combination_type(cards) - Identify combination (single, pair, gang, etc.)can_beat(play, trick) - Check if play legally beats trickget_all_combinations(hand) - Get all possible combinations from handfrom modeling_gangoffour import GangOfFourNet
# Load from Hugging Face Hub
model = GangOfFourNet.from_pretrained("quintana42/gang-of-four-neural")
# Or load from local directory
model = GangOfFourNet.from_pretrained("./my_local_model")
# Use GPU
model = GangOfFourNet.from_pretrained("quintana42/gang-of-four-neural", device="cuda")
# After training
model.save_pretrained("./my_trained_model")
A complete browser-based example using ONNX Runtime Web:
Features:
The model was trained using imitation learning from an expert heuristic strategy:
Gang of Four is a Chinese climbing card game similar to Big Two/Tichu:
config.json - Model configurationmodel.safetensors - Model weights (safetensors format)modeling_gangoffour.py - Model code with from_pretrained supportgame_utils.py - Encoding/decoding utilities (Card, GameEncoder, decode_action)rules.py - Game rules (get_valid_plays, can_beat, get_combination_type)torch>=2.0.0
safetensors>=0.4.0
huggingface_hub>=0.20.0
@misc{gangoffour-neural,
author = {quintana42},
title = {Gang of Four Neural AI},
year = {2026},
publisher = {Hugging Face},
url = {https://huggingface.co/quintana42/gang-of-four-neural}
}
MIT License