Add Hugging Face Spaces deployment ($0/month)

- Dockerfile.hf: HF-specific Dockerfile (port 7860, UID 1000)
- scripts/deploy_hf.sh: one-command deploy to HF Spaces
- .github/workflows/keep-alive.yml: pings Space every 12h to
prevent 48h inactivity sleep
- Updated CLAUDE.md with all three deployment options

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.github/workflows/keep-alive.yml

@@ -0,0 +1,44 @@
+name: Keep HF Space Alive
+
+# Ping the Hugging Face Space every 12 hours to prevent 48h sleep.
+# The Space URL is stored as a repository variable (not secret — it's public).
+
+on:
+  schedule:
+    # Every 12 hours: at 06:00 and 18:00 UTC
+    - cron: "0 6,18 * * *"
+  workflow_dispatch: # Allow manual trigger
+
+jobs:
+  ping:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Ping HF Space health endpoint
+        env:
+          SPACE_URL: ${{ vars.HF_SPACE_URL }}
+        run: |
+          if [ -z "$SPACE_URL" ]; then
+            echo "HF_SPACE_URL variable not set — skipping"
+            exit 0
+          fi
+
+          echo "Pinging $SPACE_URL/api/health ..."
+
+          # First request may wake the Space (takes up to 2 min)
+          HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
+            --max-time 180 \
+            "$SPACE_URL/api/health")
+
+          echo "Response: HTTP $HTTP_CODE"
+
+          if [ "$HTTP_CODE" = "200" ]; then
+            echo "Space is alive!"
+          else
+            echo "Space returned $HTTP_CODE — it may be starting up"
+            # Retry after 60 seconds (Space may still be booting)
+            sleep 60
+            HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
+              --max-time 180 \
+              "$SPACE_URL/api/health")
+            echo "Retry response: HTTP $HTTP_CODE"
+          fi

CLAUDE.md

@@ -120,7 +120,22 @@ Services: `api` (FastAPI :8000), `ollama` (LLM :11434), `ingest`/`enrich` (one-s
 
 ## Infrastructure (Terraform)
 
-Two deployment options:
+Three deployment options:
+
+### Hugging Face Spaces — Free ($0/month, easiest)
+
+`Dockerfile.hf` + `scripts/deploy_hf.sh` — Docker Space on HF free tier (2 vCPU, 16 GB RAM).
+
+```bash
+# One-time: create Space at huggingface.co/new-space (Docker SDK, CPU basic)
+# Set GROQ_API_KEY as a Secret in Space Settings
+huggingface-cli login
+./scripts/deploy_hf.sh <username>/researchradar
+```
+
+- Sleeps after 48h inactivity; `.github/workflows/keep-alive.yml` pings every 12h to prevent this
+- Set `HF_SPACE_URL` as a GitHub repo variable for the keep-alive to work
+- Redeployments: re-run `deploy_hf.sh` or push to the HF Space repo directly
 
 ### Oracle Cloud — Always Free ($0/month, recommended for demos)
 

Dockerfile.hf

@@ -0,0 +1,69 @@
+# Hugging Face Spaces Dockerfile
+# Free tier: 2 vCPU, 16 GB RAM, 50 GB ephemeral disk
+# Must listen on port 7860, runs as UID 1000
+
+# ── Stage 1: Build frontend ─────────────────────────────────────────
+FROM node:22-slim AS frontend
+
+WORKDIR /frontend
+COPY frontend/package.json frontend/package-lock.json* ./
+RUN npm ci --no-audit --no-fund 2>/dev/null || npm install --no-audit --no-fund
+COPY frontend/ .
+RUN npm run build
+
+# ── Stage 2: Build Python dependencies ──────────────────────────────
+FROM python:3.12-slim AS builder
+
+WORKDIR /build
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc g++ && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
+
+# ── Stage 3: Runtime ────────────────────────────────────────────────
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Copy installed packages from builder
+COPY --from=builder /install /usr/local
+
+# NLTK data (punkt tokenizer for BM25)
+RUN python -m nltk.downloader -d /usr/share/nltk_data punkt punkt_tab
+
+ENV NLTK_DATA=/usr/share/nltk_data
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# HF Spaces runs as UID 1000 — create matching user
+RUN useradd -m -u 1000 user
+
+# Copy application code (owned by user)
+COPY --chown=user src/ ./src/
+COPY --chown=user scripts/ ./scripts/
+
+# Copy frontend build
+COPY --chown=user --from=frontend /frontend/dist ./frontend/dist
+
+# Data dir — writable by user
+RUN mkdir -p /app/data && chown user:user /app/data
+
+# Model cache
+ENV HF_HOME=/app/.cache/huggingface
+RUN mkdir -p /app/.cache/huggingface && chown -R user:user /app/.cache
+
+# Default to Groq (cloud LLM) — key set via HF Spaces secrets
+ENV LLM_BACKEND=groq
+ENV SQLITE_DB_PATH=/app/data/researchradar.db
+ENV CHROMA_DB_PATH=/app/data/chroma_db
+
+USER user
+ENV HOME=/home/user
+ENV PATH=/home/user/.local/bin:$PATH
+
+EXPOSE 7860
+
+CMD ["uvicorn", "src.api.app:app", "--host", "0.0.0.0", "--port", "7860"]

scripts/deploy_hf.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+# Deploy ResearchRadar to Hugging Face Spaces.
+#
+# Prerequisites:
+#   1. Create a Space at huggingface.co/new-space (Docker SDK)
+#   2. Set GROQ_API_KEY as a Secret in Space Settings
+#   3. Install: pip install huggingface_hub
+#   4. Login: huggingface-cli login
+#
+# Usage:
+#   ./scripts/deploy_hf.sh <hf_username>/<space_name>
+#
+# Example:
+#   ./scripts/deploy_hf.sh arkgithubforyou/researchradar
+
+set -e
+
+SPACE_ID="${1:?Usage: deploy_hf.sh <hf_username>/<space_name>}"
+SPACE_REPO="https://huggingface.co/spaces/${SPACE_ID}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+
+echo "=== Deploying ResearchRadar to HF Space: ${SPACE_ID} ==="
+
+# Create a temp directory for the HF Space repo
+TMPDIR=$(mktemp -d)
+trap "rm -rf $TMPDIR" EXIT
+
+echo "1. Cloning HF Space repo..."
+git clone "${SPACE_REPO}" "$TMPDIR/space" 2>/dev/null || {
+    echo "   Space doesn't exist yet or clone failed."
+    echo "   Create it first at: https://huggingface.co/new-space"
+    echo "   - Select 'Docker' as the SDK"
+    echo "   - Set hardware to 'CPU basic (Free)'"
+    exit 1
+}
+
+echo "2. Copying project files..."
+# Copy everything needed for the Docker build
+rsync -a --delete \
+    --exclude='.git/' \
+    --exclude='data/' \
+    --exclude='.venv/' \
+    --exclude='venv/' \
+    --exclude='__pycache__/' \
+    --exclude='*.pyc' \
+    --exclude='.env' \
+    --exclude='terraform/' \
+    --exclude='terraform-oci/' \
+    --exclude='frontend/node_modules/' \
+    --exclude='frontend/dist/' \
+    --exclude='.pytest_cache/' \
+    --exclude='.ruff_cache/' \
+    --exclude='htmlcov/' \
+    "$PROJECT_DIR/" "$TMPDIR/space/"
+
+echo "3. Setting up HF Space config..."
+# Use the HF-specific Dockerfile
+cp "$TMPDIR/space/Dockerfile.hf" "$TMPDIR/space/Dockerfile"
+
+# Create the required README.md with YAML frontmatter
+cat > "$TMPDIR/space/README.md" << 'EOF'
+---
+title: ResearchRadar
+emoji: 🔬
+colorFrom: indigo
+colorTo: blue
+sdk: docker
+app_port: 7860
+short_description: RAG-powered NLP research paper explorer
+startup_duration_timeout: 30m
+pinned: false
+---
+
+# ResearchRadar
+
+RAG-powered NLP/ML research paper explorer. Hybrid retrieval (BM25 + vector + cross-encoder reranking) + LLM generation over ACL Anthology papers.
+
+**Features:**
+- 🔍 Ask natural language questions about NLP research
+- 📄 Browse and filter papers by venue, year, method, dataset
+- 📊 Interactive analytics dashboard with trends, top entities, and co-occurrence
+- ⚡ Powered by Groq API for fast LLM inference
+
+Built with FastAPI, React, ChromaDB, and sentence-transformers.
+EOF
+
+echo "4. Pushing to HF Space..."
+cd "$TMPDIR/space"
+git add -A
+git commit -m "Deploy ResearchRadar $(date +%Y-%m-%d)" 2>/dev/null || {
+    echo "   No changes to deploy."
+    exit 0
+}
+git push
+
+echo ""
+echo "=== Deployed! ==="
+echo "Space URL: ${SPACE_REPO}"
+echo ""
+echo "NOTE: First build takes ~5-10 minutes."
+echo "Set GROQ_API_KEY as a Secret in Space Settings:"
+echo "  ${SPACE_REPO}/settings"