DEPLOYMENT.md

Hugging Face Deployment Guide

Overview

This guide explains how to deploy the Lung Cancer Clinical Decision Support System to Hugging Face Spaces.

Prerequisites

• Hugging Face account
• Git installed locally
• OpenAI API key (for the agent)
• GitHub Personal Access Token (for side effects storage)

Deployment Steps

1. Create a New Hugging Face Space

1. Go to Hugging Face Spaces
2. Click "Create new Space"
3. Configure:
   • Space name: moazx-api (or your preferred name)
   • License: Choose appropriate license
   • SDK: Docker
   • Hardware: CPU Basic (or upgrade as needed)

2. Configure Environment Variables

In your Hugging Face Space settings, add these secrets:

OPENAI_API_KEY=your_openai_api_key_here
GITHUB_TOKEN=your_github_token_here
GITHUB_REPO=your_username/your_repo_name
GITHUB_BRANCH=main
PORT=7860

3. Deploy the Application

Option A: Direct Push to Hugging Face

# Clone your Hugging Face Space repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/moazx-api
cd moazx-api

# Copy all backend files
cp -r /path/to/backend/* .

# Add and commit
git add .
git commit -m "Initial deployment"
git push

Option B: Using Hugging Face CLI

# Install Hugging Face CLI
pip install huggingface_hub

# Login
huggingface-cli login

# Push to Space
huggingface-cli upload YOUR_USERNAME/moazx-api . --repo-type=space

4. Verify Deployment

1. Wait for the Space to build (check the logs)
2. Once running, test the API:
   • Visit: https://YOUR_USERNAME-moazx-api.hf.space
   • Check health: https://YOUR_USERNAME-moazx-api.hf.space/health
   • View docs: https://YOUR_USERNAME-moazx-api.hf.space/docs

5. Deploy Frontend

The frontend is configured to use the API at https://moazx-api.hf.space.

Option A: Serve from the same Space

The frontend files are already in the /frontend directory and will be served automatically.

Option B: Deploy to separate hosting

Deploy the frontend folder to:

• Netlify
• Vercel
• GitHub Pages
• Any static hosting service

API Endpoints

Once deployed, your API will be available at:

Base URL: https://moazx-api.hf.space

Endpoints:
- GET  /                          - API information
- GET  /health                    - Health check
- GET  /health/initialization     - Initialization status
- POST /auth/login                - User login
- POST /auth/logout               - User logout
- GET  /auth/status               - Authentication status
- GET  /ask                       - Ask a question (non-streaming)
- GET  /ask/stream                - Ask a question (streaming)
- GET  /export/{format}           - Export conversation

Frontend Configuration

The frontend is already configured to use the Hugging Face API:

// In frontend/script.js
this.apiBase = 'https://moazx-api.hf.space';

Authentication

The system uses session-based authentication:

1. Default credentials (change in production):

   • Username: admin
   • Password: admin123

2. To change credentials, update api/routers/auth.py

Monitoring

Monitor your deployment:

1. Hugging Face Space Logs: Check the logs tab in your Space
2. API Health: Monitor /health endpoint
3. Initialization Status: Check /health/initialization

Troubleshooting

Issue: Space fails to build

• Check Dockerfile syntax
• Verify all dependencies in requirements.txt
• Check Space logs for specific errors

Issue: API returns 500 errors

• Verify environment variables are set correctly
• Check that OPENAI_API_KEY is valid
• Review application logs

Issue: CORS errors in frontend

• Verify CORS middleware configuration in api/middleware.py
• Ensure frontend URL is in allowed origins

Issue: Slow initialization

• The system loads models in the background
• Check /health/initialization for status
• Consider upgrading to better hardware tier

Performance Optimization

For Better Performance:

1. Upgrade to GPU hardware tier (for faster embeddings)
2. Use persistent storage for cached data
3. Enable CDN for frontend assets

Memory Management:

• Current setup uses CPU-optimized models
• Faiss-cpu for vector search
• Sentence-transformers for embeddings

Security Considerations

1. Change default credentials in production
2. Rotate API keys regularly
3. Enable rate limiting (already configured)
4. Use HTTPS (automatic on Hugging Face)
5. Review CORS settings for production

Updating the Deployment

To update your deployment:

# Make changes locally
git add .
git commit -m "Update description"
git push

# Hugging Face will automatically rebuild

Cost Considerations

• Free tier: CPU Basic (limited resources)
• Paid tiers: Better performance and reliability
• API costs: OpenAI API usage (pay per token)

Support

For issues:

1. Check Hugging Face Space logs
2. Review application logs at /logs/app.log
3. Test endpoints using /docs (Swagger UI)

Additional Resources

• Hugging Face Spaces Documentation
• FastAPI Documentation
• Docker Documentation