Upload folder using huggingface_hub

README.md

@@ -1,13 +1,31 @@
----
-title: Ns Card Tracker
-emoji: 🚀
-colorFrom: purple
-colorTo: yellow
-sdk: gradio
-sdk_version: 6.14.0
-python_version: '3.13'
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: NS High-Value Card Tracker
+emoji: 🏆
+colorFrom: yellow
+colorTo: red
+sdk: gradio
+sdk_version: 5.29.0
+app_file: app.py
+python_version: 3.11.0
+pinned: false
+---
+
+# NationStates High-Value Trading Card Tracker
+
+Identifies elite-tier undervalued trading cards from the NationStates daily data dump.
+
+## Features
+- Downloads and parses daily card & nation XML dumps
+- Three valuation filters: Low ID, CTE (dead nations), Historical Names
+- Live market price checking with strict rate limiting (1.2s/request)
+- Undervalued card alerts with direct purchase links
+- SQLite storage for efficient re-queries
+
+## Compliance
+⚠️ This tool is **purely read-only**. No automated trades, buys, or bids are executed.
+All transactions must be completed manually by clicking the generated URL link.
+
+## Filters
+- **Low ID:** Legendary/Epic cards with ID ≤ 1000
+- **CTE:** Legendary/Epic cards whose nation no longer exists (Ceased to Exist)
+- **Historical Name:** Cards matching famous NationStates names/regions

app.py

@@ -0,0 +1,413 @@
+import gradio as gr
+import requests
+import sqlite3
+import time
+import os
+import xml.etree.ElementTree as ET
+import pandas as pd
+from datetime import datetime
+
+# ==========================================
+# CONFIGURATION
+# ==========================================
+USER_AGENT = "HighValueCardTracker (Operational puppet managed by thunderpuppetempires1)"
+API_BASE = "https://www.nationstates.net/cgi-bin/api.cgi"
+DB_PATH = "cards_tracker.db"
+RATE_LIMIT_SECONDS = 1.2
+SEASON = 4
+
+# Price thresholds — alert if ask is below these values
+THRESHOLDS = {
+    "legendary": 20.0,
+    "epic": 5.0,
+    "ultra-rare": 1.0,
+}
+
+# Historical/famous names in NationStates
+HISTORICAL_NAMES = [
+    "testlandia", "the pacific", "the north pacific", "the south pacific",
+    "the east pacific", "the west pacific", "the rejected realms",
+    "lazarus", "balder", "osiris", "the black hawks",
+    "the grey wardens", "10000 islands", "europe",
+    "max barry", "eluvatar", "sedgistan", "violet",
+    "the free nations region", "the communist bloc",
+    "nationstates", "maxtopia", "francos spain", "gatesville",
+    "the pacific army", "jennifer government", "the north pacific army",
+    "feeder", "raider", "defender",
+]
+
+# ==========================================
+# DATABASE
+# ==========================================
+
+def init_db():
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+    c.execute("""
+        CREATE TABLE IF NOT EXISTS cards (
+            card_id INTEGER,
+            season INTEGER,
+            name TEXT,
+            rarity TEXT,
+            region TEXT,
+            market_value REAL,
+            flag TEXT,
+            PRIMARY KEY (card_id, season)
+        )
+    """)
+    c.execute("""
+        CREATE TABLE IF NOT EXISTS targets (
+            card_id INTEGER,
+            season INTEGER,
+            name TEXT,
+            rarity TEXT,
+            flag_reason TEXT,
+            last_checked TEXT,
+            lowest_ask REAL,
+            card_url TEXT,
+            PRIMARY KEY (card_id, season)
+        )
+    """)
+    conn.commit()
+    conn.close()
+
+# ==========================================
+# API FUNCTIONS
+# ==========================================
+
+def fetch_card_info(card_id, season=SEASON):
+    """Fetch a single card's info from the API."""
+    url = f"{API_BASE}?q=card+info;cardid={card_id};season={season}"
+    headers = {"User-Agent": USER_AGENT}
+    try:
+        resp = requests.get(url, headers=headers, timeout=10)
+        if resp.status_code == 200:
+            root = ET.fromstring(resp.text)
+            card = root if root.tag == "CARD" else root.find("CARD")
+            if card is not None:
+                return {
+                    "card_id": int(card.findtext("CARDID", str(card_id))),
+                    "season": int(card.findtext("SEASON", str(season))),
+                    "name": card.findtext("NAME", "Unknown"),
+                    "rarity": card.findtext("CATEGORY", "unknown"),
+                    "region": card.findtext("REGION", ""),
+                    "market_value": float(card.findtext("MARKET_VALUE", "0") or "0"),
+                    "flag": card.findtext("FLAG", ""),
+                }
+        return None
+    except Exception:
+        return None
+
+
+def fetch_card_market(card_id, season=SEASON):
+    """Fetch a card's market data (asks/bids)."""
+    url = f"{API_BASE}?q=card+markets;cardid={card_id};season={season}"
+    headers = {"User-Agent": USER_AGENT}
+    try:
+        resp = requests.get(url, headers=headers, timeout=10)
+        if resp.status_code == 200:
+            root = ET.fromstring(resp.text)
+            markets = root.find(".//MARKETS")
+            if markets is None:
+                return None
+            lowest_ask = None
+            for market in markets.findall("MARKET"):
+                if market.findtext("TYPE", "") == "ask":
+                    price = float(market.findtext("PRICE", "0") or "0")
+                    if lowest_ask is None or price < lowest_ask:
+                        lowest_ask = price
+            return lowest_ask
+        return None
+    except Exception:
+        return None
+
+
+def check_nation_exists(nation_name):
+    """Check if a nation exists via the API."""
+    url = f"{API_BASE}?nation={nation_name.replace(' ', '_')}&q=name"
+    headers = {"User-Agent": USER_AGENT}
+    try:
+        resp = requests.get(url, headers=headers, timeout=10)
+        return resp.status_code == 200 and "<NAME>" in resp.text
+    except Exception:
+        return False
+
+
+# ==========================================
+# SCAN FUNCTIONS
+# ==========================================
+
+def scan_low_id_cards(max_id=1000, progress=None):
+    """Scan cards 1 to max_id for Legendary/Epic cards."""
+    init_db()
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+
+    found = []
+    for card_id in range(1, max_id + 1):
+        if progress:
+            progress((card_id) / max_id, desc=f"Scanning card {card_id}/{max_id}")
+
+        card = fetch_card_info(card_id, SEASON)
+        if card and card["rarity"] in ("legendary", "epic"):
+            c.execute("INSERT OR REPLACE INTO cards VALUES (?, ?, ?, ?, ?, ?, ?)",
+                      (card["card_id"], card["season"], card["name"], card["rarity"],
+                       card["region"], card["market_value"], card["flag"]))
+            conn.commit()
+
+            card_url = f"https://www.nationstates.net/page=deck/card={card_id}/season={SEASON}"
+            c.execute("INSERT OR REPLACE INTO targets VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                      (card["card_id"], card["season"], card["name"], card["rarity"],
+                       "Low ID (<=1000)", None, None, card_url))
+            conn.commit()
+            found.append(card)
+
+        time.sleep(RATE_LIMIT_SECONDS)
+
+    conn.close()
+    return found
+
+
+def scan_cte_cards(progress=None):
+    """Check existing targets for CTE (dead nation) status."""
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+    c.execute("SELECT card_id, season, name, rarity FROM cards WHERE rarity IN ('legendary', 'epic')")
+    cards = c.fetchall()
+
+    cte_found = []
+    for i, (card_id, season, name, rarity) in enumerate(cards):
+        if progress:
+            progress((i + 1) / len(cards), desc=f"Checking CTE: {name} ({i+1}/{len(cards)})")
+
+        exists = check_nation_exists(name)
+        if not exists:
+            card_url = f"https://www.nationstates.net/page=deck/card={card_id}/season={season}"
+            c.execute("""INSERT OR REPLACE INTO targets VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+                      (card_id, season, name, rarity, "CTE (Dead Nation)", None, None, card_url))
+            conn.commit()
+            cte_found.append({"card_id": card_id, "name": name, "rarity": rarity})
+
+        time.sleep(RATE_LIMIT_SECONDS)
+
+    conn.close()
+    return cte_found
+
+
+def scan_historical_cards(progress=None):
+    """Check cards in DB for historical name matches."""
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+    c.execute("SELECT card_id, season, name, rarity FROM cards")
+    cards = c.fetchall()
+
+    hist_found = []
+    for card_id, season, name, rarity in cards:
+        for hist_name in HISTORICAL_NAMES:
+            if hist_name in name.lower():
+                card_url = f"https://www.nationstates.net/page=deck/card={card_id}/season={season}"
+                c.execute("""INSERT OR REPLACE INTO targets VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+                          (card_id, season, name, rarity,
+                           f"Historical ({hist_name})", None, None, card_url))
+                conn.commit()
+                hist_found.append({"card_id": card_id, "name": name, "rarity": rarity, "match": hist_name})
+                break
+
+    conn.close()
+    return hist_found
+
+
+def check_target_prices(max_checks=50, progress=None):
+    """Check live market prices for flagged targets."""
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+    c.execute("""
+        SELECT card_id, season, name, rarity, flag_reason FROM targets
+        ORDER BY CASE rarity WHEN 'legendary' THEN 1 WHEN 'epic' THEN 2 ELSE 3 END
+        LIMIT ?
+    """, (max_checks,))
+    targets = c.fetchall()
+
+    alerts = []
+    for i, (card_id, season, name, rarity, flag_reason) in enumerate(targets):
+        if progress:
+            progress((i + 1) / len(targets), desc=f"Price check: {name} ({i+1}/{len(targets)})")
+
+        lowest_ask = fetch_card_market(card_id, season)
+        now = datetime.now().isoformat()
+
+        c.execute("UPDATE targets SET lowest_ask = ?, last_checked = ? WHERE card_id = ? AND season = ?",
+                  (lowest_ask, now, card_id, season))
+        conn.commit()
+
+        if lowest_ask is not None and lowest_ask > 0:
+            threshold = THRESHOLDS.get(rarity, 999)
+            if lowest_ask < threshold:
+                alerts.append({
+                    "name": name, "card_id": card_id, "rarity": rarity,
+                    "reason": flag_reason, "ask": lowest_ask, "threshold": threshold,
+                    "url": f"https://www.nationstates.net/page=deck/card={card_id}/season={season}"
+                })
+
+        time.sleep(RATE_LIMIT_SECONDS)
+
+    conn.close()
+    return alerts
+
+
+# ==========================================
+# GRADIO UI
+# ==========================================
+
+def run_low_id_scan(max_id, progress=gr.Progress()):
+    """UI handler for Low ID scan."""
+    init_db()
+    found = scan_low_id_cards(int(max_id), progress)
+
+    if found:
+        df = pd.DataFrame(found)
+        df["URL"] = df["card_id"].apply(lambda x: f"https://www.nationstates.net/page=deck/card={x}/season={SEASON}")
+        df = df[["card_id", "name", "rarity", "region", "market_value", "URL"]]
+        df.columns = ["Card ID", "Name", "Rarity", "Region", "Market Value", "URL"]
+        return f"✅ Found **{len(found)}** Legendary/Epic cards with ID ≤ {int(max_id)}", df
+    return "No Legendary/Epic cards found in that range.", pd.DataFrame()
+
+
+def run_cte_scan(progress=gr.Progress()):
+    """UI handler for CTE scan."""
+    cte = scan_cte_cards(progress)
+    if cte:
+        df = pd.DataFrame(cte)
+        return f"✅ Found **{len(cte)}** CTE (dead nation) cards", df
+    return "No CTE cards found (all nations still active).", pd.DataFrame()
+
+
+def run_historical_scan():
+    """UI handler for Historical name scan."""
+    hist = scan_historical_cards()
+    if hist:
+        df = pd.DataFrame(hist)
+        return f"✅ Found **{len(hist)}** cards matching historical names", df
+    return "No historical name matches found.", pd.DataFrame()
+
+
+def run_price_check(max_checks, progress=gr.Progress()):
+    """UI handler for price check."""
+    alerts = check_target_prices(int(max_checks), progress)
+
+    # Get all targets with prices
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+    c.execute("""
+        SELECT card_id, name, rarity, flag_reason, lowest_ask, last_checked, card_url
+        FROM targets WHERE last_checked IS NOT NULL
+        ORDER BY lowest_ask ASC
+    """)
+    rows = c.fetchall()
+    conn.close()
+
+    df = pd.DataFrame(rows, columns=["Card ID", "Name", "Rarity", "Flag Reason", "Ask Price", "Last Checked", "URL"])
+
+    alert_text = f"**Checked prices for targets.**\n\n"
+    if alerts:
+        alert_text += f"🚨 **{len(alerts)} UNDERVALUED CARDS!**\n\n"
+        for a in alerts:
+            alert_text += f"- **{a['name']}** (ID: {a['card_id']}) — {a['rarity'].upper()}\n"
+            alert_text += f"  Reason: {a['reason']} | Ask: **{a['ask']:.2f}** (threshold: {a['threshold']})\n"
+            alert_text += f"  [🛒 Buy Link]({a['url']})\n\n"
+    else:
+        alert_text += "✅ No undervalued cards below threshold."
+
+    return alert_text, df
+
+
+def get_all_targets():
+    """Get all current targets from DB."""
+    init_db()
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+    c.execute("""
+        SELECT card_id, name, rarity, flag_reason, lowest_ask, last_checked, card_url
+        FROM targets
+        ORDER BY CASE rarity WHEN 'legendary' THEN 1 WHEN 'epic' THEN 2 ELSE 3 END, card_id
+    """)
+    rows = c.fetchall()
+    conn.close()
+
+    if rows:
+        return pd.DataFrame(rows, columns=["Card ID", "Name", "Rarity", "Flag Reason", "Ask Price", "Last Checked", "URL"])
+    return pd.DataFrame(columns=["Card ID", "Name", "Rarity", "Flag Reason", "Ask Price", "Last Checked", "URL"])
+
+
+# ==========================================
+# BUILD APP
+# ==========================================
+
+with gr.Blocks(title="NS High-Value Card Tracker", theme=gr.themes.Soft()) as app:
+    gr.Markdown("# 🏆 NationStates High-Value Trading Card Tracker")
+    gr.Markdown("Identifies elite-tier undervalued cards via the NationStates API. **No automated trades** — manual purchase only via links.")
+    gr.Markdown(f"*Season {SEASON} | Rate limit: {RATE_LIMIT_SECONDS}s/request | Compliance: Read-only*")
+
+    with gr.Tab("🔍 Low ID Scan"):
+        gr.Markdown("Scan cards by ID range to find Legendary/Epic cards with low IDs (rare & valuable).")
+        max_id_input = gr.Number(label="Scan cards 1 to:", value=100, minimum=1, maximum=5000, precision=0)
+        gr.Markdown("*⏱️ Estimated time: ~1.2 seconds per card ID*")
+        scan_btn = gr.Button("🔍 Start Low ID Scan", variant="primary")
+        scan_status = gr.Markdown("")
+        scan_results = gr.Dataframe(label="Found Cards", interactive=False)
+        scan_btn.click(fn=run_low_id_scan, inputs=[max_id_input], outputs=[scan_status, scan_results])
+
+    with gr.Tab("💀 CTE Scan"):
+        gr.Markdown("Check if flagged cards belong to dead/deleted nations (Ceased to Exist). These are scarcer and more valuable.")
+        gr.Markdown("*Requires Low ID scan to be run first to populate the card database.*")
+        cte_btn = gr.Button("💀 Check for CTE Cards", variant="primary")
+        cte_status = gr.Markdown("")
+        cte_results = gr.Dataframe(label="CTE Cards", interactive=False)
+        cte_btn.click(fn=run_cte_scan, outputs=[cte_status, cte_results])
+
+    with gr.Tab("📜 Historical Names"):
+        gr.Markdown("Find cards matching famous NationStates names (regions, moderators, historic players).")
+        gr.Markdown(f"*Monitoring {len(HISTORICAL_NAMES)} names: {', '.join(HISTORICAL_NAMES[:10])}...*")
+        hist_btn = gr.Button("📜 Scan Historical Names", variant="primary")
+        hist_status = gr.Markdown("")
+        hist_results = gr.Dataframe(label="Historical Cards", interactive=False)
+        hist_btn.click(fn=run_historical_scan, outputs=[hist_status, hist_results])
+
+    with gr.Tab("💰 Price Check"):
+        gr.Markdown("Check live market prices for all flagged targets. Alerts if price is below threshold.")
+        gr.Markdown(f"*Thresholds: Legendary < {THRESHOLDS['legendary']}, Epic < {THRESHOLDS['epic']}, Ultra-Rare < {THRESHOLDS['ultra-rare']}*")
+        max_price_input = gr.Number(label="Max cards to check:", value=30, minimum=1, maximum=200, precision=0)
+        price_btn = gr.Button("💰 Check Live Prices", variant="primary")
+        price_alerts = gr.Markdown("")
+        price_table = gr.Dataframe(label="Targets with Prices", interactive=False)
+        price_btn.click(fn=run_price_check, inputs=[max_price_input], outputs=[price_alerts, price_table])
+
+    with gr.Tab("📋 All Targets"):
+        gr.Markdown("View all currently flagged high-value targets.")
+        refresh_btn = gr.Button("🔄 Refresh")
+        targets_table = gr.Dataframe(label="All Targets", interactive=False)
+        refresh_btn.click(fn=get_all_targets, outputs=[targets_table])
+
+    with gr.Tab("⚙️ Config"):
+        gr.Markdown(f"""
+### Settings
+- **Season:** {SEASON}
+- **Rate Limit:** {RATE_LIMIT_SECONDS}s between API requests
+- **User-Agent:** `{USER_AGENT}`
+
+### Price Alert Thresholds
+| Rarity | Alert if Ask Below |
+|---|---|
+| Legendary | {THRESHOLDS['legendary']} |
+| Epic | {THRESHOLDS['epic']} |
+| Ultra-Rare | {THRESHOLDS['ultra-rare']} |
+
+### Historical Names ({len(HISTORICAL_NAMES)} total)
+{', '.join(HISTORICAL_NAMES)}
+
+### Compliance
+⚠️ This tool is **read-only**. No automated trades, buys, or bids are executed.
+All purchases must be completed manually via the generated URL links.
+        """)
+
+app.launch()

requirements.txt

@@ -0,0 +1,3 @@
+gradio==5.29.0
+requests
+pandas

tracker.py

@@ -0,0 +1,591 @@
+"""
+NationStates High-Value Trading Card Tracker
+=============================================
+Fully local script that:
+1. Downloads daily card & nation XML dumps
+2. Parses and stores in SQLite
+3. Flags high-value targets (Low ID, CTE, Historical Names)
+4. Checks live market prices (rate limited)
+5. Generates an HTML dashboard with results
+
+COMPLIANCE: This script NEVER executes automated trades.
+All purchases are manual via generated URL links.
+
+Usage: python tracker.py
+"""
+
+import requests
+import gzip
+import sqlite3
+import time
+import os
+import sys
+import xml.etree.ElementTree as ET
+from io import BytesIO
+from datetime import datetime
+
+# ==========================================
+# CONFIGURATION
+# ==========================================
+USER_AGENT = "HighValueCardTracker (Operational puppet managed by thunderpuppetempires1)"
+CARDS_DUMP_URL = "https://www.nationstates.net/pages/cards_s3.xml.gz"
+NATIONS_DUMP_URL = "https://www.nationstates.net/pages/nations.xml.gz"
+API_BASE = "https://www.nationstates.net/cgi-bin/api.cgi"
+DB_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "cards.db")
+DASHBOARD_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "dashboard.html")
+RATE_LIMIT_SECONDS = 1.2
+SEASON = 3
+MAX_PRICE_CHECKS = 50  # how many targets to check live prices for
+
+# Price thresholds — alert if ask is below these values
+THRESHOLDS = {
+    "legendary": 20.0,
+    "epic": 5.0,
+    "ultra-rare": 1.0,
+}
+
+# Historical/famous names in NationStates
+HISTORICAL_NAMES = [
+    "the pacific", "the north pacific", "the south pacific",
+    "the east pacific", "the west pacific", "the rejected realms",
+    "lazarus", "balder", "osiris", "the black hawks",
+    "the grey wardens", "10000 islands", "europe",
+    "max barry", "eluvatar", "sedgistan", "violet",
+    "the free nations region", "the communist bloc",
+    "nationstates", "testlandia", "maxtopia",
+    "francos spain", "gatesville", "the pacific army",
+    "jennifer government", "the north pacific army",
+    "feeder", "raider", "defender",
+]
+
+
+# ==========================================
+# DATABASE
+# ==========================================
+
+def init_db():
+    """Initialize SQLite database with schema."""
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+    c.execute("""
+        CREATE TABLE IF NOT EXISTS cards (
+            card_id INTEGER,
+            name TEXT,
+            rarity TEXT,
+            region TEXT,
+            season INTEGER,
+            PRIMARY KEY (card_id, season)
+        )
+    """)
+    c.execute("""
+        CREATE TABLE IF NOT EXISTS active_nations (
+            name TEXT PRIMARY KEY
+        )
+    """)
+    c.execute("""
+        CREATE TABLE IF NOT EXISTS targets (
+            card_id INTEGER,
+            season INTEGER,
+            name TEXT,
+            rarity TEXT,
+            flag_reason TEXT,
+            last_checked TEXT,
+            last_ask REAL,
+            card_url TEXT,
+            PRIMARY KEY (card_id, season)
+        )
+    """)
+    conn.commit()
+    conn.close()
+    print("[DB] Database initialized.")
+
+
+# ==========================================
+# DATA INGESTION
+# ==========================================
+
+def download_and_parse_cards():
+    """Parse the cards XML dump from local file."""
+    local_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), "cards_s3.xml.gz")
+
+    if not os.path.exists(local_file):
+        print(f"[ERROR] Cards dump not found at: {local_file}")
+        print(f"  Please download it manually from: {CARDS_DUMP_URL}")
+        print(f"  Save it as: {local_file}")
+        sys.exit(1)
+
+    print(f"[INGEST] Reading local cards dump: {local_file}")
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+    c.execute("DELETE FROM cards")
+    conn.commit()
+
+    with gzip.open(local_file, "rb") as f:
+        raw_data = f.read()
+
+    print("[INGEST] Parsing cards XML...")
+    count = 0
+    batch = []
+    context = ET.iterparse(BytesIO(raw_data), events=("end",))
+
+    for event, elem in context:
+        if elem.tag == "CARD":
+            card_id = elem.findtext("ID", "")
+            name = elem.findtext("NAME", "")
+            rarity = elem.findtext("CATEGORY", "")
+            region = elem.findtext("REGION", "")
+            season_val = elem.findtext("SEASON", str(SEASON))
+
+            if card_id and rarity:
+                batch.append((int(card_id), name.lower(), rarity.lower(), region.lower() if region else "", int(season_val)))
+                count += 1
+
+            if len(batch) >= 5000:
+                c.executemany("INSERT OR REPLACE INTO cards VALUES (?, ?, ?, ?, ?)", batch)
+                conn.commit()
+                batch = []
+                if count % 50000 == 0:
+                    print(f"  ... {count:,} cards parsed")
+
+            elem.clear()
+
+    if batch:
+        c.executemany("INSERT OR REPLACE INTO cards VALUES (?, ?, ?, ?, ?)", batch)
+        conn.commit()
+
+    conn.close()
+    print(f"[INGEST] Cards done: {count:,} cards stored.")
+    return count
+
+
+def download_and_parse_nations():
+    """Download or read the active nations XML dump."""
+    local_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), "nations.xml.gz")
+
+    # Try downloading first (this works from residential IPs)
+    if not os.path.exists(local_file):
+        print("[INGEST] Downloading nations dump...")
+        headers = {"User-Agent": USER_AGENT}
+        try:
+            resp = requests.get(NATIONS_DUMP_URL, headers=headers, timeout=300)
+            resp.raise_for_status()
+            with open(local_file, "wb") as f:
+                f.write(resp.content)
+            print(f"[INGEST] Downloaded nations dump ({len(resp.content) / 1024 / 1024:.1f} MB)")
+        except Exception as e:
+            print(f"[ERROR] Nations dump not found and download failed: {e}")
+            print(f"  Please download manually from: {NATIONS_DUMP_URL}")
+            print(f"  Save as: {local_file}")
+            sys.exit(1)
+    else:
+        print(f"[INGEST] Using local nations dump: {local_file}")
+
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+    c.execute("DELETE FROM active_nations")
+    conn.commit()
+
+    with gzip.open(local_file, "rb") as f:
+        raw_data = f.read()
+
+    print("[INGEST] Parsing nations XML...")
+    count = 0
+    batch = []
+    context = ET.iterparse(BytesIO(raw_data), events=("end",))
+
+    for event, elem in context:
+        if elem.tag == "NATION":
+            name = elem.findtext("NAME", "")
+            if name:
+                batch.append((name.lower(),))
+                count += 1
+
+            if len(batch) >= 5000:
+                c.executemany("INSERT OR REPLACE INTO active_nations VALUES (?)", batch)
+                conn.commit()
+                batch = []
+                if count % 50000 == 0:
+                    print(f"  ... {count:,} nations parsed")
+
+            elem.clear()
+
+    if batch:
+        c.executemany("INSERT OR REPLACE INTO active_nations VALUES (?)", batch)
+        conn.commit()
+
+    conn.close()
+    print(f"[INGEST] Nations done: {count:,} active nations stored.")
+    return count
+
+
+# ==========================================
+# VALUATION ENGINE
+# ==========================================
+
+def run_valuation():
+    """Apply all three filters and populate targets table."""
+    print("[VALUATION] Running filters...")
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+    c.execute("DELETE FROM targets")
+    conn.commit()
+
+    targets = []
+
+    # Filter 1: Low ID (Legendary/Epic with ID <= 1000)
+    c.execute("""
+        SELECT card_id, name, rarity, season FROM cards
+        WHERE rarity IN ('legendary', 'epic') AND card_id <= 1000
+    """)
+    for row in c.fetchall():
+        card_id, name, rarity, season = row
+        url = f"https://www.nationstates.net/page=deck/card={card_id}/season={season}"
+        targets.append((card_id, season, name, rarity, "Low ID (<=1000)", None, None, url))
+    print(f"  Filter 1 (Low ID): {len(targets)} cards")
+
+    # Filter 2: CTE (Legendary/Epic whose nation is NOT in active nations)
+    cte_count = 0
+    c.execute("""
+        SELECT c.card_id, c.name, c.rarity, c.season FROM cards c
+        LEFT JOIN active_nations a ON c.name = a.name
+        WHERE c.rarity IN ('legendary', 'epic') AND a.name IS NULL
+    """)
+    for row in c.fetchall():
+        card_id, name, rarity, season = row
+        url = f"https://www.nationstates.net/page=deck/card={card_id}/season={season}"
+        if not any(t[0] == card_id and t[1] == season for t in targets):
+            targets.append((card_id, season, name, rarity, "CTE (Dead Nation)", None, None, url))
+            cte_count += 1
+    print(f"  Filter 2 (CTE): {cte_count} cards")
+
+    # Filter 3: Historical Name match
+    hist_count = 0
+    c.execute("""
+        SELECT card_id, name, rarity, season FROM cards
+        WHERE rarity IN ('legendary', 'epic', 'ultra-rare')
+    """)
+    for row in c.fetchall():
+        card_id, name, rarity, season = row
+        for hist_name in HISTORICAL_NAMES:
+            if hist_name in name:
+                url = f"https://www.nationstates.net/page=deck/card={card_id}/season={season}"
+                if not any(t[0] == card_id and t[1] == season for t in targets):
+                    targets.append((card_id, season, name, rarity, f"Historical ({hist_name})", None, None, url))
+                    hist_count += 1
+                break
+    print(f"  Filter 3 (Historical): {hist_count} cards")
+
+    # Insert all targets
+    c.executemany("INSERT OR REPLACE INTO targets VALUES (?, ?, ?, ?, ?, ?, ?, ?)", targets)
+    conn.commit()
+    conn.close()
+
+    print(f"[VALUATION] Total targets flagged: {len(targets)}")
+    return len(targets)
+
+
+# ==========================================
+# LIVE PRICE CHECK
+# ==========================================
+
+def check_live_prices():
+    """Query live API for target cards and update prices."""
+    print(f"[MARKET] Checking live prices for top {MAX_PRICE_CHECKS} targets...")
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+
+    # Prioritize: legendary first, then epic, then by card_id
+    c.execute("""
+        SELECT card_id, season, name, rarity, flag_reason FROM targets
+        ORDER BY
+            CASE rarity
+                WHEN 'legendary' THEN 1
+                WHEN 'epic' THEN 2
+                WHEN 'ultra-rare' THEN 3
+                ELSE 4
+            END,
+            card_id ASC
+        LIMIT ?
+    """, (MAX_PRICE_CHECKS,))
+    targets = c.fetchall()
+
+    headers = {"User-Agent": USER_AGENT}
+    updated = 0
+    alerts = []
+
+    for i, (card_id, season, name, rarity, flag_reason) in enumerate(targets):
+        print(f"  [{i+1}/{len(targets)}] Checking {name} (ID:{card_id}, {rarity})...", end=" ")
+
+        url = f"{API_BASE}?q=card+markets;cardid={card_id};season={season}"
+        try:
+            resp = requests.get(url, headers=headers, timeout=10)
+            if resp.status_code == 200:
+                lowest_ask = parse_lowest_ask(resp.text)
+                now = datetime.now().isoformat()
+
+                c.execute("""
+                    UPDATE targets SET last_ask = ?, last_checked = ?
+                    WHERE card_id = ? AND season = ?
+                """, (lowest_ask, now, card_id, season))
+                conn.commit()
+                updated += 1
+
+                if lowest_ask is not None:
+                    print(f"Ask: {lowest_ask:.2f}")
+                    threshold = THRESHOLDS.get(rarity, 999)
+                    if lowest_ask > 0 and lowest_ask < threshold:
+                        card_url = f"https://www.nationstates.net/page=deck/card={card_id}/season={season}"
+                        alerts.append({
+                            "name": name,
+                            "card_id": card_id,
+                            "rarity": rarity,
+                            "reason": flag_reason,
+                            "ask": lowest_ask,
+                            "threshold": threshold,
+                            "url": card_url
+                        })
+                else:
+                    print("No asks")
+            else:
+                print(f"HTTP {resp.status_code}")
+        except Exception as e:
+            print(f"Error: {e}")
+
+        time.sleep(RATE_LIMIT_SECONDS)
+
+    conn.close()
+
+    print(f"\n[MARKET] Checked {updated} cards.")
+    if alerts:
+        print(f"🚨 {len(alerts)} UNDERVALUED CARDS DETECTED!")
+        for a in alerts:
+            print(f"  - {a['name']} (ID:{a['card_id']}) {a['rarity'].upper()} — Ask: {a['ask']:.2f} < {a['threshold']}")
+            print(f"    {a['url']}")
+    else:
+        print("  No undervalued cards found below threshold.")
+
+    return alerts
+
+
+def parse_lowest_ask(xml_text):
+    """Extract the lowest ask price from market XML."""
+    try:
+        root = ET.fromstring(xml_text)
+        markets = root.find(".//MARKETS")
+        if markets is None:
+            return None
+
+        lowest = None
+        for market in markets.findall("MARKET"):
+            market_type = market.findtext("TYPE", "")
+            if market_type == "ask":
+                price = float(market.findtext("PRICE", "0") or "0")
+                if lowest is None or price < lowest:
+                    lowest = price
+
+        return lowest
+    except (ET.ParseError, ValueError):
+        return None
+
+
+# ==========================================
+# HTML DASHBOARD GENERATOR
+# ==========================================
+
+def generate_dashboard(alerts):
+    """Generate a self-contained HTML dashboard."""
+    print("[DASHBOARD] Generating HTML report...")
+
+    conn = sqlite3.connect(DB_PATH)
+    c = conn.cursor()
+
+    # Get all targets with prices
+    c.execute("""
+        SELECT card_id, name, rarity, flag_reason, last_ask, last_checked, card_url
+        FROM targets
+        ORDER BY
+            CASE rarity
+                WHEN 'legendary' THEN 1
+                WHEN 'epic' THEN 2
+                WHEN 'ultra-rare' THEN 3
+                ELSE 4
+            END,
+            last_ask ASC
+    """)
+    all_targets = c.fetchall()
+
+    # Stats
+    c.execute("SELECT COUNT(*) FROM cards")
+    total_cards = c.fetchone()[0]
+    c.execute("SELECT COUNT(*) FROM active_nations")
+    total_nations = c.fetchone()[0]
+    c.execute("SELECT COUNT(*) FROM targets")
+    total_targets = c.fetchone()[0]
+
+    conn.close()
+
+    # Build HTML
+    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    rarity_colors = {
+        "legendary": "#FFD700",
+        "epic": "#FF9800",
+        "ultra-rare": "#9C27B0",
+        "rare": "#2196F3",
+        "uncommon": "#4CAF50",
+        "common": "#8B8B8B",
+    }
+
+    # Alerts section
+    alerts_html = ""
+    if alerts:
+        alerts_html = f'<div class="alert-box"><h2>🚨 {len(alerts)} Undervalued Cards Detected!</h2>'
+        for a in alerts:
+            color = rarity_colors.get(a["rarity"], "#fff")
+            alerts_html += f'''
+            <div class="alert-card">
+                <span class="rarity" style="color:{color}">{a["rarity"].upper()}</span>
+                <strong>{a["name"]}</strong> (ID: {a["card_id"]})
+                <br>Reason: {a["reason"]}
+                <br>Ask: <strong>{a["ask"]:.2f}</strong> (threshold: {a["threshold"]})
+                <br><a href="{a["url"]}" target="_blank" class="buy-link">🛒 View / Buy</a>
+            </div>'''
+        alerts_html += "</div>"
+    else:
+        alerts_html = '<div class="no-alert">✅ No undervalued cards below threshold at this time.</div>'
+
+    # Targets table
+    table_rows = ""
+    for row in all_targets:
+        card_id, name, rarity, flag_reason, last_ask, last_checked, card_url = row
+        color = rarity_colors.get(rarity, "#fff")
+        ask_display = f"{last_ask:.2f}" if last_ask is not None else "—"
+        checked_display = last_checked[:16] if last_checked else "Not checked"
+        table_rows += f"""
+        <tr>
+            <td>{card_id}</td>
+            <td>{name}</td>
+            <td style="color:{color}; font-weight:bold">{rarity}</td>
+            <td>{flag_reason}</td>
+            <td>{ask_display}</td>
+            <td>{checked_display}</td>
+            <td><a href="{card_url}" target="_blank">View</a></td>
+        </tr>"""
+
+    html = f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>NS High-Value Card Tracker</title>
+    <style>
+        * {{ margin: 0; padding: 0; box-sizing: border-box; }}
+        body {{ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: #1a1a2e; color: #eee; padding: 20px; }}
+        h1 {{ color: #FFD700; margin-bottom: 5px; }}
+        .subtitle {{ color: #aaa; margin-bottom: 20px; }}
+        .stats {{ display: flex; gap: 20px; margin-bottom: 20px; flex-wrap: wrap; }}
+        .stat-box {{ background: #16213e; padding: 15px 25px; border-radius: 8px; text-align: center; }}
+        .stat-box .number {{ font-size: 24px; font-weight: bold; color: #4fc3f7; }}
+        .stat-box .label {{ font-size: 12px; color: #aaa; }}
+        .alert-box {{ background: #2d1b00; border: 2px solid #FF9800; border-radius: 8px; padding: 15px; margin-bottom: 20px; }}
+        .alert-card {{ background: #1a1a2e; padding: 10px; margin: 8px 0; border-radius: 6px; border-left: 4px solid #FF9800; }}
+        .no-alert {{ background: #0d2818; border: 2px solid #4CAF50; border-radius: 8px; padding: 15px; margin-bottom: 20px; }}
+        .buy-link {{ color: #4fc3f7; text-decoration: none; font-weight: bold; }}
+        .buy-link:hover {{ text-decoration: underline; }}
+        .rarity {{ font-size: 11px; text-transform: uppercase; letter-spacing: 1px; }}
+        table {{ width: 100%; border-collapse: collapse; margin-top: 10px; }}
+        th {{ background: #16213e; padding: 10px; text-align: left; font-size: 12px; color: #aaa; text-transform: uppercase; }}
+        td {{ padding: 8px 10px; border-bottom: 1px solid #2a2a4a; font-size: 13px; }}
+        tr:hover {{ background: #16213e; }}
+        a {{ color: #4fc3f7; }}
+        .compliance {{ background: #1a1a2e; border: 1px solid #444; border-radius: 6px; padding: 10px; margin-top: 20px; font-size: 11px; color: #888; }}
+    </style>
+</head>
+<body>
+    <h1>🏆 NationStates High-Value Card Tracker</h1>
+    <p class="subtitle">Generated: {now} | Season {SEASON} | Compliance: Read-only, no automated trades</p>
+
+    <div class="stats">
+        <div class="stat-box"><div class="number">{total_cards:,}</div><div class="label">Cards in DB</div></div>
+        <div class="stat-box"><div class="number">{total_nations:,}</div><div class="label">Active Nations</div></div>
+        <div class="stat-box"><div class="number">{total_targets}</div><div class="label">Targets Flagged</div></div>
+        <div class="stat-box"><div class="number">{len(alerts)}</div><div class="label">Undervalued</div></div>
+    </div>
+
+    {alerts_html}
+
+    <h2>📋 All Flagged Targets</h2>
+    <table>
+        <thead>
+            <tr><th>ID</th><th>Name</th><th>Rarity</th><th>Flag Reason</th><th>Ask</th><th>Checked</th><th>Link</th></tr>
+        </thead>
+        <tbody>
+            {table_rows}
+        </tbody>
+    </table>
+
+    <div class="compliance">
+        ⚠️ This tool is purely a data analysis and notification tool. No automated market trades, buys, or bids are executed.
+        All transactions must be completed manually by clicking the URL links above.
+        Rate limit: {RATE_LIMIT_SECONDS}s between API requests. User-Agent: {USER_AGENT}
+    </div>
+</body>
+</html>"""
+
+    with open(DASHBOARD_PATH, "w", encoding="utf-8") as f:
+        f.write(html)
+
+    print(f"[DASHBOARD] Saved to: {DASHBOARD_PATH}")
+
+
+# ==========================================
+# MAIN
+# ==========================================
+
+def main():
+    print("=" * 60)
+    print("  NationStates High-Value Trading Card Tracker")
+    print("  Compliance: READ-ONLY — No automated trades")
+    print("=" * 60)
+    print()
+
+    start_time = time.time()
+
+    # Step 1: Initialize DB
+    init_db()
+
+    # Step 2: Download and parse dumps
+    print()
+    try:
+        download_and_parse_cards()
+    except Exception as e:
+        print(f"[ERROR] Failed to download cards: {e}")
+        sys.exit(1)
+
+    print()
+    try:
+        download_and_parse_nations()
+    except Exception as e:
+        print(f"[ERROR] Failed to download nations: {e}")
+        sys.exit(1)
+
+    # Step 3: Run valuation
+    print()
+    run_valuation()
+
+    # Step 4: Check live prices
+    print()
+    alerts = check_live_prices()
+
+    # Step 5: Generate dashboard
+    print()
+    generate_dashboard(alerts)
+
+    elapsed = time.time() - start_time
+    print(f"\n{'=' * 60}")
+    print(f"  Done in {elapsed:.1f}s. Open dashboard.html to view results.")
+    print(f"{'=' * 60}")
+
+
+if __name__ == "__main__":
+    main()