DEPLOY_HF_SPACES.md

# Deploy to Hugging Face Spaces (Gradio)

This project is now ready for Hugging Face Spaces.

## Option A (recommended): single Space repo with checkpoints

Use this when you want the simplest deployment.

1. Create a new Hugging Face Space:
- SDK: Gradio
- Hardware: CPU Basic to start, upgrade to GPU for faster inference

2. Push this project to that Space repo.

3. Ensure these files are present at the Space repo root:
- app.py
- requirements.txt
- configs/config.yaml
- models/
- data/
- utils/
- checkpoints/changeformer_best.pth (or your preferred model)

4. In Space Settings, set startup file to `app.py` (default for Gradio Spaces).

5. Optional: reduce initial footprint by keeping only one checkpoint (for example `changeformer_best.pth`) inside `checkpoints/`.

## Option B: Space app + separate model repo

Use this when you want a smaller Space repo and keep large checkpoints elsewhere.

1. Upload checkpoint files to a separate Hugging Face model repo.

2. In your Space Settings -> Variables, set:
- `HF_MODEL_REPO`: owner/repo-name
- `HF_MODEL_REVISION`: optional branch/tag/commit (for reproducible deployment)

3. On startup, `app.py` will auto-download expected checkpoint filenames into `checkpoints/`.

Expected checkpoint names:
- siamese_cnn_best.pth
- unet_pp_best.pth
- changeformer_best.pth

## Space README metadata (required in Space repo)

In the Space repository README.md, include this at the top:

```yaml
---
title: Military Base Change Detection
emoji: satellite
colorFrom: blue
colorTo: red
sdk: gradio
sdk_version: 4.44.1
app_file: app.py
pinned: false
python_version: 3.10
---
```

## Notes

- CPU hardware works, but inference can be slow for larger images.
- For better latency, choose a GPU Space.
- `app.py` now detects Spaces automatically and binds to `0.0.0.0`.
- If no local checkpoints are found, it will try `HF_MODEL_REPO`.

## Quick local validation before push

```bash
pip install -r requirements.txt
python app.py
```

Then open the local Gradio URL and test one sample pair.