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](https://huggingface.co/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:

```bash
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

```bash
# 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

```bash
# 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:

```javascript
// 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:

```bash
# 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](https://huggingface.co/docs/hub/spaces)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [Docker Documentation](https://docs.docker.com/)