# 🚀 Hugging Face Spaces Deployment Guide

## ✅ **Step 1: Repository is Ready!**

Your code has been successfully pushed to GitHub with all the modular architecture and automatic fine-tuning features.

## 🌐 **Step 2: Create Hugging Face Space**

### **Option A: Web Interface (Recommended)**
1. Go to [https://huggingface.co/new-space](https://huggingface.co/new-space)
2. **Space Settings:**
   - **Name**: `vietnamese-sentiment-analysis` (or your choice)
   - **License**: MIT (or your preferred license)
   - **Hardware**: CPU Basic (free) or GPU T4 (for faster fine-tuning)
   - **Visibility**: Public (free) or Private
   - **SDK**: Gradio

### **Option B: Using Git**
```bash
# Clone your Hugging Face Space (replace with your space URL)
git clone https://huggingface.co/spaces/your-username/your-space-name
cd your-space-name

# Add your repository as remote
git remote add upstream https://github.com/your-username/SentimentAnalysis.git
git pull upstream main
git push origin main
```

## 📋 **Step 3: Files to Upload**

Make sure these files are in your Space:

```
SentimentAnalysis/
├── app.py                    # ✅ Main application
├── requirements.txt          # ✅ Dependencies
├── py/
│   ├── __init__.py          # ✅ Package
│   ├── api_controller.py    # ✅ API controller
│   ├── fine_tune_sentiment.py # ✅ Fine-tuning script
│   └── pages/               # ✅ UI pages
│       ├── __init__.py
│       ├── single_analysis.py
│       ├── batch_analysis.py
│       ├── model_info.py
│       └── api_endpoints.py
```

## ⚙️ **Step 4: Space Configuration**

### **Requirements.txt Check:**
Ensure your `requirements.txt` includes:
```
torch>=2.0.0
transformers>=4.21.0
datasets>=2.0.0
gradio>=4.44.1
fastapi>=0.104.0
uvicorn>=0.24.0
pydantic>=2.5.0
psutil>=5.9.0
accelerate>=0.21.0
```

### **Hardware Selection:**
- **CPU Basic**: Free, but fine-tuning will be slow (30-60 minutes)
- **GPU T4**: Paid, but fine-tuning will be fast (5-10 minutes)
- **GPU A10G**: More expensive, best performance

## 🚀 **Step 5: Deployment Process**

### **What Happens Automatically:**
1. **Environment Detection**: App detects it's running on Hugging Face Spaces
2. **Model Loading**: Tries to load fine-tuned model, runs fine-tuning if needed
3. **API Server**: Starts REST API on port 7861 automatically
4. **Gradio Interface**: Launches with all 4 tabs

### **Expected Timeline:**
- **Initial Build**: 2-5 minutes (installing dependencies)
- **First Run**: 10-30 minutes (fine-tuning, depends on hardware)
- **Subsequent Runs**: 1-2 minutes (model already created)

## 📱 **Step 6: Testing Your Space**

Once deployed, your Space will have:

### **Main Interface** (Main URL):
- 📝 **Single Text Analysis** - Analyze individual Vietnamese texts
- 📊 **Batch Analysis** - Process multiple texts
- ℹ️ **Model Information** - View model details and memory usage
- 🌐 **REST API Endpoints** - API documentation and examples

### **REST API** (Your Space URL + :7861):
- **Interactive Docs**: `https://your-space.hf.space:7861/docs`
- **Health Check**: `GET /health`
- **Analysis**: `POST /analyze`
- **Batch**: `POST /analyze/batch`

## 🎯 **Step 7: API Usage Examples**

### **Python Example:**
```python
import requests

response = requests.post(
    "https://your-space.hf.space:7861/analyze",
    json={"text": "Giảng viên dạy rất hay và tâm huyết."}
)
result = response.json()
print(f"Sentiment: {result['sentiment']}")
print(f"Confidence: {result['confidence']:.2%}")
```

### **cURL Example:**
```bash
curl -X POST "https://your-space.hf.space:7861/analyze" \
     -H "Content-Type: application/json" \
     -d '{"text": "Giảng viên dạy rất hay và tâm huyết."}'
```

## ⚠️ **Step 8: Troubleshooting**

### **Common Issues:**

1. **Build Fails:**
   - Check requirements.txt has all dependencies
   - Ensure no syntax errors in Python files
   - Check Space logs for specific error messages

2. **Fine-Tuning Takes Too Long:**
   - Consider upgrading to GPU hardware
   - The process will complete eventually on CPU

3. **API Not Working:**
   - API runs on port 7861 (different from main Gradio port)
   - Check if CORS is enabled (included in our setup)

4. **Memory Issues:**
   - The app includes automatic memory cleanup
   - Batch size is limited to 10 texts
   - GPU spaces have more memory available

## 🔧 **Step 9: Advanced Configuration**

### **Custom Fine-Tuned Model:**
If you have your own fine-tuned model on Hugging Face Hub:
1. Update line 32 in `app.py`:
   ```python
   self.finetuned_model = "your-username/your-model-name"
   ```

### **Custom Fine-Tuning Parameters:**
Modify `py/fine_tune_sentiment.py` to adjust:
- Learning rate
- Number of epochs
- Batch size
- Dataset

## 📊 **Step 10: Monitoring**

### **Space Metrics:**
- Usage statistics in your Space dashboard
- API endpoint performance
- Model loading time
- Memory usage (shown in Model Info tab)

## 🎉 **Success Indicators:**

Your deployment is successful when you see:
- ✅ Gradio interface loads with all 4 tabs
- ✅ Model information shows "vietnamese_sentiment_finetuned"
- ✅ API documentation is accessible at `/docs`
- ✅ Test analysis returns correct sentiment predictions
- ✅ Health check endpoint returns status "healthy"

## 📞 **Support**

If you encounter issues:
1. Check the Space logs for error messages
2. Verify all files are uploaded correctly
3. Test locally with `python app.py` first
4. Review the fine-tuning process in the logs

Your modular Vietnamese Sentiment Analysis app is now ready for production deployment! 🚀