Hugging Face's logo

Spaces:
mistral-hackaton-2026
/
TB-Guard-XAI
Sleeping

App Files Community
TB-Guard-XAI / GDRIVE_SETUP.md
Vignesh-19's picture
Vignesh-19
Upload folder using huggingface_hub
ee9c1ec verified
preview code
|
Raw History Blame Contribute Delete
9.25 kB

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

🚀 Setup Instructions (15 minutes)

Step 1: Enable Google Drive API

  1. Go to Google Cloud Console
  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 

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:

# 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) 

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) 

python gdrive_batch_processor.py

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

Process Once (Single Run) 

python gdrive_batch_processor.py once

Processes all files in inbox and exits.

Custom HF Space URL 

# 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
  1. 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:

processor.watch_and_process(interval=60)  # Check every 60 seconds

Change Folder Names

Edit at top of gdrive_batch_processor.py:

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:

[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:

sudo systemctl enable tb-gdrive-processor
sudo systemctl start tb-gdrive-processor

Run as Windows Service

Use NSSM (Non-Sucking Service Manager):

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 

# Linux
sudo systemctl status tb-gdrive-processor

# Windows
nssm status TB-Guard-XAI-GDrive

View Logs 

# 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