HUGGINGFACE_DEPLOYMENT.md

# Hugging Face Spaces Deployment Guide

This guide will help you deploy your HackRx Insurance Policy Assistant to Hugging Face Spaces.

## Prerequisites

1. A Hugging Face account (free at https://huggingface.co)
2. A Google Gemini API key
3. Your code pushed to a Git repository (GitHub, GitLab, etc.)

## Step 1: Prepare Your Repository

Your repository should contain the following files:
- `app.py` - Main application entry point
- `Dockerfile` - Docker configuration
- `requirements.txt` - Python dependencies
- `parser.py`, `embedder.py`, `retriever.py`, `llm.py` - Application modules
- `.dockerignore` - Docker build optimization

## Step 2: Create a Hugging Face Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Choose the following settings:
   - **Owner**: Your username
   - **Space name**: `hackrx-insurance-assistant` (or your preferred name)
   - **Space SDK**: `Docker`
   - **License**: Choose appropriate license
   - **Visibility**: Public or Private (your choice)

## Step 3: Connect Your Repository

1. In your new Space, go to the "Settings" tab
2. Under "Repository", click "Connect to existing repository"
3. Select your Git provider (GitHub, GitLab, etc.)
4. Choose your repository
5. Click "Connect"

## Step 4: Configure Environment Variables

1. In your Space settings, go to the "Repository secrets" section
2. Add the following secret:
   - **Name**: `GOOGLE_API_KEY`
   - **Value**: Your Google Gemini API key

## Step 5: Deploy

1. Push your code to your Git repository
2. Hugging Face Spaces will automatically detect the changes and start building
3. You can monitor the build progress in the "Logs" tab
4. Once built successfully, your API will be available at `https://your-space-name.hf.space`

## Step 6: Test Your Deployment

### Health Check
```bash
curl https://your-space-name.hf.space/
```

### Test API Endpoint
```bash
curl -X POST https://your-space-name.hf.space/api/v1/hackrx/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here" \
  -d '{
    "documents": "https://example.com/insurance-policy.pdf",
    "questions": ["What is the coverage amount?"]
  }'
```

## Troubleshooting

### Common Issues

1. **Build Fails**: Check the logs in the "Logs" tab for error messages
2. **Environment Variable Not Set**: Ensure `GOOGLE_API_KEY` is set in Space secrets
3. **Port Issues**: The application runs on port 7860 (default for Hugging Face Spaces)
4. **Memory Issues**: If you encounter memory issues, consider optimizing the Dockerfile

### Debugging

1. Check the build logs in the "Logs" tab
2. Monitor the application logs for runtime errors
3. Test locally first to ensure everything works

## API Documentation

Once deployed, your API will have the following endpoints:

- `GET /` - Health check
- `GET /health` - API status
- `POST /api/v1/hackrx/run` - Process PDF from URL
- `POST /api/v1/hackrx/local` - Process local PDF file

## Cost Considerations

- Hugging Face Spaces offers free hosting for public spaces
- Private spaces may have usage limits
- Consider the cost of Google Gemini API calls

## Security Notes

- Keep your API keys secure
- Use appropriate authentication for production use
- Consider rate limiting for public APIs

## Updates

To update your deployment:
1. Push changes to your Git repository
2. Hugging Face Spaces will automatically rebuild and deploy
3. Monitor the build process in the "Logs" tab