Getting new models into the modeling app¶

This document describes how new models can be added to the modeling app.

Note that when talking about adding a model to the modeling app, we are usually referring to adding a new model template (unconfigured model) that can then be used to create configured models (models that can be trained and used for predictions).

Currently, chap comes with some model templates and configured models that will be seeded on startup. These are defined in config/configured_models/default.yaml a long with a description of how new model templates and configured models can be added. Currently, in order to get a new model template available in the modeling app, someone with access to this configuration file on the server where chap is deployed will need to add the new model template there.

Note that configured models can also be created directly through the modeling app (if the model template already exists).

We are currently also working on a system for adding new model templates through the modeling app. Note that this functionality has not benn released yet, and is planned for a future release. The rest of this document describes how that system works.

System for adding model templates through the modeling app¶

This functionality is not released yet, but planned for a future release.

The backend of chap-core provides API endpoints to manage model templates. In order to not allow arbitrary model templates to be added, a whitelist system is used.

Whitelist System¶

How It Works¶

CHAP maintains a list of approved model templates via remote YAML whitelists. The backend:

Reads URLs from config/approved_model_repos.yaml
Fetches each URL and parses the YAML whitelist
Merges all results into a single approved list
Validates add requests against this merged list
Caches the whitelist for 5 minutes to reduce network calls

Whitelist Format¶

Remote whitelists use this format:

- url: https://github.com/dhis2-chap/chap_auto_ewars
  versions:
    stable: "@209759add6e13778f7061b8add8fbe814799a6cb"
    nightly: "@main"

- url: https://github.com/dhis2-chap/ewars_template
  versions:
    v3: "@e4520a2123a3228c10947f2b25029c3f7190e320"

Each entry has: - url: The base GitHub repository URL - versions: Named versions mapping to Git refs (commits or branches)

See the API documentation for endpoints under /api/v1/model-templates for details on how to list and add model templates using this system.

Adding a new model-template to the whitelist¶

In order to add a new model-template to our whitelist, you should make a pull-request to the model-repositories repository. Note that main.yaml is what is by default in the approved_model_repos.yaml file, so this is where one would usually add new model-templates if they are to be available to every deployment of chap-core.

It is also possible to add custom whitelist sources to your own deployment of chap-core, see the section below for deployers.

Specifically, follow these steps to add a new model to the approved list:

Fork the model-repositories repository

Edit main.yaml to add the new entry:

- url: https://github.com/your-org/your-model
  versions:
    latest: "@abc123def456"  # Use a specific commit hash for stability

Submit a pull request for review
Once merged, the model becomes available after the cache TTL (5 minutes) or backend restart

For Deployers¶

Custom Whitelist Sources¶

To add custom whitelist sources for your deployment:

Edit config/approved_model_repos.yaml:

- https://raw.githubusercontent.com/dhis2-chap/model-repositories/main/main.yaml
- https://raw.githubusercontent.com/my-org/my-models/main/approved.yaml

Restart the backend for changes to take effect

Security Considerations¶

Only add whitelist URLs from trusted sources
Prefer commit hashes over branch names for version pinning
Regularly audit the approved model list