How the engine works

Last updated

The Black Grimoire is a deck-ranking engine that combines a collaborative-filtering model trained on 4,725,876 real decklists with a rule-based synergy graph that reads each commander's oracle text, a WotC Commander Bracket classifier, and Frank Karsten's land-count formula. Every suggestion the engine makes carries a stated reason rather than a bare number, and every limitation of the underlying data is documented below rather than hidden.

The corpus

4,725,876 public decklists scraped from Moxfield, Archidekt, EDHREC as of 2026-10-20. The signal is likes and views only — no tournament win/loss data exists in the corpus. That is a real limitation, not a footnote: a card can be popular without being strong in a given meta.

Collaborative filtering

Card recommendations come from matrix factorization (SVD) over the deck corpus, the same family of technique streaming services use to recommend shows. It retrains automatically after every 50,000 new decks added to the corpus.

A contextual bandit (Vowpal Wabbit) sits on top and reranks suggestions based on which cards players actually pick when offered a choice. It retrains every 6 hours.

Commander synergy graph

Each commander's oracle text is parsed into a producer/consumer graph over 16 resource types — tokens, +1/+1 counters, treasure, graveyard, and more. A card that produces a resource your commander consumes (or vice versa) scores higher, and the reason is stated in plain language rather than left as a number.

EDHREC-style lift

lift = ln(rate of a card in decks running this commander ÷ rate of that card in decks sharing the same color identity)

A lift above zero means a card shows up more often with this commander than base rate for its colors would predict — the standard way EDHREC-style synergy is measured.

WotC Commander Bracket classifier

Every build is checked against Wizards of the Coast's official Commander Bracket criteria: Game Changers (Scryfall's own flag), mass land denial, chained extra turns, and two-card infinite combos. The builder targets bracket 2 through 5 depending on the power level you ask for, and a build is rejected and rebuilt if it drifts outside the requested bracket's rules.

The table below is the exact rule set the classifier checks. Bracket 2 is the strictest: it excludes every Game Changer and any card that performs mass land denial, chains extra turns, or completes a two-card infinite combo. Bracket 3 relaxes the Game Changer limit to three cards but keeps the other three restrictions in place. Brackets 4 and 5 (cEDH) place no restriction on any of the four criteria, since both are explicitly high-power brackets under the official rules.

Bracket rules at a glance
BracketGame Changers allowedMass land denialChained extra turnsTwo-card infinite combos
20Not allowedNot allowedNot allowed
3Up to 3Not allowedNot allowedNot allowed (no early combos)
4UnlimitedAllowedAllowedAllowed
5 (cEDH)UnlimitedAllowedAllowedAllowed

Land count — Karsten's formula

lands = 31.42 + 3.13 × average mana value − 0.28 × cheap ramp/draw spells (99-card deck), MDFC land-backs credited 0.38 each

From Frank Karsten's 2022 land-count research, applied per 99-card deck. Modal double-faced land-backs count as 0.38 of a land each rather than a full one, since only one side of the card is actually a land.

A worked example: a 99-card deck with an average mana value of 2.7 and 8 cheap ramp or draw spells computes as 31.42 + 3.13 × 2.7 − 0.28 × 8 = 37.63, which rounds up to 38 lands. If that same deck runs 2 modal double-faced land-backs, they are credited at 0.38 each, for a combined credit of 0.76 — bringing the physical land count down to 37.

Deck optimizer — how cuts and adds are chosen

The optimizer takes an existing list instead of building one. Cuts are ranked by an additive score with every reason shown to you, in this order of weight:

  1. Legality— not legal in the chosen format, outside the commander's colour identity, or over the copy limit (1 in singleton formats, 4 elsewhere; basic lands and “any number” cards excepted). Always cut.
  2. Role quotas— when the deck runs more removal, draw, ramp, wipes or protection than the format's band (the same bands the deck pages use), the weakest cards in that role are flagged.
  3. Synergy — in commander formats, cards with no synergy edges to the commander or the rest of the deck, then the bottom decile by per-card synergy score. Function cards (ramp, removal, draw) are judged on quota only, never on synergy.
  4. Curve and meta — a mana-value bucket two or more cards above the archetype target adds a point; in 60-card formats, absence from the current meta top list adds a point.

Adds come from four sources, deduplicated and filtered to the deck's colours and the format's legality: role gaps, cards that co-occur with yours in 4,725,876public decks, the commander's inclusion rates, and the format's meta staples. Each cut is paired with an add of the same role where one exists. With a saved collection, owned cards are listed first but nothing is hidden.

lands = 19.59 + 1.90 × average mana value − 0.28 × cheap ramp/draw spells (60-card deck)

Lands are never cut or added by the swap list; the land target is reported separately with Karsten's 60-card formula above (99-card decks use the formula in the previous section). Colour sources are counted from each land's produced mana; fetch lands and choose-a-type lands count for every colour in the deck. The source check is a three-band approximation of Karsten's tables, not the full per-turn table.

Best deck — ranking and climbing your own commanders

Best deck takes a collection (and optionally a commander) and finds the strongest buildable list, rather than building one commander at a time. It optimizes for a single objective:

objective = Deck Score + 10 × goldfish tempo + 5 × opening-hand keep rate − 2 × role-window penalty

Without a commander named, it first pre-ranks your owned commanders by a co-play score (how often each shows up alongside your other owned cards in the deck corpus) down to the top 24, then screens those 24 by the full objective above. It climbs the best one — swapping cards for owned or buy-budget alternatives, up to 3 passes — until a full pass finds no improving swap, the pass cap is hit, or about 3.5 minutes of climbing elapse, whichever comes first. The buy budget lets it spend on unowned cards on top of what you own, never past the budget you set.

Limits, stated plainly:no partner commanders and no Brawl yet (Commander only); and the model can't reliably separate commanders within about 1.5 points of each other on the objective — treat a close ranking as a tie, not a verdict.

How suggestions are ranked, step by step

  1. Build the candidate pool: every card legal for the chosen format and commander's color identity.
  2. Score each candidate with the collaborative-filtering model, based on its similarity pattern across the deck corpus.
  3. Adjust that score with the synergy-graph pass, rewarding cards that produce or consume a resource the commander cares about.
  4. Rerank with the contextual bandit, which nudges scores toward cards players have actually picked in similar situations.
  5. Apply the bracket budget, dropping or capping any card that would push the deck past the requested Commander Bracket.
  6. Set the land count using Karsten's formula, crediting any modal double-faced lands in the final list.

How AI is used — and where it is not

  • Deck building, scoring, the optimizer, the bracket classifier, land counts and the commander pages use no generative AI. They are deterministic code over the deck corpus. The collaborative-filtering model and the contextual bandit described above are classic machine learning trained on public decklists, not language models.
  • The consultant chat uses Claude (Anthropic), with OpenAI as a fallback.It is only available when signed in. Your message, the deck list and its stats are sent to Anthropic to answer, or to OpenAI once your plan's monthly Claude allowance is used, once the site-wide monthly Claude budget is reached, or if the Claude call fails; proposed edits are checked against the deck and change nothing until you click Apply. The site stores token counts per request, not the text of the conversation.
  • The code was written with heavy AI assistance. AI coding agents (Anthropic Claude, OpenAI Codex) wrote most of the code, tests and documentation from my specifications, and AI reviewer agents check each change before it ships. I decide what gets built, set the acceptance tests, and check the output against real decklists.

Declaration in the AI-DECLARATION.md 0.1.2 format — level auto; design copilot, implementation auto, testing auto, documentation auto, review auto, deployment copilot.

Limitations, stated plainly

  • No win-rate data exists in the corpus — rankings reflect popularity (likes/views), not proven results.
  • Popularity is biased toward decks that get built and shared, which skews toward casual and semi-competitive lists.
  • A full build evaluates the entire eligible card pool against the corpus each time, so builds take 30 to 90 seconds.