Upload folder using huggingface_hub

HF_SPACE_GUIDE.md

@@ -0,0 +1,109 @@
+# HF Space Deployment & Dataset Guide
+
+## Files to Upload to HF Space
+
+```
+your-hf-space/
+├── README.md                  # HF Space metadata (YAML header)
+├── app.py                     # Main application
+├── requirements.txt           # Python dependencies
+├── finetuned_best.pth         # Model checkpoint
+└── src/
+    ├── data_collection.py     # Runtime dependency
+    └── collection_common.py   # Runtime dependency
+```
+
+## Space README.md
+
+The `README.md` on the HF Space repo **must** start with this YAML frontmatter:
+
+```yaml
+---
+title: Soil Texture Classification
+emoji: 🌍
+colorFrom: brown
+colorTo: green
+sdk: gradio
+sdk_version: "4.44.0"
+app_file: app.py
+pinned: false
+---
+```
+
+This is separate from the local project `README.md`.
+
+## Space Secrets
+
+Set these in **Space Settings → Repository secrets**:
+
+| Secret | Value | Purpose |
+|---|---|---|
+| `HF_TOKEN` | Your HF write-access token | Auth for dataset upload |
+| `HF_CONTRIB_DATASET_REPO` | `your-username/soil-submissions` | Private dataset repo to receive exported data |
+| `CONTRIBUTION_DATA_DIR` | `/data/community_submissions` | Uses HF persistent storage (survives restarts) |
+
+**Enable persistent storage** in Space Settings so uploaded data survives container restarts.
+
+## How Data Flows
+
+1. Users upload images + labels via **Contribute Data** or **Dataset Management** tabs.
+2. Data is saved to persistent storage at `CONTRIBUTION_DATA_DIR`.
+3. The Space auto-exports submission bundles to `HF_CONTRIB_DATASET_REPO` at **23:50 UTC daily** or when disk usage exceeds 90%.
+4. Owner downloads from the private dataset repo (see below).
+
+The download mechanism is invisible to users — no download UI is exposed.
+
+## How to Download Uploaded Dataset
+
+First, create a **private dataset repo** on HF (e.g., `your-username/soil-submissions`).
+
+### Option A: Python script (recommended)
+
+```python
+from huggingface_hub import snapshot_download
+
+snapshot_download(
+    repo_id="your-username/soil-submissions",
+    repo_type="dataset",
+    local_dir="./downloaded_data",
+    token="hf_YOUR_TOKEN",
+)
+```
+
+### Option B: HF CLI one-liner
+
+```bash
+huggingface-cli download your-username/soil-submissions \
+    --repo-type dataset \
+    --local-dir ./downloaded_data \
+    --token hf_YOUR_TOKEN
+```
+
+### Option C: Full sync + curation pipeline
+
+Downloads, deduplicates, and curates data into a train-ready format:
+
+```bash
+pip install pandas  # extra dependency for this script
+
+python src/sync_space_data.py \
+    --dataset_repo your-username/soil-submissions \
+    --date 2026-02-14
+```
+
+Outputs curated data to `data/labeled/community/` ready for training.
+
+### Option D: HF Web UI
+
+Go to `https://huggingface.co/datasets/your-username/soil-submissions` and download files directly from the browser.
+
+## Optional Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `CONTRIBUTION_DAILY_EXPORT_HOUR_UTC` | `23` | Hour (UTC) for daily auto-export |
+| `CONTRIBUTION_DAILY_EXPORT_MINUTE_UTC` | `50` | Minute (UTC) for daily auto-export |
+| `CONTRIBUTION_MAX_USAGE_PERCENT` | `90` | Disk usage % that triggers immediate export |
+| `CONTRIBUTION_DEDUPLICATE_IMAGES` | `1` | Deduplicate identical images by hash |
+| `CONTRIBUTION_PRUNE_AFTER_EXPORT` | `0` | Delete local data after successful export |
+| `CONTRIBUTION_STORAGE_QUOTA_BYTES` | `0` | Custom storage quota (0 = use disk total) |

README.md

@@ -5,6 +5,7 @@ colorFrom: yellow
 colorTo: green
 sdk: gradio
 sdk_version: "4.44.0"
+python_version: "3.10"
 app_file: app.py
 pinned: false
 ---

requirements.txt

@@ -12,7 +12,7 @@ opencv-python-headless>=4.8.0
 matplotlib>=3.7.0
 
 # WebUI - Required for Gradio interface
-gradio>=4.0.0
+gradio==4.44.0
 
 # Hub sync/export (Space -> Dataset)
-huggingface_hub>=0.26.0
+huggingface_hub>=0.26.0,<1.0.0