Skip to content

Working with the model engine (ML4)

mli is the interpretability half of ParleML: ml4 builds the model, mli explains it.

In short

  • mli reads ml4 through one small contract: InterpretablePipeline and LeafModelHandle. Every frame it hands over is a plain, column-named pandas.DataFrame.
  • The deployed pipeline makes the predictions. SHAP, archetypes and rules describe the best readable base tree on the board, which may be a different model.
  • Ml4OriginRegistry rolls engineered features back to their source columns.
  • ml4 clustering, anomaly and forecasting results are drawn by parleml_mli.unsupervised and parleml_mli.forecasting.
  • For a worked example, see Explain an ml4 model.

The contract mli consumes

mli reads ml4 through one small, dependency-free surface: ml4's InterpretablePipeline and LeafModelHandle (the interpretability contract). mli never imports autogluon.

The contract makes one promise that keeps the integration clean: every frame-valued call takes and returns a plain, column-named pandas.DataFrame. There are no sparse matrices, bare arrays, positional f0.. names or engine wrappers. So transform and prepare_member_introspection_frame both hand mli a readable frame whose columns are the real engineered feature names, and mli runs SHAP, archetypes and rules on it directly.

ml4 computes no attributions itself. Every SHAP value comes from mli's adapters (parleml_mli.adapters.shap_utils.compute_shap_values). If you bring your own pipeline object, implementing that contract with the same single-frame guarantee is all mli needs.

Profile any fitted model

mli profiles any fitted tree ensemble or glass-box model. The simplest path hands fit_profiler a fitted estimator and its training frame. See Bring-your-own-model for the walkthrough, and Profiling for what the result holds.

Feature origins: explanations in business terms

A model engine engineers many derived columns: target encodings, embeddings, interactions, domain parses. parleml_mli.adapters.ml4_encoding.Ml4OriginRegistry records which raw column each engineered feature came from, so drivers, archetypes and rules roll up to the names your business already uses instead of col__te_oof_3. Pass it to fit_profiler(..., encoding_registry=...), built from the raw column names: Ml4OriginRegistry(raw_df.columns).

Which model a view describes

The deployed model scores, the best base tree explains. At inference the deployed model produces the prediction: predict_proba_from_encoded for binary and multiclass, predict_point_from_encoded for regression. Regression has no probabilities, so proba_calibrated is None and there is no decision threshold.

Every explanation artifact (per-row SHAP, archetypes and rules) is read on the member frame (prepare_member_introspection_frame). It describes the best introspectable base tree, the model the profile's global artifacts were fit on. FittedPipeline.best_introspectable_leaf() picks it: the best-scoring readable base model, with LightGBM, XGBoost and CatBoost preferred over glass-box models. It need not be the deployed model, so rules exist even when the deployed model is a weighted ensemble or a foundation model.

When nothing on the board is readable, native analysis is unavailable. The app then falls back to lite analysis. When the deployed model is a single readable model, it is the base tree, and the two views describe the same model.

Bind the pipeline for per-row reason codes with result.justifier(pipeline=loaded_pipeline). The pipeline transforms and scores the raw row; the base tree explains it. Native glass-box structures of the deployed models are available through parleml_mli.adapters.ml4_pipeline.explain_pipeline(pipeline).

Details: task coverage

Binary and multiclass score through predict_proba_from_encoded; regression scores through predict_point_from_encoded. The SHAP path handles all three. A multiclass model yields a (rows, features, classes) tensor sliced to the active class. Binary and regression yield a (rows, features) block; the binary negative class reads it negated.

Unsupervised and forecasting results

ml4's clustering and anomaly detectors and its forecasters are drawn and profiled through mli's plotting modules (parleml_mli.unsupervised.clustering.plots, parleml_mli.unsupervised.anomaly.plots, parleml_mli.forecasting.plots). Every chart is registered under the id the ParleML server serves:

  • parleml_mli.unsupervised.registry.render_unsupervised_plot(pipeline, kind) draws cluster maps, profiles and anomaly rationale from a fitted parleml_ml4.unsupervised.UnsupervisedPipeline.
  • parleml_mli.forecasting.plots.render_forecast_plot(kind, result=...) does the same for a forecast.

To log the standard chart set with an unsupervised MLflow run, pass plots=parleml_mli.unsupervised.registry.mlflow_plots(pipeline, X) to UnsupervisedPipeline.log_mlflow_run. ml4 writes the figures it is given and never imports mli. See Interactive visualizations.

AI-written narration

Business-language narration (archetype names, cluster names) is an annotation a host adds after the analysis, through an injected Ask. See AI-written narration. The analysis itself is always deterministic and never calls a model.

Next