Docs, parameters,
references.
Everything you need to reason about what EpiChat will and won't do — architecture, parameters, disease defaults, and the seven-phase data roadmap.
Architecture
EpiChat is a six-layer pipeline. The LLM handles language; templates handle the simulation. Free-form code is never executed.
User NL query (any language · text · URL · report · web search)
│
▼
Layer 0 Input Enricher (Claude Haiku + web_search — extracts OutbreakContext)
│ Structured facts: disease, location, cases, R₀, interventions
▼
Layer 1 LLM Parameter Parser (Claude API + extraction prompt)
│ SimParams JSON · resolver pulls UN WPP, WHO GHO, World Bank
│ β recalibrated for age-structured networks after demographics applied
▼
Layer 1b Fact-Checker (disease_parameters.json — no LLM call)
│ ⚠ warns if R₀, dur_inf, or dur_exp outside literature ranges
▼
Layer 2 Code generator (Jinja2 → Starsim Python)
│ Python script
▼
Layer 3 Execution engine (subprocess sandbox, 90s timeout)
│ Stats JSON + plot file
▼
Layer 4 Results narrator (Claude API + narration prompt, in user's language)
│ Plain-language summary
▼
User: epidemic curve + interpretationDisease models
Six compartmental models, each specified directly or inferred from a disease name.
| Model | Compartments | Use case | Required extras |
|---|---|---|---|
| SIR | S → I → R | Standard acute (flu, COVID acute) | — |
| SEIR | S → E → I → R | Latent period (measles, SARS) | dur_exp |
| SIS | S → I → S | No lasting immunity (gonorrhea) | — |
| SIRS | S → I → R → S | Waning immunity (COVID endemic) | dur_immune |
| SEIRS | S → E → I → R → S | Latent + waning (COVID full) | dur_exp, dur_immune |
| SEIAR | S → E → I|A → R | Asymptomatic transmission (flu, COVID) | dur_exp, p_asymp, rel_trans_asymp |
Built-in disease defaults
Name a disease without full parameters and EpiChat fills these in.
| Disease | Model | dur_inf | dur_exp | n_contacts | p_death | Notes |
|---|---|---|---|---|---|---|
| Generic SIR | SIR | 10 d | — | 4 | 0.0 | R₀ = 2.5 |
| COVID (acute) | SIR | 8 d | — | 6 | 0.01 | |
| COVID (endemic) | SIRS | 8 d | — | 6 | 0.005 | immune = 180 d |
| COVID (full) | SEIRS | 8 d | 5 d | 6 | 0.005 | immune = 180 d |
| Influenza | SIR | 5 d | — | 6 | 0.001 | |
| Measles | SEIR | 8 d | 12 d | 10 | 0.001 | R₀ ≈ 15 |
| SARS-like | SEIR | 10 d | 5 d | 5 | 0.05 | |
| Ebola | SIR | 10 d | — | 3 | 0.5 | |
| Gonorrhea | SIS | 90 d | — | 2 | 0.0 | R₀ ≈ 2 |
Parameters
Every parameter is validated by a Pydantic schema before the template layer sees it.
| Parameter | Type | Default | Description |
|---|---|---|---|
| disease_type | string | sir | sir · seir · sis · sirs · seirs · seiar |
| n_agents | int | 10,000 | Population size · 10 → 1,000,000 |
| beta | float | computed | β = R₀ × 365 / (n_contacts × dur_inf) for random networks. For age-structured networks β is back-solved from the POLYMOD spectral radius so approx_R₀() matches the intended value. |
| init_prev | float | 0.01 | Seed fraction infected |
| dur_inf | float | 10.0 | Infectious period (days) |
| dur_exp | float? | null | Latent period · required for SEIR/SEIRS/SEIAR |
| dur_immune | float? | null | Immunity days before waning · SIRS/SEIRS |
| p_death | float | 0.0 | Infection fatality rate |
| p_asymp | float | 0.3 | Asymptomatic fraction · SEIAR only |
| sim_dur_years | float | 1.0 | Simulation horizon |
| network_type | string | random | random · age_structured |
| n_contacts | int | 4 | Avg daily contacts |
| network_beta | float | 1.0 | Transmission multiplier per contact |
Interventions
Up to three intervention types can combine in a single simulation.
Vaccine
Removes a fraction of agents from the susceptible pool. start_day=0 = pre-existing immunity; >0 = ongoing campaign starting that day.
Treatment
Reduces infectious duration or mortality for a fraction of infected agents. Optional daily capacity cap.
Seasonality
Modulates transmission rate sinusoidally over the year — scale is variation strength, shift is phase (0.0 = winter peak, 0.5 = summer peak).
NL query tips
EpiChat's parser understands a wide range of phrasing. A few useful patterns:
| You say | EpiChat does |
|---|---|
| "R0 = 2.5" | Converts to β via R₀ × 365 / (n_contacts × dur_inf) |
| "COVID", "flu", "measles" | Applies built-in disease defaults |
| "80% vaccinated" | Vaccine intervention, start_day=0 |
| "campaign starting month 3" | Vaccine intervention, start_day=90 |
| "winter peak" / "seasonal" | Seasonality · scale=0.3, shift=0.0 |
| "endemic" / "long-run" | Enables demographics |
| "age-structured" / "school-age" | network_type=age_structured |
| "masks" / "50% mask uptake" | network_beta ≈ 0.75 |
| "seed 42" / "reproducible" | rand_seed=42 |
| Query in French, Spanish, Arabic, Chinese… | Language auto-detected; narration and summaries respond in kind |
| Paste a WHO situation report or bulletin | Enricher extracts structured facts (cases, CFR, R₀, interventions) before simulation |
| "https://..." URL to an article | Page fetched client-side; facts extracted from full text |
| "Search for recent Mpox news in West Africa" | Built-in web search retrieves context before parameter extraction |
Disease parameter database
EpiChat ships a literature-backed JSON database (epichat/data/disease_parameters.json) covering 8 diseases. When a named disease is detected, the fact-checker compares R₀, infectious period, and incubation period against published ranges and shows a ⚠ warning if any value is out of range. The database is student-extensible: adding a disease requires only editing the JSON file — no Python changes needed.
| Disease | R₀ range | Incubation (days) | Infectious (days) | Source |
|---|---|---|---|---|
| Measles | 12–18 | 6–21 | 4–12 | PubMed 28757186 · PMC5930806 |
| Mumps | 10–12 | 14–25 | 7–25 | PMC557899 · PMC5930806 |
| Rubella | 2–5 | 13–24 | 7–21 | PMC8893344 · PMC5930806 |
| Varicella | 8–10 | 10–21 | 4–10 | PMC8954496 · PMC5930806 |
| Pertussis | 12–17 | 3–7 | 14–28 | PMC11679829 · PMC5930806 |
| Influenza (seasonal) | 1.2–1.4 | 1–4 | 1–10 | PMC4169819 · PMC5930806 |
| Meningococcal | 1.0–1.9 | 1–10 | 1–7 | ScienceDirect S1567134820301X · PMC5930806 |
| Hepatitis A | 2.1–2.8 | 20–125 | 14–28 | PMC6152969 · PMC5930806 |
The database is being expanded to cover COVID-19, Ebola, dengue, RSV, cholera, TB, polio, and Mpox (Phase 9 in the roadmap). Additional parameters per disease — IFR (p_death), contact rate (n_contacts), immunity duration (dur_immune) — will be added as literature data is collected.
Roadmap
Seven phases remaining, in priority order. Phases 4 (country demographics) and 7 (multilingual support) are complete as of v0.3. Complexity is implementation effort; impact is how much it moves the scientific needle.
| # | Phase | Data / Notes | Complexity | Impact |
|---|---|---|---|---|
| 1 | Disease parameter DB extension | More diseases (COVID, Ebola, dengue…) + more params per disease (p_death, n_contacts…) | Low (data) / Low–Med (Python) | High |
| 2 | Country contact matrices | Prem et al. 2021 (177 countries) · SOCRATES · CoMix | Medium | High |
| 3 | Age-specific severity | O'Driscoll 2021 · CDC COVID-NET · FluView | Medium | High |
| 4 | HouseholdNet | DHS · IPUMS · UN household data · ACS | High | Medium |
| 5 | Calibration vs surveillance | OWID · CDC Tracker · WHO FluNet · Tycho | High | Very High |
| 6 | STI networks | DHS sexual module · NATSAL · CDC NHBS | Very High | Medium |
| 7 | Geospatial metapopulation | WorldPop · OAG · OSM | Very High | High |
Risks · mitigations
| Risk | Mitigation |
|---|---|
| Invalid Starsim code | Template-based generation — no free-form LLM code |
| Parameter hallucination | Pydantic validation; literature-range fact-checking via disease_parameters.json; ⚠ warning shown in chat and CLI when values are outside known ranges |
| Wrong R₀ on age-structured network | β back-solved from POLYMOD spectral radius after demographics applied; recalibrated on every R₀ / dur_inf modification mid-conversation |
| Execution failure | 3-attempt recovery loop with LLM re-parameterization |
| Timeout | 90-second subprocess limit |
| API instability | Starsim version pinned in requirements.txt |