matrice-compute 0.1.19__py3-none-any.whl → 0.1.21__py3-none-any.whl

matrice_compute/instance_utils.py

@@ -95,28 +95,72 @@ def get_instance_info(service_provider: str = None, instance_id: str = None) ->
     return str(auto_service_provider), str(auto_instance_id)
 
 
+def _normalize_timestamp(timestamp_str: str) -> str:
+    """
+    Normalize timestamp string to handle different precision levels.
+    
+    Handles nanoseconds (9 digits), microseconds (6 digits), milliseconds (3 digits),
+    and various timezone formats across different cloud providers.
+    
+    Args:
+        timestamp_str (str): Timestamp string in various formats
+        
+    Returns:
+        str: Normalized timestamp string compatible with fromisoformat()
+    """
+    # Replace 'Z' with '+00:00' for UTC timestamps
+    timestamp_str = timestamp_str.replace("Z", "+00:00")
+    
+    # Handle fractional seconds - Python's datetime only supports up to 6 digits (microseconds)
+    # Some providers (like OCI, GCP) may return nanoseconds (9 digits)
+    if "." in timestamp_str:
+        # Split into main part and fractional part
+        if "+" in timestamp_str:
+            main_part, tz_part = timestamp_str.rsplit("+", 1)
+            tz_suffix = "+" + tz_part
+        elif timestamp_str.count("-") > 2:  # Has negative timezone offset
+            main_part, tz_part = timestamp_str.rsplit("-", 1)
+            tz_suffix = "-" + tz_part
+        else:
+            main_part = timestamp_str
+            tz_suffix = ""
+        
+        # Split main part into date/time and fractional seconds
+        datetime_part, fractional = main_part.rsplit(".", 1)
+        
+        # Truncate fractional seconds to 6 digits (microseconds)
+        if len(fractional) > 6:
+            fractional = fractional[:6]
+        
+        # Reconstruct timestamp
+        timestamp_str = f"{datetime_part}.{fractional}{tz_suffix}"
+    
+    return timestamp_str
+
+
 @log_errors(default_return=0, raise_exception=False, log_error=False)
 def calculate_time_difference(start_time_str: str, finish_time_str: str) -> int:
     """
     Calculate time difference between start and finish times.
+    
+    Robust handling of timestamps from different cloud providers (AWS, GCP, Azure, OCI)
+    and different precision levels (nanoseconds, microseconds, milliseconds).
 
     Args:
-        start_time_str (str): Start time string
-        finish_time_str (str): Finish time string
+        start_time_str (str): Start time string in ISO format
+        finish_time_str (str): Finish time string in ISO format
 
     Returns:
         int: Time difference in seconds
     """
-    if os.environ["SERVICE_PROVIDER"] in [
-        "AWS",
-        "OCI",
-        "LAMBDA",
-    ]:
-        start_time = datetime.fromisoformat(start_time_str.split(".")[0] + "+00:00")
-        finish_time = datetime.fromisoformat(finish_time_str.split(".")[0] + "+00:00")
-    else:
-        start_time = datetime.fromisoformat(start_time_str.replace("Z", "+00:00"))
-        finish_time = datetime.fromisoformat(finish_time_str.replace("Z", "+00:00"))
+    # Normalize both timestamps to handle different formats
+    normalized_start = _normalize_timestamp(start_time_str)
+    normalized_finish = _normalize_timestamp(finish_time_str)
+    
+    # Parse the normalized timestamps
+    start_time = datetime.fromisoformat(normalized_start)
+    finish_time = datetime.fromisoformat(normalized_finish)
+    
     return int((finish_time - start_time).total_seconds())
 
 
@@ -129,14 +173,25 @@ def has_gpu() -> bool:
         bool: True if GPU is present, False otherwise
     """
     try:
-        subprocess.run("nvidia-smi", timeout=5)
-        return True
+        result = subprocess.run(
+            ["nvidia-smi"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=5,
+            check=False,
+        )
+        return result.returncode == 0
     except subprocess.TimeoutExpired:
-        logging.warning("nvidia-smi command timed out after 5 seconds")
+        logging.debug("nvidia-smi command timed out after 5 seconds")
+        return False
+    except FileNotFoundError:
+        logging.debug("nvidia-smi not found on this system")
+        return False
+    except Exception:
         return False
 
 
-@log_errors(default_return=0, raise_exception=False)
+@log_errors(default_return=0, raise_exception=False, log_error=False)
 def get_gpu_memory_usage() -> float:
     """
     Get GPU memory usage percentage.
@@ -144,17 +199,35 @@ def get_gpu_memory_usage() -> float:
     Returns:
         float: Memory usage between 0 and 1
     """
-    command = "nvidia-smi --query-gpu=memory.used,memory.total --format=csv,nounits,noheader"
+    command = ["nvidia-smi", "--query-gpu=memory.used,memory.total", "--format=csv,nounits,noheader"]
     try:
-        output = subprocess.check_output(command.split(), timeout=5).decode("ascii").strip().split("\n")
+        result = subprocess.run(
+            command,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=5,
+            check=False,
+        )
+        if result.returncode != 0:
+            logging.debug("nvidia-smi command failed in get_gpu_memory_usage")
+            return 0
+        output = result.stdout.decode("ascii").strip().split("\n")
         memory_percentages = []
         for line in output:
-            used, total = map(int, line.split(","))
-            usage_percentage = used / total
-            memory_percentages.append(usage_percentage)
-        return min(memory_percentages)
+            if line.strip():
+                used, total = map(int, line.split(","))
+                if total > 0:
+                    usage_percentage = used / total
+                    memory_percentages.append(usage_percentage)
+        return min(memory_percentages) if memory_percentages else 0
     except subprocess.TimeoutExpired:
-        logging.warning("nvidia-smi command timed out after 5 seconds in get_gpu_memory_usage")
+        logging.debug("nvidia-smi command timed out after 5 seconds in get_gpu_memory_usage")
+        return 0
+    except (ValueError, IndexError) as e:
+        logging.debug("Error parsing GPU memory info: %s", e)
+        return 0
+    except Exception as e:
+        logging.debug("Unexpected error in get_gpu_memory_usage: %s", e)
         return 0
 
 
@@ -194,7 +267,7 @@ def get_mem_usage() -> float:
     return mem_usage
 
 
-@log_errors(default_return=[], raise_exception=False)
+@log_errors(default_return=[], raise_exception=False, log_error=False)
 def get_gpu_info() -> list:
     """
     Get GPU information.
@@ -202,23 +275,34 @@ def get_gpu_info() -> list:
     Returns:
         list: GPU information strings
     """
-    proc = subprocess.Popen(
-        [
-            "nvidia-smi",
-            "--query-gpu=index,uuid,utilization.gpu,memory.total,memory.used,memory.free,driver_version,name,gpu_serial,display_active,display_mode,temperature.gpu",
-            "--format=csv,noheader,nounits",
-        ],
-        stdout=subprocess.PIPE,
-        stderr=subprocess.PIPE,
-    )
     try:
-        stdout, stderr = proc.communicate(timeout=5)
-        output = stdout.decode("UTF-8")
-        return output.split("\n")[:-1]
-    except subprocess.TimeoutExpired:
-        logging.warning("nvidia-smi command timed out after 5 seconds in get_gpu_info")
-        proc.kill()
-        proc.communicate()  # flush output after kill
+        proc = subprocess.Popen(
+            [
+                "nvidia-smi",
+                "--query-gpu=index,uuid,utilization.gpu,memory.total,memory.used,memory.free,driver_version,name,gpu_serial,display_active,display_mode,temperature.gpu",
+                "--format=csv,noheader,nounits",
+            ],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        try:
+            stdout, stderr = proc.communicate(timeout=5)
+            if proc.returncode != 0:
+                logging.debug("nvidia-smi command failed in get_gpu_info")
+                return []
+            output = stdout.decode("UTF-8")
+            result = [line for line in output.split("\n") if line.strip()]
+            return result
+        except subprocess.TimeoutExpired:
+            logging.debug("nvidia-smi command timed out after 5 seconds in get_gpu_info")
+            proc.kill()
+            proc.communicate()  # flush output after kill
+            return []
+    except FileNotFoundError:
+        logging.debug("nvidia-smi not found on this system")
+        return []
+    except Exception as e:
+        logging.debug("Error getting GPU info: %s", e)
         return []
 
 
@@ -241,11 +325,29 @@ def is_docker_running() -> bool:
     Returns:
         bool: True if Docker containers are running
     """
-    command = "docker ps"
-    docker_images = (
-        subprocess.check_output(command.split()).decode("ascii").split("\n")[:-1][1:]
-    )
-    return bool(docker_images)
+    command = ["docker", "ps"]
+    try:
+        result = subprocess.run(
+            command,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+            timeout=10,
+        )
+        if result.returncode != 0:
+            logging.warning("docker ps command failed")
+            return False
+        docker_images = result.stdout.decode("ascii").split("\n")[:-1][1:]
+        return bool(docker_images)
+    except subprocess.TimeoutExpired:
+        logging.warning("docker ps command timed out")
+        return False
+    except FileNotFoundError:
+        logging.warning("docker command not found")
+        return False
+    except Exception as e:
+        logging.warning("Error checking if docker is running: %s", e)
+        return False
 
 
 @log_errors(default_return=None, raise_exception=False)
@@ -487,22 +589,45 @@ def get_required_gpu_memory(action_details: dict) -> int:
 
 @log_errors(default_return=True, raise_exception=False)
 def is_allowed_gpu_device(gpu_index: int) -> bool:
-    """Check if GPU device is allowed.
+    """Check if GPU device is allowed based on GPUS environment variable.
+
+    The GPUS environment variable can be used to restrict which GPU devices
+    are available for allocation (e.g., GPUS="0,2" allows only GPU 0 and 2).
 
     Args:
         gpu_index (int): GPU device index
 
     Returns:
-        bool: True if GPU is allowed
+        bool: True if GPU is allowed (or no filter is set), False otherwise
     """
     gpus = os.environ.get("GPUS")
     if not gpus:
+        # No filter set - all GPUs are allowed
+        return True
+
+    try:
+        allowed_gpus = [int(x) for x in gpus.split(",") if x.strip()]
+        is_allowed = int(gpu_index) in allowed_gpus
+
+        if not is_allowed:
+            logging.debug(
+                "GPU %d is not in allowed GPU list: %s",
+                gpu_index,
+                allowed_gpus
+            )
+
+        return is_allowed
+
+    except ValueError as e:
+        logging.warning(
+            "Invalid GPUS environment variable format '%s': %s. Allowing all GPUs.",
+            gpus,
+            e
+        )
         return True
-    allowed_gpus = [int(x) for x in gpus.split(",") if x.strip()]
-    return int(gpu_index) in allowed_gpus
 
 
-@log_errors(raise_exception=True)
+@log_errors(raise_exception=True, log_error=False)
 def get_gpu_with_sufficient_memory_for_action(
     action_details: dict,
 ) -> list:
@@ -518,44 +643,167 @@ def get_gpu_with_sufficient_memory_for_action(
     Raises:
         ValueError: If insufficient GPU memory
     """
+    action_id = action_details.get("_id", "unknown")
     required_gpu_memory = get_required_gpu_memory(action_details)
-    command = "nvidia-smi --query-gpu=memory.free --format=csv"
+
+    logging.info(
+        "Action %s: Searching for GPU(s) with %d MB available memory",
+        action_id,
+        required_gpu_memory
+    )
+
+    command = ["nvidia-smi", "--query-gpu=memory.free", "--format=csv"]
     try:
-        memory_free_info = subprocess.check_output(command.split(), timeout=5).decode("ascii").split("\n")
+        result = subprocess.run(
+            command,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=5,
+            check=False,
+        )
+        if result.returncode != 0:
+            error_msg = f"nvidia-smi command failed with return code {result.returncode}"
+            logging.error("Action %s: %s", action_id, error_msg)
+            raise ValueError("Failed to get GPU information - nvidia-smi command failed")
+        memory_free_info = result.stdout.decode("ascii").strip().split("\n")
     except subprocess.TimeoutExpired:
-        logging.error("nvidia-smi command timed out after 5 seconds in get_gpu_with_sufficient_memory_for_action")
+        logging.error(
+            "Action %s: nvidia-smi command timed out after 5 seconds",
+            action_id
+        )
         raise ValueError("Failed to get GPU information - nvidia-smi timed out")
-    
+    except FileNotFoundError:
+        logging.error(
+            "Action %s: nvidia-smi not found on this system",
+            action_id
+        )
+        raise ValueError("nvidia-smi not found - no GPU support available")
+    except Exception as e:
+        logging.error(
+            "Action %s: Error running nvidia-smi: %s",
+            action_id,
+            e
+        )
+        raise ValueError(f"Failed to get GPU information: {e}")
+
     if len(memory_free_info) < 2:
+        logging.error(
+            "Action %s: No GPU information available from nvidia-smi output",
+            action_id
+        )
         raise ValueError("No GPU information available from nvidia-smi")
-    memory_free_values = [int(x.split()[0]) for x in memory_free_info[1:-1]]
+
+    try:
+        memory_free_values = [int(x.split()[0]) for x in memory_free_info[1:] if x.strip()]
+    except (ValueError, IndexError) as e:
+        logging.error(
+            "Action %s: Error parsing GPU memory information: %s",
+            action_id,
+            e
+        )
+        raise ValueError(f"Error parsing GPU memory information: {e}")
+
+    if not memory_free_values:
+        logging.error("Action %s: No GPU devices found", action_id)
+        raise ValueError("No GPU devices found")
+
+    # Log all available GPUs and their free memory
+    logging.info(
+        "Action %s: Found %d GPU(s) - Free memory: %s",
+        action_id,
+        len(memory_free_values),
+        ", ".join([f"GPU{i}: {mem}MB" for i, mem in enumerate(memory_free_values)])
+    )
+
+    # Check GPUS environment variable for allowed devices
+    allowed_gpus = os.environ.get("GPUS", "")
+    if allowed_gpus:
+        logging.info(
+            "Action %s: GPU device filter active - allowed devices: %s",
+            action_id,
+            allowed_gpus
+        )
+
+    # For smaller memory requirements, try to fit on a single GPU first
     if required_gpu_memory < 80000:
+        logging.debug(
+            "Action %s: Required memory %d MB < 80000 MB - attempting single GPU allocation",
+            action_id,
+            required_gpu_memory
+        )
         try:
-            return get_single_gpu_with_sufficient_memory_for_action(action_details)
-        except ValueError:
-            pass
+            single_gpu = get_single_gpu_with_sufficient_memory_for_action(action_details)
+            logging.info(
+                "Action %s: Successfully allocated single GPU: %s",
+                action_id,
+                single_gpu
+            )
+            return single_gpu
+        except ValueError as e:
+            logging.debug(
+                "Action %s: Single GPU allocation failed (%s) - will try multiple GPUs",
+                action_id,
+                str(e)
+            )
+
+    # Multi-GPU allocation: accumulate GPUs until we have enough memory
+    logging.info(
+        "Action %s: Attempting multi-GPU allocation for %d MB",
+        action_id,
+        required_gpu_memory
+    )
+
     selected_gpus = []
     total_memory = 0
     for i, mem in enumerate(memory_free_values):
         if not is_allowed_gpu_device(i):
+            logging.debug(
+                "Action %s: Skipping GPU %d - not in allowed device list",
+                action_id,
+                i
+            )
             continue
         if total_memory >= required_gpu_memory:
             break
         selected_gpus.append(i)
         total_memory += mem
+        logging.debug(
+            "Action %s: Added GPU %d (%d MB free) - Total: %d MB",
+            action_id,
+            i,
+            mem,
+            total_memory
+        )
+
     if total_memory >= required_gpu_memory:
+        logging.info(
+            "Action %s: Successfully allocated %d GPU(s): %s (Total memory: %d MB >= Required: %d MB)",
+            action_id,
+            len(selected_gpus),
+            selected_gpus,
+            total_memory,
+            required_gpu_memory
+        )
         return selected_gpus
-    raise ValueError(
-        f"Insufficient GPU memory available. Required: {required_gpu_memory}, Available: {total_memory}"
+
+    error_msg = (
+        f"Insufficient GPU memory available. "
+        f"Required: {required_gpu_memory}MB, "
+        f"Available: {total_memory}MB across {len(selected_gpus)} GPU(s)"
     )
+    logging.error("Action %s: %s", action_id, error_msg)
+    raise ValueError(error_msg)
 
 
-@log_errors(raise_exception=True)
+@log_errors(raise_exception=True, log_error=False)
 def get_single_gpu_with_sufficient_memory_for_action(
     action_details: dict,
 ) -> list:
     """
-    Get single GPU with sufficient memory.
+    Get single GPU with sufficient memory using best-fit algorithm.
+
+    Best-fit selects the GPU with the smallest amount of free memory
+    that still meets the requirements, minimizing fragmentation.
 
     Args:
         action_details (dict): Action details
@@ -566,30 +814,126 @@ def get_single_gpu_with_sufficient_memory_for_action(
     Raises:
         ValueError: If no GPU has sufficient memory
     """
+    action_id = action_details.get("_id", "unknown")
     required_gpu_memory = get_required_gpu_memory(action_details)
-    command = "nvidia-smi --query-gpu=memory.free --format=csv"
+
+    logging.debug(
+        "Action %s: Finding best-fit single GPU for %d MB",
+        action_id,
+        required_gpu_memory
+    )
+
+    command = ["nvidia-smi", "--query-gpu=memory.free", "--format=csv"]
     try:
-        memory_free_info = subprocess.check_output(command.split(), timeout=5).decode("ascii").split("\n")
+        result = subprocess.run(
+            command,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=5,
+            check=False,
+        )
+        if result.returncode != 0:
+            raise ValueError("Failed to get GPU information - nvidia-smi command failed")
+        memory_free_info = result.stdout.decode("ascii").strip().split("\n")
     except subprocess.TimeoutExpired:
-        logging.error("nvidia-smi command timed out after 5 seconds in get_single_gpu_with_sufficient_memory_for_action")
+        logging.error(
+            "Action %s: nvidia-smi timed out in single GPU selection",
+            action_id
+        )
         raise ValueError("Failed to get GPU information - nvidia-smi timed out")
-    
+    except FileNotFoundError:
+        raise ValueError("nvidia-smi not found - no GPU support available")
+    except Exception as e:
+        logging.error(
+            "Action %s: Error running nvidia-smi: %s",
+            action_id,
+            e
+        )
+        raise ValueError(f"Failed to get GPU information: {e}")
+
     if len(memory_free_info) < 2:
         raise ValueError("No GPU information available from nvidia-smi")
-    memory_free_values = [int(x.split()[0]) for x in memory_free_info[1:-1]]
+
+    try:
+        memory_free_values = [int(x.split()[0]) for x in memory_free_info[1:] if x.strip()]
+    except (ValueError, IndexError) as e:
+        raise ValueError(f"Error parsing GPU memory information: {e}")
+
+    if not memory_free_values:
+        raise ValueError("No GPU devices found")
+
+    # Best-fit algorithm: find GPU with minimum free memory that meets requirement
     best_fit_gpu = None
     best_fit_memory = float("inf")
+
     for i, mem in enumerate(memory_free_values):
+        # Check if GPU is in allowed list
         if not is_allowed_gpu_device(i):
+            logging.debug(
+                "Action %s: Skipping GPU %d (not in allowed list) - %d MB free",
+                action_id,
+                i,
+                mem
+            )
             continue
-        if mem >= required_gpu_memory and mem < best_fit_memory:
-            best_fit_gpu = i
-            best_fit_memory = mem
+
+        # Check if GPU has sufficient memory
+        if mem >= required_gpu_memory:
+            logging.debug(
+                "Action %s: GPU %d is candidate - %d MB free (required: %d MB)",
+                action_id,
+                i,
+                mem,
+                required_gpu_memory
+            )
+
+            # Best-fit: choose GPU with smallest sufficient memory
+            if mem < best_fit_memory:
+                best_fit_gpu = i
+                best_fit_memory = mem
+                logging.debug(
+                    "Action %s: GPU %d is new best-fit candidate",
+                    action_id,
+                    i
+                )
+        else:
+            logging.debug(
+                "Action %s: GPU %d insufficient - %d MB free < %d MB required",
+                action_id,
+                i,
+                mem,
+                required_gpu_memory
+            )
+
     if best_fit_gpu is not None:
+        logging.info(
+            "Action %s: Selected best-fit GPU %d with %d MB free (required: %d MB, waste: %d MB)",
+            action_id,
+            best_fit_gpu,
+            best_fit_memory,
+            required_gpu_memory,
+            best_fit_memory - required_gpu_memory
+        )
         return [best_fit_gpu]
-    raise ValueError(
-        f"No single GPU with sufficient memory ({required_gpu_memory}MB) available"
-    )
+
+    # No suitable GPU found - provide detailed error
+    suitable_gpus = [
+        f"GPU{i}: {mem}MB (need {required_gpu_memory}MB)"
+        for i, mem in enumerate(memory_free_values)
+        if is_allowed_gpu_device(i)
+    ]
+
+    if not suitable_gpus:
+        error_msg = f"No allowed GPUs available (GPUS env filter active)"
+    else:
+        error_msg = (
+            f"No single GPU with sufficient memory. "
+            f"Required: {required_gpu_memory}MB. "
+            f"Available GPUs: {', '.join(suitable_gpus)}"
+        )
+
+    logging.warning("Action %s: %s", action_id, error_msg)
+    raise ValueError(error_msg)
 
 
 @log_errors(default_return=(None, None), raise_exception=False)
@@ -692,47 +1036,112 @@ def get_encrypted_access_key_pair(
     
     return encoded_access_key, encoded_secret_key
 
-@log_errors(default_return=False, raise_exception=False)
-def check_public_port_exposure(port: int) -> bool:
+def _get_private_ip() -> str:
     """
-    Check if port is publicly accessible.
+    Get the actual private/LAN IP address using UDP socket trick.
+    This works reliably even in Docker, NAT, VPN, etc.
+    
+    Returns:
+        str: Private IP address or None if not available
+    """
+    try:
+        # Use UDP socket to determine which interface would be used for external connection
+        # No actual packets are sent
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+            s.connect(("8.8.8.8", 80))
+            private_ip = s.getsockname()[0]
+            return private_ip
+    except Exception:
+        return None
 
-    Args:
-        port (int): Port number to check
 
-    Returns:
-        bool: True if port is publicly accessible
-    """
-    is_public_exposed = False
-    is_locally_available = False
-    # Check if port is publicly accessible
-    public_ip = urllib.request.urlopen("https://ident.me", timeout=10).read().decode("utf8")
-    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as conn_sock:
-        conn_sock.settimeout(3)
-        result = conn_sock.connect_ex((public_ip, port))
-        is_public_exposed = result == 0
+def _public_ip_is_local(public_ip: str) -> bool:
+    """
+    Check if a public IP address is actually assigned to a local network interface.
+    This is true on cloud servers with real public IPs, false behind NAT.
     
-    # Check if port is locally available
-    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as bind_sock:
-        bind_sock.setsockopt(
-            socket.SOL_SOCKET,
-            socket.SO_REUSEADDR,
-            1,
-        )
-        bind_sock.bind(("", port))
-        bind_sock.listen(1)
-        is_locally_available = True
-
-    if not is_public_exposed:
-        logging.debug(
-            "Port %d is not publicly exposed",
-            port,
-        )
+    Args:
+        public_ip (str): The public IP to check
+        
+    Returns:
+        bool: True if the public IP is on a local interface
+    """
+    try:
+        for iface, addrs in psutil.net_if_addrs().items():
+            for addr in addrs:
+                if addr.family == socket.AF_INET:
+                    if addr.address == public_ip:
+                        return True
         return False
-    if not is_locally_available:
-        logging.debug(
-            "Port %d is not locally available",
-            port,
-        )
+    except Exception:
         return False
-    return True
+
+
+@log_errors(default_return=("localhost", True), raise_exception=False)
+def get_best_service_ip_and_network(port: int) -> tuple:
+    """
+    Determine the best IP address and network configuration for a service.
+    
+    This function intelligently selects the best IP to bind a service to:
+    
+    Priority:
+    1. Public IP if it's actually on a local interface (cloud servers)
+    2. Private/LAN IP (NAT, local network, Docker)
+    3. localhost with --net=host (fallback)
+    
+    Args:
+        port (int): Port number for the service
+        
+    Returns:
+        tuple: (ip_address, use_host_network) where:
+            - ip_address: The IP address to use (public, private, or localhost)
+            - use_host_network: True if should use --net=host, False if should use port mapping
+    """
+    try:
+        # Check if port is available (not already in use)
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as test_sock:
+                test_sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                test_sock.bind(("0.0.0.0", port))
+                test_sock.listen(1)
+                # Port is available - socket closes automatically
+        except OSError as e:
+            logging.warning(f"Port {port} is already in use or cannot be bound: {e}, will use --net=host")
+            return "localhost", True
+        
+        # Get the actual private/LAN IP
+        private_ip = _get_private_ip()
+        if private_ip:
+            logging.info(f"Determined private/LAN IP: {private_ip}")
+        else:
+            logging.debug("Could not determine private IP")
+        
+        # Try to get public IP from external service
+        public_ip = None
+        try:
+            public_ip = urllib.request.urlopen("https://ident.me", timeout=10).read().decode("utf8").strip()
+            # Validate it's a proper IP address
+            socket.inet_aton(public_ip)
+            logging.info(f"Determined external/public IP: {public_ip}")
+        except Exception as e:
+            logging.debug(f"Could not determine public IP: {e}")
+        
+        # Decision logic: Choose the best IP
+        
+        # 1. If public IP is on a local interface, use it (cloud server with real public IP)
+        if public_ip and _public_ip_is_local(public_ip):
+            logging.info(f"Public IP {public_ip} is on local interface, using it for port {port}")
+            return public_ip, False
+        
+        # 2. If we have a valid private IP, use it (most common case: NAT, LAN, Docker)
+        if private_ip and not private_ip.startswith("127."):
+            logging.info(f"Using private/LAN IP {private_ip} for port {port}")
+            return private_ip, False
+        
+        # 3. Fall back to localhost with --net=host
+        logging.info(f"No suitable IP found, using localhost with --net=host for port {port}")
+        return "localhost", True
+        
+    except Exception as e:
+        logging.warning(f"Error determining best IP for port {port}: {e}, falling back to localhost")
+        return "localhost", True