CoolFace
Apppublic

therenald/humanitarianRAG

sourceHugging Faceupdated 4mo agoView on Hugging Face
0likes
App README

RQ1b user-study app (hosted)

Self-contained deploy copy of the counterbalanced user study. The original project is untouched; this directory is what gets pushed to a Hugging Face Space.

  • —App flow: access gate → welcome → (brief → timed work → Likert) ×4 → qualitative → done
  • —Tools compared: RAG (evidence synthesis, prompt B, hybrid retrieval) vs keyword (BM25)
  • —Source links: both tools show "Open PDF · p.N" + "Report page" links to the original ReliefWeb documents (uses corpus_bundleA/corpus_metadata.csv, a slim doc_id→url map bundled here). RAG also has interactive inline citation pills.
  • —Counterbalancing & tasks: ui/study_config.py (identical to the local version)
  • —Embedding model: BAAI/bge-large-en-v1.5 (downloads from the HF hub on first run)
  • —Data: appended to a Google Sheet (ui/sheets.py); falls back to local CSV if Sheets isn't configured
The host filesystem is ephemeral — responses MUST go to the Google Sheet, not local CSV, or they are lost on restart.

One-time setup

1. Google Sheet + service account (data sink)

  1. 1.In Google Cloud Console → create a project → enable the Google Sheets API.
  2. 2.Create a service account → add a JSON key → download it.
  3. 3.Create a Google Sheet for the results. Copy its ID from the URL (https://docs.google.com/spreadsheets/d/<THIS_IS_THE_ID>/edit).
  4. 4.Share the Sheet with the service account's email (...@...iam.gserviceaccount.com) as Editor. (The app auto-creates task_data and qualitative tabs.)

2. Create the Space

  1. 1.huggingface.co → New Space → Docker SDK (blank) → CPU basic (free, 16 GB). (HF removed the native Streamlit SDK; the bundled Dockerfile runs Streamlit on port 7860.) Or via CLI: hf repo create <name> --repo-type space --space_sdk docker.
  2. 2.Push this directory to the Space (see "Deploy" below).

3. Space secrets (Settings → Variables and secrets → add as Secrets)

NameValue
STUDY_PASSCODESJSON map of personal access code → participant id, e.g. {"k7m2":"P1","q4r9":"P2",...}. Each participant gets one unique code that unlocks the study and assigns their id (no self-selection). Optionally add a "<code>":"DEMO" entry: a walkthrough code that runs the full flow but saves nothing (kept out of the counterbalanced schedule).
GOOGLE_API_KEYyour Gemini API key (used by the RAG tool)
SPREADSHEET_IDthe Google Sheet id from step 1.3
GCP_SERVICE_ACCOUNTthe entire service-account JSON, pasted as one value

On HF these become environment variables; ui/sheets.py reads GCP_SERVICE_ACCOUNT / SPREADSHEET_ID, and ui/study_app.py reads STUDY_PASSCODES, from the env. Give each participant only their own code in their invitation. (If STUDY_PASSCODES is unset, e.g. local dev, the gate is skipped and the welcome screen offers a participant dropdown instead.)

Deploy

bash
cd study_deploy
git init && git lfs install
git lfs track "*.pkl" "*.sqlite3" "*.bin"   # already in .gitattributes
git add . && git commit -m "Deploy user-study app"
git remote add origin https://huggingface.co/spaces/<user>/<space-name>
git push origin main

The Space builds from requirements.txt and launches ui/study_app.py. First boot is slow (it downloads the ~1.3 GB bge-large model); subsequent boots are fast.

Local smoke test

Without secrets, the gate is skipped and writes fall back to local CSV:

bash
streamlit run ui/study_app.py

Updating tasks/wording later

ui/study_config.py here is a copy. If you change tasks/Likert wording in the main project, re-copy that file here before redeploying so the two stay in sync.