Upload folder using huggingface_hub

README.md

@@ -14,6 +14,8 @@ tags:
 
 # bridge2vec
 
+<p align="center"><img src="assets/logo.svg" alt="Bridge2Vec logo: the four card suits on a dark tile" width="200"></p>
+
 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]
@@ -21,6 +23,10 @@ Embeddings for contract bridge hands. Two hands land close together when they ta
 
 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.
 
+![A random bridge deal: 13 cards for each of North, East, South and West around a dashed table](assets/deal.svg)
+
+One deal, four hands. The model sees each hand alone.
+
 ## 🚀 Usage
 
 The repo holds the script that trained the model, so one command embeds a hand (spades, hearts, diamonds, clubs):
@@ -43,11 +49,50 @@ uv run https://huggingface.co/jgalego/bridge2vec/resolve/main/bridge2vec.py embe
 
 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.
+| | |
+|---|---|
+| Parameters | 4,912,479 (4 layers, width 256, embedding 128) |
+| Data | 200,000 deals |
+| Steps | 50000, 1024 deals per step |
+| Learning rate | 0.0003, cosine |
+| Final loss | 1.2938 (table 0.7635), 0.667 of cells exact |
+| Hardware | NVIDIA A10G, 81 min |
 
 ## 📊 Results
 
-Not evaluated yet.
+**Tables.** Predicted against exact tables for all 32,000 test deals, per cell.
+
+| MAE (tricks) | Exact | Within one | Whole table exact |
+|---|---|---|---|
+| 0.366 | 0.654 | 0.984 | 0.016 |
+
+**Hands.** From one hand alone, the expected-table head is off by 0.345 tricks per cell on the 1000 test hands; guessing the average hand is off by 1.251.
+
+**Hard pairs.** Hands with the same suit-length pattern and similar HCP look alike to a counting rule. Among them, for an anchor and two mates whose expected tables differ from the anchor's by more than half a trick, the embedding must rank the closer table first. Out of 98,216 triplets it gets 0.769 right; chance, and any rule that only counts points and cards per suit, gets 0.5.
+
+**Retrieval.** Each test hand is matched to its nearest other test hand; the score is the mean difference between their expected tables, in tricks, so lower is better. Deals are matched the same way on their exact tables, excluding deals that share the test hand; a deal's embedding is its four hand embeddings in seat order.
+
+| Nearest by | Hands | Deals |
+|---|---|---|
+| Embedding | 0.836 | 1.788 |
+| HCP and suit lengths | 0.613 | 1.411 |
+| Random | 1.752 | 3.131 |
+
+![The test hands' embeddings flattened with UMAP, coloured by expected notrump tricks](results/map.png)
+
+The test hands' embeddings, flattened with UMAP and coloured by expected notrump tricks with the hand declaring.
+
+### Auxiliary weight
+
+The same model trained with three weights on the table and value heads, each on its own branch (`aux0`, `aux0.1`, `aux1`). `main` is `aux0.1`.
+
+| Aux weight | Table MAE | Exact | Hard pairs | Hand retrieval | Deal retrieval |
+|---|---|---|---|---|---|
+| 0 | 0.365 | 0.655 | 0.775 | 0.826 | 1.775 |
+| 0.1 | 0.366 | 0.654 | 0.769 | 0.836 | 1.788 |
+| 1 | 0.380 | 0.642 | 0.776 | 0.845 | 1.793 |
+
+The weight barely matters here, and hard pairs do not collapse at any value. Retrieval by embedding is worse than by HCP and suit lengths at every weight.
 
 ## ⚠️ Limitations