fix(ai): surface actionable fix for libGL.so.1 missing on headless installs

Proxmox LXC and other headless Linux installs lack libgl1, causing
all AI tools to show a misleading "install opencv-python-headless"
error even though the pip package is already installed. Detect the
libGL ImportError and suggest `apt-get install -y libgl1` instead.

packages/ai/python/colorize.py

@@ -13,7 +13,9 @@ try:
     import cv2
     from PIL import Image
 except ImportError as _e:
-    print(json.dumps({"error": f"Missing dependency: {_e}. Install opencv-python-headless, numpy, and Pillow."}))
+    _msg = str(_e)
+    _hint = "Fix with: apt-get install -y libgl1" if "libGL" in _msg else "Install opencv-python-headless, numpy, and Pillow."
+    print(json.dumps({"error": f"Missing dependency: {_msg}. {_hint}"}))
     sys.exit(1)
 
 

packages/ai/python/inpaint.py

@@ -101,9 +101,11 @@ def main():
             import cv2
             import onnxruntime
         except ImportError as e:
+            msg = str(e)
+            hint = "Fix with: apt-get install -y libgl1" if "libGL" in msg else "Requires opencv-python-headless and onnxruntime."
             print(json.dumps({
                 "success": False,
-                "error": f"Missing dependency: {e}. Requires opencv-python-headless and onnxruntime.",
+                "error": f"Missing dependency: {msg}. {hint}",
             }))
             sys.exit(1)
 

packages/ai/python/noise_removal.py

@@ -444,10 +444,12 @@ def main():
 
         try:
             import cv2
-        except ImportError:
+        except ImportError as e:
+            msg = str(e)
+            hint = "Fix with: apt-get install -y libgl1" if "libGL" in msg else "Install with: pip install opencv-python-headless"
             print(json.dumps({
                 "success": False,
-                "error": "OpenCV is not installed. Install with: pip install opencv-python-headless",
+                "error": f"Missing dependency: {msg}. {hint}",
             }))
             sys.exit(1)
 

packages/ai/python/outpaint.py

@@ -160,9 +160,11 @@ def main():
             import cv2
             import onnxruntime
         except ImportError as e:
+            msg = str(e)
+            hint = "Fix with: apt-get install -y libgl1" if "libGL" in msg else "Requires opencv-python-headless and onnxruntime."
             print(json.dumps({
                 "success": False,
-                "error": f"Missing dependency: {e}. Requires opencv-python-headless and onnxruntime.",
+                "error": f"Missing dependency: {msg}. {hint}",
             }))
             sys.exit(1)
 

packages/ai/python/red_eye_removal.py

@@ -290,12 +290,14 @@ def main():
                 )
             )
 
-        except ImportError:
+        except ImportError as e:
+            msg = str(e)
+            hint = "Fix with: apt-get install -y libgl1" if "libGL" in msg else "Install with: pip install mediapipe numpy opencv-python"
             print(
                 json.dumps(
                     {
                         "success": False,
-                        "error": "Red-eye removal requires MediaPipe, NumPy, and OpenCV. Install with: pip install mediapipe numpy opencv-python",
+                        "error": f"Missing dependency: {msg}. {hint}",
                     }
                 )
             )

packages/ai/python/restore.py

@@ -16,7 +16,9 @@ try:
     import cv2
     from PIL import Image
 except ImportError as _e:
-    print(json.dumps({"error": f"Missing dependency: {_e}. Install opencv-python-headless, numpy, and Pillow."}))
+    _msg = str(_e)
+    _hint = "Fix with: apt-get install -y libgl1" if "libGL" in _msg else "Install opencv-python-headless, numpy, and Pillow."
+    print(json.dumps({"error": f"Missing dependency: {_msg}. {_hint}"}))
     sys.exit(1)