Simulation integration blueprint

A safe, reviewable path from Python model to decision-ready scenario workspace.

This implementation brief defines the technical boundary for a Python-backed epidemic simulation. It is designed for approved research and public-health workflows, not autonomous clinical or emergency decision-making.

Review delivery sequence

Service boundary

Recommended execution architecture

Browser scenario workspace

A React interface collects validated scenario parameters, shows model status, and renders approved results. It never runs Python or stores sensitive source data.

Application API gateway

A server-side API validates requests, enforces authorization and quotas, creates an immutable job record, and submits work to an isolated simulation service.

Isolated Python simulation service

A containerized Python worker runs only versioned, allowlisted model packages and approved datasets. It has no public ingress and no direct access to browser sessions.

Job queue and result store

A queue decouples requests from execution. A short-lived result store holds structured outputs, provenance, and logs; the app polls or receives status updates through the API.

Governance and observability

Every run records model version, parameter set, dataset version, user identity, timestamps, resource use, and validation status for review and reproducibility.

Execution lifecycle

API contract and execution lifecycle

01
Create run
POST /api/simulations accepts a schema-validated scenario and returns a run ID, queued status, and estimated limits. The API rejects unknown fields and unsafe values.
02
Track run
GET /api/simulations/:runId returns queued, running, succeeded, failed, timed_out, or cancelled status with progress metadata that is safe to expose.
03
Read results
GET /api/simulations/:runId/results returns a compact, versioned JSON result only after completion. Large artifacts are referenced through short-lived, authorized download URLs.
04
Cancel run
POST /api/simulations/:runId/cancel requests cooperative cancellation. The worker checks cancellation between simulation batches and the platform enforces a hard timeout.

Controlled scenario design

Scenario inputs

Population and geography

Population size or approved population profile
Geographic unit or approved synthetic region
Age or risk strata when supported by the model
Initial exposed, infectious, and recovered counts or rates

Pathogen and transmission

Model family and approved model version
Basic or effective reproduction number range
Latent and infectious period assumptions
Importation rate and optional variant parameters

Interventions and behavior

Vaccination coverage and effectiveness assumptions
Contact reduction or mobility adjustment
Testing, isolation, and reporting-delay assumptions
Intervention start dates and duration

Run controls

Forecast horizon in days
Number of stochastic replicates
Random seed or reproducibility mode
Requested output resolution and aggregation level

Decision-ready results

Required outputs

Forecast trajectories

Time-series medians and uncertainty intervals for susceptible, exposed, infectious, recovered, cases, admissions, ICU demand, and deaths only when the approved model supports them.

Risk and threshold indicators

Probability of exceeding configured thresholds, peak timing, peak magnitude, growth rate, and scenario comparison deltas.

Spatial summaries

Aggregated risk values by approved geographic unit. No individual-level locations, raw mobility traces, or re-identifiable records are returned.

Sensitivity and provenance

Dominant parameter drivers, uncertainty summary, model version, dataset version, validation state, run timestamp, and a reproducibility identifier.

Export package

A human-readable briefing plus machine-readable JSON/CSV for authorized users, marked with assumptions, limitations, and non-operational-use guidance.

Accessible analysis

Visualization requirements

Scenario summary panel

Show the selected assumptions, model version, data version, run status, and clear warnings before results are interpreted.

Forecast chart

Render median trajectories with confidence or credible bands, threshold lines, and accessible tabular equivalents for every chart.

Scenario comparison

Allow side-by-side comparison of up to three approved scenarios with consistent scales and explicit assumption differences.

Risk map

Use aggregated choropleth or grid views with uncertainty overlays, a legend, date selector, and a non-map table alternative.

Sensitivity view

Show ranked drivers and uncertainty contribution without implying causal certainty beyond the model's validated scope.

Guardrails

Operational limits

Access

Restrict simulation creation to authenticated, role-authorized users. Public visitors may view explanatory content but cannot submit runs.

Request size

Accept only compact JSON inputs; reject file uploads and raw datasets in the first release. Approved datasets are selected server-side by identifier.

Runtime

Default to a 60-second interactive run limit, with a hard maximum of 5 minutes for authorized batch jobs. Terminate workers that exceed memory, CPU, or wall-clock limits.

Concurrency

Start with one active run per user and a small workspace-wide queue. Apply per-user and per-IP rate limits at the API gateway.

Scale

Cap interactive forecasts to 365 days, 100 geographic units, and 1,000 stochastic replicates until performance testing validates higher limits.

Retention

Keep completed results for 30 days by default, then delete or aggregate them according to the organization’s retention policy. Keep audit metadata separately under governed retention.

Defense in depth

Security and governance model

Isolation

Run Python in a minimal, non-root container with a read-only filesystem, no shell access, no package installation, strict CPU and memory quotas, and outbound network access disabled by default.

Model allowlisting

Deploy signed, versioned model artifacts only. Do not execute user-supplied Python, notebooks, pickles, serialized objects, or arbitrary model files.

Data minimization

Use aggregated, de-identified, approved datasets. Keep protected health information out of browser payloads, logs, exports, and model result objects.

Authorization

Enforce role-based access for run creation, dataset selection, result viewing, exports, and administrative model configuration. Scope every run to an organization or workspace.

Validation

Validate all inputs with strict schemas, numeric ranges, enum allowlists, and cross-field rules. Normalize units server-side and reject impossible or unsupported combinations.

Audit and monitoring

Record access, parameter changes, model and dataset versions, execution events, failures, and exports. Alert on repeated failures, quota abuse, and anomalous request patterns.

Human oversight

Label all outputs as decision support. Require qualified epidemiological review before operational use, and maintain documented validation, bias, and change-control processes.

Implementation plan

Delivery sequence

01
Model intake and validation
Receive the Python code, dependency lockfile, model documentation, test fixtures, expected inputs, expected outputs, and validation evidence.
02
Containerize and test
Package the model in an isolated service, add deterministic test runs, define resource profiles, and verify reproducibility against reference outputs.
03
Build the API boundary
Implement authenticated job endpoints, strict schemas, queue integration, status handling, audit events, and result retention controls.
04
Build the scenario workspace
Replace the disabled button with a role-gated form, status state, accessible charts, maps, comparison views, and export controls.
05
Pilot under governance
Run with synthetic or approved de-identified data, compare outputs with expert expectations, document limitations, and approve production release criteria.

This specification supports a research and public-health decision-support workflow. It does not establish clinical advice, emergency authority, regulatory clearance, or a substitute for qualified epidemiological review.