PUBLIC_MODELS_GUIDE.md

Medical AI Platform - Public Model Configuration

Overview

This Medical AI Platform is designed to work WITHOUT requiring HuggingFace authentication for most use cases. All core medical AI models used are public and freely available.

---

Model Access Strategy

Public Models (No Authentication Required)

The following models are public on HuggingFace and work without HF_TOKEN:

1. Bio_ClinicalBERT (emilyalsentzer/Bio_ClinicalBERT)

   • Document type classification
   • Clinical text understanding
   • Public - No auth needed

2. BioGPT-Large (microsoft/BioGPT-Large)

   • Clinical text generation
   • Medical summarization
   • Public - No auth needed

3. Biomedical NER (d4data/biomedical-ner-all)

   • Named entity recognition
   • Medical entity extraction
   • Public - No auth needed

4. PubMedBERT (microsoft/BiomedNLP-PubMedBERT-base-uncased-abstract-fulltext)

   • Medical text understanding
   • General analysis
   • Public - No auth needed

5. SciBERT (allenai/scibert_scivocab_uncased)

   • Drug interaction detection
   • Scientific text analysis
   • Public - No auth needed

6. RoBERTa-SQuAD2 (deepset/roberta-base-squad2)

   • Medical question answering
   • Public - No auth needed

7. BigBird-Pegasus (google/bigbird-pegasus-large-pubmed)

   • Clinical summarization
   • Long document processing
   • Public - No auth needed

When HF_TOKEN Is Needed

HF_TOKEN is ONLY required for:

• Gated models (e.g., some Google MedGemma models)
• Private organization models
• Models with specific access restrictions

For this platform: HF_TOKEN is OPTIONAL

---

Architecture Design

Robust Fallback System

1. Try loading public model WITHOUT authentication
   ↓
2. If model requires auth AND HF_TOKEN available → Use token
   ↓
3. If model fails → Use alternative public model
   ↓
4. If all AI models fail → Fallback to keyword analysis

Error Handling

The system gracefully handles:

• Missing HF_TOKEN (uses public models)
• Network connectivity issues (cached models)
• Model download failures (alternative models)
• Authentication errors (informative logs)

---

Deployment Configuration

HuggingFace Spaces

No HF_TOKEN required in Space secrets

The platform will:

1. Check if HF_TOKEN exists
2. Log: "HF_TOKEN not configured - using public models"
3. Load all public models successfully
4. Provide full functionality

Environment Variables

Optional:

HF_TOKEN=hf_xxx  # Only for gated models

Always Available:

TRANSFORMERS_CACHE=/app/.cache/huggingface
HF_HOME=/app/.cache/huggingface
PYTHONUNBUFFERED=1
TOKENIZERS_PARALLELISM=false

---

Code Implementation

Model Loader (model_loader.py)

# Get HF token from environment (optional - most models are public)
HF_TOKEN = os.getenv("HF_TOKEN", None)

if HF_TOKEN:
    logger.info("HF_TOKEN found - will use for gated models if needed")
else:
    logger.info("HF_TOKEN not found - using public models only (this is normal)")

Loading Strategy

def load_model(self, model_key: str):
    # Try without token first (works for public models)
    pipeline_kwargs = {
        "task": task,
        "model": model_id,
        "device": device,
        "trust_remote_code": True
    }
    
    # Only add token if it exists
    if HF_TOKEN:
        pipeline_kwargs["token"] = HF_TOKEN
    
    model = pipeline(**pipeline_kwargs)

Error Messages

if "401" in error or "unauthorized" in error:
    if not HF_TOKEN:
        logger.error("Model requires auth but HF_TOKEN not available")
        logger.error("Using public alternative")
    else:
        logger.error("Auth failed even with HF_TOKEN")

---

Testing Without HF_TOKEN

Steps:

1. Deploy to HuggingFace Spaces without adding HF_TOKEN secret
2. Platform starts successfully
3. Logs show: "HF_TOKEN not configured - using public models"
4. Upload medical PDF
5. Bio_ClinicalBERT loads from public HuggingFace Hub
6. Analysis completes successfully
7. Results display AI classification

Expected Logs:

INFO - HF_TOKEN not configured - using public models (Bio_ClinicalBERT, BioGPT, etc.)
INFO - This is normal - most HuggingFace models are public
INFO - Model Loader initialized on device: cuda
INFO - Loading model: emilyalsentzer/Bio_ClinicalBERT for task: text-classification
INFO - Successfully loaded model: emilyalsentzer/Bio_ClinicalBERT
INFO - Document classified as: radiology (confidence: 0.89, method: ai_model)

---

Benefits of This Approach

1. Reliability: No dependency on external secrets
2. Simplicity: Works out-of-the-box without configuration
3. Robustness: Handles token expiration gracefully
4. Transparency: Clear logs about model availability
5. Flexibility: Can still use HF_TOKEN for gated models if needed

---

Troubleshooting

If Models Don't Load

Issue: "Failed to load model"

Check:

1. Is the model ID correct?
2. Is the model public on HuggingFace?
3. Does the model exist? (some may be renamed/moved)
4. Network connectivity to huggingface.co?

Solution:

• All models used are verified public
• Platform will fallback to keyword analysis if models fail
• Check logs for specific error messages

If Authentication Errors Occur

Issue: "401 Unauthorized" or "Authentication required"

This means:

• Model is gated/private (not expected for our models)
• Model access changed to require auth

Solution:

1. Replace with alternative public model
2. Add HF_TOKEN if model is critical
3. Use keyword fallback (already implemented)

---

Verified Public Models

All models have been verified as public on HuggingFace Hub:

• ✅ Bio_ClinicalBERT - Public
• ✅ BioGPT-Large - Public
• ✅ biomedical-ner-all - Public
• ✅ PubMedBERT - Public
• ✅ SciBERT - Public
• ✅ RoBERTa-SQuAD2 - Public
• ✅ BigBird-Pegasus-PubMed - Public

Last verified: 2025-10-28

---

Conclusion

The Medical AI Platform does NOT require HF_TOKEN for normal operation.

All core functionality works with public HuggingFace models. The platform is designed to be robust, reliable, and work without external authentication dependencies.

---

Status: Production Ready
Authentication: Optional
Public Models: 7+ verified
Fallback System: Implemented