TROUBLESHOOTING_QUICK_REFERENCE.md

# TRIQA Hugging Face Demo - Quick Troubleshooting Reference

## 🚨 Common Errors & Quick Fixes

### 1. Short Description Too Long
**Error**: `"short_description" length must be less than or equal to 60 characters long`

**Quick Fix**:
```yaml
# In README.md
short_description: TRIQA-IQA  # 9 characters
```

### 2. Missing timm Module
**Error**: `ModuleNotFoundError: No module named 'timm'`

**Quick Fix**:
```txt
# Add to requirements.txt
timm>=0.6.0
```

### 3. Model Files Not Found
**Error**: `FileNotFoundError: [Errno 2] No such file or directory: 'feature_models/...'`

**Quick Fix**:
1. Download from Box: https://utexas.box.com/s/8aw6axc2lofouja65uc726lca8b1cduf
2. Create directories: `feature_models/` and `Regression_Models/`
3. Upload model files to correct locations

### 4. Build Failures
**Error**: Various build errors

**Quick Fix**:
1. Check space logs
2. Verify all dependencies in requirements.txt
3. Test locally: `python app.py`

## 📋 Essential Files Checklist

### Required Files:
- [ ] `app.py` - Main application
- [ ] `README.md` - Space description
- [ ] `requirements.txt` - Dependencies
- [ ] `package.json` - Node.js config
- [ ] `convnext_original.py` - Model architecture
- [ ] `convnext_finetune.py` - Model architecture
- [ ] `sample_image/` - Sample images

### Model Files (Download from Box):
- [ ] `feature_models/convnext_tiny_22k_224.pth` (170MB)
- [ ] `feature_models/triqa_quality_aware.pth` (107MB)
- [ ] `Regression_Models/KonIQ_scaler.save`
- [ ] `Regression_Models/KonIQ_TRIQA.save` (111MB)

## 🔧 Quick Commands

### Upload Files:
```bash
# Python CLI
python upload_to_space.py

# Git method
git clone https://huggingface.co/spaces/your-username/triqa-iqa
cd triqa-iqa
cp ../huggingface_demo/* .
git add . && git commit -m "Add TRIQA demo" && git push
```

### Test Locally:
```bash
# Test file structure
python test_demo.py

# Test app
python app.py
```

### Update Single File:
```bash
python -c "from huggingface_hub import HfApi; api = HfApi(); api.upload_file(path_or_fileobj='filename', path_in_repo='filename', repo_id='S-Rajesh/triqa-iqa', repo_type='space')"
```

## 📊 Requirements.txt Template

```txt
gradio>=4.0.0
torch>=1.8.0
torchvision>=0.9.0
timm>=0.6.0
pillow>=8.0.0
numpy>=1.19.0
scikit-learn>=0.24.0
```

## 🎯 README.md Metadata Template

```yaml
---
title: TRIQA Image Quality Assessment
emoji: 🖼️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.0.0
app_file: app.py
pinned: false
license: mit
short_description: TRIQA-IQA
---
```

## 🚀 Space URL Format

```
https://huggingface.co/spaces/USERNAME/SPACE-NAME
```

Example: `https://huggingface.co/spaces/S-Rajesh/triqa-iqa`

## ⚡ Quick Debug Steps

1. **Check build logs** in your space
2. **Verify file paths** are correct
3. **Test locally** before uploading
4. **Check dependencies** in requirements.txt
5. **Verify model files** are uploaded

## 📞 Quick Links

- **Space**: https://huggingface.co/spaces/S-Rajesh/triqa-iqa
- **Box Download**: https://utexas.box.com/s/8aw6axc2lofouja65uc726lca8b1cduf
- **GitHub**: https://github.com/rajeshsureddi/triqa
- **Paper**: https://arxiv.org/pdf/2507.12687

## ✅ Success Indicators

- [ ] Space builds without errors
- [ ] Demo interface loads
- [ ] Sample images display
- [ ] Quality prediction works
- [ ] Paper links are accessible

---

**Remember**: Most issues are solved by checking the build logs and ensuring all dependencies are properly listed in requirements.txt! 🎯