UPLOAD_TO_SPACES_CHECKLIST.md

# HuggingFace Spaces Upload Checklist

## ✅ Pre-Upload Checklist

Your app is ready! Just upload these files:

### Required Files (Check off as you upload)

- [ ] `app.py` ← **MAIN FILE - HuggingFace Spaces needs this exact name**
- [ ] `llm.py`
- [ ] `extractors.py`
- [ ] `tagging.py`
- [ ] `chunking.py`
- [ ] `validation.py`
- [ ] `reporting.py`
- [ ] `dashboard.py`
- [ ] `production_logger.py`
- [ ] `quote_extractor.py`
- [ ] `requirements.txt`

**Total: 11 files**

---

## 🚫 DO NOT Upload

- ❌ `.env` file
- ❌ `test_*.py` files
- ❌ `*.log` files
- ❌ `logs/` folder
- ❌ `outputs/` folder
- ❌ `__pycache__/` folder

---

## 🎯 Upload Steps

### 1. Create Your Space
1. Go to: https://huggingface.co/new-space
2. Enter a name (e.g., `transcriptor-ai`)
3. Choose **Gradio** as SDK
4. Select **GPU** hardware (T4 minimum) ⚠️ **IMPORTANT!**
5. Click "Create Space"

### 2. Upload Files

**Method A: Drag & Drop**
1. Click "Files" tab in your Space
2. Click "Upload files"
3. Drag all 11 files from the checklist above
4. Click "Commit"

**Method B: Git Repository**
1. Create a new Git repo
2. Copy the 11 files above
3. Add `.gitignore` (already created for you)
4. Push to repo
5. Connect repo to Space in Settings

### 3. Configure Space (Optional)

Go to **Settings → Variables** and add (all optional):

| Variable | Value | Why |
|----------|-------|-----|
| `DEBUG_MODE` | `True` | See detailed logs |
| `LLM_TEMPERATURE` | `0.7` | Already the default |

**You don't need to configure anything** - it works out of the box!

---

## ⏱️ What to Expect

### First Startup
1. **Installing dependencies:** 2-5 minutes
2. **Downloading Phi-3-mini model:** 2-5 minutes
3. **Total:** ~5-10 minutes

Watch the **Logs** tab - you'll see:
```
Installing dependencies...
✅ Configuration loaded for HuggingFace Spaces
🚀 TranscriptorAI Enterprise - LLM Backend: local
[Local Model] Loading microsoft/Phi-3-mini-4k-instruct...
Downloading model files...
[Local Model] ✅ Model loaded on cuda:0
Running on local URL:  http://0.0.0.0:7860
```

### Subsequent Startups
- **Only 30-60 seconds** (model is cached)

---

## ✅ Verify It's Working

### 1. Check Startup Logs

Look for these lines in the Logs tab:

✅ `Configuration loaded for HuggingFace Spaces`
✅ `LLM Backend: local`
✅ `Model loaded on cuda:0` ← GPU confirmed!
✅ `Running on local URL`

### 2. Test with Sample

1. Click "Upload Files"
2. Upload a DOCX transcript
3. Select "HCP" as interviewee type
4. Click "Analyze Transcripts"
5. Wait 5-10 minutes for processing

**Expected Result:**
- Quality Score: 0.7-1.0 (not 0.00!)
- CSV and PDF downloads available
- Dashboard shows charts

---

## 🐛 Common Issues

### Issue: `ModuleNotFoundError: No module named 'xyz'`
**Solution:** Upload the missing `xyz.py` file

### Issue: Very slow or hangs
**Check:** Did you select GPU hardware?
1. Go to Settings
2. Under Hardware, choose "GPU (T4)"
3. Restart Space

### Issue: Quality Score 0.00
**Solution:**
1. Add Variable: `DEBUG_MODE=True`
2. Check logs for error messages
3. Look for "[Local Model] ✅ Generated" to confirm it's working

### Issue: Out of memory
**Solution:**
1. Add Variable: `LOCAL_MODEL=TinyLlama/TinyLlama-1.1B-Chat-v1.0`
2. OR upgrade to larger GPU

---

## 💰 Cost

### Free Tier (CPU)
- ⚠️ Very slow (10+ minutes per transcript)
- Not recommended

### GPU (T4) - ~$0.60/hour
- ✅ Recommended
- Fast processing (~5-10 min per transcript)
- Space sleeps after inactivity (saves money)
- Only charged when active

---

## 📋 Quick Reference

**Space must have:**
- `app.py` as main file ✅ (already correct)
- `requirements.txt` with dependencies ✅ (already correct)
- GPU hardware selected ⚠️ (you must select this)

**No .env file needed** - everything configured in code ✅

**No terminal commands needed** - all automatic ✅

---

## 🎉 Ready to Deploy!

1. ✅ Check you have all 11 files
2. ✅ Create Space with GPU hardware
3. ✅ Upload files via drag & drop
4. ✅ Wait for build (watch Logs tab)
5. ✅ Test with a transcript

**See `FILES_TO_UPLOAD.txt` for the complete list of files.**

---

## 📞 Still Stuck?

Common causes:
1. **Forgot to upload a file** - Check all 11 files are uploaded
2. **Selected CPU instead of GPU** - Change in Settings
3. **Uploaded .env file** - Delete it, not needed on Spaces

---

**Last Updated:** October 2025

**You're ready - just upload the 11 files and you're done!** 🚀