README.md

---
title: SRH Pathology Validation Study
emoji: 🔬
colorFrom: purple
colorTo: indigo
sdk: gradio
sdk_version: 4.44.1
python_version: "3.11"
app_file: app.py
pinned: false
---

# SRH Pathology Validation Study annotation app

Blinded, resume-safe expert-validation app for the generate-to-discover study on Stimulated Raman Histology.
Two pre-registered arms (see `../protocol.md`), one grading unit per screen:

- **Task A - realism & memorization:** one SRH patch, blinded to source; judge Real vs AI-generated,
  confidence, whether it looks copied, and clinical plausibility.
- **Task B - discovered-category review:** a grid of patches the model grouped as one discovered category;
  judge whether it is a coherent, clinically meaningful morphology (+ optional description). Includes hidden
  positive/negative controls.

## Reused infrastructure
First-login self-setup auth (invite -> choose own username/password, pbkdf2-hashed in a private dataset),
localStorage resume (closing the tab does not sign you out), append-only per-(reader,item) storage to a
private dataset + local backup, per-image display-only zoom/brightness/contrast, blinded + deterministic
per-reader randomization, and a fully on-screen self-explanatory UI.

## Run locally
```bash
pip install -r requirements.txt
python build_cases_example.py   # generates data/cases.json + placeholder SRH-like images (demo)
python app.py                   # http://127.0.0.1:7860  (demo invites reader1/changeme)
```

## Deploy as a Hugging Face Space (Gradio)
Upload `app.py`, `requirements.txt`, `README.md`, and (for a demo) `data/`. Set secrets in Settings:
- `HF_TOKEN` (write) for the private response/account dataset.
- `READER_CREDENTIALS` = JSON of one-time invites, e.g. `{"Dr A":"<pw1>","Dr B":"<pw2>"}`.
- `RESPONSE_DATASET` = e.g. `DrSyedFaizan/srh-reader-responses` (private, auto-created).
- `CASES_DATASET` (optional) = private dataset with the real `cases.json` + images (pulled at boot).
- `APP_SECRET` (optional) = random string signing resume tokens.

## Storage schema (robust)
Append-only per reader (`responses/<reader>.jsonl`), one record per graded item keyed by
`(annotator, case_id)` with `arm` and a `dims` dict of the arm's answers (Task A stores the hidden
`true_source`; Task B stores `cluster_id` and `is_control`). Layout/wording changes never overwrite prior data.

## Real cases
Run `build_cases_example.py` and read its docstring for the exact schema, then replace the demo with real
generated/real SRH patches (Arm A) and discovered-cluster exemplars (Arm B) via a private `CASES_DATASET`.