Kagamicho/cs_chatbot

1# Deploying to Hugging Face Spaces2 3This guide walks you through getting the chatbot running on a free Hugging Face4Space — gives you a stable URL like `https://<user>-<space>.hf.space/` that5survives restarts (unlike the cloudflared quick-tunnel approach).6 7## Why HF Spaces for this app specifically8 9- The embedding model (`intfloat/multilingual-e5-large`, ~2.4GB) is **already10  cached on HF infrastructure** — first startup loads in seconds, not minutes11- Free tier: 16GB RAM, 2 vCPU, plenty for this workload12- Docker SDK means our existing FastAPI app runs as-is13- Private Spaces (visible only to you + invited collaborators) cost $014 15## Trade-offs to know up front16 17- **Cold start**: Spaces sleep after 48h of zero traffic. First request after18  sleep takes ~60s to wake. Fine for internal team testing; upgrade to "Always19  On" ($9/mo) when promoting to customer-facing.20- **CPU-only on free tier**: Acceptable latency (~5-15s per LLM call, matches21  the Gemini API roundtrip we already see locally)22- **Ephemeral filesystem**: JSONL chat logs are lost on container restart.23  For test/review use this is OK — ratings already in localStorage of testers'24  browsers are unaffected. For long-term persistence, migrate logs to Firestore.25 26## One-time setup27 28### 1. GitHub account + repo29 30You'll need a GitHub account (free at https://github.com/signup).31 32Create a **private** repo (call it e.g. `remix-chatbot`). Don't initialize with33README — we already have one.34 35Generate a Personal Access Token:361. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)372. Click "Generate new token (classic)"383. Note: `remix-chatbot deploy`394. Expiration: 90 days405. Scopes: tick `repo` (everything under it)416. Generate, copy the token — you won't see it again42 43### 2. Hugging Face account + token44 45Sign up at https://huggingface.co/join (free, just email).46 47Generate an access token:481. HF → Settings → Access Tokens → New token492. Name: `remix-chatbot-deploy`503. Type: **Write** (not read-only — we need to push)514. Copy the token52 53### 3. Set the GEMINI_API_KEY as an HF Space secret54 55(Done from the HF UI after creating the Space — instructions below.)56 57## Push the code58 59From `apps/chatbot/`:60 61```bash62# Configure git identity (one-time, if not already set globally)63git config user.name "Your Name"64git config user.email "you@example.com"65 66# Stage HF-deployment artifacts (these are excluded from .gitignore by default,67# but we force-include them so HF doesn't have to re-ingest from scratch)68git add -f data/processed/chunks.parquet \69           data/indexes/chroma \70           data/indexes/bm25.pkl71 72# Stage everything else (changes + new files)73git add -A74 75# Commit76git commit -m "Deploy: HF Spaces-ready (Dockerfile, README frontmatter, bundled KB)"77 78# Add remote + push (replace USER and REPO with your values)79git remote add origin https://USER:TOKEN@github.com/USER/REPO.git80git push -u origin main81```82 83The first push will be ~70-80 MB (mostly the bundled chroma data). That's fine84for GitHub — well under the 100MB-per-file limit.85 86## Create the HF Space87 881. https://huggingface.co/new-space892. Owner: your username (or org)903. Space name: e.g. `remix-bot`914. License: `mit` (or any — internal use)925. SDK: **Docker** → "Blank" template936. Visibility: **Private** (important — KB contains internal company Q&A)947. Hardware: **CPU basic** (free, 16GB RAM)958. Click "Create Space"96 97## Connect Space to GitHub (auto-deploy on push)98 99In the new Space:1001. Settings → "Linked Repositories" → "Add a linked repository"1012. Authorize Hugging Face GitHub App for your private repo1023. Select the repo, branch `main`, sync on push103 104OR (alternative) push directly to the HF Space's git repo:105 106```bash107git remote add hf https://USER:HF_TOKEN@huggingface.co/spaces/USER/SPACE_NAME108git push hf main109```110 111## Set the GEMINI_API_KEY secret112 113In the Space:1141. Settings → "Variables and secrets" → "New secret"1152. Name: `GEMINI_API_KEY`1163. Value: paste your Gemini API key from https://aistudio.google.com/apikey1174. Save118 119The Space will rebuild automatically after a secret is added.120 121## First build122 123Watch the "Logs" tab in the Space dashboard. The build does:124 1251. Pull `python:3.11-slim` base image1262. Install pip dependencies (~3-5 min the first time, cached on rebuilds)1273. Copy app code + bundled data1284. Start uvicorn129 130Expected: 8-15 minutes for the first build. Subsequent builds (just code131changes, no dep changes) finish in 2-3 minutes.132 133## URLs after deploy134 135- Chat widget:    `https://<user>-<space>.hf.space/`136- CS review page: `https://<user>-<space>.hf.space/review.html`137 138Both are HTTPS, both stable across restarts.139 140## Invite team collaborators141 142Space → Settings → "Collaborators" → add HF usernames. Private Spaces are143visible only to you and invited people.144 145## Common issues146 147**Build fails on "Read-only file system"** — Some pip versions complain about148the build env. The Dockerfile uses `pip install --user --no-cache-dir` to149avoid this; if you hit it, check that `USER user` came before the pip line.150 151**Bot returns "API quota exceeded"** — You hit Gemini's free tier rate limit.152Either wait (limits reset hourly), upgrade to paid Gemini, or share the test153load with your team across the day rather than burst-testing.154 155**Chunks not loading / "0 sources" responses** — Re-check that156`data/indexes/chroma/` actually committed. From your local repo:157`git ls-tree HEAD data/indexes/chroma/ | head` should show files. If empty,158the force-include in .gitignore didn't fire; redo `git add -f data/indexes/`.159 160**Container OOMs** — Free tier is 16GB which is way more than this app needs.161If it actually OOMs, you've got a leak elsewhere. Check `/admin/test-stats`162endpoint for anything growing unboundedly.163 164## Updating after the initial deploy165 166To push new code changes to the live Space:167 168```bash169git add -A170git commit -m "fix: <whatever>"171git push origin main172# HF auto-builds the Space (~2-3 min); or push directly to hf remote173```174 175To update the bundled KB (e.g., after re-ingesting new Q&A):176 177```bash178# After running ingest locally179git add -f data/processed/chunks.parquet data/indexes/chroma data/indexes/bm25.pkl180git commit -m "kb: refresh after Agentforce Q&A update"181git push origin main182```183