feat(backend): rewire for hugging face spaces deployment

- registry.py: replace gdown / Google Drive with
huggingface_hub.snapshot_download from bani57/checkpoints. The
remote layout mirrors the on-disk one under CHECKPOINTS_ROOT, so the
scan logic finds files unchanged and the old _distribute_checkpoints
step is gone.
- settings.py: env-drive ALLOWED_HOSTS, CORS_ALLOWED_ORIGINS,
RESEARCH_ROOT and CHECKPOINTS_ROOT so dev (local repo paths) and
prod (writable /app/checkpoints) share one settings file. Add
whitenoise + django.contrib.staticfiles for same-origin SPA
serving via SPA_DIST_DIR / WHITENOISE_ROOT, plus SecurityMiddleware,
CsrfViewMiddleware and XFrameOptionsMiddleware (deploy-check
hygiene). HSTS / secure cookies / CSRF_TRUSTED_ORIGINS gated on
DEBUG=False; SECURE_SSL_REDIRECT stays off because HF Spaces
terminates TLS upstream.
- urls.py: add a non-API catch-all view that serves dist/index.html
so Vue Router (and its Lara Croft 404) handles client-side routes.
- requirements.txt: drop gdown, add huggingface_hub,
whitenoise[brotli], gunicorn. Trim the conda-only comment to the
packages actually present in website_c (rdkit, boost).
- README.md: rewrite Prerequisites, the env-var table and the
Startup Sequence; add a Deployment section pointing at the
Dockerfile / docker compose flow.

src/backend/README.md

@@ -4,24 +4,33 @@ Stateless REST API serving the PhD research models. No database — PyTorch chec
 
 ## Prerequisites
 
-1. **Conda environment** with pre-installed system deps:
+1. **Mamba environment** mirroring the deployment image. The repo-root `environment.yml`
+   captures the conda half (Python 3.9, `rdkit=2023.03.2`, `boost=1.78`, cairo, etc.):
    ```bash
-   conda create -n website python=3.9
-   conda activate website
-   conda install -c conda-forge rdkit=2023.03.2 graph-tool=2.45
+   mamba env create -n website_c -f ../../environment.yml
+   mamba activate website_c
    ```
 
-2. **Pip dependencies**:
+2. **Pip dependencies** (GPU torch, Django, DRF, …):
    ```bash
-   pip install -r requirements.txt
+   pip install --extra-index-url https://download.pytorch.org/whl/cu118 -r requirements.txt
    ```
 
-3. **Model checkpoints** — downloaded automatically from Google Drive on first boot (via `gdown`). Alternatively, manually place files in:
+3. **Model checkpoints** — downloaded automatically from the Hugging Face Hub model repo
+   `bani57/checkpoints` on first boot. The remote layout mirrors the on-disk one, so
+   `huggingface_hub.snapshot_download(local_dir=CHECKPOINTS_ROOT)` drops files directly
+   into the expected paths:
    - `src/research/COINs-KGGeneration/graph_completion/checkpoints/` (COINs: `{dataset}_{algorithm}.tar`)
-   - `src/research/COINs-KGGeneration/graph_completion/results/{dataset}/` (KBGAT TransE init: `transe_model.tar`; auto-distributed from `transe_model_{dataset}.tar` in the Drive's `checkpoints_coins` folder)
+   - `src/research/COINs-KGGeneration/graph_completion/results/{dataset}/` (KBGAT TransE init: `transe_model.tar`)
    - `src/research/COINs-KGGeneration/graph_generation/checkpoints/` (KG anomaly: `{dataset}.ckpt`, `{dataset}_correct.ckpt`)
    - `src/research/MultiProxAn/checkpoints/` (graph generation: `{dataset}.ckpt`, `{dataset}_c.ckpt`)
 
+   To (re-)publish the checkpoints to the Hub from a local copy:
+   ```bash
+   huggingface-cli login   # one-time
+   python ../../scripts/upload_checkpoints.py --create
+   ```
+
 4. **Dataset files** — the raw KG data files must be present under `src/research/COINs-KGGeneration/data/` (FB15k-237, WN18RR, NELL-995).
 
 ## Running
@@ -45,19 +54,54 @@ The API is served at `http://localhost:8000/api/v1/`.
 | `DJANGO_SECRET_KEY` | `dev-insecure-key-change-in-production` | Django secret key. **Set in production.** |
 | `DJANGO_DEBUG` | `True` | Enable debug mode. Set to `False` in production. |
 | `DJANGO_ALLOWED_HOSTS` | `localhost,127.0.0.1` | Comma-separated allowed hosts. |
+| `CORS_ALLOWED_ORIGINS` | `https://bani57-website.hf.space` | Comma-separated allowed CORS origins. |
 | `TORCH_DEVICE` | Auto (`cuda:0` if available, else `cpu`) | PyTorch device for model inference. |
+| `RESEARCH_ROOT` | `<repo>/src/research` | Where the research-code modules live. |
+| `CHECKPOINTS_ROOT` | Same as `RESEARCH_ROOT` | Where `huggingface_hub` deposits weights. In the container this is `/app/checkpoints` on a writable volume. |
+| `HF_CHECKPOINTS_REPO` | `bani57/checkpoints` | HF Hub model repo holding all weights. |
+| `HF_TOKEN` | unset | Only needed if the checkpoint repo is private. |
+| `SPA_DIST_DIR` | `<backend>/dist` | Folder containing `index.html` from `npm run build`. WhiteNoise serves assets from here. |
 
 ## Startup Sequence
 
-On boot (`ApiConfig.ready()`), the `ModelRegistry` initializes:
+In the deployment container the entrypoint script pre-warms the checkpoint download
+from the Hugging Face Hub *before* gunicorn starts, so workers never block on the
+network. Then on Django boot (`ApiConfig.ready()`), the `ModelRegistry` initializes:
 
-1. **Download checkpoints** from Google Drive if not already present locally
+1. **Verify / download checkpoints** from `bani57/checkpoints` on HF Hub if any expected
+   subdir is missing. Idempotent — a no-op when the entrypoint already populated the tree
+   or when running locally with weights on disk.
 2. **Scan checkpoint directories** to detect available models per method
 3. **Load lightweight COINs Loaders** — one per dataset (freebase, wordnet, nell), loading graph data, name maps, and train/val/test splits. Heavy arrays (node neighbours ~275MB each, community neighbours, adjacency dicts) are freed after initialization to keep memory low.
 4. **Generate sample subgraphs** for KG anomaly using the COINs Loaders
 
 All model weights (COINs inference, graph generation, KG anomaly) are loaded lazily at first inference request.
 
+## Deployment
+
+The site is packaged as a single Docker image and deployed to a Hugging Face Space
+(`bani57/website` -> <https://bani57-website.hf.space>). The image:
+
+- builds the Vue SPA with `npm run build` in a Node 20 stage,
+- assembles a `mambaorg/micromamba` runtime mirroring the local `website_c` env from
+  `environment.yml` + `requirements.txt` (GPU torch wheels, `cu118`),
+- copies the SPA `dist/` next to Django so WhiteNoise serves it on the same origin as
+  `/api/v1/`,
+- runs `entrypoint.sh`, which `snapshot_download`s checkpoints from
+  `bani57/checkpoints` on HF Hub into `/app/checkpoints` and execs `gunicorn` on `0.0.0.0:7860`.
+
+Local reproduction:
+```bash
+docker compose up --build
+# -> http://localhost:7860
+```
+
+Push to the Space (one-time remote setup):
+```bash
+git remote add hf https://huggingface.co/spaces/bani57/website
+git push hf master:main
+```
+
 ## API Endpoints
 
 All endpoints are prefixed with `/api/v1/`.

src/backend/api/services/registry.py

@@ -60,25 +60,20 @@ def _safe_load_lightning_checkpoint(cls, ckpt_path):
     return model
 
 
-GDRIVE_FOLDER_ID = "14Bf8fi4KJn0rDdh9y8EFyA5b8OpQyXWi"
-
-GDRIVE_SUBFOLDERS = {
-    "coins": {
-        "folder_name": "COINs-KGGeneration/checkpoints_coins",
-        "local_dir_setting": "COINS_COMPLETION_DIR",
-        "local_subdir": "checkpoints",
-    },
-    "kg_generation": {
-        "folder_name": "COINs-KGGeneration/checkpoints_kg_generation",
-        "local_dir_setting": "DIGRESS_KG_DIR",
-        "local_subdir": "checkpoints",
-    },
-    "multiproxan": {
-        "folder_name": "MultiProxAn/checkpoints",
-        "local_dir_setting": "MULTIPROXAN_DIR",
-        "local_subdir": "checkpoints",
-    },
-}
+# Hugging Face Hub model repo holding all checkpoints.  The repo mirrors the
+# on-disk layout under settings.CHECKPOINTS_ROOT (RESEARCH_ROOT by default), so
+# snapshot_download() drops every file into its final location and the scan
+# routines below find them unchanged.
+HF_CHECKPOINTS_REPO = os.environ.get("HF_CHECKPOINTS_REPO", "bani57/checkpoints")
+
+# Per-area checkpoint subdirectories (relative to CHECKPOINTS_ROOT).  Used to
+# detect a fully-populated tree so we can skip the network round-trip on warm
+# starts.
+_CHECKPOINT_SUBDIRS = (
+    Path("COINs-KGGeneration") / "graph_completion" / "checkpoints",
+    Path("COINs-KGGeneration") / "graph_generation" / "checkpoints",
+    Path("MultiProxAn") / "checkpoints",
+)
 
 # Shared sampler hyperparameters used across all COINs experiments
 _SAMPLER_HPARS = {
@@ -340,36 +335,45 @@ class ModelRegistry:
     # ---- Checkpoint download -------------------------------------------
 
     def _download_checkpoints(self):
-        """Download checkpoints from Google Drive if not already present locally."""
+        """Download checkpoints from Hugging Face Hub if not already present.
+
+        The HF repo mirrors the on-disk layout under ``CHECKPOINTS_ROOT``, so a
+        single ``snapshot_download`` drops every file into its final location.
+        Idempotent: when all expected subdirs are populated we skip the
+        network round-trip.  In production the entrypoint script also pre-warms
+        this download before gunicorn starts, so workers never block on it.
+        """
         if self._all_checkpoint_dirs_populated():
-            logger.info("All checkpoint directories already populated, skipping Google Drive download")
+            logger.info("All checkpoint directories already populated, skipping HF Hub download")
             return
 
         try:
-            import gdown
+            from huggingface_hub import snapshot_download
         except ImportError:
-            logger.warning("gdown not installed, skipping checkpoint download")
+            logger.warning("huggingface_hub not installed, skipping checkpoint download")
             return
 
-        gdrive_url = f"https://drive.google.com/drive/folders/{GDRIVE_FOLDER_ID}"
-        logger.info("Downloading checkpoints from Google Drive: %s", gdrive_url)
+        target = Path(settings.CHECKPOINTS_ROOT)
+        target.mkdir(parents=True, exist_ok=True)
+        logger.info("Downloading checkpoints from HF Hub repo %s -> %s", HF_CHECKPOINTS_REPO, target)
 
         try:
-            staging_dir = Path(settings.BASE_DIR) / ".checkpoint_staging"
-            staging_dir.mkdir(exist_ok=True)
-
-            gdown.download_folder(
-                gdrive_url, output=str(staging_dir), quiet=False, resume=True,
+            snapshot_download(
+                repo_id=HF_CHECKPOINTS_REPO,
+                repo_type="model",
+                local_dir=str(target),
+                local_dir_use_symlinks=False,
+                max_workers=4,
+                token=os.environ.get("HF_TOKEN"),
             )
-
-            self._distribute_checkpoints(staging_dir)
         except Exception:
-            logger.exception("Failed to download checkpoints from Google Drive, continuing with local files")
+            logger.exception("Failed to download checkpoints from HF Hub, continuing with local files")
 
     def _all_checkpoint_dirs_populated(self):
-        """Check if all checkpoint dirs already have at least one checkpoint file."""
-        for config in GDRIVE_SUBFOLDERS.values():
-            dest_dir = Path(getattr(settings, config["local_dir_setting"])) / config["local_subdir"]
+        """True if every expected checkpoint subdir contains at least one weight file."""
+        root = Path(settings.CHECKPOINTS_ROOT)
+        for sub in _CHECKPOINT_SUBDIRS:
+            dest_dir = root / sub
             if not dest_dir.exists():
                 return False
             ckpt_files = list(dest_dir.glob("*.tar")) + list(dest_dir.glob("*.ckpt"))
@@ -377,40 +381,6 @@ class ModelRegistry:
                 return False
         return True
 
-    def _distribute_checkpoints(self, staging_dir):
-        """Move downloaded files from staging into the correct checkpoint directories."""
-        for group, config in GDRIVE_SUBFOLDERS.items():
-            src_dir = staging_dir / config["folder_name"]
-            if not src_dir.exists():
-                logger.warning("Expected staging subfolder not found: %s", src_dir)
-                continue
-
-            dest_dir = Path(getattr(settings, config["local_dir_setting"])) / config["local_subdir"]
-            dest_dir.mkdir(parents=True, exist_ok=True)
-
-            for src_file in src_dir.iterdir():
-                if not src_file.is_file():
-                    continue
-                # transe_model.tar files (named transe_model_{dataset}.tar) are used for KBGAT
-                # initialization and must land in results/{dataset}/ not checkpoints/.
-                if group == "coins" and src_file.stem.startswith("transe_model_"):
-                    dataset_name = src_file.stem[len("transe_model_"):]
-                    transe_dest_dir = Path(getattr(settings, config["local_dir_setting"])) / "results" / dataset_name
-                    transe_dest_dir.mkdir(parents=True, exist_ok=True)
-                    transe_dest_file = transe_dest_dir / "transe_model.tar"
-                    if transe_dest_file.exists() and transe_dest_file.stat().st_size == src_file.stat().st_size:
-                        logger.debug("TransE model already present, skipping: %s", transe_dest_file)
-                        continue
-                    logger.info("Installing TransE model: %s -> %s", src_file.name, transe_dest_dir)
-                    src_file.replace(transe_dest_file)
-                    continue
-                dest_file = dest_dir / src_file.name
-                if dest_file.exists() and dest_file.stat().st_size == src_file.stat().st_size:
-                    logger.debug("Checkpoint already present, skipping: %s", dest_file.name)
-                    continue
-                logger.info("Installing checkpoint: %s -> %s", src_file.name, dest_dir)
-                src_file.replace(dest_file)
-
     # ---- Checkpoint scanning -------------------------------------------
 
     def _scan_checkpoints(self):

src/backend/requirements.txt

@@ -3,8 +3,14 @@ django==4.2.*
 djangorestframework==3.14.*
 django-cors-headers==4.*
 
-# Checkpoint download from Google Drive
-gdown>=4.7
+# Static-file serving (SPA dist + Django admin) — single-origin deploy
+whitenoise[brotli]>=6.7
+
+# Production WSGI server
+gunicorn>=21.2
+
+# Checkpoint download from Hugging Face Hub (replaces gdown / Google Drive)
+huggingface_hub>=0.25
 
 # PyTorch with CUDA 11.8 (falls back to CPU at runtime if no GPU present)
 --extra-index-url https://download.pytorch.org/whl/cu118
@@ -35,6 +41,7 @@ scikit-learn>=1.0
 Pillow>=9.5.0
 overrides==7.3.1
 
-# Conda-only deps (must be pre-installed, not in pip requirements):
-# rdkit==2023.03.2 (conda create -c conda-forge)
-# graph-tool==2.45 (conda install -c conda-forge)
+# Conda-only deps (must be pre-installed via the bundled environment.yml):
+#   rdkit=2023.03.2  — required, used by molecule rendering for the
+#                      MultiProxAn QM9/MOSES/Guacamol demos
+#   boost=1.78       — rdkit transitive on conda-forge

src/backend/research_api/settings.py

@@ -21,12 +21,17 @@ ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "localhost,127.0.0.1").sp
 INSTALLED_APPS = [
     "corsheaders",
     "rest_framework",
+    "django.contrib.staticfiles",
     "api",
 ]
 
 MIDDLEWARE = [
     "corsheaders.middleware.CorsMiddleware",
+    "django.middleware.security.SecurityMiddleware",
+    "whitenoise.middleware.WhiteNoiseMiddleware",
     "django.middleware.common.CommonMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.middleware.clickjacking.XFrameOptionsMiddleware",
 ]
 
 ROOT_URLCONF = "research_api.urls"
@@ -45,16 +50,47 @@ REST_FRAMEWORK = {
 }
 
 CORS_ALLOWED_ORIGINS = [
-    "https://bani57.pythonanywhere.com",
+    o.strip() for o in os.environ.get(
+        "CORS_ALLOWED_ORIGINS", "https://bani57-website.hf.space"
+    ).split(",") if o.strip()
 ]
 if DEBUG:
     CORS_ALLOW_ALL_ORIGINS = True
 
+# Security headers (active when DEBUG=False).  Gated on DEBUG so local dev
+# over plain HTTP doesn't get redirected/blocked.
+SECURE_CONTENT_TYPE_NOSNIFF = True
+SECURE_REFERRER_POLICY = "same-origin"
+X_FRAME_OPTIONS = "DENY"
+if not DEBUG:
+    SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
+    SECURE_SSL_REDIRECT = False  # HF Spaces terminates TLS upstream; redirect would loop
+    SECURE_HSTS_SECONDS = 31536000
+    SECURE_HSTS_INCLUDE_SUBDOMAINS = True
+    SECURE_HSTS_PRELOAD = False
+    CSRF_COOKIE_SECURE = True
+    SESSION_COOKIE_SECURE = True
+    CSRF_TRUSTED_ORIGINS = [o for o in CORS_ALLOWED_ORIGINS if o.startswith("https://")]
+
+# Research code root.  Inside the container the checkpoints live alongside the
+# research code under /app/research; in dev they live in the repo at
+# src/research/.  CHECKPOINTS_ROOT is what huggingface_hub will populate.
+RESEARCH_ROOT = Path(os.environ.get("RESEARCH_ROOT", PROJECT_ROOT / "src" / "research"))
+CHECKPOINTS_ROOT = Path(os.environ.get("CHECKPOINTS_ROOT", RESEARCH_ROOT))
+
 # Research code paths
-COINS_DATA_DIR = PROJECT_ROOT / "src" / "research" / "COINs-KGGeneration" / "data"
-COINS_COMPLETION_DIR = PROJECT_ROOT / "src" / "research" / "COINs-KGGeneration" / "graph_completion"
-DIGRESS_KG_DIR = PROJECT_ROOT / "src" / "research" / "COINs-KGGeneration" / "graph_generation"
-MULTIPROXAN_DIR = PROJECT_ROOT / "src" / "research" / "MultiProxAn"
+COINS_DATA_DIR = RESEARCH_ROOT / "COINs-KGGeneration" / "data"
+COINS_COMPLETION_DIR = CHECKPOINTS_ROOT / "COINs-KGGeneration" / "graph_completion"
+DIGRESS_KG_DIR = CHECKPOINTS_ROOT / "COINs-KGGeneration" / "graph_generation"
+MULTIPROXAN_DIR = CHECKPOINTS_ROOT / "MultiProxAn"
+
+# Static files & SPA dist (Vue's npm run build output, copied into the image)
+STATIC_URL = "/static/"
+STATIC_ROOT = BASE_DIR / "staticfiles"
+STATICFILES_STORAGE = "whitenoise.storage.CompressedManifestStaticFilesStorage"
+SPA_DIST_DIR = Path(os.environ.get("SPA_DIST_DIR", BASE_DIR / "dist"))
+WHITENOISE_ROOT = str(SPA_DIST_DIR)
+WHITENOISE_INDEX_FILE = "index.html"
 
 DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
 

src/backend/research_api/urls.py

@@ -1,5 +1,23 @@
-from django.urls import include, path
+from django.conf import settings
+from django.http import FileResponse, Http404
+from django.urls import include, path, re_path
+
+
+def spa_index(_request):
+    """Serve the SPA shell for any non-API path.
+
+    WhiteNoise serves real files from ``SPA_DIST_DIR`` (assets, favicon, …)
+    before URL routing, so this view only fires for client-side routes such
+    as ``/cv``, ``/demos/coins`` or unknown paths — Vue Router picks them up
+    on the client (the wildcard route renders the Lara Croft 404).
+    """
+    index = settings.SPA_DIST_DIR / "index.html"
+    if not index.exists():
+        raise Http404("SPA build is missing — run `npm run build` in src/frontend first")
+    return FileResponse(open(index, "rb"), content_type="text/html")
+
 
 urlpatterns = [
     path("api/v1/", include("api.urls")),
+    re_path(r"^(?!api/).*$", spa_index, name="spa-index"),
 ]