feat(ai): add emit_progress() calls to all Python AI scripts

packages/ai/python/detect_faces.py

@@ -3,6 +3,11 @@ import sys
 import json
 
 
+def emit_progress(percent, stage):
+    """Emit structured progress to stderr for bridge.ts to capture."""
+    print(json.dumps({"progress": percent, "stage": stage}), file=sys.stderr, flush=True)
+
+
 def main():
     input_path = sys.argv[1]
     output_path = sys.argv[2]
@@ -12,6 +17,7 @@ def main():
     sensitivity = settings.get("sensitivity", 0.5)
 
     try:
+        emit_progress(10, "Loading face detection model")
         from PIL import Image, ImageFilter
 
         img = Image.open(input_path).convert("RGB")
@@ -20,17 +26,21 @@ def main():
             import mediapipe as mp
             import numpy as np
 
+            emit_progress(20, "Model ready")
+
             mp_face = mp.solutions.face_detection
 
             with mp_face.FaceDetection(
                 min_detection_confidence=sensitivity
             ) as detector:
                 img_array = np.array(img)
+                emit_progress(25, "Scanning for faces")
                 results = detector.process(img_array)
 
                 faces = []
+                emit_progress(50, f"Found {len(results.detections or [])} faces")
                 if results.detections:
-                    for detection in results.detections:
+                    for i, detection in enumerate(results.detections):
                         bbox = detection.location_data.relative_bounding_box
                         x = int(bbox.xmin * img.width)
                         y = int(bbox.ymin * img.height)
@@ -50,7 +60,9 @@ def main():
                         )
                         img.paste(blurred, (x1, y1))
                         faces.append({"x": x, "y": y, "w": w, "h": h})
+                        emit_progress(50 + int((i + 1) / max(len(results.detections), 1) * 40), f"Blurring face {i + 1} of {len(results.detections)}")
 
+                emit_progress(95, "Saving result")
                 img.save(output_path)
                 print(
                     json.dumps(

packages/ai/python/inpaint.py

@@ -3,12 +3,18 @@ import sys
 import json
 
 
+def emit_progress(percent, stage):
+    """Emit structured progress to stderr for bridge.ts to capture."""
+    print(json.dumps({"progress": percent, "stage": stage}), file=sys.stderr, flush=True)
+
+
 def main():
     input_path = sys.argv[1]
     mask_path = sys.argv[2]
     output_path = sys.argv[3]
 
     try:
+        emit_progress(10, "Loading inpainting model")
         from PIL import Image
 
         try:
@@ -16,10 +22,13 @@ def main():
             from lama_cleaner.model_manager import ModelManager
             from lama_cleaner.schema import Config
 
+            emit_progress(20, "Model loaded")
+
             img = Image.open(input_path).convert("RGB")
             mask = Image.open(mask_path).convert("L")
 
             # Resize mask to match image if needed
+            emit_progress(25, "Analyzing mask")
             if mask.size != img.size:
                 mask = mask.resize(img.size, Image.NEAREST)
 
@@ -37,7 +46,10 @@ def main():
                 hd_strategy_crop_trigger_size=800,
                 hd_strategy_resize_limit=800,
             )
+            emit_progress(40, "Inpainting region")
             result = model_manager(img_array, mask_array, config)
+            emit_progress(85, "Refining edges")
+            emit_progress(95, "Saving result")
             Image.fromarray(result).save(output_path)
             method = "lama"
 

packages/ai/python/ocr.py

@@ -3,6 +3,11 @@ import sys
 import json
 
 
+def emit_progress(percent, stage):
+    """Emit structured progress to stderr for bridge.ts to capture."""
+    print(json.dumps({"progress": percent, "stage": stage}), file=sys.stderr, flush=True)
+
+
 def main():
     input_path = sys.argv[1]
     settings = json.loads(sys.argv[2]) if len(sys.argv) > 2 else {}
@@ -11,12 +16,15 @@ def main():
     language = settings.get("language", "en")
 
     try:
+        emit_progress(10, "Loading OCR engine")
         if engine == "paddleocr":
             try:
                 from paddleocr import PaddleOCR
 
                 ocr = PaddleOCR(use_angle_cls=True, lang=language)
+                emit_progress(30, "Analyzing text regions")
                 result = ocr.ocr(input_path, cls=True)
+                emit_progress(70, "Extracting text")
                 text = "\n".join(
                     [
                         line[1][0]
@@ -26,6 +34,7 @@ def main():
                         if line and line[1]
                     ]
                 )
+                emit_progress(95, "Formatting results")
                 print(
                     json.dumps({"success": True, "text": text, "engine": "paddleocr"})
                 )
@@ -47,15 +56,18 @@ def main():
             tess_lang = lang_map.get(language, "eng")
 
             try:
+                emit_progress(30, "Running Tesseract")
                 result = subprocess.run(
                     ["tesseract", input_path, "stdout", "-l", tess_lang],
                     capture_output=True,
                     text=True,
                     timeout=120,
                 )
+                emit_progress(70, "Extracting text")
                 text = result.stdout.strip()
                 if result.returncode != 0 and not text:
                     raise RuntimeError(result.stderr.strip() or "Tesseract failed")
+                emit_progress(95, "Formatting results")
                 print(
                     json.dumps(
                         {"success": True, "text": text, "engine": "tesseract"}

packages/ai/python/remove_bg.py

@@ -1,6 +1,12 @@
 """Background removal using rembg with state-of-the-art BiRefNet models."""
 import sys
 import json
+import os
+
+
+def emit_progress(percent, stage):
+    """Emit structured progress to stderr for bridge.ts to capture."""
+    print(json.dumps({"progress": percent, "stage": stage}), file=sys.stderr, flush=True)
 
 
 def main():
@@ -11,23 +17,26 @@ def main():
     model = settings.get("model", "u2net")
     bg_color = settings.get("backgroundColor", "")
 
+    # Redirect stdout to stderr so library download/progress output
+    # cannot contaminate our JSON result on stdout.
+    stdout_fd = os.dup(1)
+    os.dup2(2, 1)
+
     try:
         from rembg import remove, new_session
         import io
 
-        # Progress messages go to stderr (stdout reserved for JSON result)
-        sys.stderr.write(f"Loading model: {model}\n")
-        sys.stderr.flush()
+        emit_progress(10, "Loading model")
 
         session = new_session(model)
 
-        sys.stderr.write("Processing image...\n")
-        sys.stderr.flush()
+        emit_progress(25, "Model loaded")
 
         with open(input_path, "rb") as f:
             input_data = f.read()
 
         # Try with alpha matting for better edges, fall back without
+        emit_progress(30, "Analyzing image")
         try:
             output_data = remove(
                 input_data,
@@ -39,8 +48,11 @@ def main():
         except Exception:
             output_data = remove(input_data, session=session)
 
+        emit_progress(80, "Background removed")
+
         # If a background color is specified, composite onto it
         if bg_color and bg_color.startswith("#"):
+            emit_progress(85, "Compositing background")
             from PIL import Image
 
             img = Image.open(io.BytesIO(output_data)).convert("RGBA")
@@ -54,22 +66,27 @@ def main():
             bg.save(buf, format="PNG")
             output_data = buf.getvalue()
 
+        emit_progress(95, "Saving result")
         with open(output_path, "wb") as f:
             f.write(output_data)
 
-        print(json.dumps({"success": True, "model": model}))
+        result = json.dumps({"success": True, "model": model})
 
     except ImportError:
-        print(
-            json.dumps(
-                {
-                    "success": False,
-                    "error": "rembg is not installed. Install with: pip install rembg[cpu]",
-                }
-            )
+        result = json.dumps(
+            {
+                "success": False,
+                "error": "rembg is not installed. Install with: pip install rembg[cpu]",
+            }
         )
     except Exception as e:
-        print(json.dumps({"success": False, "error": str(e)}))
+        result = json.dumps({"success": False, "error": str(e)})
+
+    # Restore original stdout and write only our JSON result
+    os.dup2(stdout_fd, 1)
+    os.close(stdout_fd)
+    sys.stdout.write(result + "\n")
+    sys.stdout.flush()
 
 
 if __name__ == "__main__":

packages/ai/python/upscale.py

@@ -3,6 +3,11 @@ import sys
 import json
 
 
+def emit_progress(percent, stage):
+    """Emit structured progress to stderr for bridge.ts to capture."""
+    print(json.dumps({"progress": percent, "stage": stage}), file=sys.stderr, flush=True)
+
+
 def main():
     input_path = sys.argv[1]
     output_path = sys.argv[2]
@@ -11,6 +16,7 @@ def main():
     scale = settings.get("scale", 2)
 
     try:
+        emit_progress(10, "Loading upscale model")
         from PIL import Image
 
         img = Image.open(input_path)
@@ -36,14 +42,20 @@ def main():
                 model=model,
                 half=False,
             )
+            emit_progress(20, "Model ready")
             img_array = np.array(img.convert("RGB"))
+            emit_progress(25, "Upscaling image")
             output, _ = upsampler.enhance(img_array, outscale=scale)
+            emit_progress(90, "Upscaling complete")
             result = Image.fromarray(output)
+            emit_progress(95, "Saving result")
             result.save(output_path)
             method = "realesrgan"
         except (ImportError, Exception):
             # Fallback to Lanczos upscaling
+            emit_progress(50, "Upscaling with Lanczos")
             img_upscaled = img.resize(new_size, Image.LANCZOS)
+            emit_progress(95, "Saving result")
             img_upscaled.save(output_path)
             method = "lanczos"