Model releases¶
CHART installs model artifacts, administrative geography, and model-area
mapping from versioned model-release*.json files below pipelines/models/.
Onboarding and its dropdowns do not maintain a separate country list.
What the manifest controls¶
| Section | Purpose |
|---|---|
schema_version |
Contract version. Existing embedded-geography releases are version 1; new shared-place-set releases use version 2. |
| Identity | Immutable release id, version, module, outcome, hazard, health domain, and source Git reference |
runtime |
Adapter and artifact type used to prepare the model |
input_contract |
Model-specific variables, units, shape, and ordering |
output_contract |
Effect measure, confidence level, and any derived-result policy |
presentation |
User-facing labels plus the dashboard visualization and figures used for this model |
model_files |
Artifact filenames and SHA-256 checksums |
geography / areas |
Version 1: embedded places and fitted mappings |
place_set / coverage |
Version 2: checksummed shared places plus fitted mappings owned by this release |
Administrative geography and model geography are deliberately separate.
Kenya declares 47 navigation and climate-extraction counties. The middle-layer
areas mapping connects 46 of them to five fitted climate-zone blocks.
Multiple counties can use the same block without the UI or inference code
knowing Kenya-specific rules. Turkana is declared in geography.places but
omitted from areas: it may be shown later as an unsupported catalog place,
but setup cannot select it because no North-western model exists.
flowchart LR
user["Administrative selection"] --> place["Manifest place"]
place --> boundary["Local climate boundary"]
place --> mapping["Model-area mapping"]
boundary --> input["Prepared model input"]
mapping --> runtime["Release runtime adapter"]
input --> runtime
Manifest field reference¶
Identity, runtime, and contracts¶
| Field | Meaning and rule |
|---|---|
schema_version |
Use 1 for existing embedded geography or 2 for a shared place set. |
id |
Globally unique immutable release identity. Changing content requires a new ID. |
version |
Model-team release version shown in provenance; it does not replace id. |
module |
CHART capability, currently prediction for these models. |
outcome |
Stable machine key such as lbw or under_5_mortality; never use display copy here. |
climate_hazard |
Stable hazard key such as extreme_heat. |
health_domain |
Stable health-domain taxonomy key. |
base_uri |
Versioned s3:// prefix containing the immutable artifacts. |
runtime.adapter |
Registered backend adapter, such as compact_r_registry. Unknown adapters fail preparation. |
runtime.artifact_type |
Artifact packaging type, such as rds; it is not inferred from UI labels. |
input_contract |
Variables, units, interval, order, and dimensions accepted by the scorer. |
output_contract |
Effect measure, confidence level, and derived-output rules. |
presentation |
Human-readable copy and UI rendering metadata. These values must not be used for model routing. |
release_notes |
Scientific and operational limitations for this exact release. |
source_git_ref |
Immutable model-team source revision used to build the artifact. |
Artifact fields¶
| Field | Meaning and rule |
|---|---|
model_files[].filename |
Basename below base_uri; paths and duplicate filenames are rejected. |
model_files[].sha256 |
Lowercase 64-character digest checked before activation and by inference. |
areas[].model_file |
Must exactly match one declared filename. |
Geography fields¶
New releases should use schema version 2. place_set pins the place-set ID,
version, repository path, and SHA-256. coverage maps supported place codes to
artifact blocks. The backend verifies the place-set file, shape file, hierarchy,
and coverage before setup can display or install the release. See
pipelines/places/README.md for the checked-in Kenya and MP place sets.
Version 1 remains supported for registered releases and carries the equivalent
information in geography and areas.
The top-level geography object declares:
country_codeandcountry_name;root_idandroot_path;analytics_slug, which identifies the analytical geography in the backend;boundary_artifact, when the release installs local polygons;- ordered
levels.keyis the stable application key,labelis the exact UI label, andsort_ordercontrols display order.
geography.levels[] is the single source of truth for administrative labels.
For example, India declares geo_level_1 as State, while Kenya declares the
same generic level key as County. Setup does not translate or guess these
labels.
Each geography.places[] entry declares the user-facing hierarchy:
place_code: stable analytical place code;display_nameand globally stablegeography_id;app_level, which must reference onegeography.levels[].key;level_label, which must exactly equal that level's canonical label;parent_place_code, or null for a top-level administrative area;pathandsort_orderfor navigation and dropdowns;boundary_key, matchingadmin_unit_codein the boundary GeoJSON.
Each areas[] entry then maps an eligible place_code to the exact
model_area_name expected inside model_file, plus any model-specific
validated options. Its country_code and administrative level must agree
with the corresponding place. model_area_name may be a different grain: for
example, Kajiado County maps to the South-eastern climate-zone block.
presentation.model_scope_label supplies the matching human-readable scope,
such as climate-zone model; it explains the mapping but never controls it.
presentation.visualization.kind selects a registered dashboard renderer.
The current releases use odds_ratio_icon_array; figure and
context_figure select manifest-approved pictograms. A new visualization kind
must be implemented and tested before that release is activated. Outcome names
must never be used in the browser to guess a chart or icon.
The schema rejects duplicate level keys or labels, duplicate place codes, geography IDs, paths or boundary keys, unknown levels or parents, parent cycles, country/level mismatches, and place labels that disagree with the canonical level declaration.
What onboarding includes¶
Setup derives its choices from all installed manifests using these rules:
- A country appears only when at least one enabled release has a
geographysection and at least one fittedareasmapping. - A place is selectable only when its
place_codeappears inareasfor at least one installed model release in that country. - An unsupported ancestor may be retained only as a hierarchy grouping needed to reach supported children; it cannot be submitted as the final choice.
- Labels and level order come from
geography.levels, not from hard-coded country logic in the browser. - Each selectable place includes
modelMappingsderived from installed releases: release, outcome, exactmodel_area_name, and model-scope label. Onboarding shows this beside the administrative choice so operators can verify, for example,Kajiado County → South-eastern (climate-zone model). - The backend repeats the same checks when setup is submitted, so a caller cannot bypass the dropdown and install an unsupported place.
Consequently, the current India setup shows Madhya Pradesh—not every Indian state—and its ten supported divisions. Kenya setup shows 46 supported counties. Turkana remains a known navigation geography but is not an installation choice until an approved North-western mapping is supplied.
The backend returns canonical levels, filtered places, a
predictionSupported flag, and manifest-derived modelMappings through
GET /setup/options. The browser builds Country → parent → child controls from
that response. Setup rejects a geography payload that differs from the
installed manifest or has no model mapping.
Launching the installation registers, verifies, and starts every enabled
release discovered under pipelines/models/, not only releases for the
administrator's selected country. Setup fails as one transaction if any
installed artifact is missing or invalid. A failed first-run attempt can be
retried with corrected wizard details; it does not require an authenticated
installation reset.
Changing the current working area is not an installation reset. Administrators may switch among model-backed areas within their assigned installation country; other users remain inside their explicitly assigned geography. Planning and Dashboard list outcomes available at the selected place or below it. For example, an MP state workspace lists both LBW and under-five mortality. LBW may run at state or division level; under-five mortality automatically requires a supported division because the release has no fitted state block.
Add or update a model¶
- Put the model implementation under
pipelines/models/<family>/. - Upload the immutable artifact under a new versioned
base_uriand calculate its SHA-256. - Add a new
model-release*.json. Use the Kenya and MP review manifests as complete examples. - Add or reference a boundary artifact whose
admin_unit_codevalues match the manifestboundary_keyvalues. - Implement a runtime adapter if the declared adapter does not already exist.
- Validate the manifest and artifact.
- Run backend, onboarding, inference-parity, and web-build checks.
Discovery is recursive below pipelines/models/. Review releases appear only
when the generic CHART_ENABLE_REVIEW_MODELS gate is enabled.
Runtime adapters¶
Setup dispatches artifact preparation through runtime.adapter. The current
compact R models use compact_r_registry. A future outcome can use a different
adapter and input contract without adding outcome-specific branches to
onboarding or geography loading.
An unsupported adapter fails preparation explicitly; CHART does not activate a release it cannot verify and load.
Where the artifact lives at runtime¶
The manifest's base_uri is metadata — the app never fetches from S3
directly. The runtime opens the file from disk under MODEL_CACHE_DIR
(default /models in containers, pipelines/models/ in local dev) and
verifies the SHA256 before POSTing the local path to the R scorer's
/models/load. Two failure modes:
MODEL_RELEASE_FILE_MISSING— no file with the manifest'sfilenameexists anywhere underMODEL_CACHE_DIR. Populate the cache directory.MODEL_RELEASE_CHECKSUM_MISMATCH— a file with the right name exists but its SHA256 doesn't match. The wrong file was uploaded, or the manifest's hash is stale.
On AWS the chart-model-sync container copies the whole model bucket
(except archive/) into the shared chart-lbw-model Docker volume before
the R container starts, with a single aws s3 sync. Locally, the .rds
files live under pipelines/models/ and the same discovery logic finds
them via rglob(filename). See
From R output to the dashboard
for how the sync runs, and
AWS sandbox → Model artifacts on S3
for the bucket layout, versioning policy, and how to add a new release.
Updating an existing deployment¶
Never edit the identity or model mapping of a registered release. Publish a new release ID and version, update artifact checksums, and activate that release. Historical predictions retain their original release ID and input hash.
Required checks¶
- Every selectable place has at least one model mapping and a complete, acyclic parent chain.
- Every place label exactly matches its declared canonical level label.
- Every boundary key resolves to exactly one polygon.
- Every artifact matches its SHA-256.
- Every area maps to a real model block.
- The runtime returns the requested release, version, file, and checksum.
- Existing model parity tests still pass.
- Role and geography authorization is enforced for prediction requests.
See Add a geography and model for boundary and mapping details, and Modeling for interpretation constraints.