pier97/mtgda

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.

Install

pip install "mtgda @ git+https://github.com/pier-tmp/mtgda.git"

Stateful API

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

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.