README.md

metadata

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:

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 (git lfs install once per machine).

2. On 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/:

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

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

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

{
  "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).