def resolve_country(ip_address: str | None) -> str:
    """
    Resolves client IP address to a country name.
    For local/demo testing, identifies private/localhost IPs cleanly.
    Returns 'Unknown' if IP is missing or unresolvable.
    
    This function is isolated so it can later be replaced with a GeoIP provider.
    """
    if not ip_address:
        return "Unknown"

    cleaned_ip = ip_address.strip()
    
    # Check for localhost / loopback addresses
    if cleaned_ip in ("127.0.0.1", "::1", "localhost", "testclient"):
        return "Local / Demo"

    # Check for common private IP ranges
    if (
        cleaned_ip.startswith("10.") or
        cleaned_ip.startswith("192.168.") or
        cleaned_ip.startswith("172.16.") or
        cleaned_ip.startswith("172.17.") or
        cleaned_ip.startswith("172.18.") or
        cleaned_ip.startswith("172.19.") or
        cleaned_ip.startswith("172.20.") or
        cleaned_ip.startswith("172.21.") or
        cleaned_ip.startswith("172.22.") or
        cleaned_ip.startswith("172.23.") or
        cleaned_ip.startswith("172.24.") or
        cleaned_ip.startswith("172.25.") or
        cleaned_ip.startswith("172.26.") or
        cleaned_ip.startswith("172.27.") or
        cleaned_ip.startswith("172.28.") or
        cleaned_ip.startswith("172.29.") or
        cleaned_ip.startswith("172.30.") or
        cleaned_ip.startswith("172.31.")
    ):
        return "Local / Demo"

    return "Unknown"

    return "Unknown"