Presets¶

Named one-line factories that return a fully-formed Ml4Config with a strategy pre-set (the training policy with its fold and stack budget, the roster, and the FE toggles). See the configuration guide for the catalogue.

In short

Each preset is a zero-argument factory such as presets.quick_explore(); PRESETS maps every name to its factory.
A preset sets the strategy only; you still set data (the target and column roles).
Every preset except regulated_glassbox and regulated_scorecard sets a model-selection budget in engine.time_limit.
with_foundation_challenger and audit_friendly_fe transform an existing config.

presets ¶

Named configuration presets: one-line factories for the common ml4 scenarios.

Each factory returns a fully-formed :class:~parleml_ml4.config.Ml4Config with the strategy set (the training policy with its fold and stack budget, the roster, and the feature-engineering toggles) — the caller still supplies the dataset-specific data (target + column roles). Rather than sizing each algorithm by hand, a preset sets the validation / stacking shape with those few engine levers and only flips the roster / FE levers it means to change, so the stripped diff of a preset (see :func:~parleml_ml4.config.strip_config_defaults) is exactly its intent.

Depth is bought with ml4's own levers: how many models a run trains is roster.models, whether they are searched is hpo, how wide the feature space grows is the FE / feature-selection budget, and how the run fits is its fit shape (:func:~parleml_ml4.config.fit_shape.resolve_fit_shape). No AutoGluon preset is named in the fit.

Every preset but the two regulated glass-box ones also carries a model-selection time budget (engine.time_limit, :data:_TIME_BUDGET_S), stated in its user-facing description.

.. warning:: roster.models defaults explicitly to a single LightGBM (:data:~parleml_ml4.config.roster.DEFAULT_MODELS), not an AutoGluon portfolio. Every preset therefore exposes the roster it really trains in the template editor, and presets that want breadth must name the additional models themselves.

The public :data:PRESETS registry (name → zero-arg factory) and :data:PRESET_DOCS (user-facing copy for the wizard's template grid) are plain registries so the backend can consume them without importing AutoGluon. Presets that ml4's tabular roster cannot express (a foundation-only strongest model — the foundation model is a challenger by design, §6.5) and the recommendation tiers (a separate backend, parleml_ml4.config.recommendation) are intentionally out of scope here.

PresetDoc ¶

PresetDoc(summary: str, description: str)

User-facing copy for a built-in preset — the wizard's template grid (summary) and the template editor modal (summary + description). Kept decoupled from the factory docstrings so engineering language never leaks into the product UI.

RecommendedValidation `dataclass` ¶

RecommendedValidation(needs_complete_oof: bool = False)

What a preset's fit implies for the launch wizard's validation-strategy step.

A preset fixes the training policy, but never the split strategy (random / grouped / temporal), which depends on dataset columns and stays the user's choice. Every row is read off the preset's fit shape — see :data:PRESET_VALIDATION.

needs_complete_oof — the preset's fit trains a stacking layer, which learns from complete out-of-fold predictions. A temporal split cannot supply them: it pairs only with the chronological train/validation policy, which fits one validation slice and no bagged ensemble, so the wizard warns on that combination.

default ¶

default() -> Ml4Config

The out-of-the-box :class:Ml4Config — five-fold cross-validated bagging over a single LightGBM with the standard feature-engineering pipeline. The ROI-optimal starting point.

quick_explore ¶

quick_explore() -> Ml4Config

Trimmed budget for a fast first pass on a new dataset (data-wiring validation).

high_accuracy ¶

high_accuracy() -> Ml4Config

Chase the best score: the widest feature space and the diverse roster, bagged.

Wall-clock cost is deliberately not a constraint here, so this preset spends on both axes ml4 has — features and models. It adds the CV cat×num crosses, runs the tree-guided interaction feedback round, lets feature selection run its full round budget, and trains the same structurally-diverse roster as :func:diverse_ensemble so AutoGluon's greedy ensemble has decorrelated votes to blend.

The roster has to be named. The default roster.models is not "AutoGluon's portfolio" — ml4 always supplies its own recipe-carrying models, so it explicitly names :data:~parleml_ml4.config.roster.DEFAULT_MODELS, a single LightGBM. Inheriting that narrow default would make the accuracy preset the narrowest non-fast roster in the catalogue — max features on one booster, reliably beaten by diverse_ensemble's six.

It also serves the bagged ensemble rather than a single model refit on all the data: the k-fold ensemble usually scores better, while refit_full is a size-and-latency optimisation that costs a little accuracy. Here the artifact is allowed to be big and slow.

diverse_ensemble ¶

diverse_ensemble() -> Ml4Config

Breadth over depth: a structurally diverse roster, greedy-ensembled.

Roster breadth at the default feature cost — the cheaper half of :func:high_accuracy, which trains this same roster on top of the widest feature space. Pick this one when the budget is normal and the bet is that decorrelated models beat a better-featurised single family; pick high_accuracy when cost is not a constraint.

Feature engineering is left at the defaults on purpose: in ml4 the roster IS the breadth lever, so this preset changes the roster and the fold count and nothing else.

tuned_single ¶

tuned_single() -> Ml4Config

A single hyperparameter-tuned model (DAI / H2O / mljar style): a TPE search over the booster spaces, deployed as one model on a reserved holdout.

The tuning counterpart to the untuned presets — instead of fitting each booster once at its stock defaults it searches per-model hyperparameters over the gradient boosters and keeps the single best (no bagging, no weighted ensemble). Use it when you want a tuned, easy-to-serve single model rather than a bagged ensemble.

tuned_ensemble ¶

tuned_ensemble() -> Ml4Config

Hyperparameter-searched configs, then bagged and greedy-ensembled — the tuned counterpart to :func:diverse_ensemble.

Searches each booster family's hyperparameters and lets AutoGluon bag the tuned winners into a cross-validated weighted ensemble. Heavier than the untuned presets; use it when you want tuning and the robustness of a bagged ensemble.

reliable_tuned_ensemble ¶

reliable_tuned_ensemble() -> Ml4Config

Five-fold parameter selection followed by the standard tuned ensemble.

The 20-trial budget keeps the maximum search at 300 fits (three boosters × 20 trials × five folds) before adaptive pruning.

tuned_variants ¶

tuned_variants() -> Ml4Config

Every booster variant, each searched separately, then bagged and greedy-ensembled.

The widest roster ml4 ships: plain gradient boosting, DART and random-forest mode for LightGBM, both CatBoost grow policies, and XGBoost's tree booster — six models rather than three. The bet is structural diversity: a bagged forest and a dropout-boosted tree make different mistakes than a plain booster, and the greedy weighted ensemble is a selection procedure that can only exploit disagreement it is offered.

It is the most expensive template here, and the arithmetic is worth stating rather than discovering. With the shipped hpo.num_trials and hpo.cv_folds, the search alone is 6 x num_trials x cv_folds model fits before AutoGluon starts — and the two DART entries are additionally the slowest per trial, since DART has no usable early stopping and pays its full round budget every time (they carry a 0.5 budget brake for exactly that reason, engine.tuning._budget). The fit that follows trains 6 models at L1 and one per family at L2, each over num_bag_folds folds. The template bounds it at three hours (:data:_TIME_BUDGET_S); the search takes half and reports how many trials it actually ran.

Prefer :func:tuned_ensemble when the budget is normal — it searches the same three families at one variant each — and this when breadth is worth paying for.

real_time ¶

real_time() -> Ml4Config

Inference-latency-optimised: a single, hyperparameter-tuned Treelite-eligible booster.

The roster is restricted to LightGBM / XGBoost gradient-boosted trees (the families the compiler-free Treelite/GTIL accelerator can convert) with a single deployed model (no bagging, no weighted ensemble), and deploy.deliver_treelite is on so the artifact ships a fast model core. Because there is no ensemble to lean on, the single model is hyperparameter-tuned (see :func:_enable_hpo) — tuning is training-time only, so it does not affect inference latency, and the search stays on the Treelite-eligible boosters.

It is the one preset that narrows the space as well as choosing the roster: capacity_capped bounds the size knobs (num_leaves / max_depth / depth), which are what a tree costs per row at scoring time. Regularisation and the imbalance treatment stay fully searchable, because neither costs anything then.

It sets no serving-latency ceiling, and that is deliberate. Latency here is bounded structurally — one model instead of an ensemble, boosters small enough to stay under the cap, a narrowed feature pool, a compiled model core — not by a number this factory guesses. A numeric budget is an SLA, and an SLA belongs to the deployment, not to a preset: AutoGluon drops every model that misses it, so a value picked here without knowing the serving host would either bind on nothing or empty the roster on a slower box. If you have a hard per-row budget, set deployment.max_inference_seconds_per_row (and deployment.inference_latency_batch_size) on top of this preset.

large_dataset ¶

large_dataset() -> Ml4Config

Big-data preset (~2M+ rows / wide tables): a time-boxed, lightly-tuned LightGBM with lean FE.

Restricts the roster to a single LightGBM, time-boxes the fit, drops the data-scaling clustering encoder, narrows the interaction pass, and uses a single fast feature-selection ranker so a large table yields a usable model on day one instead of running for hours.

Searches, but on a short leash. This is the non-bagged shape, so the model is validated on one holdout rather than out-of-fold — the weakest validation ml4 offers — and pairing that with no search at all left the preset with neither cross-validation nor tuning. A large frame is precisely where a holdout is statistically sound (plenty of rows) and where a few well-chosen trials pay for themselves, so the search is on at _LARGE_DATASET_TRIALS rather than the shared 60-trial budget. The hour cap remains the binding constraint.

small_data ¶

small_data() -> Ml4Config

Small-data preset (< ~20k rows): variance control over search breadth.

Cross-validated bagging over ten folds with the stacking layer off — stacking overfits at this size. Turns feature selection off because its selection variance exceeds its value at this size. Target encoding continues to use the standard category_encoders estimators, cross-fitted inside each training fold.

text_heavy ¶

text_heavy() -> Ml4Config

Free-text-heavy preset: neural sentence embeddings on, arithmetic interaction crosses off.

Turns on the neural embedding encoder in augment mode (TF-IDF kept alongside), disables tree-guided interactions (arithmetic crosses on embedding components are noise), and runs a compact LightGBM + linear roster with a single fast feature-selection ranker.

foundation_ensemble ¶

foundation_ensemble() -> Ml4Config

The diverse roster plus the zero-shot foundation challenger, all ensembled.

The breadth bet of :func:diverse_ensemble with the tabular foundation model added as one more decorrelated member (a roster opt-in). 8-fold bagging, one bag set, no stacking layer, and every roster member trains. Best on small / medium tables and strongly GPU-friendly.

audit_friendly_fe ¶

audit_friendly_fe(config: Ml4Config) -> Ml4Config

Disable opaque FE in-place so a regulated model is transparent end-to-end (the deployed model traces cleanly back to its inputs).

Delegates to :func:~parleml_ml4.config.dependencies.disable_opaque_fe, which is the same list :func:~parleml_ml4.config.dependencies.enforce_regulated_fe_coherence applies from roster.regulated itself, so composing a preset and setting the flag by hand produce the same feature space. Silent by design: on these presets it is the documented behaviour, not a correction.

regulated_glassbox ¶

regulated_glassbox(kind: str = 'glm') -> Ml4Config

A regulated single glass-box model — glm / ebm / rulefit — with audit-friendly FE (its fit shape is one non-bagged model with no ensemble).

regulated_scorecard ¶

regulated_scorecard() -> Ml4Config

A regulated credit scorecard: a weight-of-evidence logistic whose coefficients are points.

Weight of evidence is applied to both kinds of predictor, by two different routes. A categorical is coded level by level (ce.WOEEncoder), with thin levels pooled into one shared class and the survivors shrunk toward the prior. A continuous predictor is monotone coarse-classed first — quantile pre-bins merged until every band clears a population floor (the larger of 20 rows and 5% of the fitting slice), then until the event rate is monotone across the bands, then down to at most 8 bands — and enters as the weight of evidence of its band, replacing the raw column. So income reaches the logistic as income_WE, and its points are per unit of a band's log-odds rather than per unit of currency.

The cost of the monotone requirement is stated in guides/constraints.md: a U-shaped predictor is merged until it is monotone, so one side of the U is absorbed. Split such a variable into two declared features if you need both arms.

regulated_monotonic ¶

regulated_monotonic() -> Ml4Config

A single, hyperparameter-tuned monotone-constrained booster (directions auto-derived) with audit-friendly FE — auditable via its monotone contract + SHAP, without a glass-box estimator.

Unlike the glass-box regulated presets (which stay deterministic and untuned), this is a plain monotone booster, so it is hyperparameter-tuned to make up for the single-model shape; the monotone contract is part of the recipe and stays fixed under the search. The search spans all three boosters (LightGBM / XGBoost / CatBoost) — each honours the constraint — and the winner deploys alone. Runs are reproducible for a fixed execution.seed.

with_foundation_challenger ¶

with_foundation_challenger(
    config: Optional[Ml4Config] = None,
    *,
    model: Optional[str] = None
) -> Ml4Config

Add the tabular foundation model (TabICL by default) as an ensemble challenger to config (or a fresh default config). model must be a catalogued foundation model. The challenger is then required: the fit refuses the run when its package is not installed and fails it when AutoGluon does not train it (for memory, time or an error), naming why.

Next: Configuration & presets · Hyperparameter search