fix(runtime): use start.py entrypoint to keep FastAPI & Gradio alive on Hugging Face

Dockerfile

@@ -45,12 +45,12 @@ ENV GRADIO_SERVER_NAME=0.0.0.0 \
     GRADIO_SERVER_PORT=7860 \
     USE_MOCK=1
 
-# Healthcheck points to Gradio app
+# Healthcheck ensures Gradio frontend is alive
 HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
   CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:7860', timeout=2)"
 
-# Hugging Face exposes 7860
+# Hugging Face Spaces expect public app on port 7860
 EXPOSE 7860
 
-# Run both FastAPI (backend) and Gradio (frontend)
+# Unified startup script
 CMD ["python", "start.py"]

start.py

@@ -4,6 +4,7 @@ import os
 
 
 def run_fastapi():
+    """Run FastAPI backend on port 8000."""
     subprocess.run(
         [
             "uvicorn",
@@ -15,15 +16,21 @@ def run_fastapi():
             "--proxy-headers",
             "--workers",
             str(os.getenv("UVICORN_WORKERS", 1)),
-        ]
+        ],
+        check=True,
     )
 
 
 def run_gradio():
-    pass  # noqa: just import to launch
+    """Launch Gradio UI (demo/app.py)."""
+    import demo.app  # noqa: F401
+    # This module runs demo.launch() on import
 
 
 if __name__ == "__main__":
+    # Start FastAPI in background thread
     t = threading.Thread(target=run_fastapi, daemon=True)
     t.start()
+
+    # Run Gradio in foreground (keeps container alive)
     run_gradio()