---
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.