DEPLOYMENT_GUIDE.md

# Hugging Face Spaces Deployment Guide

This guide walks you through deploying the RAG system to Hugging Face Spaces for free, permanent hosting.

## Prerequisites

- Hugging Face account ([sign up here](https://huggingface.co/join))
- Git installed on your local machine
- Code migrated to use HF Inference API (already done ✅)

## Step 1: Test Locally (Recommended)

Before deploying, test the application with HF Inference API locally:

### 1.1 Get Your HF Token

1. Go to [https://huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)
2. Click "New token"
3. Name it (e.g., "RAG System")
4. Select `read` permissions
5. Click "Generate"
6. Copy the token (starts with `hf_`)

### 1.2 Set Environment Variable

```bash
# Linux/Mac
export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Windows (PowerShell)
$env:HF_TOKEN="hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### 1.3 Install Dependencies

```bash
cd /Users/v.hirenko/Desktop/DevHubVault/my-ai-projects/rag-python-rag
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt
```

### 1.4 Run Tests

```bash
python test_hf_integration.py
```

If all tests pass, proceed to deployment!

### 1.5 Test the Application

```bash
python app.py
```

Open http://localhost:7860 and test with a few questions.

## Step 2: Create Hugging Face Space

### 2.1 Create New Space

1. Go to [https://huggingface.co/new-space](https://huggingface.co/new-space)
2. Fill in the details:
   - **Owner**: Your username (e.g., `monsara`)
   - **Space name**: `rag-python-rag`
   - **License**: MIT
   - **Select the Space SDK**: Gradio
   - **Space hardware**: CPU basic (free)
   - **Space visibility**: Public (or Private if you prefer)
3. Click "Create Space"

### 2.2 Note Your Space URL

Your Space will be available at:
```
https://huggingface.co/spaces/YOUR_USERNAME/rag-python-rag
```

## Step 3: Configure Space Secrets

### 3.1 Add HF_TOKEN Secret

1. Go to your Space page
2. Click on "Settings" (gear icon)
3. Scroll down to "Repository secrets"
4. Click "Add a secret"
5. Fill in:
   - **Name**: `HF_TOKEN`
   - **Value**: Your HF token from Step 1.1
6. Click "Add"

⚠️ **Important**: The Space will NOT work without this secret!

## Step 4: Push Code to Space

You have two options:

### Option A: Direct Git Push (Recommended)

```bash
cd /Users/v.hirenko/Desktop/DevHubVault/my-ai-projects/rag-python-rag

# Add HF Space as remote
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/rag-python-rag
# Replace YOUR_USERNAME with your actual HF username

# Push to HF Space
git push hf main
```

If prompted for credentials:
- **Username**: Your HF username
- **Password**: Your HF token (the same one you created)

### Option B: Link GitHub Repository

1. In your Space Settings
2. Find "Linked repositories"
3. Click "Link a GitHub repository"
4. Select `monsara/rag-python-rag`
5. The Space will automatically sync with your GitHub repo

## Step 5: Verify Deployment

### 5.1 Check Build Logs

1. Go to your Space page
2. Click on "Logs" tab
3. Watch the build process
4. Look for:
   ```
   ✅ HF_TOKEN validated successfully
   ✅ RAG pipeline setup complete!
   Running on local URL:  http://0.0.0.0:7860
   ```

### 5.2 Test the Space

1. Once "Running" status appears
2. Click on the Space URL
3. Try example questions
4. Verify answers are generated correctly

## Step 6: Update README (Optional)

Replace the Space README with the HF-specific one:

```bash
cd /Users/v.hirenko/Desktop/DevHubVault/my-ai-projects/rag-python-rag

# Backup current README
mv README.md README_LOCAL.md

# Use HF README
cp README_HF.md README.md

# Commit and push
git add README.md
git commit -m "Update README for HF Spaces"
git push hf main
```

## Troubleshooting

### Issue: "HF_TOKEN not found"

**Solution**: Make sure you added `HF_TOKEN` to Space secrets (Step 3.1)

### Issue: "Model not found" or "Rate limit exceeded"

**Solution**: 
- Check if you're using the correct model name in `config.py`
- Free tier has rate limits (~1000 requests/hour)
- Consider upgrading to HF Pro ($9/month)

### Issue: "Build failed"

**Solution**:
1. Check the build logs for specific errors
2. Verify `requirements.txt` has all dependencies
3. Make sure Python version is compatible (3.9+)

### Issue: "Application crashes on startup"

**Solution**:
1. Check if `app.py` is set as the entry point in Space settings
2. Verify all imports are correct
3. Check logs for Python errors

### Issue: Slow responses

**Solution**:
- Free tier uses shared infrastructure
- Upgrade to better hardware (paid)
- Or optimize chunk size and retrieval count

## Monitoring

### View Logs

```bash
# Real-time logs
# Go to Space page → Logs tab
```

### Check Usage

1. Go to your HF profile
2. Click on "Usage & billing"
3. View API usage statistics

## Updating the Space

### Update Code

```bash
cd /Users/v.hirenko/Desktop/DevHubVault/my-ai-projects/rag-python-rag

# Make your changes
git add .
git commit -m "Your update message"
git push hf main
```

The Space will automatically rebuild.

### Update Dependencies

Edit `requirements.txt`, then:

```bash
git add requirements.txt
git commit -m "Update dependencies"
git push hf main
```

### Update Configuration

Edit `config.py`, then push changes as above.

## Cost Considerations

### Free Tier (Current Setup)

- ✅ **Cost**: $0/month
- ✅ **Hosting**: Unlimited
- ⚠️ **Rate limits**: ~1000 requests/hour
- ⚠️ **Performance**: Shared CPU
- ⚠️ **Tokens**: 1024 max per response

### Upgrade Options

**HF Pro ($9/month)**:
- Higher rate limits
- Faster inference
- Priority support
- Better hardware options

**Dedicated Hardware**:
- CPU Upgrade: $0.03/hour (~$22/month)
- GPU T4: $0.60/hour (~$432/month)
- GPU A10G: $1.05/hour (~$756/month)

## Security Best Practices

1. **Never commit HF_TOKEN** to Git
2. **Use Space secrets** for all sensitive data
3. **Rotate tokens** periodically
4. **Monitor usage** for unexpected spikes
5. **Set rate limits** in your application

## Next Steps

After successful deployment:

1. ✅ Test thoroughly with various questions
2. ✅ Share the Space URL with users
3. ✅ Monitor logs for errors
4. ✅ Gather user feedback
5. ✅ Iterate and improve

## Support

If you need help:

1. Check [HF Spaces documentation](https://huggingface.co/docs/hub/spaces)
2. Visit [HF Community forums](https://discuss.huggingface.co/)
3. Open an issue on [GitHub](https://github.com/monsara/rag-python-rag/issues)

---

## Quick Reference

**Space URL**: `https://huggingface.co/spaces/YOUR_USERNAME/rag-python-rag`

**Settings**: `https://huggingface.co/spaces/YOUR_USERNAME/rag-python-rag/settings`

**Logs**: `https://huggingface.co/spaces/YOUR_USERNAME/rag-python-rag/logs`

**Push command**:
```bash
git push hf main
```

**Update secret**: Space Settings → Repository secrets → Edit

---

Good luck with your deployment! 🚀