Upload clashcr/models/card_resolver.py with huggingface_hub

clashcr/models/card_resolver.py

@@ -0,0 +1,327 @@
+"""Card resolver: convert visual evidence into card events.
+
+Rules:
+- Bats observed as grouped flying units -> Bats.
+- Three Musketeers observed as three Musketeers spawning together -> Three Musketeers.
+- Elixir Pump building spawn -> Elixir Collector.
+- Tornado vortex effect -> Tornado.
+- Vines root/tangle effect -> Vines.
+- Elixir Golem split behavior -> Elixir Golem.
+- Hero visual variant -> corresponding Hero card, not base card.
+- Evolution variant -> evolution-aware event.
+- If evidence is ambiguous, output UNKNOWN instead of guessing.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set
+
+from clashcr.utils.card_registry import CardRegistry
+from clashcr.models.evidence_model import EvidenceBundle, UnitEvidence, SpellEvidence
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ResolvedEvent:
+    card_key: str  # 'UNKNOWN' if ambiguous
+    confidence: float
+    evidence: EvidenceBundle
+    reasoning: str
+    is_ambiguous: bool = False
+    ambiguity_reason: str = ""
+
+
+class CardResolver:
+    """Maps unit/spell evidence to card plays."""
+
+    # Multi-unit card mappings: unit_name -> possible cards
+    UNIT_TO_CARDS: Dict[str, List[str]] = {
+        "skeleton": ["skeletons", "skeleton-army", "graveyard", "tombstone"],
+        "skeleton-evolution": ["skeletons-evolution"],
+        "bat": ["bats"],
+        "bat-evolution": ["bats-evolution"],
+        "goblin": ["goblins", "goblin-gang", "goblin-barrel", "goblin-drill"],
+        "spear-goblin": ["spear-goblins", "goblin-gang"],
+        "barbarian": ["barbarians", "barbarian-hut", "battle-ram", "elite-barbarians"],
+        "barbarian-evolution": ["barbarians-evolution"],
+        "hog": ["hog-rider"],
+        "hog-rider": ["hog-rider"],
+        "musketeer": ["musketeer", "three-musketeers"],
+        "mini-pekka": ["mini-pekka"],
+        "pekka": ["pekka"],
+        "knight": ["knight"],
+        "knight-evolution": ["knight-evolution"],
+        "archer": ["archers"],
+        "archer-evolution": ["archers-evolution"],
+        "minion": ["minions", "minion-horde"],
+        "mega-minion": ["mega-minion"],
+        "elite-barbarian": ["elite-barbarians"],
+        "royal-recruit": ["royal-recruits"],
+        "royal-recruit-evolution": ["royal-recruits-evolution"],
+        "wall-breaker": ["wall-breakers"],
+        "wall-breaker-evolution": ["wall-breakers-evolution"],
+        "bomber": ["bomber"],
+        "bomber-evolution": ["bomber-evolution"],
+        "battle-ram": ["battle-ram"],
+        "battle-ram-evolution": ["battle-ram-evolution"],
+        "ice-spirit": ["ice-spirit"],
+        "ice-spirit-evolution": ["ice-spirit-evolution"],
+        "fire-spirit": ["fire-spirit"],
+        "electro-spirit": ["electro-spirit"],
+        "heal-spirit": ["heal-spirit"],
+        "valkyrie": ["valkyrie"],
+        "valkyrie-evolution": ["valkyrie-evolution"],
+        "wizard": ["wizard"],
+        "witch": ["witch"],
+        "baby-dragon": ["baby-dragon"],
+        "inferno-dragon": ["inferno-dragon"],
+        "electro-dragon": ["electro-dragon"],
+        "skeleton-dragon": ["skeleton-dragons"],
+        "prince": ["prince"],
+        "dark-prince": ["dark-prince"],
+        "bandit": ["bandit"],
+        "royal-ghost": ["royal-ghost"],
+        "fisherman": ["fisherman"],
+        "hunter": ["hunter"],
+        "executioner": ["executioner"],
+        "magic-archer": ["magic-archer"],
+        "lumberjack": ["lumberjack"],
+        "miner": ["miner"],
+        "princess": ["princess"],
+        "ice-wizard": ["ice-wizard"],
+        "electro-wizard": ["electro-wizard"],
+        "night-witch": ["night-witch"],
+        "mother-witch": ["mother-witch"],
+        "golden-knight": ["golden-knight"],
+        "skeleton-king": ["skeleton-king"],
+        "archer-queen": ["archer-queen"],
+        "monk": ["monk"],
+        "mighty-miner": ["mighty-miner"],
+        "little-prince": ["little-prince"],
+        "royal-guardian": ["royal-guardian"],
+        "phoenix-big": ["phoenix"],
+        "phoenix-egg": ["phoenix"],
+        "phoenix-small": ["phoenix"],
+        "golem": ["golem"],
+        "golemite": ["golem"],
+        "lava-hound": ["lava-hound"],
+        "lava-pup": ["lava-hound"],
+        "giant": ["giant"],
+        "giant-skeleton": ["giant-skeleton"],
+        "goblin-giant": ["goblin-giant"],
+        "royal-giant": ["royal-giant"],
+        "royal-giant-evolution": ["royal-giant-evolution"],
+        "electro-giant": ["electro-giant"],
+        "mega-knight": ["mega-knight"],
+        "sparky": ["sparky"],
+        "balloon": ["balloon"],
+        "ram-rider": ["ram-rider"],
+        "battle-healer": ["battle-healer"],
+        "cannon": ["cannon"],
+        "tesla": ["tesla"],
+        "tesla-evolution": ["tesla-evolution"],
+        "inferno-tower": ["inferno-tower"],
+        "bomb-tower": ["bomb-tower"],
+        "mortar": ["mortar"],
+        "mortar-evolution": ["mortar-evolution"],
+        "x-bow": ["x-bow"],
+        "elixir-collector": ["elixir-collector"],
+        "furnace": ["furnace"],
+        "goblin-hut": ["goblin-hut"],
+        "barbarian-hut": ["barbarian-hut"],
+        "tombstone": ["tombstone"],
+        "goblin-cage": ["goblin-cage"],
+        "goblin-brawler": ["goblin-cage"],
+        "dart-goblin": ["dart-goblin"],
+        "flying-machine": ["flying-machine"],
+        "zappy": ["zappies"],
+        "rascal-boy": ["rascals"],
+        "rascal-girl": ["rascals"],
+        "royal-hog": ["royal-hogs"],
+        "cannon-cart": ["cannon-cart"],
+        "skeleton-barrel": ["skeleton-barrel"],
+        "goblin-barrel": ["goblin-barrel"],
+        "goblin-drill": ["goblin-drill"],
+        "clone": ["clone"],
+        "mirror": ["mirror"],
+        "graveyard": ["graveyard"],
+        "elixir-golem-big": ["elixir-golem"],
+        "elixir-golem-mid": ["elixir-golem"],
+        "elixir-golem-small": ["elixir-golem"],
+        "dirt": ["miner"],
+        # Spells as YOLO classes (if model detects them)
+        "fireball": ["fireball"],
+        "zap": ["zap"],
+        "zap-evolution": ["zap-evolution"],
+        "arrows": ["arrows"],
+        "poison": ["poison"],
+        "freeze": ["freeze"],
+        "rage": ["rage"],
+        "tornado": ["tornado"],
+        "earthquake": ["earthquake"],
+        "the-log": ["the-log"],
+        "barbarian-barrel": ["barbarian-barrel"],
+        "giant-snowball": ["giant-snowball"],
+        "lightning": ["lightning"],
+        "rocket": ["rocket"],
+        "royal-delivery": ["royal-delivery"],
+    }
+
+    # Cards that spawn multiple identical units
+    MULTI_UNIT_CARDS = {
+        "skeletons": {"unit": "skeleton", "count": 4},
+        "skeletons-evolution": {"unit": "skeleton-evolution", "count": 4},
+        "skeleton-army": {"unit": "skeleton", "count": 15},
+        "goblins": {"unit": "goblin", "count": 3},
+        "goblin-gang": {"unit": ["goblin", "spear-goblin"], "count": [3, 3]},
+        "minions": {"unit": "minion", "count": 3},
+        "minion-horde": {"unit": "minion", "count": 6},
+        "barbarians": {"unit": "barbarian", "count": 5},
+        "barbarians-evolution": {"unit": "barbarian-evolution", "count": 5},
+        "elite-barbarians": {"unit": "elite-barbarian", "count": 2},
+        "bats": {"unit": "bat", "count": 5},
+        "bats-evolution": {"unit": "bat-evolution", "count": 5},
+        "three-musketeers": {"unit": "musketeer", "count": 3},
+        "royal-recruits": {"unit": "royal-recruit", "count": 6},
+        "royal-recruits-evolution": {"unit": "royal-recruit-evolution", "count": 6},
+        "wall-breakers": {"unit": "wall-breaker", "count": 2},
+        "wall-breakers-evolution": {"unit": "wall-breaker-evolution", "count": 2},
+        "royal-hogs": {"unit": "royal-hog", "count": 5},
+        "rascals": {"unit": ["rascal-boy", "rascal-girl"], "count": [1, 2]},
+    }
+
+    def __init__(self, registry: Optional[CardRegistry] = None):
+        self.registry = registry or CardRegistry()
+        if not self.registry.cards:
+            self.registry.load()
+        self._recent_resolutions: List[ResolvedEvent] = []
+
+    def resolve(self, evidence: EvidenceBundle) -> ResolvedEvent:
+        """Convert an EvidenceBundle into a ResolvedEvent."""
+        units = evidence.units
+        spells = evidence.spells
+
+        # No evidence -> UNKNOWN
+        if not units and not spells:
+            return ResolvedEvent(
+                card_key="UNKNOWN",
+                confidence=0.0,
+                evidence=evidence,
+                reasoning="no_units_or_spells",
+                is_ambiguous=True,
+                ambiguity_reason="empty_evidence",
+            )
+
+        # Spell-only evidence
+        if not units and spells:
+            if len(spells) == 1:
+                sp = spells[0]
+                return ResolvedEvent(
+                    card_key=sp.spell_name,
+                    confidence=sp.confidence * 0.7,
+                    evidence=evidence,
+                    reasoning=f"single_spell_heuristic:{sp.spell_name}",
+                )
+            else:
+                names = [s.spell_name for s in spells]
+                return ResolvedEvent(
+                    card_key="UNKNOWN",
+                    confidence=0.3,
+                    evidence=evidence,
+                    reasoning=f"multiple_spells:{names}",
+                    is_ambiguous=True,
+                    ambiguity_reason=f"multiple_spell_effects:{names}",
+                )
+
+        # Building detection
+        buildings = [u for u in units if u.is_building]
+        if buildings and not any(not u.is_building for u in units):
+            if len(buildings) == 1:
+                b = buildings[0]
+                cards = self.UNIT_TO_CARDS.get(b.unit_name, [b.unit_name])
+                return ResolvedEvent(
+                    card_key=cards[0],
+                    confidence=b.confidence * 0.8,
+                    evidence=evidence,
+                    reasoning=f"single_building:{b.unit_name}",
+                )
+
+        # Multi-unit inference
+        unit_counts: Dict[str, int] = {}
+        for u in units:
+            unit_counts[u.unit_name] = unit_counts.get(u.unit_name, 0) + 1
+
+        for card_key, spec in self.MULTI_UNIT_CARDS.items():
+            expected_unit = spec["unit"]
+            expected_count = spec["count"]
+            if isinstance(expected_unit, list):
+                # Mixed units (e.g., Goblin Gang)
+                match = all(
+                    unit_counts.get(u, 0) >= c
+                    for u, c in zip(expected_unit, expected_count)
+                )
+                if match:
+                    return ResolvedEvent(
+                        card_key=card_key,
+                        confidence=0.75,
+                        evidence=evidence,
+                        reasoning=f"multi_unit_match:{card_key}",
+                    )
+            else:
+                if unit_counts.get(expected_unit, 0) >= expected_count:
+                    return ResolvedEvent(
+                        card_key=card_key,
+                        confidence=0.75,
+                        evidence=evidence,
+                        reasoning=f"multi_unit_match:{card_key}",
+                    )
+
+        # Single-unit fallback
+        if len(units) == 1:
+            u = units[0]
+            cards = self.UNIT_TO_CARDS.get(u.unit_name, [u.unit_name])
+            if len(cards) == 1:
+                return ResolvedEvent(
+                    card_key=cards[0],
+                    confidence=u.confidence * 0.8,
+                    evidence=evidence,
+                    reasoning=f"single_unit:{u.unit_name}",
+                )
+            else:
+                return ResolvedEvent(
+                    card_key="UNKNOWN",
+                    confidence=u.confidence * 0.5,
+                    evidence=evidence,
+                    reasoning=f"ambiguous_unit:{u.unit_name}->{'/'.join(cards)}",
+                    is_ambiguous=True,
+                    ambiguity_reason=f"unit_maps_to_multiple_cards:{cards}",
+                )
+
+        # Multiple different units -> ambiguous
+        all_names = [u.unit_name for u in units]
+        return ResolvedEvent(
+            card_key="UNKNOWN",
+            confidence=0.3,
+            evidence=evidence,
+            reasoning=f"mixed_units:{all_names}",
+            is_ambiguous=True,
+            ambiguity_reason=f"multiple_different_units:{all_names}",
+        )
+
+    def deduplicate(self, event: ResolvedEvent, cooldown_seconds: float = 2.0) -> bool:
+        """Return True if this event is a duplicate of a recent one."""
+        import time
+        now = time.monotonic()
+        for recent in self._recent_resolutions:
+            if recent.card_key == event.card_key and \
+               (now - recent.evidence.timestamp) < cooldown_seconds:
+                return True
+        self._recent_resolutions.append(event)
+        # Prune old
+        self._recent_resolutions = [
+            r for r in self._recent_resolutions
+            if (now - r.evidence.timestamp) < cooldown_seconds * 3
+        ]
+        return False