# External model specification

An external model can be provided to CHAP in two ways: 

- By specifying a path to a local code base
- or by specifying a github URL to a git repo. The url needs to start with https://github.com/

In either case, the directory or repo should be a valid MLproject directory, with an `MLproject` file. Se the specification in the [MLflow documentation](https://www.mlflow.org/docs/latest/projects.html#project-format) for details. In addition, we require the following:

- An entry point in the MLproject file called `train` with parameters `train_data` and `model`
- An entry point in the MLproject file called `predict` with parameters `historic_data`, `future_data`, `model` and `out_file`

These should contain commands that can be run to train a model and predict the future using that model. The model parameter should be used to save a model in the train step that can be read and used in the predict step. CHAP will provide all the data (the other parameters) when running a model.

[Here is an example of a valid directory with an MLproject file](https://github.com/dhis2/chap-core/tree/dev/external_models/naive_python_model_with_mlproject_file).

The following shows how you can run models that follow the specification above. If you have your own model that you want to make compatible with CHAP, follow [this guide](./developing_custom_models).

The MLproject file can specify a docker image or Python virtual environment that will be used when running the commands.


## Defining an environment for the model

If needed, CHAP currently supports specifying a docker image or a python environment file that will be used when running your model.

For models that are to be run in a production environment, this is necessary for handling dependencies.

We implement the MLProject standard, as described in the [MLflow documentation](https://www.mlflow.org/docs/latest/projects.html#project-format) (except for conda support). 

Specifying a Python environment requires that you have pyenv installed and available.