| --- |
| library_name: onnxruntime |
| language: |
| - en |
| tags: |
| - onnx |
| - magic-the-gathering |
| - draft |
| - ranking |
| - zero-shot |
| --- |
| |
| # MTG Draft Assistant v3 |
|
|
| MTG Draft Assistant ranks the cards in a booster pack using the cards selected |
| earlier in the draft. The release contains the ONNX card encoder, the ONNX draft |
| model, tokenizer files, model configuration, and a card catalog for name-based |
| inference. The Python package supplies the deterministic mechanic featurizer. |
|
|
| The source code and Python API are available on |
| [GitHub](https://github.com/pier-tmp/mtgda). |
|
|
| ## Install |
|
|
| ```bash |
| pip install "mtgda @ git+https://github.com/pier-tmp/mtgda.git" |
| ``` |
|
|
| ## Stateful API |
|
|
| ```python |
| from mtgda import MtgDraftAssistant |
| |
| assistant = MtgDraftAssistant.from_pretrained("pier97/mtgda") |
| draft = assistant.new_draft() |
| |
| recommendations = draft.see([ |
| "Lightning Bolt", |
| "Llanowar Elves", |
| "Cancel", |
| ]) |
| |
| draft.pick("Lightning Bolt") |
| ``` |
|
|
| ## Stateless API |
|
|
| ```python |
| from mtgda import DraftStep, MtgDraftAssistant |
| |
| assistant = MtgDraftAssistant.from_pretrained("pier97/mtgda") |
| history = [ |
| DraftStep( |
| pack=("Lightning Bolt", "Llanowar Elves", "Cancel"), |
| pick="Lightning Bolt", |
| ) |
| ] |
| |
| recommendations = assistant.rank( |
| history, |
| ["Shock", "Giant Growth", "Murder"], |
| ) |
| ``` |
|
|
| Card names may be replaced with Scryfall-style dictionaries for custom or newly |
| released cards. |
|
|
| ## Metrics |
|
|
| The checkpoint was selected by validation NLL. SOS and MSH were excluded from |
| training and checkpoint selection. |
|
|
| | Split | Top-1 | Top-3 | NLL | |
| |---|---:|---:|---:| |
| | Known test | 68.26% | 95.17% | 0.8184 | |
| | SOS holdout | 50.49% | 85.41% | 1.3349 | |
| | MSH holdout | 51.50% | 85.95% | 1.2839 | |
|
|
| ## Architecture |
|
|
| The card representation combines a 320-dimensional MPNet text projection, 16 |
| numeric features, and 207 deterministic mechanic flags. A two-layer causal |
| encoder-decoder transformer with 320-dimensional hidden states and eight |
| attention heads ranks the candidates in the current pack. |
|
|
| The exported graphs use ONNX opset 18. Validation against the PyTorch checkpoint |
| produced identical API ranking, with maximum absolute errors of `1.01e-5` for |
| logits and `7.67e-7` for probabilities. |
|
|
| ## Limits |
|
|
| The model supports up to 45 draft steps and 15 cards per pack. It predicts the |
| historical choices represented in its training data and does not guarantee an |
| optimal pick or account for private information unavailable in the supplied |
| draft history. |
|
|
