Deterministic rule-based NLP toolkit for detecting attacks on healthcare in conflict zones from free-text event data.
Source-agnostic adapter pattern, interactive dashboard, MIT license.
About · Install · Quick Start · Documentation · Contributing
HICE (Healthcare Interference Conflict Event) is a deterministic rule-based NLP pipeline that detects healthcare targeting in conflict zones from unstructured narrative text — without requiring labeled training data or machine learning models. It utilize a three-layer architecture: a structural gate that filters for violent events, bidirectional keyword coupling within a 45-character proximity window, and bystander disambiguation to filter false positives. Results are classified into five impact categories and scored regionally for vulnerability triage.
The framework is source-agnostic via plug-in adapters. Currently supports ACLED (used in the Myanmar case study) and UCDP GED, with a public adapter interface for any conflict event dataset.
Performance: 96.0% validated precision (3-pass AI audit, n=450). Regional rankings stable at Spearman's ρ ≥ 0.9926 under weight perturbations.
pip install git+https://github.com/TainYanTun/HICE-Framework.gitOr clone and install locally:
git clone https://github.com/TainYanTun/HICE-Framework.git
pip install HICE-Framework/hice_framework/Requires Python 3.10+. Dependencies (pandas, numpy, scipy) install automatically.
from hice_framework import ACLEDAdapter, detect_hice_from_source, classify_hice_type, VulnerabilityScorer
df = pd.read_csv("myanmar_conflict_clean.csv")
mask = detect_hice_from_source(df, ACLEDAdapter())
hice_events = df[mask].copy()
hice_events["hice_type"] = classify_hice_type(hice_events["notes"].fillna("").str.lower())
scorer = VulnerabilityScorer()
ranking = scorer.score(hice_events, admin_col="admin1")
print(ranking.head(10))Full walkthrough: docs/Usage_Guide.md
python scripts/precompute.py
uvicorn server:app --host 0.0.0.0 --port 8000python scripts/validation/run_all.pyOutput written to validation/validation_summary.json.
| Guide | Description |
|---|---|
| Usage Guide | End-to-end walkthrough with data loading, detection, classification, scoring |
| Detection Pipeline | Three-layer architecture: structural gate, keyword coupling, bystander filtering |
| Signal System | All keyword patterns, proximity window, bystander regex rules |
| Classification | Five-category priority system with validation results |
| Source Adapters | Adapter pattern for ACLED, UCDP GED, custom datasets |
| Vulnerability Score — Formula & Worked Example | Formula breakdown, category weights, full per-incident step-by-step calculation |
| Validation Framework | AI audit, category validation, sensitivity methodology |
| Dashboard API | FastAPI routes, precompute pipeline, simulator |
| Layer | Step | Status |
|---|---|---|
| 1 | Structural gate — kinetic events only | ✅ |
| 2a | Health keyword detection (23 patterns) | ✅ |
| 2b | Bidirectional proximity coupling (45-char window) | ✅ |
| 2c | Targeting verbs, action phrases, soft casualty coupling | ✅ |
| 3 | Bystander disambiguation (F1 civilian lists, F2 aid context, F3 spatial) | ✅ |
| — | Five-category HICE classification | ✅ |
| — | Regional vulnerability scoring with sensitivity analysis | ✅ |
| — | Interactive dashboard with pipeline simulator | ✅ |
| Category | Weight | Description |
|---|---|---|
| Personnel Targeting | 1.0 | Medical staff killed, arrested, shot, or abducted |
| Systemic Attack | 0.9 | Infrastructure damage + staff present |
| Infrastructure Damage | 0.6 | Facilities bombed, burned, shelled, looted |
| Access Disruption | 0.5 | Closures, blockades, proximity violence |
| Humanitarian Disruption | 0.3 | Supply chain or logistics interference |
├── data/ # Conflict event data + precomputed dashboard data
├── docs/ # Documentation guides
├── hice_framework/ # Core library (adapter, detector, signals, scoring)
├── notebooks/ # Jupyter notebooks for research analysis
├── research/ # LaTeX paper, figures, assets
├── scripts/
│ ├── precompute.py # Dashboard data generator
│ ├── generate/ # Figure/chart generation scripts
│ ├── audit/ # Precision validation scripts
│ └── validation/ # Validation suite runner
├── static/ # Dashboard CSS
├── templates/ # Dashboard HTML
├── validation/ # Validation samples and output artifacts
├── server.py # FastAPI dashboard
└── requirements.txt
The Myanmar case study uses ACLED data (Feb 2021–Apr 2025, 80,000+ events). The adapter architecture also supports UCDP GED and any custom dataset with free-text narrative columns.
- Do No Harm: Geospatial resolution limited to administrative region level to prevent tactical exploitation.
- Verified Floor: Detected counts are confirmed minimums; actual figures in communication-blackout regions are likely higher.
- ICRC Alignment: Data governance follows the ICRC Handbook on Data Protection in Humanitarian Action.
Contributions welcome. See docs/ for system documentation and methodology details.
MIT License. Conflict data sourced from ACLED.