feat: add HuggingFace Spaces deployment (Dockerfile, artifact scripts, CORS fix)

.dockerignore

@@ -0,0 +1,33 @@
+# Version control
+.git
+.gitignore
+
+# Python virtual env (large, not needed in container)
+venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# Frontend (served separately via Vercel)
+frontend/
+
+# Raw data (large, not needed at inference)
+data/raw/
+
+# Notebooks
+notebooks/
+
+# Docs
+docs/
+
+# Dev artifacts
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+
+# OS files
+.DS_Store
+Thumbs.db

Dockerfile

@@ -0,0 +1,38 @@
+# ============================================================
+# DeepReads — FastAPI backend for HuggingFace Spaces (Docker)
+# Port: 7860 (HF Spaces requirement)
+# ============================================================
+
+FROM python:3.11-slim
+
+# System dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc g++ libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install Python dependencies first (layer-cached)
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy source code
+COPY src/ src/
+COPY scripts/ scripts/
+
+# Create required directories
+RUN mkdir -p models data/processed data/outputs/figures
+
+# HuggingFace Spaces injects these at runtime via Space secrets:
+#   HF_REPO_ID  — your model artifact repo, e.g. "yourname/deepreads-artifacts"
+#   HF_TOKEN    — (optional) if the artifact repo is private
+#   FRONTEND_URL — your Vercel frontend URL (for CORS), e.g. "https://deepreads.vercel.app"
+
+# Download artifacts and start the API server
+# The download script is a no-op if files already exist (fast restarts)
+CMD python scripts/download_artifacts.py && \
+    uvicorn src.api.app:app \
+        --host 0.0.0.0 \
+        --port 7860 \
+        --workers 1 \
+        --timeout-keep-alive 75

scripts/download_artifacts.py

@@ -0,0 +1,93 @@
+"""
+Download model and data artifacts from HuggingFace Hub at startup.
+
+Run once before starting the API server. Files are cached locally so
+subsequent restarts skip the download entirely.
+
+Usage:
+    python scripts/download_artifacts.py
+
+Environment variables:
+    HF_REPO_ID   — HuggingFace model repo, e.g. "yashb18/deepreads-artifacts"
+    HF_TOKEN     — Optional HF token (only needed if repo is private)
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Artifact manifest
+# Each entry: (repo_filename, local_path)
+# ---------------------------------------------------------------------------
+
+ROOT = Path(__file__).resolve().parent.parent
+
+ARTIFACT_MAP: list[tuple[str, Path]] = [
+    # ── Models ──────────────────────────────────────────────────────────────
+    ("models/two_tower.pt",          ROOT / "models" / "two_tower.pt"),
+    ("models/item_embeddings.npy",   ROOT / "models" / "item_embeddings.npy"),
+    ("models/item_index.pkl",        ROOT / "models" / "item_index.pkl"),
+    ("models/naive_baseline.pkl",    ROOT / "models" / "naive_baseline.pkl"),
+    ("models/naive_category.pkl",    ROOT / "models" / "naive_category.pkl"),
+    ("models/lgbm_model.pkl",        ROOT / "models" / "lgbm_model.pkl"),
+    # ── Processed data ──────────────────────────────────────────────────────
+    ("data/processed/item_features.parquet",  ROOT / "data" / "processed" / "item_features.parquet"),
+    ("data/processed/user_features.parquet",  ROOT / "data" / "processed" / "user_features.parquet"),
+    ("data/processed/train.parquet",          ROOT / "data" / "processed" / "train.parquet"),
+    ("data/processed/feature_artifacts.pkl",  ROOT / "data" / "processed" / "feature_artifacts.pkl"),
+    ("data/processed/item_encoder.pkl",       ROOT / "data" / "processed" / "item_encoder.pkl"),
+    ("data/processed/user_encoder.pkl",       ROOT / "data" / "processed" / "user_encoder.pkl"),
+]
+
+
+def main() -> None:
+    repo_id = os.environ.get("HF_REPO_ID", "")
+    if not repo_id:
+        print("ERROR: HF_REPO_ID environment variable is not set.", file=sys.stderr)
+        print("  Set it to your HuggingFace model repo, e.g.:", file=sys.stderr)
+        print("    export HF_REPO_ID=yourname/deepreads-artifacts", file=sys.stderr)
+        sys.exit(1)
+
+    token = os.environ.get("HF_TOKEN") or None
+
+    try:
+        from huggingface_hub import hf_hub_download
+    except ImportError:
+        print("ERROR: huggingface_hub is not installed. Run: pip install huggingface-hub", file=sys.stderr)
+        sys.exit(1)
+
+    missing = [(repo_fn, local) for repo_fn, local in ARTIFACT_MAP if not local.exists()]
+
+    if not missing:
+        print("All artifacts already present — skipping download.")
+        return
+
+    print(f"Downloading {len(missing)} artifact(s) from {repo_id} …")
+
+    for repo_filename, local_path in missing:
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+        print(f"  ↓  {repo_filename}")
+        try:
+            downloaded = hf_hub_download(
+                repo_id=repo_id,
+                filename=repo_filename,
+                repo_type="model",
+                token=token,
+                local_dir=ROOT,
+                local_dir_use_symlinks=False,
+            )
+            # hf_hub_download places files under local_dir/<filename>
+            # which matches local_path exactly, so nothing to move.
+            _ = downloaded
+        except Exception as exc:
+            print(f"ERROR: Failed to download {repo_filename}: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    print("Download complete.")
+
+
+if __name__ == "__main__":
+    main()

scripts/upload_artifacts.py

@@ -0,0 +1,99 @@
+"""
+Upload model and data artifacts to a HuggingFace Hub model repository.
+
+Run this ONCE from your local machine before deploying the Space.
+
+Usage:
+    HF_REPO_ID=yourname/deepreads-artifacts python scripts/upload_artifacts.py
+
+Environment variables:
+    HF_REPO_ID   — target HF model repo (will be created if it doesn't exist)
+    HF_TOKEN     — your HF write token (from https://huggingface.co/settings/tokens)
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+ARTIFACT_MAP: list[tuple[Path, str]] = [
+    # (local_path, repo_filename)
+    # ── Models ──────────────────────────────────────────────────────────────
+    (ROOT / "models" / "two_tower.pt",          "models/two_tower.pt"),
+    (ROOT / "models" / "item_embeddings.npy",   "models/item_embeddings.npy"),
+    (ROOT / "models" / "item_index.pkl",        "models/item_index.pkl"),
+    (ROOT / "models" / "naive_baseline.pkl",    "models/naive_baseline.pkl"),
+    (ROOT / "models" / "naive_category.pkl",    "models/naive_category.pkl"),
+    (ROOT / "models" / "lgbm_model.pkl",        "models/lgbm_model.pkl"),
+    # ── Processed data ──────────────────────────────────────────────────────
+    (ROOT / "data" / "processed" / "item_features.parquet",  "data/processed/item_features.parquet"),
+    (ROOT / "data" / "processed" / "user_features.parquet",  "data/processed/user_features.parquet"),
+    (ROOT / "data" / "processed" / "train.parquet",          "data/processed/train.parquet"),
+    (ROOT / "data" / "processed" / "feature_artifacts.pkl",  "data/processed/feature_artifacts.pkl"),
+    (ROOT / "data" / "processed" / "item_encoder.pkl",       "data/processed/item_encoder.pkl"),
+    (ROOT / "data" / "processed" / "user_encoder.pkl",       "data/processed/user_encoder.pkl"),
+]
+
+
+def main() -> None:
+    repo_id = os.environ.get("HF_REPO_ID", "")
+    if not repo_id:
+        print("ERROR: Set HF_REPO_ID, e.g.:")
+        print("  export HF_REPO_ID=yourname/deepreads-artifacts")
+        sys.exit(1)
+
+    token = os.environ.get("HF_TOKEN") or None
+    if not token:
+        print("WARNING: HF_TOKEN not set. Will try using cached credentials.")
+        print("  Get a write token at https://huggingface.co/settings/tokens")
+
+    try:
+        from huggingface_hub import HfApi
+    except ImportError:
+        print("ERROR: pip install huggingface-hub")
+        sys.exit(1)
+
+    api = HfApi(token=token)
+
+    # Create repo if it doesn't exist
+    try:
+        api.create_repo(repo_id=repo_id, repo_type="model", exist_ok=True, private=False)
+        print(f"Repository ready: https://huggingface.co/{repo_id}")
+    except Exception as e:
+        print(f"ERROR creating repo: {e}")
+        sys.exit(1)
+
+    missing = [(local, repo_fn) for local, repo_fn in ARTIFACT_MAP if not local.exists()]
+    if missing:
+        print(f"WARNING: {len(missing)} local file(s) not found and will be skipped:")
+        for local, _ in missing:
+            print(f"  {local}")
+
+    to_upload = [(local, repo_fn) for local, repo_fn in ARTIFACT_MAP if local.exists()]
+    total = len(to_upload)
+    print(f"\nUploading {total} file(s) to {repo_id} …\n")
+
+    for i, (local_path, repo_filename) in enumerate(to_upload, 1):
+        size_mb = local_path.stat().st_size / 1_048_576
+        print(f"  [{i}/{total}] {repo_filename}  ({size_mb:.1f} MB)")
+        try:
+            api.upload_file(
+                path_or_fileobj=str(local_path),
+                path_in_repo=repo_filename,
+                repo_id=repo_id,
+                repo_type="model",
+            )
+        except Exception as e:
+            print(f"    ERROR: {e}")
+            sys.exit(1)
+
+    print(f"\nDone! All artifacts uploaded to:")
+    print(f"  https://huggingface.co/{repo_id}")
+    print(f"\nNext: set HF_REPO_ID={repo_id} as a Space secret.")
+
+
+if __name__ == "__main__":
+    main()

src/api/app.py

@@ -86,7 +86,6 @@ app = FastAPI(
 cors_origins = [
     "http://localhost:3000",
     "http://localhost:3001",
-    "https://*.vercel.app",
 ]
 env_origin = os.getenv("FRONTEND_URL")
 if env_origin:
@@ -95,6 +94,8 @@ if env_origin:
 app.add_middleware(
     CORSMiddleware,
     allow_origins=cors_origins,
+    # Wildcard for all Vercel preview/production deployments
+    allow_origin_regex=r"https://.*\.vercel\.app",
     allow_credentials=True,
     allow_methods=["*"],
     allow_headers=["*"],