Upload clashcr/utils/card_registry.py with huggingface_hub

clashcr/utils/card_registry.py

@@ -0,0 +1,285 @@
+"""Card registry synced from RoyaleAPI and Official Clash Royale API.
+
+Sources:
+- RoyaleAPI static data: https://royaleapi.github.io/cr-api-data/json/cards.json
+- Official API: https://api.clashroyale.com/v1/cards (requires token)
+- RoyaleAPI new-card feed: https://royaleapi.com/blog/tags/new-card?lang=en
+
+Usage:
+    registry = CardRegistry()
+    registry.sync()
+    print(registry.cards)
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+import requests
+import yaml
+
+
+ROYALEAPI_CARDS_URL = "https://royaleapi.github.io/cr-api-data/json/cards.json"
+OFFICIAL_CARDS_URL = "https://api.clashroyale.com/v1/cards"
+ROYALEAPI_NEW_CARD_FEED = "https://royaleapi.com/blog/tags/new-card?lang=en"
+
+
+@dataclass
+class Card:
+    id: str
+    name: str
+    sc_key: str
+    elixir_cost: int
+    card_type: str  # Troop, Spell, Building
+    rarity: str
+    is_evolution: bool = False
+    is_hero: bool = False
+    is_tower_troop: bool = False
+    is_champion: bool = False
+    icon_url: Optional[str] = None
+    image_url: Optional[str] = None
+    evolution_parent: Optional[str] = None  # base card name if this is an evolution
+    hero_parent: Optional[str] = None  # base card name if this is a hero variant
+
+
+@dataclass
+class SyncMetadata:
+    timestamp: str
+    royaleapi_url: str
+    official_api_url: str
+    new_card_feed_url: str
+    card_count: int
+    source_card_count_royaleapi: int
+    source_card_count_official: int
+    missing_from_official: List[str] = field(default_factory=list)
+    missing_from_royaleapi: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+
+
+class CardRegistry:
+    """Maintains an up-to-date card registry with sync capabilities."""
+
+    def __init__(self, cache_path: Optional[str] = None):
+        self.cache_path = Path(cache_path) if cache_path else Path.home() / ".clashcr" / "cards_registry.json"
+        self.cards: Dict[str, Card] = {}
+        self.metadata: Optional[SyncMetadata] = None
+        self._by_sc_key: Dict[str, Card] = {}
+        self._by_name_lower: Dict[str, Card] = {}
+
+    def _fetch_royaleapi(self) -> List[dict]:
+        resp = requests.get(ROYALEAPI_CARDS_URL, timeout=30)
+        resp.raise_for_status()
+        data = resp.json()
+        if isinstance(data, dict) and "items" in data:
+            return data["items"]
+        return data
+
+    def _fetch_official(self, api_token: Optional[str] = None) -> List[dict]:
+        token = api_token or os.environ.get("CLASH_ROYALE_API_TOKEN")
+        if not token:
+            return []
+        headers = {"Authorization": f"Bearer {token}"}
+        resp = requests.get(OFFICIAL_CARDS_URL, headers=headers, timeout=30)
+        resp.raise_for_status()
+        data = resp.json()
+        return data.get("items", [])
+
+    def _normalize_name(self, name: str) -> str:
+        return name.lower().replace(" ", "-").replace(".", "").replace("'", "")
+
+    def _classify_card(self, raw: dict) -> Card:
+        name = raw.get("name", "")
+        sc_key = raw.get("sc_key", "")
+        rarity = raw.get("rarity", "")
+        card_type = raw.get("type", "")
+        elixir = raw.get("elixir", -1)
+        # Handle string elixir
+        if isinstance(elixir, str):
+            try:
+                elixir = int(elixir)
+            except ValueError:
+                elixir = -1
+
+        is_champion = rarity.lower() == "champion"
+        is_hero = "hero" in name.lower() or "hero" in sc_key.lower()
+        is_evolution = raw.get("is_evolution", False) or "-evolution" in sc_key.lower() or "evolution" in name.lower()
+        is_tower_troop = "tower" in card_type.lower() or raw.get("is_tower_troop", False)
+
+        # Infer parent for evolutions / heroes
+        evolution_parent = None
+        hero_parent = None
+        if is_evolution and not is_hero:
+            # Strip evolution suffixes to guess parent
+            base = name.lower().replace(" evolution", "").replace("-evolution", "").replace(" evolved ", " ")
+            evolution_parent = base.strip()
+        if is_hero:
+            base = name.lower().replace("hero ", "").replace("hero-", "").strip()
+            hero_parent = base
+
+        return Card(
+            id=str(raw.get("id", "")),
+            name=name,
+            sc_key=sc_key,
+            elixir_cost=elixir,
+            card_type=card_type,
+            rarity=rarity,
+            is_evolution=is_evolution,
+            is_hero=is_hero,
+            is_tower_troop=is_tower_troop,
+            is_champion=is_champion,
+            icon_url=raw.get("icon_url") or raw.get("iconUrls", {}).get("medium"),
+            image_url=raw.get("image_url") or raw.get("iconUrls", {}).get("medium"),
+            evolution_parent=evolution_parent,
+            hero_parent=hero_parent,
+        )
+
+    def sync(self, api_token: Optional[str] = None, fail_on_stale: bool = True) -> SyncMetadata:
+        """Sync cards from RoyaleAPI and Official API.
+
+        Args:
+            api_token: Official Clash Royale API bearer token.
+            fail_on_stale: If True, raise RuntimeError if registry appears stale.
+        """
+        warnings: List[str] = []
+        royaleapi_cards = self._fetch_royaleapi()
+        official_cards = self._fetch_official(api_token)
+
+        # Merge: prefer official API data when available, fallback to RoyaleAPI
+        by_id: Dict[str, dict] = {}
+        for c in royaleapi_cards:
+            cid = str(c.get("id", c.get("name", "")))
+            by_id[cid] = c
+
+        official_by_id: Dict[str, dict] = {}
+        for c in official_cards:
+            cid = str(c.get("id", c.get("name", "")))
+            official_by_id[cid] = c
+            by_id[cid] = c  # official overrides
+
+        # Build Card objects
+        self.cards = {}
+        for cid, raw in by_id.items():
+            card = self._classify_card(raw)
+            self.cards[cid] = card
+            self._by_sc_key[card.sc_key.lower()] = card
+            self._by_name_lower[self._normalize_name(card.name)] = card
+
+        # Detect missing cards
+        missing_from_official = [c.get("name", cid) for cid, c in by_id.items() if cid not in official_by_id]
+        missing_from_royaleapi = [c.get("name", cid) for cid, c in official_by_id.items() if cid not in by_id]
+
+        # Staleness checks
+        expected_min_cards = 120  # As of 2024 baseline
+        if len(self.cards) < expected_min_cards:
+            msg = f"Card registry suspiciously small: {len(self.cards)} cards (expected >= {expected_min_cards})"
+            if fail_on_stale:
+                raise RuntimeError(msg)
+            warnings.append(msg)
+
+        # Check for known 2024-2025 cards that should exist
+        known_new_cards = [
+            "dagger-duchess", "little-prince", "royal-guardian",
+            "vines", "spirit-empress", "rune-giant", "berserker",
+            "boss-bandit", "goblinstein", "royal-chef",
+        ]
+        for cn in known_new_cards:
+            if cn not in self._by_name_lower:
+                warnings.append(f"Known new card '{cn}' missing from registry")
+
+        self.metadata = SyncMetadata(
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            royaleapi_url=ROYALEAPI_CARDS_URL,
+            official_api_url=OFFICIAL_CARDS_URL,
+            new_card_feed_url=ROYALEAPI_NEW_CARD_FEED,
+            card_count=len(self.cards),
+            source_card_count_royaleapi=len(royaleapi_cards),
+            source_card_count_official=len(official_cards),
+            missing_from_official=missing_from_official,
+            missing_from_royaleapi=missing_from_royaleapi,
+            warnings=warnings,
+        )
+
+        self.save()
+        return self.metadata
+
+    def save(self) -> None:
+        self.cache_path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "metadata": asdict(self.metadata) if self.metadata else {},
+            "cards": {cid: asdict(c) for cid, c in self.cards.items()},
+        }
+        with open(self.cache_path, "w", encoding="utf-8") as f:
+            json.dump(payload, f, indent=2, ensure_ascii=False)
+
+    def load(self) -> bool:
+        if not self.cache_path.exists():
+            return False
+        with open(self.cache_path, "r", encoding="utf-8") as f:
+            payload = json.load(f)
+        meta = payload.get("metadata", {})
+        self.metadata = SyncMetadata(**meta) if meta else None
+        self.cards = {}
+        for cid, cdict in payload.get("cards", {}).items():
+            self.cards[cid] = Card(**cdict)
+        self._rebuild_indices()
+        return True
+
+    def _rebuild_indices(self) -> None:
+        self._by_sc_key = {}
+        self._by_name_lower = {}
+        for card in self.cards.values():
+            self._by_sc_key[card.sc_key.lower()] = card
+            self._by_name_lower[self._normalize_name(card.name)] = card
+
+    def get_by_name(self, name: str) -> Optional[Card]:
+        return self._by_name_lower.get(self._normalize_name(name))
+
+    def get_by_sc_key(self, sc_key: str) -> Optional[Card]:
+        return self._by_sc_key.get(sc_key.lower())
+
+    def get_evolutions(self) -> List[Card]:
+        return [c for c in self.cards.values() if c.is_evolution]
+
+    def get_heroes(self) -> List[Card]:
+        return [c for c in self.cards.values() if c.is_hero]
+
+    def get_champions(self) -> List[Card]:
+        return [c for c in self.cards.values() if c.is_champion]
+
+    def get_tower_troops(self) -> List[Card]:
+        return [c for c in self.cards.values() if c.is_tower_troop]
+
+    def get_cost(self, name: str) -> int:
+        card = self.get_by_name(name)
+        return card.elixir_cost if card else -1
+
+    def list_names(self) -> List[str]:
+        return sorted([c.name for c in self.cards.values()])
+
+    def to_yaml(self, path: str) -> None:
+        data = {
+            "metadata": asdict(self.metadata) if self.metadata else {},
+            "cards": [asdict(c) for c in self.cards.values()],
+        }
+        with open(path, "w", encoding="utf-8") as f:
+            yaml.dump(data, f, sort_keys=False, allow_unicode=True)
+
+
+if __name__ == "__main__":
+    reg = CardRegistry()
+    try:
+        meta = reg.sync(fail_on_stale=False)
+        print(f"Synced {meta.card_count} cards at {meta.timestamp}")
+        for w in meta.warnings:
+            print(f"WARNING: {w}")
+    except Exception as e:
+        print(f"Sync failed: {e}")
+        if reg.load():
+            print(f"Loaded cached {len(reg.cards)} cards")
+        else:
+            print("No cache available")