---
title: DataX Outlet Intelligence API
emoji: 📊
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0
short_description: Outlet potential + SHAP + Gemini XAI backend
---

# DataX Outlet Intelligence — Backend (Hugging Face Space)

FastAPI service that exposes the gold-layer artifacts of the
DataStorm v7.0 pipeline through 18 JSON endpoints, including an
on-demand Gemini 2.5 Flash narrative for any outlet.

This Space is **automatically rebuilt** on every push to the `main`
branch of the source GitHub repo via a GitHub Actions workflow.

| | |
|---|---|
| Source | <https://github.com/AdithaBuwaneka/DataX-DataStorm-7.0> |
| Workflow | `.github/workflows/deploy-backend-to-hf.yml` |
| Health probe | `GET /health` |
| OpenAPI / Swagger | `GET /docs` |

## Required Space secret

| Name | Where to set | Purpose |
|---|---|---|
| `GEMINI_API_KEY` | Settings → Variables and secrets → New secret | Enables the `/api/xai/explain/{id}` Gemini narrative endpoint |

Without `GEMINI_API_KEY` the rest of the API still works; only the
narrative endpoint returns HTTP 503.

## Endpoints (summary)

| Endpoint | Returns |
|---|---|
| `GET /health` | Liveness probe + data-loaded confirmation |
| `GET /api/summary` | Dashboard KPI tiles |
| `GET /api/outlets` | Paginated outlet list |
| `GET /api/outlets/{id}` | Drill-down + SHAP + counterfactual + actions + cooler ROI |
| `POST /api/xai/explain/{id}` | Gemini narrative |
| `GET /api/budget/*` | LKR 5M Western Province allocation |
| `GET /api/cooler-roi/*` | Top-100 cooler deployment |
| `GET /api/dormancy/*` | At-risk outlets |
| `GET /api/scorecard` | 10-distributor benchmark |
| `GET /api/territories` | HDBSCAN clusters |
| `GET /api/forensics` | Beyond-DQ forensic findings |
| `GET /api/shap/global` | Global mean \|SHAP\| ranking |

Full reference at <https://huggingface.co/spaces/adithaf7/datax-outlet-intelligence-api/docs>.