Pharos
Heat-medication risk intelligence for NHS primary care networks.
Pharos combines NHS patient registration, prescribing, deprivation, climate
vulnerability, and Gasparrini heat-mortality data to compute a ranked heat-
medication risk score for every GP practice and PCN in London. It exposes a
FastAPI backend, a Qdrant-based RAG knowledge base, a WhatsApp LangGraph agent,
and a React dashboard.
Quick Start
See system_design.md for the full judge-facing architecture, data catalog, and
risk formula. The code below implements that design.
Windows
# 1. Set environment variables (copy .env.example to .env and fill in secrets)
cp .env.example .env
# 2. One-click setup (PowerShell 5.1 compatible)
.\local.ps1
# Or run phases separately:
.\local.ps1 setup
.\local.ps1 pipeline
.\local.ps1 rag
# 3. Start API and frontend (in separate terminals)
.\local.ps1 api
.\local.ps1 web
macOS / Linux
# 1. Set environment variables
cp .env.example .env
# 2. Setup, run migrations, data pipeline, and build the RAG index
./scripts/local.sh setup
./scripts/local.sh pipeline
./scripts/local.sh rag
# 3. Start API and frontend (in separate terminals)
./scripts/local.sh api
./scripts/local.sh web
Both PHAROS_ prefixed and plain system-design env var names (e.g.
DATABASE_URL, KIMI_API_KEY) are accepted.
Repository Layout
.
├── packages/api # FastAPI backend, data pipeline, agent
├── packages/rag # Qdrant + Docling + Chonkie + FastEmbed RAG
├── frontend # React + TypeScript + Tailwind + shadcn/ui + Deck.gl
├── infra # Terraform skeleton
├── scripts # Local setup scripts
├── data # NHS, prescribing, geography, climate data
└── .github/workflows # CI/CD workflows
Data Pipeline
The DuckDB ETL pipeline ingests NHS, prescribing, geography, and climate data,
computes practice and PCN heat-medication risk scores, and writes the results
into PostgreSQL.
cd packages/api
uv run python -m pharos.pipelines.run_all --reset
The pipeline produces:
gp_practices — active GP practices with PCN linkage
pcns — Primary Care Networks with aggregated risk
risk_scores — practice and PCN risk scores
lsoa_scores, lsoa_practice_population, nspl_cache, cooling_centers
API
cd packages/api
uv run uvicorn pharos.main:app --host 127.0.0.1 --port 8000
Endpoints:
GET /health — API and database health
GET /api/pcns — ranked PCN risk scores
GET /api/pcns/{pcn_code} — detailed risk for a PCN
GET /api/pcns/{pcn_code}/nearby — nearest cooling centers
GET /api/pcns/lsoa-tiers — LSOA choropleth tier mapping
GET /api/alert-status — UKHSA heat-health alert
POST /api/outreach/draft — draft outreach message
POST /api/outreach/send — send approved outreach message
POST /api/whatsapp/webhook — Twilio WhatsApp webhook
GET /api/whatsapp/recent — recent conversation mirror
GET /api/fhir/risk-assessment/{pcn_code} — UK Core FHIR R4 RiskAssessment
RAG Knowledge Base
The RAG builder implements the system-design retrieval pipeline:
- Docling parses PDFs to clean Markdown.
- Chonkie (
RecursiveChunker with markdown recipe) creates semantic chunks.
- Kimi generates contextual enrichment for each chunk.
- FastEmbed creates dense (bge-small) and sparse (BM25) vectors.
- Qdrant stores a hybrid collection and serves dense+sparse RRF fusion.
- bge-reranker-base reranks the fused results.
cd packages/rag
uv run python -m pharos_rag.build
Frontend
cd frontend
pnpm install
pnpm run dev
The dashboard shows the current UKHSA alert, a ranked PCN list, a London Deck.gl
choropleth (light-mode Carto basemap, all data driven by /api/pcns/lsoa-tiers),
a drill-down panel with drug breakdown charts, and a WhatsApp conversation mirror.
UI components are built with shadcn/ui.
Tests
cd packages/api
uv run pytest -q
Migrations
Alembic migrations live in packages/api/migrations/. They are applied via the
GitHub Actions workflow in .github/workflows/migrations.yml whenever the
migrations directory changes on the main branch.
cd packages/api
uv run alembic upgrade head
Deployment
Deploy the API to Google Cloud Run (or any container host) using the
packages/api/Dockerfile. The container runs migrations on startup and serves
FastAPI on port 8080.
gcloud run deploy pharos-api --source packages/api/ --region europe-west2 \
--allow-unauthenticated \
--set-env-vars="$(grep -v '^#' .env | xargs | tr ' ' ',')"
Deploy the frontend to Vercel:
cd frontend
VITE_API_URL=https://your-api-url.run.app pnpm exec vercel --prod
A Terraform skeleton is also provided in infra/main.tf using the Google Cloud Run
and Vercel providers.
License
MIT