Upload folder using huggingface_hub

README.md

@@ -0,0 +1,61 @@
+---
+datasets:
+- jgalego/bridge2vec-deals
+library_name: pytorch
+license: mit
+model_name: bridge2vec
+pipeline_tag: feature-extraction
+tags:
+- contract-bridge
+- double-dummy
+- embeddings
+- weird2vec
+---
+
+# bridge2vec
+
+Embeddings for contract bridge hands. Two hands land close together when they take tricks alike. Part of Weird2Vec, embedding models for data nobody embeds.
+
+> [!NOTE]
+> **What is double dummy?** A bridge deal is 52 cards dealt into four hands of 13: North, East, South and West. Double-dummy analysis assumes every player sees all four hands and plays perfectly. For each trump suit, or notrump, and each declarer, it gives the number of tricks declarer takes: a table of 5 × 4 numbers. Players at the table can't see the other hands, but double-dummy tricks are the usual yardstick for judging hands and contracts.
+
+The model embeds one hand, the 13 cards a player sees when bidding. It reads each hand on its own and then has to predict the deal's double-dummy table from the four hand embeddings alone, so each embedding must carry what matters for taking tricks: lengths, honours, intermediates. Hands that could swap seats without changing the table end up close.
+
+## 🚀 Usage
+
+The repo holds the script that trained the model, so one command embeds a hand (spades, hearts, diamonds, clubs):
+
+```
+uv run https://huggingface.co/jgalego/bridge2vec/resolve/main/bridge2vec.py embed --hand AKQ32.KJ4.T9.A87
+```
+
+It prints HCP and suit lengths, the expected tricks when this hand or its partner declares, the five most similar test hands, and the 128-dimensional embedding. With `--deal` it predicts a whole deal's table and prints the exact one next to it:
+
+```
+uv run https://huggingface.co/jgalego/bridge2vec/resolve/main/bridge2vec.py embed --deal "N:AKQ32.KJ4.T9.A87 JT98.AQ2.KQ8.K92 765.T98.AJ65.QJ3 4.7653.7432.T654"
+```
+
+## 🃏 Data
+
+[jgalego/bridge2vec-deals](https://huggingface.co/datasets/jgalego/bridge2vec-deals): random deals, each solved double dummy with [DDS](https://github.com/dds-bridge/dds) through [endplay](https://github.com/dominicprice/endplay). The test split holds 1,000 random North hands, each dealt 32 times with random East, South and West hands. Averaging a test hand's 32 tables gives its expected table.
+
+## 🏋️ Training
+
+A transformer reads a hand's 13 cards, each a suit plus a rank, and pools them into a unit vector. For each declarer, an MLP reads the four hand embeddings in the order declarer, left-hand opponent, partner, right-hand opponent, and predicts declarer's tricks in each strain, so rotating the seats rotates the table. Each step relabels the suits at random and moves the table rows to match, since double-dummy results don't depend on suit names. Two small heads read a single embedding: one predicts the hand's expected table, the other its HCP and suit lengths.
+
+Not trained yet.
+
+## 📊 Results
+
+Not evaluated yet.
+
+## ⚠️ Limitations
+
+- Double dummy is perfect play with all cards visible. Real play and bidding involve hidden cards, so the embedding knows nothing about conventions or what an auction reveals.
+- Deals are random, not from real games, where bidding selects which deals get played.
+- Expected tables average 32 deals per test hand, so they carry sampling noise.
+
+## 📚 Data and software
+
+- [DDS](https://github.com/dds-bridge/dds): B. Haglund and S. Hein's double-dummy solver.
+- [endplay](https://github.com/dominicprice/endplay): D. Price's Python bridge library, which wraps DDS.