README.md

metadata

title: Virus Prediction API
emoji: 🦠
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit

🦠 Virus Prediction API

AI-powered viral infection prediction system with dual-model architecture for comprehensive diagnosis assistance.

Features

• 26 Major Virus Categories: Dengue, Chikungunya, Japanese Encephalitis, Hepatitis variants, Influenza, SARS-CoV-2, and more
• 13 Sub-categories: Advanced classification for "Other Viruses" category
• Comprehensive Symptom Analysis: Neurological, GI, respiratory, dermatological, and systemic symptoms
• Geo-temporal Intelligence: Incorporates seasonal patterns and geographical factors
• FastAPI Backend: High-performance REST API with automatic documentation
• MongoDB Atlas Integration: Persistent storage for predictions and analytics

API Endpoints

🏥 Core Endpoints

• GET / - Interactive API documentation (Swagger UI)
• GET /health - Health check and system status
• POST /predict - Make virus prediction from patient data
• POST /validate - Submit validation feedback
• GET /mappings - Get virus and symptom mappings
• GET /location-mappings - Get authoritative state/district encoders for frontend forms
• GET /locations - Alias for /location-mappings
• GET /stats - Get prediction statistics

📍 Location Mappings Response

GET /location-mappings returns frontend-safe location config and exact model-compatible encoder values for labstate and districtencoded.

Example response:

{
  "states": ["Andhra Pradesh", "Tamil Nadu"],
  "districts_by_state": {
    "Andhra Pradesh": ["Ananthapuramu", "Chittoor"],
    "Tamil Nadu": ["Chennai", "Coimbatore"]
  },
  "state_mapping": {
    "Andhra Pradesh": 1,
    "Tamil Nadu": 26
  },
  "district_mapping": {
    "Ananthapuramu": 24,
    "Chennai": 130
  },
  "district_mapping_by_state": {
    "Andhra Pradesh": {
      "Ananthapuramu": 24,
      "Chittoor": 140
    },
    "Tamil Nadu": {
      "Chennai": 130,
      "Coimbatore": 145
    }
  },
  "source": "csv:state_encoding_map.csv,district_state_mapping.csv",
  "timestamp": "2026-03-13T12:00:00.000000",
  "warnings": []
}

Source and fallback behavior:

• Preferred source is repository mapping files (state_encoding_map.csv, district_state_mapping.csv, district_encoding_map.csv).
• district_mapping only includes district names that are globally unambiguous. If the same district name exists in multiple states, use district_mapping_by_state[state][district].
• If CSV mappings are missing or partial, the API attempts to extract encoded location classes from model preprocessing artifacts.
• If only encoded classes are available, synthetic labels like encoded_26 are returned with warnings.
• Endpoint is resilient: it always returns HTTP 200 with stable keys, even when only partial mapping data is available.

📊 Example Request

curl -X POST "https://your-space-url/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "age": 30,
    "SEX": 1,
    "PATIENTTYPE": 1,
    "durationofillness": 3,
    "labstate": 32,
    "districtencoded": 120,
    "month": 8,
    "year": 2024,
    "syndrome": 5,
    "FEVER": 1,
    "HEADACHE": 1,
    "MYALGIA": 1
  }'

Setup

MongoDB Atlas Connection

This API requires MongoDB Atlas for data persistence. Set up your connection:

1. Create a free MongoDB Atlas cluster at mongodb.com/cloud/atlas
2. Get your connection string
3. Add to Hugging Face Spaces Secrets:
   • Key: MONGODB_URI
   • Value: mongodb+srv://username:password@cluster.mongodb.net/virus_prediction?retryWrites=true&w=majority

Hugging Face Spaces Deployment

1. Create a new Space on Hugging Face
2. Select SDK: Docker
3. Add secret: MONGODB_URI with your MongoDB Atlas connection string
4. Upload all files from this directory
5. Space will auto-build and deploy

System Architecture

Model Architecture

• Primary Model: Custom Gated Residual Tabular Transformer (CustomMajor.pth - 26 classes)
• Secondary Model: Custom Gated Residual Tabular Transformer (CustomOther.pth - 13 sub-classes)
• Feature Engineering: 80+ engineered features including temporal, geographical, and symptom interactions

Optimizations for Free Tier

• ✅ CPU-only inference (no GPU required)
• ✅ Model size: ~10MB (well within limits)
• ✅ Cached model loading
• ✅ Minimal dependencies (~800MB PyTorch + ~150MB others)
• ✅ External MongoDB Atlas (no local storage needed)

Technical Specifications

• Framework: FastAPI
• ML Framework: PyTorch
• Database: MongoDB Atlas
• Python: 3.11
• Port: 7860 (HF Spaces default)

Model Performance

• Accuracy: State-of-the-art performance on viral infection classification
• Inference Speed: < 1 second per prediction (CPU)
• Memory Usage: ~2GB RAM with models loaded

Medical Disclaimer

⚠️ This system is designed to assist healthcare professionals and should not be used as a substitute for professional medical diagnosis, treatment, or advice. Always consult qualified medical personnel for patient care decisions.

License

MIT License

Authors

Developed for advanced AI-driven diagnostic assistance in viral infections.