# Quick Start Guide

Get your OCR API running on Hugging Face Spaces in minutes!

## 🚀 Deploy in 3 Steps

### Step 1: Create Space (2 minutes)
1. Go to https://huggingface.co/new-space
2. Name: `handyhome-ocr-api`
3. SDK: **Docker**
4. Click "Create Space"

### Step 2: Upload Files (3 minutes)
1. Click "Files" tab → "Add file" → "Upload files"
2. Upload all files from `huggingface-ocr` folder
3. Click "Commit changes to main"

### Step 3: Wait for Build (5-10 minutes)
- Go to "App" tab
- Watch build logs
- When done, you'll see: "Running on http://0.0.0.0:7860"

## ✅ Test Your API

```bash
# Check health
curl https://YOUR-USERNAME-handyhome-ocr-api.hf.space/health

# Test extraction
curl -X POST https://YOUR-USERNAME-handyhome-ocr-api.hf.space/api/extract-national-id \
  -H "Content-Type: application/json" \
  -d '{"document_url": "YOUR_IMAGE_URL"}'
```

## 📚 Available Endpoints

### Philippine IDs
- `/api/extract-national-id` - National ID
- `/api/extract-drivers-license` - Driver's License
- `/api/extract-prc` - PRC ID
- `/api/extract-umid` - UMID
- `/api/extract-sss` - SSS ID
- `/api/extract-passport` - Passport
- `/api/extract-postal` - Postal ID
- `/api/extract-phic` - PhilHealth ID

### Clearances
- `/api/extract-nbi` - NBI Clearance
- `/api/extract-police-clearance` - Police Clearance
- `/api/extract-tesda` - TESDA Certificate

### Utility
- `/api/analyze-document` - Identify document type
- `/health` - Health check
- `/` - Full API documentation

## 🔧 Integration Example

```python
import requests

# Your Hugging Face Space URL
API_BASE = "https://YOUR-USERNAME-handyhome-ocr-api.hf.space"

def extract_national_id(image_url):
    response = requests.post(
        f"{API_BASE}/api/extract-national-id",
        json={"document_url": image_url},
        timeout=300
    )
    return response.json()

# Use it
result = extract_national_id("https://example.com/id.jpg")
print(result)
```

## 💡 Tips

- **First request is slow**: PaddleOCR loads models on first use (~30 seconds)
- **Image quality matters**: Use clear, well-lit photos
- **Timeout**: Set timeout to 5 minutes for first request
- **Free tier**: Space sleeps after 48 hours of inactivity

## 🐛 Troubleshooting

**Build fails?**
- Wait and retry - first build can timeout
- Check build logs for specific errors

**503 Error?**
- Space is sleeping - just visit the URL to wake it

**Slow responses?**
- Normal for first request (loading models)
- Subsequent requests are faster (2-5 seconds)

## 📖 Full Documentation

- See `README.md` for complete API documentation
- See `DEPLOYMENT_GUIDE.md` for detailed deployment steps

## 🎯 Next Steps

1. Deploy your OCR Space
2. Update your main app to use it
3. Test with real documents
4. Monitor usage in Space settings

---

Need help? Check `DEPLOYMENT_GUIDE.md` for detailed instructions!