api migration v1

DOCKER_SDK_SETUP.md

@@ -0,0 +1,233 @@
+# 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.
+