aedis_world_gen.py

# aedis_world_gen.py
"""
Procedural fill for the Public Transparency Portal.

The hand-authored jobs in aedis_public_world.JOBS (with the real, carefully
designed scams) stay the centerpiece for WA / OR / ID. This module fills in
ALL 50 states with organic-looking filler jobs so that, in a demo, clicking
any state tab shows a populated ledger - completed, underway, a few flagged.

Determinism: we seed the RNG per-state so the same state always generates the
same jobs across runs/processes. That keeps the portal stable (a job's detail
page matches what was listed) without persisting anything.

The global/world tab uses COUNTRIES - a flat roster of nations with summary
numbers, no per-state drill-down (per the design: the world view just shows
every country, blockchain-style).
"""
import random

# All 50 states + DC, with a representative city per state for filler jobs.
STATES = {
    "AL": ("Alabama", "Birmingham"), "AK": ("Alaska", "Anchorage"),
    "AZ": ("Arizona", "Phoenix"), "AR": ("Arkansas", "Little Rock"),
    "CA": ("California", "Sacramento"), "CO": ("Colorado", "Denver"),
    "CT": ("Connecticut", "Hartford"), "DE": ("Delaware", "Wilmington"),
    "FL": ("Florida", "Orlando"), "GA": ("Georgia", "Atlanta"),
    "HI": ("Hawaii", "Honolulu"), "ID": ("Idaho", "Boise"),
    "IL": ("Illinois", "Chicago"), "IN": ("Indiana", "Indianapolis"),
    "IA": ("Iowa", "Des Moines"), "KS": ("Kansas", "Wichita"),
    "KY": ("Kentucky", "Louisville"), "LA": ("Louisiana", "New Orleans"),
    "ME": ("Maine", "Portland"), "MD": ("Maryland", "Baltimore"),
    "MA": ("Massachusetts", "Boston"), "MI": ("Michigan", "Detroit"),
    "MN": ("Minnesota", "Minneapolis"), "MS": ("Mississippi", "Jackson"),
    "MO": ("Missouri", "St. Louis"), "MT": ("Montana", "Billings"),
    "NE": ("Nebraska", "Omaha"), "NV": ("Nevada", "Las Vegas"),
    "NH": ("New Hampshire", "Manchester"), "NJ": ("New Jersey", "Newark"),
    "NM": ("New Mexico", "Albuquerque"), "NY": ("New York", "Albany"),
    "NC": ("North Carolina", "Charlotte"), "ND": ("North Dakota", "Fargo"),
    "OH": ("Ohio", "Columbus"), "OK": ("Oklahoma", "Oklahoma City"),
    "OR": ("Oregon", "Portland"), "PA": ("Pennsylvania", "Philadelphia"),
    "RI": ("Rhode Island", "Providence"), "SC": ("South Carolina", "Columbia"),
    "SD": ("South Dakota", "Sioux Falls"), "TN": ("Tennessee", "Nashville"),
    "TX": ("Texas", "Austin"), "UT": ("Utah", "Salt Lake City"),
    "VT": ("Vermont", "Burlington"), "VA": ("Virginia", "Richmond"),
    "WA": ("Washington", "Seattle"), "WV": ("West Virginia", "Charleston"),
    "WI": ("Wisconsin", "Milwaukee"), "WY": ("Wyoming", "Cheyenne"),
    "DC": ("District of Columbia", "Washington"),
}

CATEGORIES = [
    "Clinic Construction", "Road Construction", "Power Grid",
    "Medical Research", "Housing", "Water Treatment", "School Construction",
    "Bridge Repair", "Public Transit", "Broadband Expansion",
]

# Real company name pools by job category.
# Each entry is a real, publicly verifiable organization active in the
# relevant sector. Used by _company_name() to produce realistic bidder
# names for every state's job ledger in the Transparency Portal.
_REAL_COMPANIES = {
    "Clinic Construction": [
        "Mortenson Construction", "Turner Construction Company",
        "McCarthy Building Companies", "Skanska USA Building",
        "HDR Inc.", "HKS Inc.", "Perkins & Will",
        "PCL Construction", "Hensel Phelps", "Gilbane Building Company",
        "Whiting-Turner Contracting", "DPR Construction",
        "Swinerton Builders", "Clark Construction Group", "Barton Malow",
        "Brasfield & Gorrie", "JE Dunn Construction", "Boldt Company",
    ],
    "Road Construction": [
        "Kiewit Infrastructure", "Fluor Corporation", "AECOM",
        "Bechtel Group", "PCL Civil Constructors", "Parsons Corporation",
        "Balfour Beatty US", "WSP USA", "Granite Construction",
        "Walsh Construction", "The Lane Construction Corporation",
        "Flatiron Construction", "Dragados USA", "Garney Construction",
        "Guy F. Atkinson Construction", "Ames Construction",
        "Sundt Construction", "FlatironDragados",
    ],
    "Power Grid": [
        "Quanta Services", "MYR Group Inc.", "Potelco Inc.",
        "Burns & McDonnell", "Black & Veatch", "Primoris Services",
        "MasTec Inc.", "Willbros Group", "AECOM Technical Services",
        "Jacobs Engineering Group", "Olson Electric Company",
        "Pike Electric", "Power Engineers Inc.", "WESCO International",
        "NextEra Energy Resources", "Eversource Energy Services",
        "Grid One Solutions", "Irby Construction",
    ],
    "Medical Research": [
        "Battelle Memorial Institute", "IQVIA Holdings",
        "Charles River Laboratories", "Leidos Holdings",
        "SAIC (Science Applications International)", "Syneos Health",
        "Parexel International", "ICON plc", "PRA Health Sciences",
        "Covance (Labcorp Drug Development)", "Quintiles IMS",
        "PPD (Thermo Fisher Scientific)", "Medpace Holdings",
        "Worldwide Clinical Trials", "Premier Research",
    ],
    "Housing": [
        "D.R. Horton", "Lennar Corporation", "PulteGroup",
        "NVR Inc.", "Taylor Morrison", "Meritage Homes",
        "Smith Douglas Homes", "Century Communities", "KB Home",
        "MDC Holdings", "Toll Brothers", "Beazer Homes",
        "LGI Homes", "William Lyon Homes", "Shea Homes",
    ],
    "Water Treatment": [
        "Veolia Water Technologies", "SUEZ Water Technologies",
        "Xylem Inc.", "CDM Smith", "Black & Veatch",
        "Brown and Caldwell", "Tetra Tech Inc.", "Arcadis US",
        "GHD Group", "Jacobs Engineering Group",
        "Carollo Engineers", "Hazen and Sawyer",
        "MWH Global (Stantec)", "Layne Christensen",
        "Aquatech International",
    ],
    "School Construction": [
        "Turner Construction Company", "Skanska USA Building",
        "McCarthy Building Companies", "Gilbane Building Company",
        "Whiting-Turner Contracting", "Hensel Phelps",
        "DPR Construction", "Swinerton Builders",
        "Clark Construction Group", "Barton Malow",
        "JE Dunn Construction", "Hoar Construction",
        "Robins & Morton", "Kitchell Corporation",
        "Sundt Construction",
    ],
    "Bridge Repair": [
        "AECOM", "WSP USA", "Parsons Corporation",
        "Jacobs Engineering Group", "Kiewit Infrastructure",
        "Mott MacDonald US", "HDR Inc.",
        "Michael Baker International", "Stantec Consulting",
        "TRC Companies", "KCI Technologies",
        "Atkins North America", "Gannett Fleming",
        "Hardesty & Hanover", "Modjeski and Masters",
    ],
    "Public Transit": [
        "Parsons Corporation", "AECOM", "WSP USA",
        "Jacobs Engineering Group", "HDR Inc.",
        "STV Inc.", "LTK Engineering Services",
        "IBI Group", "SYSTRA", "Stantec Consulting",
        "CH2M Hill (Jacobs)", "URS Corporation",
        "CDM Smith", "GHD Group", "Gannett Fleming",
    ],
    "Broadband Expansion": [
        "Dycom Industries", "MYR Group Inc.", "MasTec Inc.",
        "Quanta Services", "Black Box Corporation",
        "Consolidated Communications", "Telamon Corporation",
        "Tillman Infrastructure", "Ericsson North America",
        "Nokia US Operations", "Crown Castle International",
        "Zayo Group Holdings", "Lumen Technologies",
        "Windstream Holdings", "TeleCommunication Systems",
    ],
}

# Fallback generic pool used when no category match is found.
_FALLBACK_COMPANIES = [
    "Turner Construction", "Kiewit Corporation", "Bechtel Group",
    "Fluor Corporation", "AECOM", "Jacobs Engineering",
    "Parsons Corporation", "WSP USA", "Stantec Consulting",
    "Tetra Tech Inc.", "Black & Veatch", "Burns & McDonnell",
]

_PROJECT_NOUN = {
    "Clinic Construction": ["Community Clinic", "Health Center", "Urgent Care", "Family Medicine Center"],
    "Road Construction": ["Corridor Repaving", "Highway Widening", "Arterial Resurfacing", "Interchange Project"],
    "Power Grid": ["Substation Upgrade", "Grid Modernization", "Microgrid Install", "Transmission Line"],
    "Medical Research": ["Outcomes Study", "Public Health Initiative", "Care Program", "Data Initiative"],
    "Housing": ["Affordable Housing", "Transitional Housing", "Senior Residences", "Mixed-Income Units"],
    "Water Treatment": ["Water Treatment Plant", "Filtration Upgrade", "Reservoir Project", "Pipeline Renewal"],
    "School Construction": ["Elementary School", "STEM Building", "Campus Expansion", "Athletic Facility"],
    "Bridge Repair": ["Bridge Joint Repair", "Span Rehabilitation", "Overpass Retrofit", "Deck Replacement"],
    "Public Transit": ["Bus Rapid Transit", "Light Rail Extension", "Transit Hub", "Park-and-Ride"],
    "Broadband Expansion": ["Rural Broadband", "Fiber Buildout", "Connectivity Initiative", "Network Expansion"],
}

_AREA = ["North", "South", "East", "West", "Central", "Downtown", "Riverside",
         "Lakeview", "Hillcrest", "Old Town", "Midtown", "Eastside", "Westgate"]


def _company_name(rng, category=None):
    """Pick a real company name for the given job category.
    Falls back to a generic pool if the category is unknown."""
    pool = _REAL_COMPANIES.get(category, _FALLBACK_COMPANIES)
    return rng.choice(pool)


# Post-award flag reasons. NOTE: licensing/eligibility problems are caught at
# BIDDING (before award) - so a job that's already underway is NOT flagged for
# those. The few that get flagged after award are caught mid-build, and most
# are minor or get resolved. Each reason carries a severity used to shape the
# claimed/verified gap and the explanation shown to the public.
_FLAG_REASONS = [
    # minor / often-resolved (the common case)
    {"code": "minor_spec_variance", "severity": "minor",
     "text": "Minor materials variance from spec; contractor submitted a substitution request, under review."},
    {"code": "schedule_slip", "severity": "minor",
     "text": "Behind schedule on one milestone; verification of progress pending."},
    {"code": "documentation_gap", "severity": "minor",
     "text": "Milestone claimed before inspection paperwork was filed; awaiting inspector sign-off."},
    {"code": "reporting_lag", "severity": "minor",
     "text": "Self-reported progress ahead of independently verified figure; reconciliation scheduled."},
    # serious (rare)
    {"code": "material_downgrade", "severity": "serious",
     "text": "Delivered material grade lower than contracted; inspection opened."},
    {"code": "progress_overclaim", "severity": "serious",
     "text": "Claimed progress materially exceeds verified site inspection; payment hold placed."},
]


def _gen_job(rng, state_code, city, idx):
    cat = rng.choice(CATEGORIES)
    noun = rng.choice(_PROJECT_NOUN[cat])
    area = rng.choice(_AREA)
    title = f"{area} {noun}"
    company = _company_name(rng, cat)

    # Status mix: post-award flags are RARE (~3%) because licensing/eligibility
    # problems are caught at bidding, before award. The few flagged here are
    # mid-build issues, and most of those are minor.
    roll = rng.random()
    if roll < 0.03:
        status = "flagged"
    elif roll < 0.50:
        status = "active"
    else:
        status = "completed"

    flag = None
    if status == "completed":
        claimed, verified = 100, 100
    elif status == "flagged":
        flag = rng.choice(_FLAG_REASONS)
        if flag["severity"] == "minor":
            claimed = rng.randint(40, 75)
            verified = claimed - rng.randint(4, 12)   # small, explainable gap
        else:  # serious
            claimed = rng.randint(60, 90)
            verified = claimed - rng.randint(20, 38)  # wide gap
    else:  # active
        claimed = rng.randint(15, 85)
        verified = max(0, claimed - rng.randint(0, 4))  # honest: close

    budget = rng.choice([720000, 1250000, 1850000, 2600000, 3300000,
                         4200000, 5100000, 6800000, 980000, 1600000]) \
        + rng.randint(0, 9) * 10000

    if status == "completed":
        summary = f"{cat} project in {city}, {state_code}. Completed and verified."
        materials_note = ""
        spec_delivered = "Per contract"
        pay_note = "Verified"
    elif status == "flagged":
        summary = f"{cat} project in {city}, {state_code}. {flag['text']}"
        materials_note = flag["text"]
        spec_delivered = ("Substitution proposed" if flag["severity"] == "minor"
                          else "Discrepancy noted")
        pay_note = ("Hold placed pending inspection" if flag["severity"] == "serious"
                    else "Awaiting inspector sign-off")
    else:
        summary = f"{cat} project in {city}, {state_code}. In progress; tracking to plan."
        materials_note = ""
        spec_delivered = "Per contract"
        pay_note = "Verified"

    return {
        "id": f"{state_code}-GEN-{idx:04d}",
        "city": city, "state": state_code,
        "category": cat, "title": title,
        "company": company,
        "aedis_id": f"AEDIS-{state_code}-{rng.randint(2000, 9999)}",
        "budget": budget, "status": status,
        "is_scam": (status == "flagged" and flag and flag["severity"] == "serious"),
        "flag_reason": (flag["text"] if flag else None),
        "flag_severity": (flag["severity"] if flag else None),
        "claimed_pct": claimed, "verified_pct": verified,
        "summary": summary,
        "payments": [{"label": "Milestone payment", "amount": int(budget * 0.4),
                      "note": pay_note}],
        "materials": [{"item": "Primary materials", "spec_claimed": "Per contract",
                       "spec_delivered": spec_delivered, "note": materials_note}],
        "timeline": [{"label": "Awarded", "note": "Won open competitive bid; licensing verified at award"},
                     {"label": status.capitalize(), "note": (flag["text"] if flag else "")}],
    }


def generate_state_jobs(state_code):
    """Deterministically generate 15-40 filler jobs for a US state."""
    rng = random.Random("aedis-" + state_code)  # stable seed per state
    name, city = STATES[state_code]
    count = rng.randint(15, 40)
    return [_gen_job(rng, state_code, city, i + 1) for i in range(count)]


# ---- China provinces (second drill-down country) ---------------------------
# (code, province name, representative city). Codes prefixed CN- so generated
# job ids stay globally unique and recoverable.
CN_PROVINCES = {
    "CN-GD": ("Guangdong", "Guangzhou"), "CN-SC": ("Sichuan", "Chengdu"),
    "CN-HE": ("Henan", "Zhengzhou"), "CN-SD": ("Shandong", "Jinan"),
    "CN-JS": ("Jiangsu", "Nanjing"), "CN-HB": ("Hebei", "Shijiazhuang"),
    "CN-HN": ("Hunan", "Changsha"), "CN-AH": ("Anhui", "Hefei"),
    "CN-HU": ("Hubei", "Wuhan"), "CN-ZJ": ("Zhejiang", "Hangzhou"),
    "CN-YN": ("Yunnan", "Kunming"), "CN-JX": ("Jiangxi", "Nanchang"),
    "CN-LN": ("Liaoning", "Shenyang"), "CN-GX": ("Guangxi", "Nanning"),
    "CN-SX": ("Shaanxi", "Xi'an"), "CN-GZ": ("Guizhou", "Guiyang"),
    "CN-SH": ("Shanghai", "Shanghai"), "CN-BJ": ("Beijing", "Beijing"),
    "CN-GS": ("Gansu", "Lanzhou"), "CN-XJ": ("Xinjiang", "Urumqi"),
}


def generate_region_jobs(region_code, region_map):
    """Generalized: deterministically generate filler jobs for any region in a
    given region_map ({code: (name, city)}). Used for both US states and China
    provinces so both drill-downs share one engine."""
    rng = random.Random("aedis-" + region_code)
    name, city = region_map[region_code]
    count = rng.randint(15, 40)
    return [_gen_job(rng, region_code, city, i + 1) for i in range(count)]


# ---- Open-for-bid opportunities (the contractor "Find Work" view) ----------
# Maps each job category to the license a contractor needs (mirrors
# aedis_registry.JOB_TYPES so the two stay consistent).
_CATEGORY_LICENSE = {
    "Clinic Construction": "Healthcare-facility construction license",
    "Road Construction": "Heavy/highway contractor license (DOT-prequalified)",
    "Power Grid": "High-voltage electrical contractor license",
    "Medical Research": "Registered research entity (IRB + biosafety)",
    "Housing": "General building contractor license",
    "Water Treatment": "Civil / water systems contractor license",
    "School Construction": "General building contractor license",
    "Bridge Repair": "Heavy/highway (structural) contractor license",
    "Public Transit": "Civil / transit infrastructure license",
    "Broadband Expansion": "Telecommunications / utility contractor license",
}

# A few representative counties per state for the opportunity location.
_COUNTIES = ["Central County", "Riverside County", "Lakeshore County",
             "Highland County", "Valley County", "Harbor County",
             "Summit County", "Prairie County"]


def generate_open_opportunities(state_code):
    """Deterministic list of OPEN-FOR-BID public jobs in a state, with the
    license each requires and the public-bid framing. Separate seed from the
    ledger generator so these are distinct 'open' postings."""
    rng = random.Random("openbid-" + state_code)
    name, city = STATES[state_code]
    count = rng.randint(6, 14)
    out = []
    for i in range(count):
        cat = rng.choice(CATEGORIES)
        noun = rng.choice(_PROJECT_NOUN[cat])
        area = rng.choice(_AREA)
        county = rng.choice(_COUNTIES)
        budget = rng.choice([720000, 1250000, 1850000, 2600000, 3300000,
                             4200000, 5100000, 980000, 1600000]) + rng.randint(0, 9) * 10000
        bids_so_far = rng.randint(0, 7)
        closes_days = rng.randint(3, 28)
        out.append({
            "id": f"{state_code}-OPP-{i+1:03d}",
            "title": f"{area} {noun}",
            "category": cat,
            "county": county,
            "city": city,
            "state": state_code,
            "budget": budget,
            "license_required": _CATEGORY_LICENSE.get(cat, "General contractor license"),
            "bids_so_far": bids_so_far,
            "closes_in_days": closes_days,
        })
    return out


# ---- Additional drill-down countries (to reach 15 clickable) ---------------
# Each is {region_code: (region_name, representative_city)}. Region codes are
# prefixed with the country code so generated job ids stay globally unique.
IN_STATES = {
    "IN-MH": ("Maharashtra", "Mumbai"), "IN-UP": ("Uttar Pradesh", "Lucknow"),
    "IN-TN": ("Tamil Nadu", "Chennai"), "IN-KA": ("Karnataka", "Bengaluru"),
    "IN-GJ": ("Gujarat", "Ahmedabad"), "IN-WB": ("West Bengal", "Kolkata"),
    "IN-RJ": ("Rajasthan", "Jaipur"), "IN-MP": ("Madhya Pradesh", "Bhopal"),
    "IN-BR": ("Bihar", "Patna"), "IN-TG": ("Telangana", "Hyderabad"),
    "IN-KL": ("Kerala", "Kochi"), "IN-PB": ("Punjab", "Ludhiana"),
}
BR_STATES = {
    "BR-SP": ("São Paulo", "São Paulo"), "BR-RJ": ("Rio de Janeiro", "Rio de Janeiro"),
    "BR-MG": ("Minas Gerais", "Belo Horizonte"), "BR-BA": ("Bahia", "Salvador"),
    "BR-PR": ("Paraná", "Curitiba"), "BR-RS": ("Rio Grande do Sul", "Porto Alegre"),
    "BR-PE": ("Pernambuco", "Recife"), "BR-CE": ("Ceará", "Fortaleza"),
    "BR-AM": ("Amazonas", "Manaus"), "BR-GO": ("Goiás", "Goiânia"),
}
NG_STATES = {
    "NG-LA": ("Lagos", "Lagos"), "NG-KN": ("Kano", "Kano"),
    "NG-RV": ("Rivers", "Port Harcourt"), "NG-OY": ("Oyo", "Ibadan"),
    "NG-KD": ("Kaduna", "Kaduna"), "NG-FC": ("FCT Abuja", "Abuja"),
    "NG-EN": ("Enugu", "Enugu"), "NG-BO": ("Borno", "Maiduguri"),
}
ID_PROVINCES = {
    "ID-JK": ("Jakarta", "Jakarta"), "ID-JB": ("West Java", "Bandung"),
    "ID-JT": ("Central Java", "Semarang"), "ID-JI": ("East Java", "Surabaya"),
    "ID-SN": ("North Sumatra", "Medan"), "ID-BT": ("Banten", "Serang"),
    "ID-SS": ("South Sulawesi", "Makassar"), "ID-BA": ("Bali", "Denpasar"),
}
KE_COUNTIES = {
    "KE-NB": ("Nairobi", "Nairobi"), "KE-MB": ("Mombasa", "Mombasa"),
    "KE-KS": ("Kisumu", "Kisumu"), "KE-NK": ("Nakuru", "Nakuru"),
    "KE-UG": ("Uasin Gishu", "Eldoret"), "KE-KJ": ("Kiambu", "Thika"),
    "KE-MC": ("Machakos", "Machakos"), "KE-KL": ("Kilifi", "Kilifi"),
}
DE_STATES = {
    "DE-BY": ("Bavaria", "Munich"), "DE-NW": ("North Rhine-Westphalia", "Cologne"),
    "DE-BW": ("Baden-Württemberg", "Stuttgart"), "DE-NI": ("Lower Saxony", "Hanover"),
    "DE-HE": ("Hesse", "Frankfurt"), "DE-BE": ("Berlin", "Berlin"),
    "DE-SN": ("Saxony", "Dresden"), "DE-RP": ("Rhineland-Palatinate", "Mainz"),
}
GB_REGIONS = {
    "GB-LND": ("Greater London", "London"), "GB-SE": ("South East", "Brighton"),
    "GB-NW": ("North West", "Manchester"), "GB-WM": ("West Midlands", "Birmingham"),
    "GB-YH": ("Yorkshire", "Leeds"), "GB-SCT": ("Scotland", "Glasgow"),
    "GB-WLS": ("Wales", "Cardiff"), "GB-NIR": ("Northern Ireland", "Belfast"),
}
BR_LABEL = "State"
JP_PREFECTURES = {
    "JP-13": ("Tokyo", "Tokyo"), "JP-27": ("Osaka", "Osaka"),
    "JP-23": ("Aichi", "Nagoya"), "JP-14": ("Kanagawa", "Yokohama"),
    "JP-01": ("Hokkaido", "Sapporo"), "JP-40": ("Fukuoka", "Fukuoka"),
    "JP-28": ("Hyogo", "Kobe"), "JP-26": ("Kyoto", "Kyoto"),
}
MX_STATES = {
    "MX-CMX": ("Mexico City", "Mexico City"), "MX-JAL": ("Jalisco", "Guadalajara"),
    "MX-NLE": ("Nuevo León", "Monterrey"), "MX-PUE": ("Puebla", "Puebla"),
    "MX-GUA": ("Guanajuato", "León"), "MX-VER": ("Veracruz", "Veracruz"),
    "MX-CHH": ("Chihuahua", "Chihuahua"), "MX-BCN": ("Baja California", "Tijuana"),
}
ZA_PROVINCES = {
    "ZA-GT": ("Gauteng", "Johannesburg"), "ZA-WC": ("Western Cape", "Cape Town"),
    "ZA-KZN": ("KwaZulu-Natal", "Durban"), "ZA-EC": ("Eastern Cape", "Gqeberha"),
    "ZA-LP": ("Limpopo", "Polokwane"), "ZA-MP": ("Mpumalanga", "Nelspruit"),
    "ZA-FS": ("Free State", "Bloemfontein"), "ZA-NW": ("North West", "Mahikeng"),
}
EG_GOVERNORATES = {
    "EG-C": ("Cairo", "Cairo"), "EG-ALX": ("Alexandria", "Alexandria"),
    "EG-GZ": ("Giza", "Giza"), "EG-DK": ("Dakahlia", "Mansoura"),
    "EG-SHR": ("Sharqia", "Zagazig"), "EG-QH": ("Qalyubia", "Banha"),
    "EG-BNS": ("Beni Suef", "Beni Suef"), "EG-ASN": ("Aswan", "Aswan"),
}
PK_PROVINCES = {
    "PK-PB": ("Punjab", "Lahore"), "PK-SD": ("Sindh", "Karachi"),
    "PK-KP": ("Khyber Pakhtunkhwa", "Peshawar"), "PK-BA": ("Balochistan", "Quetta"),
    "PK-IS": ("Islamabad", "Islamabad"), "PK-GB": ("Gilgit-Baltistan", "Gilgit"),
}
PH_REGIONS = {
    "PH-NCR": ("Metro Manila", "Manila"), "PH-CEB": ("Cebu", "Cebu City"),
    "PH-DAV": ("Davao", "Davao City"), "PH-CL": ("Central Luzon", "Angeles"),
    "PH-CAL": ("Calabarzon", "Calamba"), "PH-WV": ("Western Visayas", "Iloilo"),
    "PH-NM": ("Northern Mindanao", "Cagayan de Oro"), "PH-IL": ("Ilocos", "Vigan"),
}

# ===== BATCH 1: major countries by population / prominence =====
RU_REGIONS = {
    "RU-MOW": ("Moscow", "Moscow"), "RU-SPE": ("Saint Petersburg", "Saint Petersburg"),
    "RU-NVS": ("Novosibirsk Oblast", "Novosibirsk"), "RU-SVE": ("Sverdlovsk Oblast", "Yekaterinburg"),
    "RU-TA": ("Tatarstan", "Kazan"), "RU-KDA": ("Krasnodar Krai", "Krasnodar"),
    "RU-CHE": ("Chelyabinsk Oblast", "Chelyabinsk"), "RU-SAM": ("Samara Oblast", "Samara"),
    "RU-BA": ("Bashkortostan", "Ufa"), "RU-ROS": ("Rostov Oblast", "Rostov-on-Don"),
    "RU-PRI": ("Primorsky Krai", "Vladivostok"), "RU-KYA": ("Krasnoyarsk Krai", "Krasnoyarsk"),
}
BD_DIVISIONS = {
    "BD-DH": ("Dhaka", "Dhaka"), "BD-CG": ("Chattogram", "Chattogram"),
    "BD-KH": ("Khulna", "Khulna"), "BD-RJ": ("Rajshahi", "Rajshahi"),
    "BD-SY": ("Sylhet", "Sylhet"), "BD-BR": ("Barishal", "Barishal"),
    "BD-RP": ("Rangpur", "Rangpur"), "BD-MY": ("Mymensingh", "Mymensingh"),
}
ET_REGIONS = {
    "ET-AA": ("Addis Ababa", "Addis Ababa"), "ET-OR": ("Oromia", "Adama"),
    "ET-AM": ("Amhara", "Bahir Dar"), "ET-TI": ("Tigray", "Mekelle"),
    "ET-SN": ("Southern Nations", "Hawassa"), "ET-SO": ("Somali", "Jijiga"),
    "ET-AF": ("Afar", "Semera"), "ET-DD": ("Dire Dawa", "Dire Dawa"),
}
VN_REGIONS = {
    "VN-HN": ("Hanoi", "Hanoi"), "VN-SG": ("Ho Chi Minh City", "Ho Chi Minh City"),
    "VN-DN": ("Da Nang", "Da Nang"), "VN-HP": ("Hai Phong", "Hai Phong"),
    "VN-CT": ("Can Tho", "Can Tho"), "VN-QN": ("Quang Ninh", "Ha Long"),
    "VN-NA": ("Nghe An", "Vinh"), "VN-KH": ("Khanh Hoa", "Nha Trang"),
}
IR_PROVINCES = {
    "IR-THR": ("Tehran", "Tehran"), "IR-ISF": ("Isfahan", "Isfahan"),
    "IR-RAZ": ("Razavi Khorasan", "Mashhad"), "IR-FAR": ("Fars", "Shiraz"),
    "IR-EAZ": ("East Azerbaijan", "Tabriz"), "IR-KHZ": ("Khuzestan", "Ahvaz"),
    "IR-GIL": ("Gilan", "Rasht"), "IR-MAZ": ("Mazandaran", "Sari"),
}
TR_PROVINCES = {
    "TR-34": ("Istanbul", "Istanbul"), "TR-06": ("Ankara", "Ankara"),
    "TR-35": ("Izmir", "Izmir"), "TR-16": ("Bursa", "Bursa"),
    "TR-07": ("Antalya", "Antalya"), "TR-01": ("Adana", "Adana"),
    "TR-42": ("Konya", "Konya"), "TR-27": ("Gaziantep", "Gaziantep"),
}
FR_REGIONS = {
    "FR-IDF": ("Île-de-France", "Paris"), "FR-ARA": ("Auvergne-Rhône-Alpes", "Lyon"),
    "FR-PAC": ("Provence-Alpes-Côte d'Azur", "Marseille"), "FR-OCC": ("Occitanie", "Toulouse"),
    "FR-NAQ": ("Nouvelle-Aquitaine", "Bordeaux"), "FR-HDF": ("Hauts-de-France", "Lille"),
    "FR-GES": ("Grand Est", "Strasbourg"), "FR-BRE": ("Brittany", "Rennes"),
}
IT_REGIONS = {
    "IT-LOM": ("Lombardy", "Milan"), "IT-LAZ": ("Lazio", "Rome"),
    "IT-CAM": ("Campania", "Naples"), "IT-SIC": ("Sicily", "Palermo"),
    "IT-VEN": ("Veneto", "Venice"), "IT-PIE": ("Piedmont", "Turin"),
    "IT-EMR": ("Emilia-Romagna", "Bologna"), "IT-TOS": ("Tuscany", "Florence"),
}
TH_REGIONS = {
    "TH-BKK": ("Bangkok", "Bangkok"), "TH-CMI": ("Chiang Mai", "Chiang Mai"),
    "TH-CON": ("Chon Buri", "Pattaya"), "TH-NMA": ("Nakhon Ratchasima", "Nakhon Ratchasima"),
    "TH-KKN": ("Khon Kaen", "Khon Kaen"), "TH-PKT": ("Phuket", "Phuket"),
    "TH-SRT": ("Surat Thani", "Surat Thani"), "TH-UDN": ("Udon Thani", "Udon Thani"),
}
CD_PROVINCES = {
    "CD-KN": ("Kinshasa", "Kinshasa"), "CD-HK": ("Haut-Katanga", "Lubumbashi"),
    "CD-NK": ("North Kivu", "Goma"), "CD-SK": ("South Kivu", "Bukavu"),
    "CD-KC": ("Kasaï-Central", "Kananga"), "CD-TO": ("Tshopo", "Kisangani"),
    "CD-IT": ("Ituri", "Bunia"), "CD-LU": ("Lualaba", "Kolwezi"),
}
KR_REGIONS = {
    "KR-11": ("Seoul", "Seoul"), "KR-26": ("Busan", "Busan"),
    "KR-27": ("Daegu", "Daegu"), "KR-28": ("Incheon", "Incheon"),
    "KR-41": ("Gyeonggi", "Suwon"), "KR-48": ("South Gyeongsang", "Changwon"),
    "KR-47": ("North Gyeongsang", "Pohang"), "KR-29": ("Gwangju", "Gwangju"),
}
ES_REGIONS = {
    "ES-MD": ("Madrid", "Madrid"), "ES-CT": ("Catalonia", "Barcelona"),
    "ES-AN": ("Andalusia", "Seville"), "ES-VC": ("Valencia", "Valencia"),
    "ES-GA": ("Galicia", "Vigo"), "ES-PV": ("Basque Country", "Bilbao"),
    "ES-CL": ("Castile and León", "Valladolid"), "ES-CN": ("Canary Islands", "Las Palmas"),
}
AR_PROVINCES = {
    "AR-C": ("Buenos Aires City", "Buenos Aires"), "AR-B": ("Buenos Aires Province", "La Plata"),
    "AR-X": ("Córdoba", "Córdoba"), "AR-S": ("Santa Fe", "Rosario"),
    "AR-M": ("Mendoza", "Mendoza"), "AR-T": ("Tucumán", "San Miguel de Tucumán"),
    "AR-A": ("Salta", "Salta"), "AR-N": ("Misiones", "Posadas"),
}
CO_DEPARTMENTS = {
    "CO-DC": ("Bogotá", "Bogotá"), "CO-ANT": ("Antioquia", "Medellín"),
    "CO-VAC": ("Valle del Cauca", "Cali"), "CO-ATL": ("Atlántico", "Barranquilla"),
    "CO-SAN": ("Santander", "Bucaramanga"), "CO-BOL": ("Bolívar", "Cartagena"),
    "CO-CUN": ("Cundinamarca", "Soacha"), "CO-NSA": ("Norte de Santander", "Cúcuta"),
}
CA_PROVINCES = {
    "CA-ON": ("Ontario", "Toronto"), "CA-QC": ("Quebec", "Montreal"),
    "CA-BC": ("British Columbia", "Vancouver"), "CA-AB": ("Alberta", "Calgary"),
    "CA-MB": ("Manitoba", "Winnipeg"), "CA-SK": ("Saskatchewan", "Saskatoon"),
    "CA-NS": ("Nova Scotia", "Halifax"), "CA-NB": ("New Brunswick", "Moncton"),
}

# ===== BATCH 2: more countries =====
MM_REGIONS = {
    "MM-YGN": ("Yangon", "Yangon"), "MM-MDY": ("Mandalay", "Mandalay"),
    "MM-NPT": ("Naypyidaw", "Naypyidaw"), "MM-SHN": ("Shan", "Taunggyi"),
    "MM-AYE": ("Ayeyarwady", "Pathein"), "MM-MGW": ("Magway", "Magway"),
}
UG_REGIONS = {
    "UG-KLA": ("Kampala", "Kampala"), "UG-WAK": ("Wakiso", "Wakiso"),
    "UG-MBA": ("Mbarara", "Mbarara"), "UG-GUL": ("Gulu", "Gulu"),
    "UG-JIN": ("Jinja", "Jinja"), "UG-MBL": ("Mbale", "Mbale"),
}
DZ_PROVINCES = {
    "DZ-16": ("Algiers", "Algiers"), "DZ-31": ("Oran", "Oran"),
    "DZ-25": ("Constantine", "Constantine"), "DZ-09": ("Blida", "Blida"),
    "DZ-19": ("Sétif", "Sétif"), "DZ-23": ("Annaba", "Annaba"),
}
UA_OBLASTS = {
    "UA-30": ("Kyiv", "Kyiv"), "UA-63": ("Kharkiv", "Kharkiv"),
    "UA-51": ("Odesa", "Odesa"), "UA-12": ("Dnipropetrovsk", "Dnipro"),
    "UA-46": ("Lviv", "Lviv"), "UA-23": ("Zaporizhzhia", "Zaporizhzhia"),
}
PL_VOIVODESHIPS = {
    "PL-MZ": ("Masovia", "Warsaw"), "PL-MA": ("Lesser Poland", "Kraków"),
    "PL-DS": ("Lower Silesia", "Wrocław"), "PL-WP": ("Greater Poland", "Poznań"),
    "PL-SL": ("Silesia", "Katowice"), "PL-PM": ("Pomerania", "Gdańsk"),
}
MA_REGIONS = {
    "MA-CAS": ("Casablanca-Settat", "Casablanca"), "MA-RAB": ("Rabat-Salé-Kénitra", "Rabat"),
    "MA-MAR": ("Marrakesh-Safi", "Marrakesh"), "MA-FES": ("Fès-Meknès", "Fès"),
    "MA-TAN": ("Tangier-Tetouan", "Tangier"), "MA-AGA": ("Souss-Massa", "Agadir"),
}
SA_REGIONS = {
    "SA-01": ("Riyadh", "Riyadh"), "SA-02": ("Makkah", "Jeddah"),
    "SA-04": ("Eastern Province", "Dammam"), "SA-03": ("Madinah", "Medina"),
    "SA-05": ("Qassim", "Buraidah"), "SA-14": ("Asir", "Abha"),
}
PE_REGIONS = {
    "PE-LMA": ("Lima", "Lima"), "PE-ARE": ("Arequipa", "Arequipa"),
    "PE-LAL": ("La Libertad", "Trujillo"), "PE-PIU": ("Piura", "Piura"),
    "PE-CUS": ("Cusco", "Cusco"), "PE-LAM": ("Lambayeque", "Chiclayo"),
}
MY_STATES = {
    "MY-14": ("Kuala Lumpur", "Kuala Lumpur"), "MY-10": ("Selangor", "Shah Alam"),
    "MY-07": ("Penang", "George Town"), "MY-01": ("Johor", "Johor Bahru"),
    "MY-13": ("Sarawak", "Kuching"), "MY-12": ("Sabah", "Kota Kinabalu"),
}
GH_REGIONS = {
    "GH-AA": ("Greater Accra", "Accra"), "GH-AH": ("Ashanti", "Kumasi"),
    "GH-WP": ("Western", "Sekondi-Takoradi"), "GH-NP": ("Northern", "Tamale"),
    "GH-EP": ("Eastern", "Koforidua"), "GH-CP": ("Central", "Cape Coast"),
}
MZ_PROVINCES = {
    "MZ-MPM": ("Maputo City", "Maputo"), "MZ-N": ("Nampula", "Nampula"),
    "MZ-S": ("Sofala", "Beira"), "MZ-Z": ("Zambezia", "Quelimane"),
    "MZ-T": ("Tete", "Tete"), "MZ-A": ("Niassa", "Lichinga"),
}
AU_STATES = {
    "AU-NSW": ("New South Wales", "Sydney"), "AU-VIC": ("Victoria", "Melbourne"),
    "AU-QLD": ("Queensland", "Brisbane"), "AU-WA": ("Western Australia", "Perth"),
    "AU-SA": ("South Australia", "Adelaide"), "AU-TAS": ("Tasmania", "Hobart"),
    "AU-ACT": ("Australian Capital Territory", "Canberra"), "AU-NT": ("Northern Territory", "Darwin"),
}
MG_REGIONS = {
    "MG-A": ("Analamanga", "Antananarivo"), "MG-T": ("Atsinanana", "Toamasina"),
    "MG-D": ("Diana", "Antsiranana"), "MG-F": ("Haute Matsiatra", "Fianarantsoa"),
    "MG-U": ("Boeny", "Mahajanga"), "MG-O": ("Atsimo-Andrefana", "Toliara"),
}
CL_REGIONS = {
    "CL-RM": ("Santiago Metropolitan", "Santiago"), "CL-VS": ("Valparaíso", "Valparaíso"),
    "CL-BI": ("Biobío", "Concepción"), "CL-AR": ("Araucanía", "Temuco"),
    "CL-AN": ("Antofagasta", "Antofagasta"), "CL-LL": ("Los Lagos", "Puerto Montt"),
}
NL_PROVINCES = {
    "NL-NH": ("North Holland", "Amsterdam"), "NL-ZH": ("South Holland", "Rotterdam"),
    "NL-UT": ("Utrecht", "Utrecht"), "NL-NB": ("North Brabant", "Eindhoven"),
    "NL-GE": ("Gelderland", "Nijmegen"), "NL-OV": ("Overijssel", "Enschede"),
}
EC_PROVINCES = {
    "EC-P": ("Pichincha", "Quito"), "EC-G": ("Guayas", "Guayaquil"),
    "EC-A": ("Azuay", "Cuenca"), "EC-M": ("Manabí", "Portoviejo"),
    "EC-O": ("El Oro", "Machala"), "EC-T": ("Tungurahua", "Ambato"),
}
GT_DEPARTMENTS = {
    "GT-GU": ("Guatemala", "Guatemala City"), "GT-QZ": ("Quetzaltenango", "Quetzaltenango"),
    "GT-ES": ("Escuintla", "Escuintla"), "GT-HU": ("Huehuetenango", "Huehuetenango"),
    "GT-SM": ("San Marcos", "San Marcos"), "GT-AV": ("Alta Verapaz", "Cobán"),
}
SN_REGIONS = {
    "SN-DK": ("Dakar", "Dakar"), "SN-TH": ("Thiès", "Thiès"),
    "SN-DB": ("Diourbel", "Diourbel"), "SN-SL": ("Saint-Louis", "Saint-Louis"),
    "SN-KA": ("Kaolack", "Kaolack"), "SN-ZG": ("Ziguinchor", "Ziguinchor"),
}
BO_DEPARTMENTS = {
    "BO-S": ("Santa Cruz", "Santa Cruz de la Sierra"), "BO-L": ("La Paz", "La Paz"),
    "BO-C": ("Cochabamba", "Cochabamba"), "BO-O": ("Oruro", "Oruro"),
    "BO-P": ("Potosí", "Potosí"), "BO-T": ("Tarija", "Tarija"),
}
RW_PROVINCES = {
    "RW-01": ("Kigali", "Kigali"), "RW-02": ("Eastern", "Rwamagana"),
    "RW-03": ("Northern", "Musanze"), "RW-04": ("Western", "Rubavu"),
    "RW-05": ("Southern", "Huye"),
}

# ===== BATCH 3 =====
AF_PROVINCES = {
    "AF-KAB": ("Kabul", "Kabul"), "AF-HER": ("Herat", "Herat"),
    "AF-KAN": ("Kandahar", "Kandahar"), "AF-BAL": ("Balkh", "Mazar-i-Sharif"),
    "AF-NAN": ("Nangarhar", "Jalalabad"), "AF-KDZ": ("Kunduz", "Kunduz"),
}
AO_PROVINCES = {
    "AO-LUA": ("Luanda", "Luanda"), "AO-BGU": ("Benguela", "Benguela"),
    "AO-HUI": ("Huíla", "Lubango"), "AO-HUA": ("Huambo", "Huambo"),
    "AO-CAB": ("Cabinda", "Cabinda"), "AO-BIE": ("Bié", "Kuito"),
}
YE_GOVERNORATES = {
    "YE-SAN": ("Sana'a", "Sana'a"), "YE-ADE": ("Aden", "Aden"),
    "YE-TAI": ("Taiz", "Taiz"), "YE-HOD": ("Al Hudaydah", "Al Hudaydah"),
    "YE-IBB": ("Ibb", "Ibb"), "YE-HDR": ("Hadhramaut", "Mukalla"),
}
SY_GOVERNORATES = {
    "SY-DI": ("Damascus", "Damascus"), "SY-HL": ("Aleppo", "Aleppo"),
    "SY-HM": ("Homs", "Homs"), "SY-LA": ("Latakia", "Latakia"),
    "SY-HI": ("Hama", "Hama"), "SY-ID": ("Idlib", "Idlib"),
}
SD_STATES = {
    "SD-KH": ("Khartoum", "Khartoum"), "SD-GZ": ("Gezira", "Wad Madani"),
    "SD-RS": ("Red Sea", "Port Sudan"), "SD-KS": ("South Kordofan", "Kadugli"),
    "SD-KA": ("Kassala", "Kassala"), "SD-ND": ("North Darfur", "El Fasher"),
}
SS_STATES = {
    "SS-EC": ("Central Equatoria", "Juba"), "SS-UY": ("Unity", "Bentiu"),
    "SS-JG": ("Jonglei", "Bor"), "SS-BN": ("Northern Bahr el Ghazal", "Aweil"),
    "SS-WR": ("Warrap", "Kuajok"),
}
IQ_GOVERNORATES = {
    "IQ-BG": ("Baghdad", "Baghdad"), "IQ-BA": ("Basra", "Basra"),
    "IQ-NI": ("Nineveh", "Mosul"), "IQ-AR": ("Erbil", "Erbil"),
    "IQ-SU": ("Sulaymaniyah", "Sulaymaniyah"), "IQ-NA": ("Najaf", "Najaf"),
}
UZ_REGIONS = {
    "UZ-TK": ("Tashkent", "Tashkent"), "UZ-SA": ("Samarqand", "Samarkand"),
    "UZ-FA": ("Fergana", "Fergana"), "UZ-AN": ("Andijan", "Andijan"),
    "UZ-NG": ("Namangan", "Namangan"), "UZ-BU": ("Bukhara", "Bukhara"),
}
KZ_REGIONS = {
    "KZ-ALA": ("Almaty", "Almaty"), "KZ-AST": ("Astana", "Astana"),
    "KZ-SH": ("Shymkent", "Shymkent"), "KZ-KAR": ("Karaganda", "Karaganda"),
    "KZ-AKT": ("Aktobe", "Aktobe"), "KZ-PAV": ("Pavlodar", "Pavlodar"),
}
NP_PROVINCES = {
    "NP-BA": ("Bagmati", "Kathmandu"), "NP-P1": ("Koshi", "Biratnagar"),
    "NP-LU": ("Lumbini", "Butwal"), "NP-GA": ("Gandaki", "Pokhara"),
    "NP-MA": ("Madhesh", "Janakpur"), "NP-SU": ("Sudurpashchim", "Dhangadhi"),
}
VE_STATES = {
    "VE-A": ("Capital District", "Caracas"), "VE-Z": ("Zulia", "Maracaibo"),
    "VE-B": ("Carabobo", "Valencia"), "VE-L": ("Lara", "Barquisimeto"),
    "VE-M": ("Miranda", "Los Teques"), "VE-G": ("Aragua", "Maracay"),
}
LK_PROVINCES = {
    "LK-1": ("Western", "Colombo"), "LK-2": ("Central", "Kandy"),
    "LK-3": ("Southern", "Galle"), "LK-5": ("Eastern", "Trincomalee"),
    "LK-7": ("North Western", "Kurunegala"), "LK-9": ("Northern", "Jaffna"),
}
ML_REGIONS = {
    "ML-BKO": ("Bamako", "Bamako"), "ML-SIK": ("Sikasso", "Sikasso"),
    "ML-SEG": ("Ségou", "Ségou"), "ML-MOP": ("Mopti", "Mopti"),
    "ML-KAY": ("Kayes", "Kayes"), "ML-KOU": ("Koulikoro", "Koulikoro"),
}
BF_REGIONS = {
    "BF-KAD": ("Centre (Ouagadougou)", "Ouagadougou"), "BF-HOU": ("Hauts-Bassins", "Bobo-Dioulasso"),
    "BF-BAM": ("Boucle du Mouhoun", "Dédougou"), "BF-NOR": ("Nord", "Ouahigouya"),
    "BF-SAH": ("Sahel", "Dori"), "BF-EST": ("Est", "Fada N'gourma"),
}
NE_REGIONS = {
    "NE-8": ("Niamey", "Niamey"), "NE-7": ("Zinder", "Zinder"),
    "NE-4": ("Maradi", "Maradi"), "NE-6": ("Tahoua", "Tahoua"),
    "NE-1": ("Agadez", "Agadez"), "NE-2": ("Diffa", "Diffa"),
}
MW_REGIONS = {
    "MW-LI": ("Lilongwe", "Lilongwe"), "MW-BL": ("Blantyre", "Blantyre"),
    "MW-MZ": ("Mzimba", "Mzuzu"), "MW-ZO": ("Zomba", "Zomba"),
    "MW-KS": ("Kasungu", "Kasungu"), "MW-MG": ("Mangochi", "Mangochi"),
}
ZM_PROVINCES = {
    "ZM-09": ("Lusaka", "Lusaka"), "ZM-08": ("Copperbelt", "Ndola"),
    "ZM-02": ("Central", "Kabwe"), "ZM-03": ("Eastern", "Chipata"),
    "ZM-04": ("Luapula", "Mansa"), "ZM-10": ("Muchinga", "Chinsali"),
}
ZW_PROVINCES = {
    "ZW-HA": ("Harare", "Harare"), "ZW-BU": ("Bulawayo", "Bulawayo"),
    "ZW-MA": ("Manicaland", "Mutare"), "ZW-MV": ("Masvingo", "Masvingo"),
    "ZW-MW": ("Mashonaland West", "Chinhoyi"), "ZW-MC": ("Mashonaland Central", "Bindura"),
}
TD_REGIONS = {
    "TD-ND": ("N'Djamena", "N'Djamena"), "TD-LO": ("Logone Occidental", "Moundou"),
    "TD-MA": ("Mayo-Kebbi Est", "Bongor"), "TD-OD": ("Ouaddaï", "Abéché"),
    "TD-SA": ("Salamat", "Am Timan"), "TD-KA": ("Kanem", "Mao"),
}
SO_REGIONS = {
    "SO-BN": ("Banaadir", "Mogadishu"), "SO-WO": ("Woqooyi Galbeed", "Hargeisa"),
    "SO-BR": ("Bari", "Bosaso"), "SO-LK": ("Lower Shabelle", "Marka"),
    "SO-JH": ("Lower Juba", "Kismayo"), "SO-MU": ("Mudug", "Galkayo"),
}

# ===== BATCH 4 =====
TN_GOVERNORATES = {
    "TN-11": ("Tunis", "Tunis"), "TN-61": ("Sfax", "Sfax"),
    "TN-51": ("Sousse", "Sousse"), "TN-41": ("Kairouan", "Kairouan"),
    "TN-71": ("Gabès", "Gabès"), "TN-81": ("Gafsa", "Gafsa"),
}
GN_REGIONS = {
    "GN-CON": ("Conakry", "Conakry"), "GN-NZ": ("Nzérékoré", "Nzérékoré"),
    "GN-KA": ("Kankan", "Kankan"), "GN-LA": ("Labé", "Labé"),
    "GN-BO": ("Boké", "Boké"), "GN-KI": ("Kindia", "Kindia"),
}
BJ_DEPARTMENTS = {
    "BJ-LI": ("Littoral", "Cotonou"), "BJ-OU": ("Ouémé", "Porto-Novo"),
    "BJ-BO": ("Borgou", "Parakou"), "BJ-AT": ("Atlantique", "Abomey-Calavi"),
    "BJ-ZO": ("Zou", "Abomey"), "BJ-DO": ("Donga", "Djougou"),
}
BI_PROVINCES = {
    "BI-BM": ("Bujumbura Mairie", "Bujumbura"), "BI-GI": ("Gitega", "Gitega"),
    "BI-NG": ("Ngozi", "Ngozi"), "BI-RT": ("Rutana", "Rutana"),
    "BI-KI": ("Kirundo", "Kirundo"), "BI-MU": ("Muyinga", "Muyinga"),
}
SL_PROVINCES = {
    "SL-W": ("Western Area", "Freetown"), "SL-N": ("Northern", "Makeni"),
    "SL-S": ("Southern", "Bo"), "SL-E": ("Eastern", "Kenema"),
}
TG_REGIONS = {
    "TG-M": ("Maritime", "Lomé"), "TG-P": ("Plateaux", "Atakpamé"),
    "TG-C": ("Centrale", "Sokodé"), "TG-K": ("Kara", "Kara"),
    "TG-S": ("Savanes", "Dapaong"),
}
LY_DISTRICTS = {
    "LY-TB": ("Tripoli", "Tripoli"), "LY-BA": ("Benghazi", "Benghazi"),
    "LY-MI": ("Misrata", "Misrata"), "LY-ZA": ("Zawiya", "Zawiya"),
    "LY-SB": ("Sabha", "Sabha"), "LY-JA": ("Jabal al Akhdar", "Bayda"),
}
JO_GOVERNORATES = {
    "JO-AM": ("Amman", "Amman"), "JO-IR": ("Irbid", "Irbid"),
    "JO-ZA": ("Zarqa", "Zarqa"), "JO-BA": ("Balqa", "Salt"),
    "JO-MA": ("Madaba", "Madaba"), "JO-AQ": ("Aqaba", "Aqaba"),
}
AZ_REGIONS = {
    "AZ-BA": ("Baku", "Baku"), "AZ-GA": ("Ganja", "Ganja"),
    "AZ-SM": ("Sumqayit", "Sumqayit"), "AZ-MI": ("Mingachevir", "Mingachevir"),
    "AZ-NA": ("Nakhchivan", "Nakhchivan"), "AZ-LA": ("Lankaran", "Lankaran"),
}
TJ_REGIONS = {
    "TJ-DU": ("Dushanbe", "Dushanbe"), "TJ-SU": ("Sughd", "Khujand"),
    "TJ-KT": ("Khatlon", "Bokhtar"), "TJ-GB": ("Gorno-Badakhshan", "Khorugh"),
    "TJ-RA": ("Districts of Republican Subordination", "Vahdat"),
}
HT_DEPARTMENTS = {
    "HT-OU": ("Ouest", "Port-au-Prince"), "HT-ND": ("Nord", "Cap-Haïtien"),
    "HT-AR": ("Artibonite", "Gonaïves"), "HT-SD": ("Sud", "Les Cayes"),
    "HT-CE": ("Centre", "Hinche"), "HT-NO": ("Nord-Ouest", "Port-de-Paix"),
}
DO_PROVINCES = {
    "DO-01": ("Distrito Nacional", "Santo Domingo"), "DO-25": ("Santiago", "Santiago"),
    "DO-32": ("Puerto Plata", "Puerto Plata"), "DO-23": ("San Pedro de Macorís", "San Pedro de Macorís"),
    "DO-11": ("La Vega", "La Vega"), "DO-18": ("La Romana", "La Romana"),
}
HN_DEPARTMENTS = {
    "HN-FM": ("Francisco Morazán", "Tegucigalpa"), "HN-CR": ("Cortés", "San Pedro Sula"),
    "HN-AT": ("Atlántida", "La Ceiba"), "HN-YO": ("Yoro", "El Progreso"),
    "HN-CH": ("Choluteca", "Choluteca"), "HN-CM": ("Comayagua", "Comayagua"),
}
NI_DEPARTMENTS = {
    "NI-MN": ("Managua", "Managua"), "NI-LE": ("León", "León"),
    "NI-MT": ("Matagalpa", "Matagalpa"), "NI-CI": ("Chinandega", "Chinandega"),
    "NI-MS": ("Masaya", "Masaya"), "NI-GR": ("Granada", "Granada"),
}
PY_DEPARTMENTS = {
    "PY-ASU": ("Asunción", "Asunción"), "PY-11": ("Central", "Areguá"),
    "PY-1": ("Concepción", "Concepción"), "PY-10": ("Alto Paraná", "Ciudad del Este"),
    "PY-3": ("Cordillera", "Caacupé"), "PY-8": ("Itapúa", "Encarnación"),
}
SV_DEPARTMENTS = {
    "SV-SS": ("San Salvador", "San Salvador"), "SV-SA": ("Santa Ana", "Santa Ana"),
    "SV-SM": ("San Miguel", "San Miguel"), "SV-LL": ("La Libertad", "Santa Tecla"),
    "SV-SO": ("Sonsonate", "Sonsonate"), "SV-US": ("Usulután", "Usulután"),
}
CM_REGIONS = {
    "CM-CE": ("Centre", "Yaoundé"), "CM-LT": ("Littoral", "Douala"),
    "CM-OU": ("West", "Bafoussam"), "CM-NW": ("Northwest", "Bamenda"),
    "CM-SW": ("Southwest", "Buea"), "CM-EN": ("Far North", "Maroua"),
}
CI_DISTRICTS = {
    "CI-AB": ("Abidjan", "Abidjan"), "CI-BS": ("Bas-Sassandra", "San-Pédro"),
    "CI-YM": ("Yamoussoukro", "Yamoussoukro"), "CI-VB": ("Vallée du Bandama", "Bouaké"),
    "CI-SC": ("Savanes", "Korhogo"), "CI-MO": ("Montagnes", "Man"),
}
TZ_REGIONS = {
    "TZ-02": ("Dar es Salaam", "Dar es Salaam"), "TZ-12": ("Mwanza", "Mwanza"),
    "TZ-03": ("Dodoma", "Dodoma"), "TZ-01": ("Arusha", "Arusha"),
    "TZ-13": ("Mbeya", "Mbeya"), "TZ-26": ("Zanzibar Urban/West", "Zanzibar City"),
}

# ===== BATCH 5: remaining states (smaller nations) =====
# For compactness, these are defined inline in _SIMPLE_REGIONS below: a country
# code -> (region_label, [(region_name, city), ...]). They get expanded into the
# same prefixed-dict format as the hand-written maps above.
_SIMPLE_REGIONS = {
    "KH": ("Province", [("Phnom Penh", "Phnom Penh"), ("Siem Reap", "Siem Reap"),
        ("Battambang", "Battambang"), ("Kandal", "Ta Khmau"), ("Kampong Cham", "Kampong Cham")]),
    "LA": ("Province", [("Vientiane", "Vientiane"), ("Savannakhet", "Kaysone Phomvihane"),
        ("Champasak", "Pakse"), ("Luang Prabang", "Luang Prabang"), ("Khammouane", "Thakhek")]),
    "KP": ("Province", [("Pyongyang", "Pyongyang"), ("South Pyongan", "Pyongsong"),
        ("North Hamgyong", "Chongjin"), ("South Hamgyong", "Hamhung"), ("North Pyongan", "Sinuiju")]),
    "PG": ("Province", [("National Capital District", "Port Moresby"), ("Morobe", "Lae"),
        ("Eastern Highlands", "Goroka"), ("Western Highlands", "Mount Hagen"), ("East New Britain", "Kokopo")]),
    "TM": ("Region", [("Ashgabat", "Ashgabat"), ("Ahal", "Anau"), ("Mary", "Mary"),
        ("Lebap", "Türkmenabat"), ("Daşoguz", "Daşoguz")]),
    "KG": ("Region", [("Bishkek", "Bishkek"), ("Osh", "Osh"), ("Chüy", "Tokmok"),
        ("Jalal-Abad", "Jalal-Abad"), ("Issyk-Kul", "Karakol")]),
    "TL": ("Municipality", [("Dili", "Dili"), ("Baucau", "Baucau"), ("Ermera", "Gleno"),
        ("Bobonaro", "Maliana"), ("Liquiçá", "Liquiçá")]),
    "ER": ("Region", [("Maekel", "Asmara"), ("Anseba", "Keren"), ("Debub", "Mendefera"),
        ("Gash-Barka", "Barentu"), ("Northern Red Sea", "Massawa")]),
    "LR": ("County", [("Montserrado", "Monrovia"), ("Nimba", "Sanniquellie"),
        ("Bong", "Gbarnga"), ("Lofa", "Voinjama"), ("Margibi", "Kakata")]),
    "MR": ("Region", [("Nouakchott", "Nouakchott"), ("Trarza", "Rosso"),
        ("Hodh Ech Chargui", "Néma"), ("Adrar", "Atar"), ("Gorgol", "Kaédi")]),
    "GM": ("Region", [("Banjul", "Banjul"), ("West Coast", "Brikama"),
        ("North Bank", "Kerewan"), ("Lower River", "Mansa Konko"), ("Central River", "Janjanbureh")]),
    "GW": ("Region", [("Bissau", "Bissau"), ("Bafatá", "Bafatá"), ("Gabú", "Gabú"),
        ("Cacheu", "Cacheu"), ("Oio", "Farim")]),
    "GA": ("Province", [("Estuaire", "Libreville"), ("Haut-Ogooué", "Franceville"),
        ("Woleu-Ntem", "Oyem"), ("Ogooué-Maritime", "Port-Gentil"), ("Ngounié", "Mouila")]),
    "CG": ("Department", [("Brazzaville", "Brazzaville"), ("Pointe-Noire", "Pointe-Noire"),
        ("Niari", "Dolisie"), ("Bouenza", "Madingou"), ("Pool", "Kinkala")]),
    "CF": ("Prefecture", [("Bangui", "Bangui"), ("Ombella-M'Poko", "Bimbo"),
        ("Ouham", "Bossangoa"), ("Nana-Mambéré", "Bouar"), ("Ouaka", "Bambari")]),
    "BW": ("District", [("South-East", "Gaborone"), ("Central", "Serowe"),
        ("North-East", "Francistown"), ("Kweneng", "Molepolole"), ("North-West", "Maun")]),
    "NA": ("Region", [("Khomas", "Windhoek"), ("Erongo", "Swakopmund"),
        ("Oshana", "Oshakati"), ("Otjozondjupa", "Otjiwarongo"), ("Hardap", "Mariental")]),
    "LS": ("District", [("Maseru", "Maseru"), ("Leribe", "Hlotse"),
        ("Berea", "Teyateyaneng"), ("Mafeteng", "Mafeteng"), ("Mohale's Hoek", "Mohale's Hoek")]),
    "SZ": ("Region", [("Hhohho", "Mbabane"), ("Manzini", "Manzini"),
        ("Lubombo", "Siteki"), ("Shiselweni", "Nhlangano")]),
    "GQ": ("Province", [("Litoral", "Bata"), ("Bioko Norte", "Malabo"),
        ("Centro Sur", "Evinayong"), ("Kié-Ntem", "Ebebiyín"), ("Wele-Nzas", "Mongomo")]),
    "DJ": ("Region", [("Djibouti", "Djibouti City"), ("Ali Sabieh", "Ali Sabieh"),
        ("Dikhil", "Dikhil"), ("Tadjourah", "Tadjourah"), ("Obock", "Obock")]),
    "KM": ("Island", [("Grande Comore", "Moroni"), ("Anjouan", "Mutsamudu"),
        ("Mohéli", "Fomboni")]),
    "MV": ("Region", [("Malé", "Malé"), ("Addu City", "Hithadhoo"),
        ("Fuvahmulah", "Fuvahmulah"), ("Kulhudhuffushi", "Kulhudhuffushi")]),
    "BT": ("District", [("Thimphu", "Thimphu"), ("Paro", "Paro"), ("Chukha", "Phuentsholing"),
        ("Wangdue Phodrang", "Wangdue"), ("Sarpang", "Gelephu")]),
    "BN": ("District", [("Brunei-Muara", "Bandar Seri Begawan"), ("Belait", "Kuala Belait"),
        ("Tutong", "Tutong"), ("Temburong", "Bangar")]),
    "FJ": ("Division", [("Central", "Suva"), ("Western", "Lautoka"),
        ("Northern", "Labasa"), ("Eastern", "Levuka")]),
    "SB": ("Province", [("Guadalcanal", "Honiara"), ("Malaita", "Auki"),
        ("Western", "Gizo"), ("Makira-Ulawa", "Kirakira")]),
    "VU": ("Province", [("Shefa", "Port Vila"), ("Sanma", "Luganville"),
        ("Tafea", "Isangel"), ("Malampa", "Lakatoro")]),
    "WS": ("District", [("Tuamasaga", "Apia"), ("A'ana", "Leulumoega"),
        ("Atua", "Lufilufi"), ("Savai'i", "Salelologa")]),
    "TO": ("Division", [("Tongatapu", "Nuku'alofa"), ("Vava'u", "Neiafu"),
        ("Ha'apai", "Pangai"), ("'Eua", "'Ohonua")]),
    "MN": ("Province", [("Ulaanbaatar", "Ulaanbaatar"), ("Darkhan-Uul", "Darkhan"),
        ("Orkhon", "Erdenet"), ("Selenge", "Sükhbaatar"), ("Khövsgöl", "Mörön")]),
    "AM": ("Province", [("Yerevan", "Yerevan"), ("Shirak", "Gyumri"),
        ("Lori", "Vanadzor"), ("Kotayk", "Hrazdan"), ("Armavir", "Armavir")]),
    "GE": ("Region", [("Tbilisi", "Tbilisi"), ("Imereti", "Kutaisi"),
        ("Adjara", "Batumi"), ("Kvemo Kartli", "Rustavi"), ("Kakheti", "Telavi")]),
    "MD": ("District", [("Chișinău", "Chișinău"), ("Bălți", "Bălți"),
        ("Gagauzia", "Comrat"), ("Cahul", "Cahul"), ("Orhei", "Orhei")]),
    "AL": ("County", [("Tirana", "Tirana"), ("Durrës", "Durrës"),
        ("Vlorë", "Vlorë"), ("Shkodër", "Shkodër"), ("Elbasan", "Elbasan")]),
    "MK": ("Region", [("Skopje", "Skopje"), ("Bitola", "Bitola"),
        ("Kumanovo", "Kumanovo"), ("Prilep", "Prilep"), ("Tetovo", "Tetovo")]),
    "RS": ("District", [("Belgrade", "Belgrade"), ("Vojvodina", "Novi Sad"),
        ("Niš", "Niš"), ("Šumadija", "Kragujevac"), ("Zlatibor", "Užice")]),
    "BA": ("Region", [("Sarajevo", "Sarajevo"), ("Banja Luka", "Banja Luka"),
        ("Tuzla", "Tuzla"), ("Zenica", "Zenica"), ("Mostar", "Mostar")]),
    "ME": ("Municipality", [("Podgorica", "Podgorica"), ("Nikšić", "Nikšić"),
        ("Pljevlja", "Pljevlja"), ("Bar", "Bar"), ("Budva", "Budva")]),
    "BG": ("Province", [("Sofia", "Sofia"), ("Plovdiv", "Plovdiv"),
        ("Varna", "Varna"), ("Burgas", "Burgas"), ("Ruse", "Ruse")]),
    "RO": ("County", [("Bucharest", "Bucharest"), ("Cluj", "Cluj-Napoca"),
        ("Timiș", "Timișoara"), ("Iași", "Iași"), ("Constanța", "Constanța")]),
    "HU": ("County", [("Budapest", "Budapest"), ("Pest", "Érd"),
        ("Borsod-Abaúj-Zemplén", "Miskolc"), ("Hajdú-Bihar", "Debrecen"), ("Csongrád", "Szeged")]),
    "CZ": ("Region", [("Prague", "Prague"), ("South Moravian", "Brno"),
        ("Moravian-Silesian", "Ostrava"), ("Plzeň", "Plzeň"), ("Central Bohemian", "Kladno")]),
    "GR": ("Region", [("Attica", "Athens"), ("Central Macedonia", "Thessaloniki"),
        ("Thessaly", "Larissa"), ("Crete", "Heraklion"), ("Western Greece", "Patras")]),
    "PT": ("District", [("Lisbon", "Lisbon"), ("Porto", "Porto"),
        ("Braga", "Braga"), ("Aveiro", "Aveiro"), ("Faro", "Faro")]),
    "SE": ("County", [("Stockholm", "Stockholm"), ("Västra Götaland", "Gothenburg"),
        ("Skåne", "Malmö"), ("Uppsala", "Uppsala"), ("Östergötland", "Linköping")]),
    "NO": ("County", [("Oslo", "Oslo"), ("Vestland", "Bergen"),
        ("Trøndelag", "Trondheim"), ("Rogaland", "Stavanger"), ("Viken", "Drammen")]),
    "FI": ("Region", [("Uusimaa", "Helsinki"), ("Pirkanmaa", "Tampere"),
        ("Southwest Finland", "Turku"), ("North Ostrobothnia", "Oulu"), ("Päijänne Tavastia", "Lahti")]),
    "DK": ("Region", [("Capital", "Copenhagen"), ("Central Denmark", "Aarhus"),
        ("Southern Denmark", "Odense"), ("North Denmark", "Aalborg"), ("Zealand", "Roskilde")]),
    "IE": ("County", [("Dublin", "Dublin"), ("Cork", "Cork"),
        ("Galway", "Galway"), ("Limerick", "Limerick"), ("Waterford", "Waterford")]),
    "AT": ("State", [("Vienna", "Vienna"), ("Styria", "Graz"),
        ("Upper Austria", "Linz"), ("Salzburg", "Salzburg"), ("Tyrol", "Innsbruck")]),
    "CH": ("Canton", [("Zürich", "Zürich"), ("Geneva", "Geneva"),
        ("Bern", "Bern"), ("Vaud", "Lausanne"), ("Basel-Stadt", "Basel")]),
    "BE": ("Province", [("Brussels", "Brussels"), ("Antwerp", "Antwerp"),
        ("East Flanders", "Ghent"), ("Liège", "Liège"), ("West Flanders", "Bruges")]),
    "BY": ("Region", [("Minsk", "Minsk"), ("Gomel", "Gomel"),
        ("Mogilev", "Mogilev"), ("Vitebsk", "Vitebsk"), ("Brest", "Brest")]),
    "SK": ("Region", [("Bratislava", "Bratislava"), ("Košice", "Košice"),
        ("Prešov", "Prešov"), ("Žilina", "Žilina"), ("Nitra", "Nitra")]),
    "HR": ("County", [("Zagreb", "Zagreb"), ("Split-Dalmatia", "Split"),
        ("Primorje-Gorski Kotar", "Rijeka"), ("Osijek-Baranja", "Osijek"), ("Istria", "Pula")]),
    "LT": ("County", [("Vilnius", "Vilnius"), ("Kaunas", "Kaunas"),
        ("Klaipėda", "Klaipėda"), ("Šiauliai", "Šiauliai"), ("Panevėžys", "Panevėžys")]),
    "LV": ("Region", [("Riga", "Riga"), ("Latgale", "Daugavpils"),
        ("Kurzeme", "Liepāja"), ("Vidzeme", "Valmiera"), ("Zemgale", "Jelgava")]),
    "EE": ("County", [("Harju", "Tallinn"), ("Tartu", "Tartu"),
        ("Ida-Viru", "Narva"), ("Pärnu", "Pärnu"), ("Lääne-Viru", "Rakvere")]),
    "SI": ("Region", [("Central Slovenia", "Ljubljana"), ("Drava", "Maribor"),
        ("Savinja", "Celje"), ("Upper Carniola", "Kranj"), ("Coastal-Karst", "Koper")]),
    "IL": ("District", [("Tel Aviv", "Tel Aviv"), ("Jerusalem", "Jerusalem"),
        ("Haifa", "Haifa"), ("Central", "Petah Tikva"), ("Southern", "Beersheba")]),
    "LB": ("Governorate", [("Beirut", "Beirut"), ("Mount Lebanon", "Baabda"),
        ("North", "Tripoli"), ("South", "Sidon"), ("Bekaa", "Zahlé")]),
    "OM": ("Governorate", [("Muscat", "Muscat"), ("Dhofar", "Salalah"),
        ("Al Batinah North", "Sohar"), ("Ad Dakhiliyah", "Nizwa"), ("Al Buraimi", "Al Buraimi")]),
    "KW": ("Governorate", [("Al Asimah", "Kuwait City"), ("Hawalli", "Hawalli"),
        ("Farwaniya", "Al Farwaniyah"), ("Ahmadi", "Al Ahmadi"), ("Jahra", "Al Jahra")]),
    "QA": ("Municipality", [("Doha", "Doha"), ("Al Rayyan", "Al Rayyan"),
        ("Al Wakrah", "Al Wakrah"), ("Al Khor", "Al Khor"), ("Umm Salal", "Umm Salal")]),
    "BH": ("Governorate", [("Capital", "Manama"), ("Muharraq", "Muharraq"),
        ("Northern", "Diraz"), ("Southern", "Riffa")]),
    "AE": ("Emirate", [("Abu Dhabi", "Abu Dhabi"), ("Dubai", "Dubai"),
        ("Sharjah", "Sharjah"), ("Ajman", "Ajman"), ("Ras Al Khaimah", "Ras Al Khaimah")]),
    "SG": ("Region", [("Central", "Singapore"), ("East", "Bedok"),
        ("North", "Woodlands"), ("North-East", "Hougang"), ("West", "Jurong")]),
    "TW": ("City", [("Taipei", "Taipei"), ("New Taipei", "Banqiao"),
        ("Taichung", "Taichung"), ("Kaohsiung", "Kaohsiung"), ("Tainan", "Tainan")]),
    "MU": ("District", [("Port Louis", "Port Louis"), ("Plaines Wilhems", "Quatre Bornes"),
        ("Flacq", "Centre de Flacq"), ("Grand Port", "Mahébourg"), ("Pamplemousses", "Triolet")]),
    "SC": ("District", [("Greater Victoria", "Victoria"), ("Anse Boileau", "Anse Boileau"),
        ("Beau Vallon", "Beau Vallon"), ("Praslin", "Baie Sainte Anne")]),
    "CV": ("Municipality", [("Praia", "Praia"), ("São Vicente", "Mindelo"),
        ("Santa Catarina", "Assomada"), ("Sal", "Espargos")]),
    "ST": ("District", [("Água Grande", "São Tomé"), ("Mé-Zóchi", "Trindade"),
        ("Lobata", "Guadalupe"), ("Príncipe", "Santo António")]),
    "TT": ("Region", [("Port of Spain", "Port of Spain"), ("San Fernando", "San Fernando"),
        ("Chaguanas", "Chaguanas"), ("Arima", "Arima"), ("Tobago", "Scarborough")]),
    "JM": ("Parish", [("Kingston", "Kingston"), ("St. Andrew", "Half Way Tree"),
        ("St. James", "Montego Bay"), ("Clarendon", "May Pen"), ("St. Catherine", "Spanish Town")]),
    "BS": ("District", [("New Providence", "Nassau"), ("Grand Bahama", "Freeport"),
        ("Abaco", "Marsh Harbour"), ("Eleuthera", "Governor's Harbour")]),
    "BB": ("Parish", [("Saint Michael", "Bridgetown"), ("Christ Church", "Oistins"),
        ("Saint Philip", "Crane"), ("Saint James", "Holetown")]),
    "BZ": ("District", [("Belize", "Belize City"), ("Cayo", "San Ignacio"),
        ("Orange Walk", "Orange Walk Town"), ("Corozal", "Corozal Town"), ("Stann Creek", "Dangriga")]),
    "GY": ("Region", [("Demerara-Mahaica", "Georgetown"), ("East Berbice-Corentyne", "New Amsterdam"),
        ("Essequibo Islands-West Demerara", "Vreed en Hoop"), ("Cuyuni-Mazaruni", "Bartica")]),
    "SR": ("District", [("Paramaribo", "Paramaribo"), ("Wanica", "Lelydorp"),
        ("Nickerie", "Nieuw Nickerie"), ("Commewijne", "Nieuw Amsterdam")]),
    "UY": ("Department", [("Montevideo", "Montevideo"), ("Canelones", "Canelones"),
        ("Maldonado", "Maldonado"), ("Salto", "Salto"), ("Paysandú", "Paysandú")]),
    "CR": ("Province", [("San José", "San José"), ("Alajuela", "Alajuela"),
        ("Cartago", "Cartago"), ("Heredia", "Heredia"), ("Puntarenas", "Puntarenas")]),
    "PA": ("Province", [("Panamá", "Panama City"), ("Colón", "Colón"),
        ("Chiriquí", "David"), ("Veraguas", "Santiago"), ("Coclé", "Penonomé")]),
    "CU": ("Province", [("Havana", "Havana"), ("Santiago de Cuba", "Santiago de Cuba"),
        ("Holguín", "Holguín"), ("Camagüey", "Camagüey"), ("Villa Clara", "Santa Clara")]),
    "MT": ("Region", [("Northern Harbour", "Birkirkara"), ("Southern Harbour", "Valletta"),
        ("Northern", "Mosta"), ("Gozo", "Victoria")]),
    "CY": ("District", [("Nicosia", "Nicosia"), ("Limassol", "Limassol"),
        ("Larnaca", "Larnaca"), ("Paphos", "Paphos"), ("Famagusta", "Paralimni")]),
    "IS": ("Region", [("Capital Region", "Reykjavík"), ("Southern Peninsula", "Keflavík"),
        ("Northeast", "Akureyri"), ("South", "Selfoss")]),
    "LU": ("Canton", [("Luxembourg", "Luxembourg City"), ("Esch-sur-Alzette", "Esch-sur-Alzette"),
        ("Diekirch", "Diekirch"), ("Grevenmacher", "Grevenmacher")]),
    "FM": ("State", [("Pohnpei", "Palikir"), ("Chuuk", "Weno"),
        ("Yap", "Colonia"), ("Kosrae", "Tofol")]),
    "KI": ("Region", [("South Tarawa", "Tarawa"), ("Line Islands", "London"),
        ("Phoenix Islands", "Kanton")]),
    "MH": ("Atoll", [("Majuro", "Majuro"), ("Kwajalein", "Ebeye"),
        ("Jaluit", "Jabor")]),
    "PW": ("State", [("Koror", "Koror"), ("Airai", "Airai"), ("Melekeok", "Ngerulmud")]),
    "NR": ("District", [("Yaren", "Yaren"), ("Aiwo", "Aiwo"), ("Anabar", "Anabar")]),
    "TV": ("Island", [("Funafuti", "Funafuti"), ("Vaitupu", "Asau"), ("Nanumea", "Nanumea")]),
    "AD": ("Parish", [("Andorra la Vella", "Andorra la Vella"), ("Escaldes-Engordany", "Escaldes-Engordany"),
        ("Encamp", "Encamp"), ("Sant Julià de Lòria", "Sant Julià de Lòria")]),
    "MC": ("Ward", [("Monte Carlo", "Monte Carlo"), ("La Condamine", "La Condamine"),
        ("Fontvieille", "Fontvieille")]),
    "LI": ("Municipality", [("Vaduz", "Vaduz"), ("Schaan", "Schaan"),
        ("Triesen", "Triesen"), ("Balzers", "Balzers")]),
    "SM": ("Municipality", [("San Marino", "San Marino"), ("Serravalle", "Serravalle"),
        ("Borgo Maggiore", "Borgo Maggiore")]),
    "VA": ("Area", [("Vatican City", "Vatican City")]),
    "AG": ("Parish", [("Saint John", "St. John's"), ("Saint George", "Piggotts"),
        ("Saint Mary", "Bolans"), ("Barbuda", "Codrington")]),
    "DM": ("Parish", [("Saint George", "Roseau"), ("Saint Andrew", "Marigot"),
        ("Saint Paul", "Pont Cassé")]),
    "GD": ("Parish", [("Saint George", "St. George's"), ("Saint Andrew", "Grenville"),
        ("Saint David", "St. David's")]),
    "KN": ("Parish", [("Saint George Basseterre", "Basseterre"), ("Christ Church Nichola Town", "Nichola Town"),
        ("Saint Paul Charlestown", "Charlestown")]),
    "LC": ("District", [("Castries", "Castries"), ("Gros Islet", "Gros Islet"),
        ("Vieux Fort", "Vieux Fort"), ("Soufrière", "Soufrière")]),
    "VC": ("Parish", [("Saint George", "Kingstown"), ("Charlotte", "Georgetown"),
        ("Grenadines", "Port Elizabeth")]),
    "NZ": ("Region", [("Auckland", "Auckland"), ("Wellington", "Wellington"),
        ("Canterbury", "Christchurch"), ("Waikato", "Hamilton"), ("Otago", "Dunedin")]),
}


def _expand_simple(code, label, regions):
    """Turn a simple [(name, city)] list into the prefixed-dict format, using a
    short numeric suffix for the region code."""
    out = {}
    for i, (name, city) in enumerate(regions, 1):
        out[f"{code}-{i:02d}"] = (name, city)
    return label, out







# Country registry for clickable drill-down countries in the global view.
# 15 countries are clickable; the rest of the global roster is "data pending".
COUNTRY_REGIONS = {
    "US": {"name": "United States", "region_label": "State", "regions": STATES},
    "CN": {"name": "China", "region_label": "Province", "regions": CN_PROVINCES},
    "IN": {"name": "India", "region_label": "State", "regions": IN_STATES},
    "ID": {"name": "Indonesia", "region_label": "Province", "regions": ID_PROVINCES},
    "PK": {"name": "Pakistan", "region_label": "Province", "regions": PK_PROVINCES},
    "BR": {"name": "Brazil", "region_label": "State", "regions": BR_STATES},
    "NG": {"name": "Nigeria", "region_label": "State", "regions": NG_STATES},
    "PH": {"name": "Philippines", "region_label": "Region", "regions": PH_REGIONS},
    "EG": {"name": "Egypt", "region_label": "Governorate", "regions": EG_GOVERNORATES},
    "MX": {"name": "Mexico", "region_label": "State", "regions": MX_STATES},
    "JP": {"name": "Japan", "region_label": "Prefecture", "regions": JP_PREFECTURES},
    "DE": {"name": "Germany", "region_label": "State", "regions": DE_STATES},
    "GB": {"name": "United Kingdom", "region_label": "Region", "regions": GB_REGIONS},
    "ZA": {"name": "South Africa", "region_label": "Province", "regions": ZA_PROVINCES},
    "KE": {"name": "Kenya", "region_label": "County", "regions": KE_COUNTIES},
    # ----- Batch 1 -----
    "RU": {"name": "Russia", "region_label": "Region", "regions": RU_REGIONS},
    "BD": {"name": "Bangladesh", "region_label": "Division", "regions": BD_DIVISIONS},
    "ET": {"name": "Ethiopia", "region_label": "Region", "regions": ET_REGIONS},
    "VN": {"name": "Vietnam", "region_label": "Province", "regions": VN_REGIONS},
    "IR": {"name": "Iran", "region_label": "Province", "regions": IR_PROVINCES},
    "TR": {"name": "Turkey", "region_label": "Province", "regions": TR_PROVINCES},
    "FR": {"name": "France", "region_label": "Region", "regions": FR_REGIONS},
    "IT": {"name": "Italy", "region_label": "Region", "regions": IT_REGIONS},
    "TH": {"name": "Thailand", "region_label": "Province", "regions": TH_REGIONS},
    "CD": {"name": "DR Congo", "region_label": "Province", "regions": CD_PROVINCES},
    "KR": {"name": "South Korea", "region_label": "Region", "regions": KR_REGIONS},
    "ES": {"name": "Spain", "region_label": "Region", "regions": ES_REGIONS},
    "AR": {"name": "Argentina", "region_label": "Province", "regions": AR_PROVINCES},
    "CO": {"name": "Colombia", "region_label": "Department", "regions": CO_DEPARTMENTS},
    "CA": {"name": "Canada", "region_label": "Province", "regions": CA_PROVINCES},
    # ----- Batch 2 -----
    "MM": {"name": "Myanmar", "region_label": "Region", "regions": MM_REGIONS},
    "UG": {"name": "Uganda", "region_label": "District", "regions": UG_REGIONS},
    "DZ": {"name": "Algeria", "region_label": "Province", "regions": DZ_PROVINCES},
    "UA": {"name": "Ukraine", "region_label": "Oblast", "regions": UA_OBLASTS},
    "PL": {"name": "Poland", "region_label": "Voivodeship", "regions": PL_VOIVODESHIPS},
    "MA": {"name": "Morocco", "region_label": "Region", "regions": MA_REGIONS},
    "SA": {"name": "Saudi Arabia", "region_label": "Region", "regions": SA_REGIONS},
    "PE": {"name": "Peru", "region_label": "Region", "regions": PE_REGIONS},
    "MY": {"name": "Malaysia", "region_label": "State", "regions": MY_STATES},
    "GH": {"name": "Ghana", "region_label": "Region", "regions": GH_REGIONS},
    "MZ": {"name": "Mozambique", "region_label": "Province", "regions": MZ_PROVINCES},
    "AU": {"name": "Australia", "region_label": "State", "regions": AU_STATES},
    "MG": {"name": "Madagascar", "region_label": "Region", "regions": MG_REGIONS},
    "CL": {"name": "Chile", "region_label": "Region", "regions": CL_REGIONS},
    "NL": {"name": "Netherlands", "region_label": "Province", "regions": NL_PROVINCES},
    "EC": {"name": "Ecuador", "region_label": "Province", "regions": EC_PROVINCES},
    "GT": {"name": "Guatemala", "region_label": "Department", "regions": GT_DEPARTMENTS},
    "SN": {"name": "Senegal", "region_label": "Region", "regions": SN_REGIONS},
    "BO": {"name": "Bolivia", "region_label": "Department", "regions": BO_DEPARTMENTS},
    "RW": {"name": "Rwanda", "region_label": "Province", "regions": RW_PROVINCES},
    # ----- Batch 3 -----
    "AF": {"name": "Afghanistan", "region_label": "Province", "regions": AF_PROVINCES},
    "AO": {"name": "Angola", "region_label": "Province", "regions": AO_PROVINCES},
    "YE": {"name": "Yemen", "region_label": "Governorate", "regions": YE_GOVERNORATES},
    "SY": {"name": "Syria", "region_label": "Governorate", "regions": SY_GOVERNORATES},
    "SD": {"name": "Sudan", "region_label": "State", "regions": SD_STATES},
    "SS": {"name": "South Sudan", "region_label": "State", "regions": SS_STATES},
    "IQ": {"name": "Iraq", "region_label": "Governorate", "regions": IQ_GOVERNORATES},
    "UZ": {"name": "Uzbekistan", "region_label": "Region", "regions": UZ_REGIONS},
    "KZ": {"name": "Kazakhstan", "region_label": "Region", "regions": KZ_REGIONS},
    "NP": {"name": "Nepal", "region_label": "Province", "regions": NP_PROVINCES},
    "VE": {"name": "Venezuela", "region_label": "State", "regions": VE_STATES},
    "LK": {"name": "Sri Lanka", "region_label": "Province", "regions": LK_PROVINCES},
    "ML": {"name": "Mali", "region_label": "Region", "regions": ML_REGIONS},
    "BF": {"name": "Burkina Faso", "region_label": "Region", "regions": BF_REGIONS},
    "NE": {"name": "Niger", "region_label": "Region", "regions": NE_REGIONS},
    "MW": {"name": "Malawi", "region_label": "Region", "regions": MW_REGIONS},
    "ZM": {"name": "Zambia", "region_label": "Province", "regions": ZM_PROVINCES},
    "ZW": {"name": "Zimbabwe", "region_label": "Province", "regions": ZW_PROVINCES},
    "TD": {"name": "Chad", "region_label": "Region", "regions": TD_REGIONS},
    "SO": {"name": "Somalia", "region_label": "Region", "regions": SO_REGIONS},
    # ----- Batch 4 -----
    "TN": {"name": "Tunisia", "region_label": "Governorate", "regions": TN_GOVERNORATES},
    "GN": {"name": "Guinea", "region_label": "Region", "regions": GN_REGIONS},
    "BJ": {"name": "Benin", "region_label": "Department", "regions": BJ_DEPARTMENTS},
    "BI": {"name": "Burundi", "region_label": "Province", "regions": BI_PROVINCES},
    "SL": {"name": "Sierra Leone", "region_label": "Province", "regions": SL_PROVINCES},
    "TG": {"name": "Togo", "region_label": "Region", "regions": TG_REGIONS},
    "LY": {"name": "Libya", "region_label": "District", "regions": LY_DISTRICTS},
    "JO": {"name": "Jordan", "region_label": "Governorate", "regions": JO_GOVERNORATES},
    "AZ": {"name": "Azerbaijan", "region_label": "Region", "regions": AZ_REGIONS},
    "TJ": {"name": "Tajikistan", "region_label": "Region", "regions": TJ_REGIONS},
    "HT": {"name": "Haiti", "region_label": "Department", "regions": HT_DEPARTMENTS},
    "DO": {"name": "Dominican Republic", "region_label": "Province", "regions": DO_PROVINCES},
    "HN": {"name": "Honduras", "region_label": "Department", "regions": HN_DEPARTMENTS},
    "NI": {"name": "Nicaragua", "region_label": "Department", "regions": NI_DEPARTMENTS},
    "PY": {"name": "Paraguay", "region_label": "Department", "regions": PY_DEPARTMENTS},
    "SV": {"name": "El Salvador", "region_label": "Department", "regions": SV_DEPARTMENTS},
    "CM": {"name": "Cameroon", "region_label": "Region", "regions": CM_REGIONS},
}


# Map every drill-down region code prefix to its region map, so generated job
# ids (e.g. "IN-MH-GEN-0003") can be recovered to their region.
def region_map_for_code(region_code):
    """Given a region code like 'IN-MH' or 'WA', return (country_code, region_map)
    or (None, None) if not a known drill-down region."""
    if region_code in STATES:
        return ("US", STATES)
    for ccode, cfg in COUNTRY_REGIONS.items():
        if ccode == "US":
            continue
        if region_code in cfg["regions"]:
            return (ccode, cfg["regions"])
    return (None, None)


# ---- Global / world roster --------------------------------------------------
# 50+ nations for the world tab. Numbers are ILLUSTRATIVE, not real statistics.
# They are derived from (population, development_gap) so the relative ordering
# is defensible: project volume scales with how many people there are AND how
# large the unmet-infrastructure gap is. High-population + high-gap nations
# (India, China, Nigeria, Indonesia...) land near the top; wealthy low-gap
# nations (Sweden, Norway...) land lower. The US is substantial but NOT #1.
#
# _NATIONS: (code, name, population_millions, development_gap 0-1)
#   development_gap ~ share of basic infrastructure need still unmet
#   (low for high-income countries, high for low-income / developing).
_NATIONS = [
    ("IN", "India", 1430, 0.46), ("CN", "China", 1410, 0.30),
    ("US", "United States", 335, 0.18), ("ID", "Indonesia", 278, 0.42),
    ("PK", "Pakistan", 240, 0.55), ("NG", "Nigeria", 224, 0.62),
    ("BR", "Brazil", 216, 0.40), ("BD", "Bangladesh", 173, 0.54),
    ("RU", "Russia", 144, 0.28), ("MX", "Mexico", 128, 0.38),
    ("ET", "Ethiopia", 126, 0.66), ("JP", "Japan", 123, 0.12),
    ("PH", "Philippines", 117, 0.48), ("EG", "Egypt", 113, 0.50),
    ("CD", "DR Congo", 102, 0.72), ("VN", "Vietnam", 99, 0.44),
    ("IR", "Iran", 89, 0.45), ("TR", "Turkey", 85, 0.34),
    ("DE", "Germany", 84, 0.10), ("TH", "Thailand", 72, 0.38),
    ("GB", "United Kingdom", 68, 0.12), ("TZ", "Tanzania", 67, 0.64),
    ("FR", "France", 65, 0.11), ("ZA", "South Africa", 60, 0.47),
    ("IT", "Italy", 59, 0.14), ("KE", "Kenya", 55, 0.60),
    ("MM", "Myanmar", 54, 0.58), ("CO", "Colombia", 52, 0.41),
    ("KR", "South Korea", 52, 0.13), ("ES", "Spain", 48, 0.14),
    ("UG", "Uganda", 48, 0.65), ("AR", "Argentina", 46, 0.33),
    ("DZ", "Algeria", 45, 0.44), ("UA", "Ukraine", 38, 0.40),
    ("PL", "Poland", 38, 0.20), ("CA", "Canada", 40, 0.11),
    ("MA", "Morocco", 38, 0.46), ("SA", "Saudi Arabia", 37, 0.26),
    ("PE", "Peru", 34, 0.45), ("MY", "Malaysia", 34, 0.30),
    ("GH", "Ghana", 34, 0.58), ("MZ", "Mozambique", 33, 0.70),
    ("AU", "Australia", 26, 0.10), ("MG", "Madagascar", 30, 0.71),
    ("CL", "Chile", 20, 0.27), ("NL", "Netherlands", 18, 0.09),
    ("EC", "Ecuador", 18, 0.43), ("GT", "Guatemala", 18, 0.55),
    ("SN", "Senegal", 18, 0.59), ("SE", "Sweden", 11, 0.08),
    ("BO", "Bolivia", 12, 0.52), ("RW", "Rwanda", 14, 0.61),
    ("NO", "Norway", 5, 0.07), ("NZ", "New Zealand", 5, 0.10),
    # ---- remaining countries (illustrative pop in millions + dev gap) -------
    # Added so the global roster lists ~all nations. Countries without a built
    # region map open to a contributor template page (see COUNTRY_REGIONS).
    ("AF", "Afghanistan", 42, 0.74), ("AO", "Angola", 36, 0.66),
    ("AL", "Albania", 3, 0.24), ("AD", "Andorra", 0.08, 0.06),
    ("AE", "United Arab Emirates", 9, 0.10), ("AG", "Antigua and Barbuda", 0.09, 0.22),
    ("AM", "Armenia", 3, 0.26), ("AT", "Austria", 9, 0.08),
    ("AZ", "Azerbaijan", 10, 0.30), ("BS", "Bahamas", 0.4, 0.18),
    ("BH", "Bahrain", 1.5, 0.12), ("BB", "Barbados", 0.3, 0.18),
    ("BY", "Belarus", 9, 0.20), ("BE", "Belgium", 12, 0.08),
    ("BZ", "Belize", 0.4, 0.40), ("BJ", "Benin", 13, 0.62),
    ("BT", "Bhutan", 0.8, 0.45), ("BA", "Bosnia and Herzegovina", 3, 0.26),
    ("BW", "Botswana", 2.6, 0.40), ("BN", "Brunei", 0.4, 0.12),
    ("BG", "Bulgaria", 6.5, 0.20), ("BF", "Burkina Faso", 23, 0.68),
    ("BI", "Burundi", 13, 0.73), ("CV", "Cabo Verde", 0.6, 0.40),
    ("KH", "Cambodia", 17, 0.52), ("CM", "Cameroon", 28, 0.62),
    ("CF", "Central African Republic", 5, 0.78), ("TD", "Chad", 18, 0.75),
    ("KM", "Comoros", 0.9, 0.62), ("CG", "Republic of the Congo", 6, 0.62),
    ("CR", "Costa Rica", 5, 0.24), ("HR", "Croatia", 4, 0.16),
    ("CU", "Cuba", 11, 0.34), ("CY", "Cyprus", 1.2, 0.14),
    ("CZ", "Czechia", 11, 0.12), ("DK", "Denmark", 6, 0.07),
    ("DJ", "Djibouti", 1.1, 0.60), ("DM", "Dominica", 0.07, 0.26),
    ("DO", "Dominican Republic", 11, 0.38), ("TL", "Timor-Leste", 1.3, 0.58),
    ("SV", "El Salvador", 6, 0.46), ("GQ", "Equatorial Guinea", 1.7, 0.60),
    ("ER", "Eritrea", 3.6, 0.72), ("EE", "Estonia", 1.3, 0.12),
    ("SZ", "Eswatini", 1.2, 0.54), ("FJ", "Fiji", 0.9, 0.40),
    ("FI", "Finland", 5.5, 0.07), ("GA", "Gabon", 2.4, 0.48),
    ("GM", "Gambia", 2.7, 0.64), ("GE", "Georgia", 3.7, 0.28),
    ("GR", "Greece", 10, 0.16), ("GD", "Grenada", 0.1, 0.26),
    ("GN", "Guinea", 14, 0.70), ("GW", "Guinea-Bissau", 2, 0.72),
    ("GY", "Guyana", 0.8, 0.42), ("HT", "Haiti", 11.5, 0.72),
    ("HN", "Honduras", 10, 0.52), ("HU", "Hungary", 9.6, 0.16),
    ("IS", "Iceland", 0.4, 0.06), ("IQ", "Iraq", 44, 0.52),
    ("IE", "Ireland", 5, 0.08), ("IL", "Israel", 9.5, 0.12),
    ("JM", "Jamaica", 2.8, 0.36), ("JO", "Jordan", 11, 0.38),
    ("KZ", "Kazakhstan", 19, 0.28), ("KI", "Kiribati", 0.13, 0.58),
    ("KP", "North Korea", 26, 0.62), ("KW", "Kuwait", 4.3, 0.12),
    ("KG", "Kyrgyzstan", 7, 0.42), ("LA", "Laos", 7.5, 0.54),
    ("LV", "Latvia", 1.8, 0.14), ("LB", "Lebanon", 5.5, 0.44),
    ("LS", "Lesotho", 2.3, 0.60), ("LR", "Liberia", 5.3, 0.70),
    ("LY", "Libya", 7, 0.46), ("LI", "Liechtenstein", 0.04, 0.06),
    ("LT", "Lithuania", 2.8, 0.14), ("LU", "Luxembourg", 0.65, 0.06),
    ("MW", "Malawi", 21, 0.68), ("MV", "Maldives", 0.5, 0.30),
    ("ML", "Mali", 23, 0.70), ("MT", "Malta", 0.5, 0.12),
    ("MH", "Marshall Islands", 0.04, 0.52), ("MR", "Mauritania", 5, 0.62),
    ("MU", "Mauritius", 1.3, 0.24), ("FM", "Micronesia", 0.11, 0.52),
    ("MD", "Moldova", 3.4, 0.34), ("MC", "Monaco", 0.04, 0.05),
    ("MN", "Mongolia", 3.4, 0.42), ("ME", "Montenegro", 0.6, 0.22),
    ("NA", "Namibia", 2.6, 0.46), ("NR", "Nauru", 0.01, 0.50),
    ("NP", "Nepal", 30, 0.56), ("NI", "Nicaragua", 7, 0.50),
    ("NE", "Niger", 26, 0.74), ("MK", "North Macedonia", 2, 0.24),
    ("OM", "Oman", 4.6, 0.18), ("PW", "Palau", 0.018, 0.40),
    ("PA", "Panama", 4.4, 0.30), ("PG", "Papua New Guinea", 10, 0.62),
    ("PY", "Paraguay", 7, 0.40), ("PT", "Portugal", 10, 0.14),
    ("QA", "Qatar", 2.7, 0.10), ("RO", "Romania", 19, 0.22),
    ("WS", "Samoa", 0.2, 0.42), ("SM", "San Marino", 0.03, 0.06),
    ("ST", "Sao Tome and Principe", 0.23, 0.56), ("RS", "Serbia", 6.6, 0.24),
    ("SC", "Seychelles", 0.1, 0.22), ("SL", "Sierra Leone", 8.4, 0.70),
    ("SG", "Singapore", 5.9, 0.07), ("SK", "Slovakia", 5.4, 0.14),
    ("SI", "Slovenia", 2.1, 0.10), ("SB", "Solomon Islands", 0.7, 0.60),
    ("SO", "Somalia", 18, 0.78), ("SS", "South Sudan", 11, 0.80),
    ("LK", "Sri Lanka", 22, 0.40), ("KN", "Saint Kitts and Nevis", 0.05, 0.24),
    ("LC", "Saint Lucia", 0.18, 0.28), ("VC", "Saint Vincent and the Grenadines", 0.1, 0.30),
    ("SD", "Sudan", 48, 0.70), ("SR", "Suriname", 0.6, 0.42),
    ("CH", "Switzerland", 8.8, 0.06), ("SY", "Syria", 22, 0.66),
    ("TW", "Taiwan", 23, 0.12), ("TJ", "Tajikistan", 10, 0.48),
    ("TG", "Togo", 8.8, 0.64), ("TO", "Tonga", 0.1, 0.42),
    ("TT", "Trinidad and Tobago", 1.5, 0.26), ("TN", "Tunisia", 12, 0.40),
    ("TM", "Turkmenistan", 6.4, 0.44), ("TV", "Tuvalu", 0.011, 0.54),
    ("UY", "Uruguay", 3.4, 0.22), ("UZ", "Uzbekistan", 35, 0.40),
    ("VU", "Vanuatu", 0.3, 0.56), ("VA", "Vatican City", 0.001, 0.05),
    ("VE", "Venezuela", 28, 0.50), ("YE", "Yemen", 34, 0.74),
    ("ZM", "Zambia", 20, 0.64), ("ZW", "Zimbabwe", 16, 0.62),
]


def _build_countries():
    out = []
    rng = random.Random("aedis-world")  # stable jitter
    for code, name, pop_m, gap in _NATIONS:
        # base project volume ~ population * gap, scaled to readable numbers,
        # with mild jitter so it doesn't look mechanically uniform.
        base = pop_m * gap
        projects = int(base * 2.2 * rng.uniform(0.9, 1.1)) + 30
        # flagged scales with gap (weaker institutions -> more caught issues)
        flagged = int(projects * (0.005 + gap * 0.03) * rng.uniform(0.8, 1.2))
        # funds scale with projects but higher-income (low-gap) spend more/project
        per_project = 6_000_000 + (1 - gap) * 28_000_000
        funds = int(projects * per_project * rng.uniform(0.9, 1.1))
        out.append({"code": code, "name": name, "projects": projects,
                    "flagged": flagged, "funds": funds})
    # sort by project volume desc for display
    out.sort(key=lambda c: -c["projects"])
    return out


COUNTRIES = _build_countries()


# ---- Register remaining drill-down countries (after _NATIONS/COUNTRIES) ------
# Côte d'Ivoire (hand-authored map) + all BATCH 5 simple-region countries.
COUNTRY_REGIONS["CI"] = {"name": "Côte d'Ivoire", "region_label": "District",
                          "regions": CI_DISTRICTS}
COUNTRY_REGIONS["TZ"] = {"name": "Tanzania", "region_label": "Region",
                          "regions": TZ_REGIONS}
# Côte d'Ivoire isn't in _NATIONS; add it so it appears in the global roster.
if not any(n[0] == "CI" for n in _NATIONS):
    _NATIONS.append(("CI", "Côte d'Ivoire", 28, 0.58))
    COUNTRIES = _build_countries()

_ROSTER_NAMES = {code: name for code, name, pop, gap in _NATIONS}
for _code, (_label, _regions) in _SIMPLE_REGIONS.items():
    _lbl, _rmap = _expand_simple(_code, _label, _regions)
    COUNTRY_REGIONS[_code] = {
        "name": _ROSTER_NAMES.get(_code, _code),
        "region_label": _lbl,
        "regions": _rmap,
    }