M5: artifact set recommendations in the build recommender

Completes the per-hero build sheet (masteries + sets + blessing + stat
readiness). recommend_sets() maps the hero's game-truth kit -> role-fit sets,
with game-truth set bonuses from artifact_sets.json and internal->UI name
mapping (CriticalDamage -> "Savage/Cruel"). Debuffers/DoT carries lead with
Speed + Accuracy sets (cadence + landing), pure attackers with damage sets,
support/tank with survivability. Wired into m5_recommender --builds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: SnoopLawg

docs/m5_recommender_guide.md

@@ -50,8 +50,10 @@ downweighted vs CC-immune bosses; the game-truth ACC floor is surfaced.
 python3 tools/m5_build_recommender.py --hero Venomage --location cb
 ```
 Maps the hero's game-truth kit → relevant masteries (filtered to the location),
-blessing, and stat focus — and checks the user's **actual ACC** against the
-floor (`[READY: you have 423]` / `[GAP: need +M]`).
+artifact sets, blessing, and stat focus — and checks the user's **actual ACC**
+against the floor (`[READY: you have 423]` / `[GAP: need +M]`). Set bonuses are
+game-truth (`artifact_sets.json`); the role→set mapping is heuristic. Set names
+are shown in UI form (internal `CriticalDamage` → "Savage/Cruel").
 
 ### What to pull / build next
 ```bash

tools/m5_build_recommender.py

@@ -80,6 +80,12 @@ def _load_blessing_relevance() -> list:
     return raw["blessings"]
 
 
+def _load_valid_sets() -> set:
+    raw = json.loads((STATIC / "artifact_sets.json").read_text(encoding="utf-8"))
+    rows = next((v for k, v in raw.items() if k != "_meta" and isinstance(v, list)), [])
+    return {r["set"] for r in rows}
+
+
 _COMPUTED_COLS = ["base_computed", "artifact_bonus", "mastery_bonus",
                   "affinity_bonus", "classic_arena_bonus", "blessing_bonus",
                   "empower_bonus", "relic_bonus", "faction_guardians_bonus"]
@@ -195,6 +201,57 @@ def relevant(mid: int) -> bool:
     return by_tree
 
 
+# Artifact set recommendations by kit role. The set BONUSES are game-truth
+# (data/static/artifact_sets.json); the role->set mapping is standard
+# team-building heuristic. Internal set code -> UI name for readability
+# (set names differ from UI, like blessings — see artifact_relic_mechanics).
+SET_UI_NAME = {
+    "CriticalDamage": "Savage/Cruel (C.DMG)", "CriticalChance": "Crit Rate",
+    "AttackPower": "Offense (ATK%)", "IgnoreDefense": "Stalwart-ish / IgnoreDef",
+    "LifeDrain": "Lifesteal", "AttackAndCritRate": "Atk+CR",
+    "AccuracyAndSpeed": "Perception (ACC+SPD)", "Accuracy": "Accuracy",
+    "AttackSpeed": "Speed", "SpeedAndResistance": "Speed+RES",
+    "Hp": "Life (HP%)", "Defense": "Defense", "Shield": "Shield",
+    "Resistance": "Resistance", "HpAndHeal": "Immortal",
+    "Counterattack": "Retaliation", "Stamina": "Relentless (TM)",
+    "DotRate": "Toxic", "BlockDebuff": "Immunity",
+    "ResistanceAndBlockDebuff": "Resist+Immunity",
+    "UnkillableAndSpdAndCrDmg": "Frenzy/Unkillable-ish",
+}
+
+
+def recommend_sets(hero: dict, location: str, valid_sets: set) -> list:
+    provides = set(hero.get("provides", []))
+    role = hero.get("synergy_role", "")
+    game_role = hero.get("game_role", "")
+    is_attacker = game_role == "Attack" or role in ("attacker", "dot")
+    is_debuffer = any(p.startswith("enemy_debuff:") for p in provides) or "dot" in role
+    is_support = role in ("support", "healer/support") or game_role == "Support"
+    is_tank = game_role in ("Defense", "Health")
+
+    picks: list[str] = []
+    # Debuffers/DoT carries lead with Speed + Accuracy (cadence + landing
+    # matter most), then damage. Pure attackers lead with damage sets.
+    if is_debuffer:
+        picks += ["AttackSpeed", "AccuracyAndSpeed", "Accuracy"]
+    if is_attacker:
+        picks += ["CriticalDamage", "AttackPower", "CriticalChance",
+                  "IgnoreDefense", "LifeDrain"]
+    if is_support or is_tank:
+        picks += ["AttackSpeed", "SpeedAndResistance", "Hp", "Defense",
+                  "Resistance", "HpAndHeal", "Shield"]
+    if location in ("arena", "tt"):
+        picks = ["AttackSpeed", "CriticalDamage", "CriticalChance"] + picks
+    # Dedup preserving order, keep only sets that exist in game data.
+    seen, out = set(), []
+    for s in picks:
+        if s in seen or s not in valid_sets:
+            continue
+        seen.add(s)
+        out.append(SET_UI_NAME.get(s, s))
+    return out[:5]
+
+
 def recommend_blessing(hero: dict, location: str, brel: list) -> list:
     provides = set(hero.get("provides", []))
     role = hero.get("synergy_role", "")
@@ -277,6 +334,9 @@ def main() -> None:
             names = ", ".join(p["name"] for p in picks)
             print(f"    {tree}: {names}")
     print()
+    sets = recommend_sets(hero, args.location, _load_valid_sets())
+    print(f"  Artifact sets (role-fit): {', '.join(sets) if sets else '(role-standard)'}")
+    print()
     bl = recommend_blessing(hero, args.location, brel)
     print(f"  Blessing (relevant + role-fit): {', '.join(bl) if bl else '(role-standard)'}")
     print()

tools/m5_recommender.py

@@ -343,6 +343,7 @@ def main() -> None:
         mrel = brmod._load_mastery_relevance()
         brel = brmod._load_blessing_relevance()
         computed = brmod._load_computed_stats()
+        valid_sets = brmod._load_valid_sets()
         print()
         print("=== Per-hero builds ===")
         for name in res["team"]:
@@ -354,8 +355,10 @@ def main() -> None:
             masts = "; ".join(
                 f"{t}: {', '.join(p['name'] for p in by_tree[t])}"
                 for t in ("Attack", "Defence", "Support") if by_tree.get(t))
+            sets = brmod.recommend_sets(hero, args.location, valid_sets)
             print(f"\n  {name}:")
             print(f"    masteries: {masts}")
+            print(f"    sets:      {', '.join(sets) if sets else '(role-standard)'}")
             print(f"    blessing:  {', '.join(bl) if bl else '(role-standard)'}")
             for s in brmod.recommend_stats(hero, args.location, computed):
                 print(f"    stat: {s}")