DOCKER_SDK_SETUP.md

# Docker SDK Setup Guide

## Overview

The Research AI Assistant now uses **Docker SDK** instead of Gradio SDK for Hugging Face Spaces deployment. This provides more control and flexibility.

## Changes Made

### 1. README.md Configuration

Changed from:
```yaml
sdk: gradio
app_file: app.py
```

To:
```yaml
sdk: docker
app_port: 7860
```

### 2. Dockerfile Configuration

**Key Features:**
- **Base Image**: Python 3.10-slim
- **Entry Point**: `main.py` (starts both Gradio and Flask API)
- **Ports**: 
  - 7860: Gradio UI (primary, exposed by HF Spaces)
  - 5001: Flask API (background thread)
- **Health Check**: Monitors Gradio endpoint

## How It Works

### Startup Sequence

1. **Docker Container Starts**
   - Runs `python main.py`

2. **main.py Initializes**
   - Starts Flask API in background thread (port 5001)
   - Creates Gradio interface from `app.py`
   - Launches Gradio on port 7860

3. **Both Services Available**
   - Gradio UI: `https://your-space.hf.space` (port 7860)
   - Flask API: Available internally (port 5001)

## File Structure

```
Research_AI_Assistant/
├── Dockerfile              # Main Dockerfile (used by HF Spaces)
├── Dockerfile.hf           # Alternative/backup Dockerfile
├── README.md               # HF Spaces config (sdk: docker)
├── main.py                 # Entry point (starts Flask + Gradio)
├── app.py                  # Gradio interface definition
└── flask_api.py            # Flask API (started by main.py)
```

## Benefits of Docker SDK

### 1. **More Control**
- Full control over container environment
- Can install system dependencies
- Custom startup scripts

### 2. **Multiple Services**
- Can run multiple processes (Gradio + Flask)
- Better resource management
- Health checks

### 3. **Flexibility**
- Not limited to Gradio's constraints
- Can add additional services
- Better debugging

### 4. **Production Ready**
- Standard Docker patterns
- Easier to migrate to other platforms
- Better for CI/CD

## Deployment

### On Hugging Face Spaces

1. **Push to Repository**
   ```bash
   git push origin main
   ```

2. **HF Spaces Auto-Builds**
   - Detects `sdk: docker` in README.md
   - Builds Docker image from Dockerfile
   - Exposes port 7860

3. **Services Start**
   - Flask API starts in background
   - Gradio UI launches on port 7860
   - Both share orchestrator instance

### Local Testing

Test the Docker build locally:

```bash
# Build image
docker build -t research-assistant .

# Run container
docker run -p 7860:7860 -p 5001:5001 \
  -e HF_TOKEN=your_token \
  research-assistant
```

## Port Configuration

### Exposed Ports

- **7860**: Gradio UI (primary, exposed by HF Spaces)
  - Accessible at: `https://your-space.hf.space`
  
- **5001**: Flask API (internal, background thread)
  - Not directly exposed by HF Spaces
  - Can be accessed via port forwarding if needed

### Internal Communication

- Flask API runs in same container
- Both services share Python process
- Shared orchestrator instance
- No network overhead

## Environment Variables

Set in HF Spaces Secrets:

```bash
HF_TOKEN=your_huggingface_token
ENABLE_FLASK_API=true      # Default: true
FLASK_PORT=5001            # Default: 5001
FLASK_HOST=0.0.0.0        # Default: 0.0.0.0
```

## Health Checks

The Dockerfile includes a health check:

```dockerfile
HEALTHCHECK --interval=30s --timeout=30s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:7860/ || exit 1
```

- Checks Gradio endpoint every 30 seconds
- 60-second startup period (allows initialization)
- 3 retries before marking unhealthy

## Troubleshooting

### Issue: Build Fails

**Check:**
1. Dockerfile syntax is correct
2. Requirements.txt has all dependencies
3. Python 3.10 is available

**Solution:**
```bash
# Test build locally
docker build -t test-build .
```

### Issue: Port Not Accessible

**Check:**
1. `app_port: 7860` in README.md
2. Gradio is listening on 0.0.0.0:7860
3. No firewall blocking

**Solution:**
- Verify in logs: "Running on local URL: http://0.0.0.0:7860"

### Issue: Flask API Not Starting

**Check:**
1. Logs show Flask initialization
2. `ENABLE_FLASK_API=true` (default)
3. Port 5001 not conflicting

**Solution:**
- Check logs for "Starting Flask API in background thread..."
- Verify Flask thread starts successfully

## Comparison: Gradio SDK vs Docker SDK

| Feature | Gradio SDK | Docker SDK |
|---------|------------|------------|
| **Setup** | Simple | More control |
| **Multiple Services** | ❌ Limited | ✅ Full control |
| **System Dependencies** | ⚠️ Limited | ✅ Full access |
| **Customization** | ⚠️ Limited | ✅ Complete |
| **Debugging** | ⚠️ Harder | ✅ Easier |
| **Port Configuration** | ⚠️ Fixed | ✅ Flexible |
| **Health Checks** | ❌ No | ✅ Yes |

## Migration Notes

### From Gradio SDK

If migrating from Gradio SDK:

1. ✅ **README.md**: Changed `sdk: gradio` → `sdk: docker`
2. ✅ **Dockerfile**: Created/updated to use `main.py`
3. ✅ **Entry Point**: Changed from `app.py` → `main.py`
4. ✅ **Ports**: Explicitly configured (7860, 5001)

### What Still Works

- ✅ All Gradio functionality preserved
- ✅ All API endpoints work
- ✅ Flask API integration works
- ✅ Orchestrator initialization unchanged

## Summary

✅ **Docker SDK**: More control and flexibility  
✅ **Dual Services**: Gradio + Flask API  
✅ **Production Ready**: Standard Docker patterns  
✅ **Health Checks**: Built-in monitoring  
✅ **Flexible**: Easy to extend and customize  

The application now uses Docker SDK for better control and flexibility while maintaining all existing functionality.