HUGGINGFACE_DEPLOYMENT.md

# Hugging Face Deployment Guide

This guide will help you deploy the Smart Budget Recommendation API to Hugging Face Spaces.

## Prerequisites

1. A Hugging Face account (sign up at https://huggingface.co)
2. MongoDB connection string ready
3. Git installed (optional, you can also use the web interface)

## Step-by-Step Deployment

### Step 1: Create a New Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Fill in the details:
   - **Space name**: `smart-budget-recommendation` (or your preferred name)
   - **SDK**: Select **Docker**
   - **Visibility**: Choose Public or Private
4. Click "Create Space"

### Step 2: Add secrets (MongoDB and optional OpenAI)

1. In your Space, go to **Settings** (gear icon)
2. Navigate to **Variables and secrets** section
3. Click **New secret**
4. Add the following secrets:
   - **Name**: `MONGODB_URI`
     - **Value**: `mongodb://expenseuser:Kem_6o%3F%[email protected]:27017/expense?authSource=admin`
   - **Name**: `OPENAI_API_KEY` *(optional, enables GPT-based recommendations)*
     - **Value**: `sk-...`
5. Click **Add secret** after each entry

### Step 3: Upload Files

You can upload files in two ways:

#### Option A: Using Git (Recommended)

1. Clone your Space repository:
```bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME
```

2. Copy all files from this project:
   - `app/` directory (all Python files)
   - `Dockerfile`
   - `requirements.txt`
   - `.dockerignore`
   - `README.md` (optional)

3. Commit and push:
```bash
git add .
git commit -m "Initial deployment"
git push
```

#### Option B: Using Web Interface

1. In your Space, click **Files and versions** tab
2. Click **Add file** → **Upload files**
3. Upload all files:
   - All files from `app/` directory
   - `Dockerfile`
   - `requirements.txt`
   - `.dockerignore`

### Step 4: Wait for Build

1. Hugging Face will automatically detect the `Dockerfile` and start building
2. You can monitor the build progress in the **Logs** tab
3. The build typically takes 2-5 minutes

### Step 5: Verify Deployment

Once the build completes:

1. Your API will be available at: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space`
2. Test the health endpoint: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health`
3. View API documentation: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/docs`

## Testing Your Deployment

### Using cURL

```bash
# Health check
curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health

# Get recommendations (replace user123 with actual user_id)
curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/recommendations/user123
```

### Using Python

```python
import requests

BASE_URL = "https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space"

# Health check
response = requests.get(f"{BASE_URL}/health")
print(response.json())

# Get recommendations
response = requests.get(f"{BASE_URL}/recommendations/user123")
print(response.json())
```

## Important Notes

1. **Port Configuration**: Hugging Face Spaces expect apps to serve on port **7860**, so the Dockerfile exposes and binds to that port.

2. **Environment Variables**: Secrets such as `MONGODB_URI` (and optional `OPENAI_API_KEY`) are injected automatically into the container environment.

3. **Cold Starts**: The first request after inactivity may take longer (cold start). Subsequent requests will be faster

4. **Resource Limits**: Free Hugging Face Spaces have resource limits. For production use, consider upgrading

5. **Custom Domain**: You can add a custom domain in Space settings if needed

## Troubleshooting

### Build Fails

- Check the **Logs** tab for error messages
- Ensure `Dockerfile` is in the root directory
- Verify all required files are uploaded

### Connection Errors

- Verify `MONGODB_URI` secret is set correctly
- Check MongoDB server is accessible from Hugging Face's servers
- Review connection string encoding (special characters should be URL-encoded)

### API Not Responding

- Check the **Logs** tab for runtime errors
- Verify the application starts successfully
- Test the `/health` endpoint first

## Updating Your Deployment

1. Make changes to your code locally
2. Commit and push to your Space repository
3. Hugging Face will automatically rebuild and redeploy

## Support

For issues specific to:
- **Hugging Face Spaces**: Check [Hugging Face Documentation](https://huggingface.co/docs/hub/spaces)
- **This Application**: Check the main README.md file