Deploy QueryLens (Gradio-SDK launcher: worker :8700 / MCP :8701 / web :7860)

app.py

@@ -1,41 +1,67 @@
 """
-Hugging Face Spaces entrypoint — Gradio SDK wrapper
-====================================================
+Hugging Face Spaces entrypoint — Gradio SDK on the free ZeroGPU tier
+====================================================================
 
-HF Spaces moved the Docker SDK to a paid tier, so this Gradio-SDK Space
-replicates the exact same three-service architecture the Docker image used:
+Free personal accounts can only host Gradio Spaces on ZeroGPU hardware
+(CPU-basic requires a paid plan), so this launcher satisfies ZeroGPU's
+startup contract while keeping the exact three-service architecture the
+Docker image used:
 
     this process (port 7860, public)
       ├── Agent.worker      → spawned uvicorn :8700  (Text2SQL / DocVQA backend)
       ├── Agent.mcp_server  → spawned uvicorn :8701  (MCP tool server)
-      └── web.app FastAPI   → serves the sepia UI + /api proxies on :7860
-
-A minimal Gradio Blocks page is mounted at ``/gradio-lp`` purely so the
-Gradio-SDK runtime sees a registered Blocks application — the real UI is
-the sepia web app at ``/``.
-
-Secrets (Space settings → Variables and Secrets, never baked into the code):
-    HF_API_TOKEN   — HF Inference API, Text-to-SQL on
-                     Qwen/Qwen2.5-Coder-7B-Instruct
-    GROQ_API_KEY   — Groq vision VQA (free tier)
-
-No DB_CONNECTION_URL is required — the bundled authentic demo employee
-SQLite database (employee-sample-database/sqlite/dataset_small/employee.db)
-auto-activates as the demo_employee profile.
+      └── web.app FastAPI   → grafted into Gradio's own server on :7860
+
+ZeroGPU contract (the two failure modes cost by the first deploy):
+  1. The platform requires at least one ``@spaces.GPU``-decorated function
+     to exist at startup AND a real ``demo.launch()`` call — skipping
+     ``launch()`` in favour of ``gr.mount_gradio_app`` + ``uvicorn.run``
+     triggers ``No @spaces.GPU function detected during startup``.
+  2. Because our app never uses a GPU, the decorated function below is a
+     no-op that is never called, so zero GPU quota is ever consumed.
+
+Serving strategy (proven pattern for FastAPI-on-ZeroGPU spaces):
+  - ``demo.launch(server_port=7860, prevent_thread_lock=True,
+    ssr_mode=False)`` makes Gradio own the public port.
+  - Our full FastAPI web app (sepia UI + /api proxies) is then grafted
+    into ``demo.app.router.routes`` as a Mount inserted in FRONT of
+    Gradio's routes, so ``/`` serves the sepia UI (Gradio also registers
+    ``get /`` and ``get /static/{path}``, which would otherwise shadow it).
+  - ``ssr_mode=False`` is mandatory: Spaces' Node SSR proxy intercepts
+    every request it does not recognise as Gradio-owned and never
+    forwards it to Python.
+  - Mounted sub-apps do not receive lifespan events, so the shared
+    httpx client of ``web.app`` is created eagerly after launch.
+
+Outside ZeroGPU (local dev / Docker), the previous behaviour is kept:
+``gr.mount_gradio_app`` + ``uvicorn.run``.
 """
 import os
-import sys
+import socket
 import subprocess
+import sys
+import time
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent
+PORT = int(os.environ.get("PORT", "7860"))
 
 
 # -----------------------------------------------------------------------------
-# Background services (same as start_hf.sh in the Docker image)
+# Background services (same as start_hf.sh in the Docker image).
+# Port-guarded: the Spaces runtime can re-execute this script inside the same
+# container, and duplicate uvicorn children would just exit with bind errors.
 # -----------------------------------------------------------------------------
-def _spawn(module: str, port: int, name: str) -> subprocess.Popen:
-    """Start a uvicorn service; output streams into the Space log viewer."""
+def _listening(port: int) -> bool:
+    with socket.socket() as s:
+        s.settimeout(0.25)
+        return s.connect_ex(("127.0.0.1", port)) == 0
+
+
+def _spawn(module: str, port: int, name: str):
+    if _listening(port):
+        print(f"[LAUNCHER] {name} already listening on :{port} — skipping spawn", flush=True)
+        return None
     print(f"[LAUNCHER] starting {name} on :{port} ...", flush=True)
     return subprocess.Popen(
         [sys.executable, "-u", "-m", "uvicorn", module,
@@ -48,25 +74,73 @@ _worker = _spawn("Agent.worker:app", 8700, "backend worker")
 _mcp = _spawn("Agent.mcp_server:app", 8701, "MCP tool server")
 
 # -----------------------------------------------------------------------------
-# Web UI: our existing FastAPI app, with a tiny Gradio shell mounted beside it
-# so the Gradio-SDK runtime is satisfied.
+# Gradio shell + ZeroGPU contract
 # -----------------------------------------------------------------------------
 import gradio as gr  # noqa: E402  (preinstalled in the Gradio-SDK runtime)
 from web.app import app as fastapi_app  # noqa: E402
 
-with gr.Blocks() as _lp:
+try:
+    import spaces  # noqa: E402  (provided by the HF runtime; absent locally)
+    _ZERO_GPU = bool(getattr(getattr(spaces, "config", None), "zero_gpu", False))
+except Exception:
+    spaces = None
+    _ZERO_GPU = False
+
+if spaces is not None:
+    @spaces.GPU
+    def _zerogpu_platform_check():
+        """Never called. HF's ZeroGPU tier statically requires at least one
+        @spaces.GPU-decorated function to exist at startup, or it kills the
+        container. The decorator only allocates a GPU when the function
+        actually runs, so this costs zero quota for our CPU-only app."""
+        return None
+
+with gr.Blocks(title="QueryLens") as _lp:
     gr.Markdown(
         "**QueryLens** — the full sepia UI is served at this Space's root `/`.\n\n"
         "This page is only an anchor for the Gradio runtime."
     )
     gr.HTML('<a href="/" style="text-decoration:none;font-weight:600;">← Open the QueryLens UI</a>')
 
-app = gr.mount_gradio_app(fastapi_app, _lp, path="/gradio-lp")
-
 
 if __name__ == "__main__":
-    import uvicorn
-
-    port = int(os.environ.get("PORT", "7860"))
-    print(f"[LAUNCHER] QueryLens web UI live on http://0.0.0.0:{port}", flush=True)
-    uvicorn.run(app, host="0.0.0.0", port=port)
+    if _ZERO_GPU:
+        import httpx
+        import web.app as _webapp
+        from starlette.routing import Mount
+
+        try:
+            # Gradio owns the public port; prevent_thread_lock returns control
+            # so we can graft the web app below, then block_thread holds the
+            # main thread (what launch() would have done).
+            _lp.launch(
+                server_name="0.0.0.0",
+                server_port=PORT,
+                prevent_thread_lock=True,
+                ssr_mode=False,
+            )
+        except OSError as exc:
+            # The Spaces runtime re-executed this script while a first copy is
+            # already serving — do not touch the port, just idle forever.
+            print(f"[LAUNCHER] port {PORT} already held by the first instance ({exc}); idling", flush=True)
+            while True:
+                time.sleep(3600)
+
+        # Mounted sub-apps do not receive startup events — initialise the
+        # shared httpx client eagerly so /api proxies never see client=None.
+        if _webapp.client is None:
+            _webapp.client = httpx.AsyncClient(timeout=_webapp.WORKER_TIMEOUT)
+
+        # Serve the full web app in front of Gradio's own routes: the visible
+        # UI (root /) becomes the sepia web app, /api/* proxies work as-is.
+        _lp.app.router.routes.insert(0, Mount("/", app=fastapi_app, name="querylens_web"))
+        print(f"[LAUNCHER] QueryLens web UI live on http://0.0.0.0:{PORT}", flush=True)
+        try:
+            _lp.block_thread()
+        except KeyboardInterrupt:
+            pass
+    else:
+        app = gr.mount_gradio_app(fastapi_app, _lp, path="/gradio-lp")
+        print(f"[LAUNCHER] QueryLens web UI live on http://0.0.0.0:{PORT}", flush=True)
+        import uvicorn
+        uvicorn.run(app, host="0.0.0.0", port=PORT)