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

curl https://your-space-name.hf.space/

Test API Endpoint

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