Configuration | Umnai | Documentation

A training configuration defines how a model is trained from a dataset.

Most projects can start with the built-in induction settings. Adjust the configuration when you need more control over sampling, model structure, training behaviour, regularisation, or resource use.

Create a configuration

Create a training configuration before starting a training job.

POST

/training-configurations

1 curl -X POST https://api.hi.umnai.com/training-configurations \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "model_training_type": "INDUCTION",
6   "name": "Sample Training Configuration"
7 }'

Response

1 {
2   "model_training_type": "INDUCTION",
3   "account": {
4     "id": "e268443e43d93dab7ebef303bbe9642f",
5     "name": "Sample Account"
6   },
7   "created_at": "2026-03-15T10:15:30.000000Z",
8   "id": "236f09a5d73018a9b8324105f1ee82df",
9   "name": "Sample Training Configuration",
10   "alpha": 0.5,
11   "alpha_factor": 0.5,
12   "bin_min_distance": 0.5,
13   "binning_strategy": "UNIFORM",
14   "bins": 1,
15   "boosting_strategy": "NO_GROUPING",
16   "created_by": {
17     "id": "dad46b2058752ffde5eaf02f1eb6abd5",
18     "name": "Sample User"
19   },
20   "early_stopping_patience": 1,
21   "estimators": 1,
22   "estimators_winsorize_level": 0.5,
23   "exclude_implicit": true,
24   "init_depth": 1,
25   "l1_ratio": 0.5,
26   "l1_ratio_delta": 0.5,
27   "learning_rate": 0.5,
28   "learning_rate_decay": 0.5,
29   "learning_rate_patience": 1,
30   "log_interval": 1,
31   "max_depth": 1,
32   "max_depth_momentum": 1,
33   "max_interaction_degree": 1,
34   "max_interactions": 1,
35   "max_iterations": 1,
36   "max_polynomial_degree": 1,
37   "max_rounds": 1,
38   "max_samples": 0.5,
39   "model_capabilities": {
40     "has_causal": false,
41     "estimators_data": false
42   },
43   "model_complexity_max_iterations": 1,
44   "model_complexity_patience": 1,
45   "partition_min_delta": 0.5,
46   "partition_min_delta_factor": 0.5,
47   "partition_min_delta_fraction": 0.5,
48   "partition_min_samples": 1,
49   "prune_patience": 1,
50   "prune_threshold": 0.5,
51   "sparse_model": true,
52   "subsample": 0.5,
53   "training_size": 0.5,
54   "updated_at": "2026-03-15T10:15:30.000000Z",
55   "validation_size": 0.5
56 }

Save the returned configuration id. Training jobs use this value when creating a model.

Training type

Training configurations are created with a model_training_type.

Type	Description
`INDUCTION`	Trains a model from a prepared dataset. This is the supported path for training a model from data.
`UPDATE_MODEL`	Exposed in the API, but not currently supported for general use.

UPDATE_MODEL is exposed in the API, but it is not currently supported. Do not use it unless you have confirmed that your workflow supports model updates.

Induction parameters

Induction exposes detailed parameters for controlling how the model is trained. You usually do not need to set them all. Use them when you need to make a deliberate change to model size, training duration, resource usage, or generalisation behaviour.

Exact defaults, allowed values, and validation constraints are available in the API reference.

Data sampling

Sampling controls how much of the dataset induction uses and how that data is split between training and validation. These settings are useful when you want to train on a subset of the data, change the validation split, or reduce memory pressure during boosting.

Parameter	Description
`max_samples`	Fraction of the dataset used for training and validation.
`training_size`	Proportion of sampled data reserved for training.
`validation_size`	Proportion of sampled data reserved for validation.
`subsample`	Fraction or number of training shards used for fitting XNN modules during boosting iterations.

Model structure

Model structure parameters control how features can be combined and how complex the induced model can become. These settings are useful when you need to control the size, depth, or interaction complexity of the model.

Parameter	Description
`max_interaction_degree`	Maximum number of features that can be combined in a single interaction module.
`max_interactions`	Maximum number of interaction modules for each interaction degree.
`init_depth`	Initial partition depth used by the XNN regressor.
`max_depth`	Maximum depth of any partition.
`max_depth_momentum`	Increment by which `max_depth` is increased during training.
`max_polynomial_degree`	Highest degree of a feature in polynomial expansions.

Model constraints

Model constraint parameters control how training uses explicitly defined constraints.

Parameter	Description
`exclude_implicit`	Excludes modules that are not part of the model constraints.

If exclude_implicit is enabled, do not also set max_interactions. Use constraints to define the allowed modules.

For more detail, see Constraints.

Training loop

Training loop parameters control how long induction runs, how model complexity increases, and when training stops. These settings are useful when training is stopping too early, running too long, or increasing complexity too aggressively.

Parameter	Description
`max_rounds`	Maximum number of training rounds unless early stopping occurs.
`max_iterations`	Maximum number of iterations for each estimator.
`early_stopping_patience`	Number of iterations with no significant improvement before early stopping.
`model_complexity_max_iterations`	Maximum consecutive training iterations with the same model complexity.
`model_complexity_patience`	Number of iterations allowed without improvement after increasing model complexity.
`boosting_strategy`	Module boosting strategy applied between iterations.

Regularisation

Regularisation parameters help control overfitting and the balance between L1 and L2 regularisation.

Parameter	Description
`alpha`	Elastic net alpha value.
`alpha_factor`	Grid-search factor around `alpha`, using log-spaced values.
`l1_ratio`	Elastic net L1 ratio value.
`l1_ratio_delta`	Grid-search range around `l1_ratio`.

Learning rate

Learning-rate parameters control how quickly the model updates during training and how that rate changes when progress stalls.

Parameter	Description
`learning_rate`	Initial learning rate for training the XNN model.
`learning_rate_decay`	Multiplier for decaying the learning rate when loss does not improve.
`learning_rate_patience`	Number of iterations allowed without improvement before learning-rate decay.

Binning

Binning parameters control how feature values are segmented before they are used in symbolic conditions.

Parameter	Description
`bins`	Maximum number of bins per feature.
`binning_strategy`	Strategy used to create bins for the XNN regressor.
`bin_min_distance`	Minimum distance between split points, used by the XNN regressor.

Partitions

Partition parameters control when and how partitions are created inside modules. These settings are useful when partitions are becoming too granular, too shallow, or insufficiently stable.

Parameter	Description
`partition_min_samples`	Minimum number of training samples in one XNN partition.
`partition_min_delta`	Minimum absolute improvement in the loss function required for a partition split.
`partition_min_delta_fraction`	Minimum fractional improvement in the loss function required for a partition split.
`partition_min_delta_factor`	Multiplier applied to `partition_min_delta_fraction` per module depth.

Prefer partition_min_delta_fraction over partition_min_delta unless you know the absolute loss improvement that should be required.

Estimators

Estimator parameters control ensemble-style training and how estimator outputs are aggregated.

Parameter	Description
`estimators`	Number of estimators to train.
`estimators_winsorize_level`	Proportion of data to winsorize at each tail when aggregating estimator outputs.

Using multiple estimators can increase runtime, resource usage, and storage requirements.

Sparse models

Sparse-model parameters control whether low-impact modules can be removed during training. These settings are useful when you want a smaller model or need to reduce low-impact modules.

Parameter	Description
`sparse_model`	Allows induction to create a sparse model.
`prune_threshold`	Threshold below which coefficients from ElasticNet are pruned.
`prune_patience`	Number of boosting rounds where a module can remain under `prune_threshold` before removal.

Model capabilities

model_capabilities exposes additional model capability flags.

Parameter	Description
`model_capabilities.estimators_data`	Whether the model has estimator capabilities.
`model_capabilities.has_causal`	Whether the model has causal capabilities.

model_capabilities.estimators_data and model_capabilities.has_causal are exposed in the API. Use them only when the workflow you are using supports them.

Logging

Logging parameters control how often training progress is reported.

Parameter	Description
`log_interval`	Frequency of logging during training.

Retrieve configurations

Retrieve training configurations when you need to reuse an existing configuration.

GET

/training-configurations

1 curl https://api.hi.umnai.com/training-configurations \
2      -H "Authorization: Bearer <token>"

Response

1 {
2   "data": [
3     {
4       "id": "ea8b745ead39ec442fc3b4fba359bf98",
5       "name": "Sample Organisation",
6       "status": "ACTIVE",
7       "created_at": "2026-03-11T16:04:19.749000Z",
8       "updated_at": null
9     }
10   ],
11   "pagination": {
12     "total_items": 1,
13     "items_per_page": 10,
14     "current_page": 1,
15     "total_pages": 1
16   }
17 }

You can filter the list by model_training_type.

To inspect a specific configuration, retrieve it by id.

GET

/training-configurations/:trainingConfigurationId

1 curl https://api.hi.umnai.com/training-configurations/{trainingConfigurationId} \
2      -H "Authorization: Bearer <token>"

Response

1 {
2   "data": [
3     {
4       "id": "ea8b745ead39ec442fc3b4fba359bf98",
5       "name": "Sample Organisation",
6       "status": "ACTIVE",
7       "created_at": "2026-03-11T16:04:19.749000Z",
8       "updated_at": null
9     }
10   ],
11   "pagination": {
12     "total_items": 1,
13     "items_per_page": 10,
14     "current_page": 1,
15     "total_pages": 1
16   }
17 }

Update a configuration

Update a training configuration when you need to rename it.

PATCH

/training-configurations/:trainingConfigurationId

1 curl -X PATCH https://api.hi.umnai.com/training-configurations/trainingConfigurationId \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "name": "Sample Training Configuration"
6 }'

Response

1 {
2   "model_training_type": "INDUCTION",
3   "account": {
4     "id": "e268443e43d93dab7ebef303bbe9642f",
5     "name": "Sample Account"
6   },
7   "created_at": "2026-03-15T10:15:30.000000Z",
8   "id": "236f09a5d73018a9b8324105f1ee82df",
9   "name": "Sample Training Configuration",
10   "alpha": 0.5,
11   "alpha_factor": 0.5,
12   "bin_min_distance": 0.5,
13   "binning_strategy": "UNIFORM",
14   "bins": 1,
15   "boosting_strategy": "NO_GROUPING",
16   "created_by": {
17     "id": "dad46b2058752ffde5eaf02f1eb6abd5",
18     "name": "Sample User"
19   },
20   "early_stopping_patience": 1,
21   "estimators": 1,
22   "estimators_winsorize_level": 0.5,
23   "exclude_implicit": true,
24   "init_depth": 1,
25   "l1_ratio": 0.5,
26   "l1_ratio_delta": 0.5,
27   "learning_rate": 0.5,
28   "learning_rate_decay": 0.5,
29   "learning_rate_patience": 1,
30   "log_interval": 1,
31   "max_depth": 1,
32   "max_depth_momentum": 1,
33   "max_interaction_degree": 1,
34   "max_interactions": 1,
35   "max_iterations": 1,
36   "max_polynomial_degree": 1,
37   "max_rounds": 1,
38   "max_samples": 0.5,
39   "model_capabilities": {
40     "has_causal": false,
41     "estimators_data": false
42   },
43   "model_complexity_max_iterations": 1,
44   "model_complexity_patience": 1,
45   "partition_min_delta": 0.5,
46   "partition_min_delta_factor": 0.5,
47   "partition_min_delta_fraction": 0.5,
48   "partition_min_samples": 1,
49   "prune_patience": 1,
50   "prune_threshold": 0.5,
51   "sparse_model": true,
52   "subsample": 0.5,
53   "training_size": 0.5,
54   "updated_at": "2026-03-15T10:15:30.000000Z",
55   "validation_size": 0.5
56 }

Delete a configuration

Delete a training configuration when it should no longer be used by future training jobs.

DELETE

/training-configurations/:trainingConfigurationId

1 curl -X DELETE https://api.hi.umnai.com/training-configurations/trainingConfigurationId \
2      -H "Authorization: Bearer <token>"