Upload QUICKSTART_SECRETS.md with huggingface_hub

QUICKSTART_SECRETS.md

@@ -0,0 +1,143 @@
+# 🔐 Quick Start: Enable Captions on Your Space
+
+Your HF Space is now deployed with **secure credential handling**. Follow these steps to enable AI captions for UI elements.
+
+## 3-Step Setup
+
+### Step 1: Get Your Qwen API Key
+1. Sign up at: **https://dashscope.console.aliyun.com/**
+2. Navigate to **API Keys**
+3. Copy your API key (format: `sk-...`)
+4. Keep it safe! ⚠️
+
+### Step 2: Add Secret to Your Space (Choose One)
+
+#### **Option A: Web UI (Easiest)**
+1. Go to: https://huggingface.co/spaces/makeitfr/omniparsev2-ui-detector
+2. Click **Settings** ⚙️ (top right)
+3. Scroll to **Secrets** section
+4. Click **Add a secret**
+5. Enter:
+   - **Name**: `QWEN_API_KEY`
+   - **Value**: `sk-your-api-key-here`
+6. Click **Save**
+7. Wait ~30 seconds for Space to restart
+
+#### **Option B: Python Script**
+```bash
+# Set your HF token
+export HF_TOKEN="hf_YOUR_TOKEN_HERE"
+
+# Run setup script
+python setup_hf_spaces_secrets.py \
+  --space makeitfr/omniparsev2-ui-detector \
+  --qwen-key "sk-your-api-key-here"
+```
+
+#### **Option C: cURL (Advanced)**
+```bash
+HF_TOKEN="hf_YOUR_TOKEN"
+
+curl -X POST \
+  "https://huggingface.co/api/spaces/makeitfr/omniparsev2-ui-detector/secrets" \
+  -H "Authorization: Bearer ${HF_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"key": "QWEN_API_KEY", "value": "sk-your-key"}'
+```
+
+### Step 3: Test It! 🎯
+1. Visit your Space: https://makeitfr-omniparsev2-ui-detector.hf.space
+2. Upload a screenshot
+3. Click **Analyze**
+4. Check results - each element now has a caption!
+
+**Example Output:**
+```json
+{
+  "element_id": "crop_0001",
+  "caption": "close button",
+  "x": 590,
+  "y": 21,
+  "confidence": 1.0
+}
+```
+
+## Environment Variables
+
+The Space automatically reads these from Secrets:
+
+| Variable | Purpose | Required |
+|---|---|---|
+| `QWEN_API_KEY` | Qwen API key | ✅ Yes |
+| `QWEN_BASE_URL` | Qwen endpoint | ❌ No (default: DashScope) |
+| `QWEN_MODEL` | Model name | ❌ No (default: `qwen-vl-max`) |
+
+## Without Secrets?
+
+If you don't set up secrets:
+- ✅ UI detection still works perfectly
+- ❌ Captions show as "unavailable"
+- Everything else functions normally
+
+## Verify Setup
+
+After adding secrets, check Space logs:
+1. Go to your Space
+2. Look for this message in logs:
+   ```
+   ✓ Caption support enabled (Qwen VL configured)
+   ```
+
+## Security Notes
+
+✅ **Secure:**
+- Secrets stored encrypted on HF servers
+- Never visible in code or logs
+- Can be changed anytime
+
+❌ **Not Secure:**
+- Hardcoding keys in Python files
+- Committing `.env` to git
+- Sharing in error messages
+
+## Get Help
+
+### Common Issues
+
+**"Caption shows 'unavailable'"**
+- Check if secret is set: Settings → Secrets
+- Verify key name is exactly `QWEN_API_KEY`
+
+**"API rate limit"**
+- Wait a few minutes
+- Check Qwen quota: https://dashscope.console.aliyun.com/
+
+**"Invalid API key"**
+- Regenerate key at dashscope.console.aliyun.com
+- Update Space secret with new key
+
+## Next: Advanced Configuration
+
+Want to customize captions? See these files:
+- [`caption_cropped_images.py`](caption_cropped_images.py) - Captioning logic
+- [`caption_integration.py`](caption_integration.py) - Integration with API
+- [`HF_SPACES_SECRETS.md`](HF_SPACES_SECRETS.md) - Full secrets guide
+
+## Pricing
+
+**Alibaba Qwen VL Pricing:**
+- ~$0.01-0.02 per image
+- 100 images ≈ $1-2
+- Check current: https://dashscope.console.aliyun.com/pricing
+
+## Done! 🎉
+
+Your Space now has:
+- ✅ Secure credential handling
+- ✅ AI-powered UI element captions
+- ✅ JSON/CSV export with captions
+- ✅ Beautiful web interface
+
+**Start analyzing:** https://makeitfr-omniparsev2-ui-detector.hf.space
+
+Questions? Check [HF_SPACES_SECRETS.md](HF_SPACES_SECRETS.md) for detailed docs.