README.md

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

```json
{
  "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

```bash
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](https://www.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.