Loading Overrides

When you call load_from_foundation_model or load_from_checkpoint, you can override several settings that were configured during training. This lets you adjust data loading, split strategy, and prediction scope without retraining.

Checkpoint Contents

Both foundation model and scenario model training write a checkpoint directory. Understanding what's inside helps when debugging or moving checkpoints between environments.

checkpoint_dir/
├── best_model.ckpt              # Best weights (selected by validation metric)
├── data.yaml                    # Data source configuration snapshot
├── dataloader.yaml              # Data loader configuration
├── task.yaml                    # Task name and parameters
├── target_fn.bin                # Serialized target function (scenario models only)
└── lightning_checkpoints/       # Epoch-by-epoch checkpoints (PyTorch Lightning)

best_model.ckpt is automatically selected from lightning_checkpoints/ based on the monitored validation metric. Each task type has a default:

Task	Default metric	Direction
Binary classification	`val_auroc_0`	Maximize
Multiclass classification	`val_multiple_targets_recall`	Maximize
Multilabel classification	`val_auroc_0`	Maximize
Regression	`val_loss`	Minimize
Recommendation	`val_HR@10_0`	Maximize

Override with metric_to_monitor and metric_monitoring_mode in TrainingParams.

What you can override

Beyond the three required arguments (checkpoint_path, downstream_task, target_fn), load_from_foundation_model accepts optional overrides that let you reuse a foundation model head, filter predictions, change the split strategy, or adjust data loading — all without retraining.

For the full parameter list and types, see the load_from_foundation_model() reference. The sections below explain when and why to use each override.

Foundation Model Head

Setting with_head=True loads the foundation model's final prediction layer. This can improve recommendation quality when the foundation model was trained on similar item interactions.

Python

from monad.ui.module import load_from_foundation_model, RecommendationTask

trainer = load_from_foundation_model(
    checkpoint_path="./foundation_model",
    downstream_task=RecommendationTask(),
    target_fn=reco_target,
    with_head=True,
)

Prediction Filtering

Narrow or exclude items from recommendation predictions on a per-entity basis:

Python

# Exclude items the entity has already interacted with
trainer = load_from_foundation_model(
    checkpoint_path="./foundation_model",
    downstream_task=RecommendationTask(),
    target_fn=reco_target,
    predictions_to_exclude_fn=lambda events, attrs, ctx: (
        list(events["transactions"]["product_id"].events)
    ),
)

Python

# Include only items from a specific category
ELECTRONICS_IDS = [...]

trainer = load_from_foundation_model(
    checkpoint_path="./foundation_model",
    downstream_task=RecommendationTask(),
    target_fn=reco_target,
    predictions_to_include_fn=lambda events, attrs, ctx: ELECTRONICS_IDS,
)

Split Override

Override the train/validation/test split strategy defined during foundation model training:

Python

from monad.ui.module import TimeSplitOverride

trainer = load_from_foundation_model(
    checkpoint_path="./foundation_model",
    downstream_task=BinaryClassificationTask(),
    target_fn=my_target_fn,
    split=TimeSplitOverride(...),
)

EntitySplitOverride is also available for entity-based splits.

Data Parameters Override

Override individual data-loading settings — extra columns, date boundaries, sampling, or split-point count — by passing them as keyword arguments directly to load_from_foundation_model. Any keyword that matches a DataParams field is applied; everything else is silently ignored.

Python

trainer = load_from_foundation_model(
    checkpoint_path="./foundation_model",
    downstream_task=BinaryClassificationTask(),
    target_fn=my_target_fn,
    extra_columns=[
        {"data_source_name": "transactions", "columns": ["order_id", "unit_price"]}
    ],
)

Pass extra column overrides to verify_target()

If your target function uses extra columns, you must also pass matching data_params_overrides when validating with verify_target().

Sampling strategy

Scenario models default to random for classification and regression tasks, and to valid for recommendation tasks. Three strategies are available:

Strategy	Supported tasks	Behavior
`random`	Classification, Regression	Default for classification and regression.
`valid`	All tasks	Default and required for recommendation.
`existing`	All tasks	Uses event timestamps as split points. Useful for same-basket prediction.

Python

trainer = load_from_foundation_model(
    ...,
    target_sampling_strategy="valid",
)

Split-point behavior

Control how events at the exact split timestamp are assigned and how much history the model sees. These settings matter most for recommendation and next-basket scenarios.

Python

trainer = load_from_foundation_model(
    ...,
    history_future_split_overrides={
        "entity_history_limit": {"transactions": 2592000},  # 30 days in seconds
        "max_data_splits_per_split_point": 200,
        "split_point_inclusion_overrides": {"transactions": "future"},
    },
)

When to use these:

Simulating limited retention — set entity_history_limit (in seconds, per source) when your production environment only has access to recent events. For example, 2592000 limits history to the last 30 days.
Next-basket recommendations — set split_point_inclusion_overrides to future for your transaction source. This places same-timestamp events into the future window, so the model learns to predict the full basket. For "given these cart items, suggest another" scenarios, use one-future (one item goes to future, rest stay in history) or one-future-all-variants (generates multiple training examples per basket).
Contextual recommendations — increase max_data_splits_per_split_point to generate more examples per split point, giving the model more context-item combinations to learn from.