Model Plan Guide

PruningConfig takes min_epochs (integer at least 1), k (integer at least 1), min_delta (number at least 0), and patience (positive integer). It compares the trial with the best k previous trials after min_epochs, using the improvement threshold and patience to decide when to stop it. Trial pruning differs from early stopping, which monitors one trial’s own validation progress.

The following example uses the SalesOrderHeader.CustomerID relationship to Customer.CustomerID in Create a Graph:

from kumoapi.model_plan import HopConfig, NumNeighborsConfig
hop1 = HopConfig(default=20)
hop1["Customer.CustomerID->SalesOrderHeader.CustomerID"] = 40
hop1["SalesOrderHeader.CustomerID->Customer.CustomerID"] = 1
plan.neighbor_sampling.num_neighbors = [
    NumNeighborsConfig(hop1=hop1, hop2=HopConfig(default=10)),
]
plan.neighbor_sampling.adaptive_sampling = False

Use graph table names, including aliases, and the actual primary-key and foreign-key columns. The two directions have separate overrides. Unlisted relationships use that hop’s default; at hop2, both directions above use 10. Each default accepts integers from -1 to 128; a named edge accepts integers from -1 to 512. 0 samples none and -1 requests all neighbors, which can exhaust memory on a large relationship. Define consecutive hops beginning with hop1, up to six hops. An unknown relationship or a gap in hop numbers is invalid; correct the graph names or configuration before fitting.

Some suggested plans use "inferred" for a target-to-entity connection in hop1. This is a task-specific fanout estimated from the data, not a general substitute for an integer on any edge. It is invalid on other connections or later hops. Use explicit integer overrides when setting your own edge counts.

To compensate for sparse earlier hops, set plan.neighbor_sampling.adaptive_sampling = True. Later hops can then sample more neighbors than their nominal count. All counts must be nonnegative: -1 is incompatible with adaptive sampling. Inspect memory use and runtime before increasing the graph context; enabling adaptation does not guarantee better validation quality.

EarlyStoppingConfig(min_delta=0.0, patience=3) requires a nonnegative improvement threshold and positive integer patience. LRSchedulerConfig takes name, interval ("step" or "epoch"), and an optional kwargs dictionary for that scheduler. Supported warmup schedule names include "constant_with_warmup", "linear_with_warmup", "cosine_with_warmup", and "cosine_with_warmup_restarts". Additional scheduler names and arguments must resolve in the installed training runtime.

For a bounded learning-rate search:

from kumoapi.model_plan import EarlyStoppingConfig
plan.training_job.num_experiments = 2
plan.training_job.manual_seed = 42
plan.optimization.base_lr = [0.001, 0.003]
plan.optimization.batch_size = [256]
plan.optimization.early_stopping = [
    EarlyStoppingConfig(min_delta=0.0, patience=3),
]

A fixed seed helps repeat a run with the same data, plan, package versions, and execution environment. It does not guarantee identical scores across devices, library versions, or parallel execution. Retain plan.as_json() and the data snapshot identity with your results. The search selects a model; it does not ensemble its trials.

Start with the scalar weighted custom training table. Reuse its custom_query, custom_snapshot, custom_training_table, and spec. Pass the same specification when suggesting the plan so Kumo knows the table contains weights:

plan = custom_query.suggest_model_plan(
    custom_snapshot, run_mode=RunMode.FAST, train_table_spec=spec
)
plan.optimization.weight_mode = ["weighted_loss"]
plan.optimization.majority_sampling_ratio = [None]

Choose one mode before creating Trainer(plan) and calling fit(custom_training_table, snapshot=custom_snapshot):

Use finite, nonnegative scalar weights, with positive weight remaining in the training population. A zero weight removes that row’s training contribution in weighted loss or its sampling probability in weighted sampling. This scalar example does not define weights for list targets or forecast sequences. Weighted link prediction permits "weighted_loss" or None, not "sample"; forecasting does not support these training weight modes.

For binary classification, optionally add a class-balancing ratio:

plan.optimization.weight_mode = ["sample"]
plan.optimization.majority_sampling_ratio = [1.0]

The ratio is the desired majority-to-minority balance. 1.0 requests equal class influence when the original classes are imbalanced. Kumo increases the minority class weight only when the observed imbalance exceeds the requested ratio. When row weights are also present, Kumo multiplies their effect by the class weights, so arbitrary row weights can change the final class balance. With "sample", these weights affect row selection; with "weighted_loss", they affect the loss. Neither mode promises an exact class count in each batch. A numeric ratio requires every weight_mode candidate to be non-None. To ignore weights, set both weight_mode=[None] and majority_sampling_ratio=[None].

Fit using the bounded procedure under Training, then compare validation metrics and class-specific behavior before retaining a configuration. Different sampling frequencies or a lower training loss do not by themselves establish better prediction quality.

For custom loss parameters, import the corresponding configuration from kumoapi.model_plan:

For a regression query, plan.optimization.loss = [HuberLossConfig(name="huber", delta=2.0)] selects a Huber loss with a custom threshold.

Historical inputs are created by TrainingTableGenerationPlan, separately from the model plan. Generated forecasts require a positive integer lag_timesteps; leaving it unspecified uses one previous target window, while 0 is rejected. year_over_year=True requests the corresponding previous-year sequence. The encoder is activated only when those values are present in the materialized table. Changing past_encoder after generation does not change the table’s lag windows or create missing historical values. Follow Generate Forecast Inputs to generate the intended horizon and historical inputs before fitting.

For a forecasting table with positive lag windows, select a historical encoder before fitting:

plan.model_architecture.past_encoder = ["decomposed"]
plan.model_architecture.handle_new_entities = True

"decomposed" is the suggested historical encoder. "normalized", "mlp", and "transformer" are alternative candidates. handle_new_entities=True uses a shared head. False adds learned parameters for individual training entities; it does not merely replace the shared head. Keep it True when you need forecasts for new entities, subject to the graph and feature requirements of your model. These settings apply to forecasting, not ordinary temporal regression.

To disable only the historical target encoder, set this before creating the trainer and fitting:

plan.model_architecture.past_encoder = [None]

Keep the generated training table’s positive lag setting unchanged. The forecasting head still receives the raw lag values; disabling their encoder does not remove historical inputs or stop generation of the lag columns. It also does not disable the separate year-over-year encoder when the table contains those inputs. This choice is distinct from lag_timesteps=0, which is rejected when constructing generated or supplied forecast training tables.

After fitting or loading the model, reuse trainer.training_table_generation_plan when generating prediction rows so the horizon, lags, year-over-year inputs, and step size match training. See Select the Prediction Population and the forecast output example. The default output has ENTITY, TIMESTAMP, and TARGET_PRED; select optional ANCHOR_TIMESTAMP explicitly when you need the common forecast anchor.