---
title: MP Dengue EWS API
emoji: 🦟
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
app_port: 7860
---

# EWS inference API (FastAPI + bundled sklearn / XGB / LGBM / CatBoost)

This `README.md` **must stay at the repository root** of your Hugging Face **Docker** Space (the YAML block above configures the Space card).

## Quick links (when the Space is running)

- **Swagger UI:** `/docs`
- **OpenAPI JSON:** `/openapi.json`
- **Health:** `GET /health`
- **Feature schema:** `GET /schema`
- **Predict:** `POST /predict`

---

## A — One-time: build the bundle (your laptop)

From the **parent** project folder (`EWS Dashboard`), with your venv activated:

```bash
python bundle_ews_pipeline.py
```

That writes **`ews_pipeline_bundle.joblib`** into this **`hf_api/`** folder.

---

## B — Option 1: Push this `hf_api` folder as the Space repo

1. **Install [Git LFS](https://git-lfs.com)** (`git lfs install` once per machine).

2. On [huggingface.co/new-space](https://huggingface.co/new-space) create a Space:
   - **SDK:** Docker  
   - **Visibility:** Public or Private  
   - **Hardware:** CPU basic (upgrade only if builds are slow)

3. **Do not** add files in the web editor — you will push from git.

4. In PowerShell, from **`hf_api/`**:

   ```powershell
   .\prepare_hf_push.ps1
   git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
   git branch -M main
   git commit -m "Initial EWS API + LFS bundle"
   git push -u origin main
   ```

   Use the **HTTPS** clone URL from the Space **Files and versions** tab (it looks like `https://huggingface.co/spaces/...`).

5. Wait for the **Build** log on the Space page. When it is green, open:
   - `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/docs`

---

## B — Option 2: Export a clean folder (no monorepo clutter)

From **`EWS Dashboard`** root:

```bash
python bundle_ews_pipeline.py
python hf_api/export_for_hf_space.py
```

This creates **`ews_hf_space_export/`** next to `hf_api/`. `cd` into it, then `git init`, LFS, `git remote add`, commit, push — same as step B4.

---

## C — Test `POST /predict`

Minimal body (21 zeros — sanity check):

```json
{
  "values": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  "population": 2500000
}
```

Or named features (missing keys default to `0`); optional `population` for `estimated_cases` / `risk_tier`:

```json
{
  "features": { "ir_lag12": 0.5, "precipitation_lag11": 10.0 },
  "population": 2000000
}
```

---

## What is inside the bundle?

- `pipeline_config.json` content (in `config`)
- `scaler`, stage-1 classifier, **non-LSTM** stage-2 regressors, meta-learner  
- LSTM is **not** included (TensorFlow-free image; LSTM slot uses the mean of other regressors in inference code).

---

## Troubleshooting

| Issue | What to do |
|--------|------------|
| Build: `COPY ews_pipeline_bundle.joblib` failed | Run `bundle_ews_pipeline.py` and ensure the joblib is committed and pushed (with **Git LFS**). |
| Push: large file rejected | Run `git lfs install` and `git lfs track "*.joblib"` before committing. |
| 404 on `/` | Open `/docs` — or use `/` (redirects to `/docs`). |