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! 🚀