README.md

# Deploying the PhysioLead Space to Hugging Face (git / Option B)

Step-by-step for pushing this demo to a Hugging Face Space using git.

---

## 0. Prerequisites

**Files you need in this folder before pushing (6 total):**

| File | Where it comes from |
|------|---------------------|
| `app.py` | this repo |
| `requirements.txt` | this repo |
| `README.md` | this repo (has the HF Space frontmatter — keep it) |
| `export_for_space.py` | this repo (optional; documentation only) |
| `physiolead_model.pt` | **run `export_for_space.py` in Kaggle**, download from Output tab |
| `physiolead_examples.npz` | same Kaggle run, same Output tab |

If you don't have the last two, run the export cell in your Kaggle notebook first
(after `model`, `ROOT`, `meta` exist). They save to `/kaggle/working/` — download
them from Kaggle's right-hand **Output** panel.

**An HF write token:**
1. huggingface.co → your avatar → **Settings** → **Access Tokens**
2. **New token** → Type: **Write** → copy it (used as your git password below).

---

## 1. Create the Space (once)

Either on the website — **New Space** → name `physiolead-ecg`, SDK **Gradio**,
license MIT — or from the CLI:

```bash
pip install huggingface_hub
huggingface-cli login          # paste your write token
huggingface-cli repo create physiolead-ecg --type space --space_sdk gradio
```

Replace `YOUR_USERNAME` below with your HF username throughout.

---

## 2. Clone, add files, push

```bash
# clone the (empty) Space repo
git clone https://huggingface.co/spaces/YOUR_USERNAME/physiolead-ecg
cd physiolead-ecg

# copy your 6 files into this folder (adjust paths to where you downloaded them)
cp /path/to/app.py .
cp /path/to/requirements.txt .
cp /path/to/README.md .
cp /path/to/export_for_space.py .
cp /path/to/physiolead_model.pt .
cp /path/to/physiolead_examples.npz .

# stage and commit
git add app.py requirements.txt README.md export_for_space.py \
        physiolead_model.pt physiolead_examples.npz
git commit -m "PhysioLead reduced-lead ECG reconstruction demo"

# push (username = your HF username, password = your WRITE token)
git push
```

The Space rebuilds automatically. Watch the **build logs** on the Space page.

---

## 3. Large-file note (only if the push is rejected)

`physiolead_model.pt` is small (a few MB) and pushes fine over plain git. But HF
Spaces track `*.pt` with **git-lfs** by default. If the push complains about file
size or LFS:

```bash
git lfs install
git lfs track "*.pt" "*.npz"
git add .gitattributes
git add physiolead_model.pt physiolead_examples.npz
git commit -m "track model + examples with LFS"
git push
```

---

## 4. Verify

Open `https://huggingface.co/spaces/YOUR_USERNAME/physiolead-ecg`.

- **Build succeeds, app loads** → pick the Normal example → you should see the
  12-lead plot and mean precordial QRS-r ≈ 0.97.
- **`load_state_dict` error in the logs** → the model classes in `app.py` don't
  match your trained model's dimensions. Fix the class definitions in `app.py` to
  match, commit, push again.
- **"examples all look the same"** → your `physiolead_examples.npz` has duplicate
  beats; re-run the (fixed) `export_for_space.py` in Kaggle and re-push just that
  file.

---

## 5. Updating later

To push a change (e.g. an edited `app.py`):

```bash
# in the physiolead-ecg folder
git add app.py
git commit -m "update app"
git push
```

The Space rebuilds on every push.

---

## Common issues

- **`Authentication failed`** — use your **write token** as the password, not your
  account password. Username is your HF username.
- **`remote: Password authentication ... deprecated`** — same fix: token, not
  password.
- **Build stuck / red status** — open the logs; a missing package goes in
  `requirements.txt`, a code error shows a traceback there.
- **Wrong SDK** — the `README.md` frontmatter must say `sdk: gradio`; if you
  created the Space as Static or Streamlit, delete and recreate as Gradio.