README.md

metadata

title: HealthBot
emoji: 🧭
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
python_version: '3.12'
pinned: false
short_description: Geography-conditioned syndemic health reasoning
license: mit

🧭 SyndemicGPS — HealthBot

Same person, different place.

The same health profile should not automatically produce the same support pathway everywhere in the world. But geography should influence the reasoning only through explicit, evidence-backed contextual variables — never through country-name stereotypes.

HealthBot holds one student's syndemic profile fixed, moves them between places, and reports exactly which evidence-gated contextual factor changed the support pathway, at what geographic resolution, and from which reporting year — or refuses to use a factor at all when the evidence is too weak or too old.

---

What it does

Operation	Ask it	What happens
Analyze	What interacting problems do you see?	Describes the individual syndemic graph G_I
Contextualize	How does living in Dhaka affect this case?	Gates one place's context into G_S
Compare	Move this person from Bangladesh to Sweden.	Same person, two places, and the flip taxonomy between them
Explain	Why did your answer change?	Attributes the difference to specific gated nodes
Counterfactual	Keep them in Bangladesh but improve mental-health services.	Moves one structural variable, person and place fixed
Ablate	Answer without using geography.	C_g* = ∅ — the individual-only baseline
Uncertainty	What do you not know?	U = [U_I, U_G, U_K, U_T] and every abstention

The five flip types (GIF(u,a,b) = D(π_a, π_b))

• priority — the order of support actions changes
• pathway — an action appears or disappears entirely
• feasibility — the same goal is delivered by a different route
• confidence — certainty moves because local evidence quality differs
• escalation — the verified crisis resource changes

---

Architecture

user message
   │
   ├─► LLM role 1  parse intent → {op, place_a, place_b, factor}      (regex parser as fallback + safety veto)
   │
   ├─► DETERMINISTIC ENGINE  syndemic/engine.py
   │      individual graph G_I · geographic context C_g = [E,H,S,D,R]
   │      evidence gate  z_i = 1[Ev(c_i) ≥ τ]
   │      resolution ladder  city → subnational → national → cross-border region → global
   │      fusion G_S · support planner π · GIF · uncertainty · V(u,g)
   │
   └─► LLM role 3  verbalise the FACTS block only

The model never produces a number. Every prevalence, index, year, resolution level and service name in an answer is computed by the engine and handed to the model inside a FACTS block, under a system prompt that forbids inventing, extrapolating or rounding anything. If the model is unreachable the app degrades to deterministic mode and still returns the full structured answer.

Three guardrails are enforced outside the model:

1. Safety veto — a self-harm pattern match routes to the safety template before the LLM parse is consulted. Geography may change which resource is named; it never moves the threshold.
2. Abstention — a factor below τ, or too stale, is excluded rather than replaced by a weaker proxy.
3. Service-capacity floor — mental-health workforce, referral capacity, campus services and crisis pathways may not back off to a global mean. A missing local service is reported as unknown, never as available.

---

Configuration

The app reads its LLM credentials from the environment. On the Space these are secrets, never files in the repo.

Variable	Default	Meaning
LLM_API_KEY	—	Dialagram / OpenAI-compatible key. Without it the app runs deterministically.
LLM_BASE_URL	https://dialagram.me/router/v1	OpenAI-compatible endpoint
LLM_MODEL	qwen-3.8-max-thinking	Default writer model; all 16 switchable in the UI
LLM_PARSER_MODEL	qwen-3.6-plus	Model that parses intent into an operation

Run locally:

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env        # fill in LLM_API_KEY
export $(grep -v '^#' .env | xargs)
python app.py               # http://localhost:7860

Deploy (from a machine holding a HF write token):

python deploy.py --repo tirtho149/HealthBot

deploy.py uploads the app and pushes LLM_API_KEY / LLM_BASE_URL / LLM_MODEL into the Space's encrypted secret store. It refuses to upload .env.

---

Where the data comes from — retrieval, not a lookup table

Name any place on earth — a country, a state, a district, a refugee camp — and four live sources are retrieved for it. No API keys anywhere.

Stage	Source	What it gives
Resolve	OpenStreetMap Nominatim	any place name → coordinates, admin area, country (states and districts, not just cities)
Measure	Open-Meteo CAMS + ERA5	PM2.5 and days above 35 °C at those coordinates — genuine city-resolution observations
Indicators	World Bank Open Data	national series with indicator codes and reporting years
Passages	Wikipedia + BM25	prose about the health system, ranked against this person's own active factors

The resolution ladder is therefore real: a point measurement enters at city level, and the gate only backs off to the World Bank's national series when the point query returns nothing — and it says so.

The two halves of RAG are kept strictly apart, and the prompt enforces it: every number comes from the gated indicators; retrieved passages may only supply narrative context and must be attributed. A passage can never introduce a statistic.

Factor	Indicator
PM2.5	EN.ATM.PM25.MC.M3
Safely managed sanitation	SH.STA.SMSS.ZS
UHC service coverage	SH.UHC.SRVS.CV.XD
Out-of-pocket health cost	SH.XPD.OOPC.CH.ZS
Food insecurity	SN.ITK.MSFI.ZS
Poverty at $3.65/day	SI.POV.LMIC
Youth unemployment	SL.UEM.1524.ZS
Diabetes prevalence	SH.STA.DIAB.ZS
Referral capacity (proxy)	SH.MED.BEDS.ZS
Communicable-disease burden (proxy)	SH.DTH.COMM.ZS
PM2.5, city level	Open-Meteo CAMS, 90-day mean at the coordinates
Extreme-heat days, city level	Open-Meteo ERA5 daily maxima at the coordinates

Evidence scores are derived from the reporting year, so an old series is penalised and can fall below τ.

What is deliberately NOT fetched. Mental-health workforce, depression prevalence, extreme-heat days, campus services and verified crisis lines have no World Bank indicator. The system does not substitute a proxy for them — it abstains, and says so. Every seeded placeholder has now been removed: all contextual values come from a live source or the factor abstains. Only the last-resort global fallback rows remain illustrative, and they are labelled illustrative global baseline in the provenance panel.

Describing yourself works too. First-person messages ("I live in Iowa, I have gained weight, I don't sleep well") are recognised as case descriptions, not questions.

The case is live too. Describe any person in the conversation and X_u is parsed from that description into the factor catalogue; the graph, the interactions, and the whole pathway rebuild around them. Nothing about the person is hard-coded — the GREC pilot student is just one example scenario.

Claim boundary

π is a contextual support pathway, not an optimal treatment policy, a causal effect estimate, or a clinically validated recommendation. Graph edges are association-level. Structural counterfactuals are reasoning probes, not forecasts. Population statistics are evidence about a place, never facts about a person. Country membership is never used as a proxy for individual behaviour, belief, or preference. No reinforcement-learning policy is trained or claimed — the RL direction is preserved as future work, requiring prospective longitudinal outcome data and a defensible reward design.

This is a research prototype for support and hypothesis generation. It does not diagnose, treat, or replace professional care. If you are in danger, contact your local emergency services.

---

Built on the SyndemicGPS concept paper, which extends the GREC university-student syndemic framework (Bangladesh, pilot n = 32) into a worldwide, geography-conditioned reasoning architecture.