# Google Drive Batch Processor Setup Guide

## 🎯 What This Does

Automatically processes chest X-rays uploaded to Google Drive using your live Hugging Face Space:
1. Upload X-rays to "TB_XRay_Inbox" folder in Google Drive
2. System detects new files and sends them to your HF Space API
3. HF Space analyzes with full pipeline (CNN → Gemini → Mistral → RAG)
4. PDF reports generated and saved to "TB_Reports" folder
5. Original X-rays moved to "TB_Processed" folder

**Key Advantage**: Uses your deployed HF Space - no local model needed! 🚀

---

## 📋 Prerequisites

- Python 3.10+
- Google Account
- **Your Hugging Face Space must be running** (https://huggingface.co/spaces/mistral-hackaton-2026/TB-Guard-XAI)
- Internet connection (for API calls)

---

## 🚀 Setup Instructions (15 minutes)

### Step 1: Enable Google Drive API

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select existing one
3. Click "Enable APIs and Services"
4. Search for "Google Drive API"
5. Click "Enable"

### Step 2: Create OAuth Credentials

1. In Google Cloud Console, go to "Credentials"
2. Click "Create Credentials" → "OAuth client ID"
3. If prompted, configure OAuth consent screen:
   - User Type: External
   - App name: TB-Guard-XAI
   - User support email: your email
   - Developer contact: your email
   - Save and continue through all steps
4. Back to "Create OAuth client ID":
   - Application type: Desktop app
   - Name: TB-Guard-XAI Desktop
   - Click "Create"
5. Download the credentials JSON file
6. Rename it to `credentials.json`
7. Move it to your TB-Guard-XAI project folder

### Step 3: Install Dependencies

```bash
pip install google-auth-oauthlib google-auth-httplib2 google-api-python-client fpdf requests
```

**Note**: No need to install PyTorch or model dependencies - we use the HF Space API!

### Step 4: Configure Hugging Face Space URL (Optional)

The script uses your deployed HF Space by default. If you need to change it:

```bash
# Set environment variable
export HF_SPACE_URL="https://your-username-tb-guard-xai.hf.space"

# Or pass as argument
python gdrive_batch_processor.py https://your-username-tb-guard-xai.hf.space
```

Default URL: `https://mistral-hackaton-2026-tb-guard-xai.hf.space`

### Step 5: First Run (Authentication)

```bash
python gdrive_batch_processor.py
```

This will:
1. Open your browser for Google authentication
2. Ask you to allow TB-Guard-XAI to access your Google Drive
3. Click "Allow"
4. Browser will show "Authentication successful"
5. Close browser and return to terminal

A `token.pickle` file will be created (stores your authentication).

### Step 6: Verify Setup

The script will:
1. Test connection to your Hugging Face Space
2. Create 3 folders in your Google Drive:
   - `TB_XRay_Inbox` - Upload X-rays here
   - `TB_Reports` - PDF reports saved here
   - `TB_Processed` - Processed X-rays moved here

You should see:
```
🔗 Testing connection to Hugging Face Space...
   URL: https://mistral-hackaton-2026-tb-guard-xai.hf.space
   ✅ API is online and ready!

✅ Google Drive folders ready:
   📥 Inbox: TB_XRay_Inbox
   📄 Reports: TB_Reports
   ✅ Processed: TB_Processed
```

---

## 🎮 Usage

### Watch Mode (Continuous)

```bash
python gdrive_batch_processor.py
```

Runs continuously, checking for new files every 30 seconds.
Press Ctrl+C to stop.

### Process Once (Single Run)

```bash
python gdrive_batch_processor.py once
```

Processes all files in inbox and exits.

### Custom HF Space URL

```bash
# Use custom Hugging Face Space
python gdrive_batch_processor.py https://your-space.hf.space

# Or set environment variable
export HF_SPACE_URL="https://your-space.hf.space"
python gdrive_batch_processor.py
```

---

## 📁 Folder Structure in Google Drive

```
My Drive/
├── TB_XRay_Inbox/          # Upload X-rays here
│   └── (empty after processing)
├── TB_Reports/             # PDF reports appear here
│   ├── patient001_report.pdf
│   ├── patient002_report.pdf
│   └── ...
└── TB_Processed/           # Processed X-rays moved here
    ├── patient001.png
    ├── patient002.png
    └── ...
```

---

## 🎬 Demo Workflow

1. **Upload X-rays**:
   - Go to Google Drive
   - Open "TB_XRay_Inbox" folder
   - Upload chest X-ray images (PNG or JPEG)

2. **Automatic Processing**:
   - Script detects new files
   - Downloads X-ray temporarily
   - **Sends to Hugging Face Space API** for analysis
   - **HF Space runs full pipeline**: CNN → Gemini → Mistral → RAG
   - Receives results and generates PDF report
   - Uploads report to "TB_Reports"
   - Moves original to "TB_Processed"
   - Cleans up temporary files

**Processing Time per X-ray:**
- Offline mode (high confidence): ~5-10 seconds
- Online mode (Gemini validation): ~15-20 seconds  
- Full pipeline (Mistral synthesis): ~20-30 seconds

3. **Access Reports**:
   - Open "TB_Reports" folder
   - Download or share PDF reports
   - Reports include: prediction, probability, uncertainty, clinical synthesis

---

## 🔧 Configuration

### Change Check Interval

Edit `gdrive_batch_processor.py`:
```python
processor.watch_and_process(interval=60)  # Check every 60 seconds
```

### Change Folder Names

Edit at top of `gdrive_batch_processor.py`:
```python
INBOX_FOLDER = "Your_Inbox_Name"
REPORTS_FOLDER = "Your_Reports_Name"
PROCESSED_FOLDER = "Your_Processed_Name"
```

---

## 🐛 Troubleshooting

### Error: "credentials.json not found"
- Download OAuth credentials from Google Cloud Console
- Rename to `credentials.json`
- Place in project root folder

### Error: "Access denied"
- Delete `token.pickle`
- Run script again to re-authenticate
- Make sure you clicked "Allow" during authentication

### Error: "API not enabled"
- Go to Google Cloud Console
- Enable Google Drive API
- Wait 1-2 minutes for activation

### Files not processing
- Check if files are in correct folder ("TB_XRay_Inbox")
- Check file format (PNG or JPEG only)
- Check script is running (should show "Watching folder...")
- **Check Hugging Face Space is running** (visit URL in browser)
- Check internet connection
- Check API timeout (default 60 seconds)

### Error: "API timeout"
- Your HF Space might be cold-starting (first request takes longer)
- Wait 1-2 minutes and try again
- Check HF Space logs for errors
- Increase timeout in code if needed

### Error: "API error: 500"
- Check HF Space logs for errors
- Verify API keys are set in HF Space (MISTRAL_API_KEY, GEMINI_API_KEY)
- Try analyzing directly on HF Space web interface first

---

## 🔒 Security Notes

- `credentials.json` - OAuth client credentials (safe to commit if public app)
- `token.pickle` - Your personal access token (DO NOT commit to git)
- Add to `.gitignore`:
  ```
  token.pickle
  credentials.json
  temp_gdrive/
  ```

---

## 🚀 Production Deployment

### Run as Background Service (Linux)

Create `/etc/systemd/system/tb-gdrive-processor.service`:
```ini
[Unit]
Description=TB-Guard-XAI Google Drive Processor
After=network.target

[Service]
Type=simple
User=your_username
WorkingDirectory=/path/to/TB-Guard-XAI
ExecStart=/path/to/python gdrive_batch_processor.py
Restart=always

[Install]
WantedBy=multi-user.target
```

Enable and start:
```bash
sudo systemctl enable tb-gdrive-processor
sudo systemctl start tb-gdrive-processor
```

### Run as Windows Service

Use NSSM (Non-Sucking Service Manager):
```bash
nssm install TB-Guard-XAI-GDrive "C:\path\to\python.exe" "C:\path\to\gdrive_batch_processor.py"
nssm start TB-Guard-XAI-GDrive
```

---

## 📊 Monitoring

### Check Status
```bash
# Linux
sudo systemctl status tb-gdrive-processor

# Windows
nssm status TB-Guard-XAI-GDrive
```

### View Logs
```bash
# Linux
journalctl -u tb-gdrive-processor -f

# Windows
# Check Windows Event Viewer
```

---

## 🎯 Use Cases

1. **Rural Clinic Batch Processing**
   - Clinic staff upload day's X-rays at 5pm
   - System processes overnight
   - Reports ready by morning

2. **Mobile Health Unit**
   - Field workers upload X-rays via mobile
   - Cloud processing while traveling
   - Reports available immediately

3. **Telemedicine**
   - Remote clinics upload to shared Drive
   - Central AI processes all cases
   - Radiologists review flagged cases

---

## 💡 Tips

- Upload files in batches for efficiency
- Use descriptive filenames (patient ID, date)
- Reports have same name as X-ray + "_report.pdf"
- System handles multiple files simultaneously
- Processed X-rays kept for audit trail

---

## 🆘 Support

If you encounter issues:
1. Check this guide's troubleshooting section
2. Verify Google Drive API is enabled
3. Check credentials.json is valid
4. Ensure internet connection is stable
5. Check Python dependencies are installed

---

**Built for TB-Guard-XAI**
**Mistral AI Worldwide Hackathon 2026**