Upload HF_SPACES_DEPLOYMENT.md with huggingface_hub

HF_SPACES_DEPLOYMENT.md

@@ -0,0 +1,123 @@
+# Deploy to Hugging Face Spaces
+
+## Why Your Current Deploy is Stuck
+
+Common causes:
+1. ❌ **No proper app entry point** - HF Spaces doesn't know what to run
+2. ❌ **Model loading timeout** - Takes >60s to initialize models
+3. ❌ **Wrong port** - Must use port 7860
+4. ❌ **Heavy dependencies** - Build fails with missing packages
+5. ❌ **Stuck on first model download** - PaddleOCR/YOLO loading hangs
+
+## Solution: Use the New HF Spaces Setup ✅
+
+I've created everything needed:
+- `app_hf_spaces.py` - Gradio UI with proper startup
+- `Dockerfile` - Optimized for HF Spaces
+- `.dockerignore` - Reduces build size
+
+## Step-by-Step Deployment
+
+### 1. **Delete Old Space** (if it exists)
+Go to https://huggingface.co/spaces and delete the stuck Space.
+
+### 2. **Create New Space**
+- Go to https://huggingface.co/new-space
+- **Owner:** Your username
+- **Space name:** `omoi-ui-detector` (or your choice)
+- **License:** OpenRAIL-M (or your choice)
+- **Space SDK:** Docker
+- Click **Create Space**
+
+### 3. **Push Code to Space**
+```bash
+cd /workspaces/omoi-v2
+
+# Add your HF token
+huggingface-cli login
+
+# Add Space remote
+git remote add space https://huggingface.co/spaces/YOUR_USERNAME/omoi-ui-detector
+
+# Push to trigger build
+git push space main
+```
+
+### 4. **Wait for Build** (5-10 minutes first time)
+- Watch progress at: https://huggingface.co/spaces/YOUR_USERNAME/omoi-ui-detector
+- Look for "Building..." → "Running"
+- First build is slow (downloads ~2GB models)
+
+### 5. **Test** ✅
+Once running, upload a UI screenshot and click "Analyze"
+
+---
+
+## Files Used in Deployment
+
+| File | Purpose |
+|------|---------|
+| `Dockerfile` | Build configuration |
+| `app_hf_spaces.py` | Main Gradio app (entry point) |
+| `config.py` | Path configuration |
+| `ui_element_analyzer.py` | Core analysis logic |
+| `.dockerignore` | Reduce build size |
+
+## Troubleshooting
+
+### Still stuck on "Starting"?
+
+1. **Check build logs:**
+   - Click your Space
+   - Click "Logs" button (top right)
+   - Look for error messages
+
+2. **Common errors:**
+   - `ModuleNotFoundError: No module named 'paddleocr'`
+     → Install might have failed, retry Space build
+   
+   - `torch not found`
+     → PyTorch install needs more time/space
+   
+   - `Dockerfile not found`
+     → Ensure files are in repo root and pushed to space
+
+3. **Force rebuild:**
+   - Go to Space settings
+   - Click "Restart" or delete & recreate
+
+### Startup too slow?
+
+- First launch takes 2-3 minutes (model download)
+- Subsequent launches are instant
+- HF Spaces has free tier limits (CPU-based)
+
+---
+
+## API-Only Alternative (Faster)
+
+If you want just the API (no Gradio UI), I can create:
+- Lightweight FastAPI container
+- Raw inference endpoints
+- No model download on first request
+
+Request this if Gradio is too slow!
+
+---
+
+## Space Settings Optimization
+
+Once deployed, go to Space **Settings** and:
+1. Set **Persistent Storage**: 10GB (for model cache)
+2. Set **SDK**: Docker ✓
+3. Enable **Community Features** (optional)
+
+---
+
+## Next Steps
+
+1. Update `YOUR_USERNAME` in git push command
+2. Run the deployment commands above
+3. Share Space URL when ready!
+
+Any issues? Check the Space logs or let me know the error!