mljar-supervised

Machine learning for your tabular data

A Python AutoML package to train models, discover features, and explain predictions.

One AutoML to rule them all

New in 1.4: RealMLP, TabM mini, Kumo, and TabICLv2 join the classic algorithms in MLJAR AutoML. Compare three model families through the same Python interface and see their validation results in one leaderboard.

Start with the published 1.4.0rc6 release candidate below, or follow the CPU and GPU installation guide to add the new models. Optional models run in Compete mode and depend on your hardware and available memory.

See the model comparison example · Read the release notes

Quickstart

Use Python 3.11 or newer. In a virtual environment, install the release candidate:

python -m pip install 'mljar-supervised==1.4.0rc6'

Predict the species of an Iris flower from four measurements. This small dataset comes with scikit-learn, so you can run the example without downloading data. We keep 30 flowers out of training to check the predictions.

from sklearn.datasets import load_iris
from sklearn.metrics import accuracy_score
from sklearn.model_selection import train_test_split
from supervised import AutoML

# Predict the flower species from four measurements.
X, y = load_iris(return_X_y=True, as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, stratify=y, random_state=42
)

automl = AutoML(
    results_path="AutoML_Iris",
    mode="Explain",
    algorithms=["Baseline", "Decision Tree", "Linear", "LightGBM"],
    total_time_limit=120,
    n_jobs=2,
)
automl.fit(X_train, y_train)

predictions = automl.predict(X_test)
print(f"Test accuracy: {accuracy_score(y_test, predictions):.1%}")
automl.report()  # Creates AutoML_Iris/README.html.
# Save example inputs so the reload example also works in a new Python session.
X_test.head(3).to_csv("iris_new_rows.csv", index=False)

Run this in a new working folder, or use the complete quickstart script. The explicit algorithm list keeps this example on standard CPU models, even if you have optional model packages installed. The training budget is 120 seconds; this small example can finish sooner.

In our recorded 1.4.0b1 runs on Python 3.11 and 3.12, the selected model predicted 29 of 30 held-out flowers correctly (96.7%). This is one small test split, not a general accuracy claim. Recorded output and setup.

AutoML directory: AutoML_Iris
The task is multiclass_classification with evaluation metric logloss
AutoML will use algorithms: ['Baseline', 'Decision Tree', 'Linear', 'LightGBM']
AutoML is generating and selecting models automatically. Review outputs before important use.
AutoML will ensemble available models
AutoML steps: ['simple_algorithms', 'default_algorithms', 'ensemble']
* Step simple_algorithms will try to check up to 3 models
1_Baseline logloss 1.098612 trained in 0.29 seconds
2_DecisionTree logloss 0.544928 trained in 3.97 seconds
3_Linear logloss 0.206915 trained in 0.53 seconds
* Step default_algorithms will try to check up to 1 model
4_Default_LightGBM logloss 0.207178 trained in 0.71 seconds
* Step ensemble will try to check up to 1 model
Ensemble logloss 0.111935 trained in 0.78 seconds
AutoML fit time: 12.23 seconds
AutoML best model: Ensemble
Test accuracy: 96.7%
[0 2 1]

Open AutoML_Iris/README.html to explore the leaderboard and model reports. The target labels are 0 (setosa), 1 (versicolor), and 2 (virginica).

Use the saved model

Training saves your models automatically. In a new Python session:

import pandas as pd
from supervised import AutoML

saved_model = AutoML(results_path="AutoML_Iris")
new_rows = pd.read_csv("iris_new_rows.csv")
print(saved_model.predict(new_rows))

The quickstart saves three held-out example inputs to iris_new_rows.csv. For your own rows, supply the same input columns. Keep the complete AutoML_Iris directory; shared preprocessing files are needed too. Use a new results path when starting another training run.

Automatic documentation

See which models were trained and how they performed. Every successful run creates a leaderboard and reports for individual models. Follow a model link to inspect its settings, validation results, and available explanations.

An actual customer-churn report from 1.4.0b1. Open the full report.

Model reports can include feature importance, learning curves, confusion matrices, and SHAP explanations, depending on the model and explain_level.

Permutation feature importance from the concrete-strength tutorial. Read the model report walkthrough to understand the result.

Need reports in your own workflow? Read them as Markdown, a dictionary, or JSON:

report = automl.report_structured(format="dict")

Explore automatic reports · Model explanations

Feature engineering

Try additional features and check whether they help. AutoML handles missing values and categorical inputs, can construct numeric combinations with golden features, and can use feature discovery to propose additional sets of columns. Feature selection can also test models with fewer inputs. Compete enables golden features by default; feature discovery and KMeans features require explicit opt-in.

# Use your training data in X_train and y_train.
feature_search = AutoML(
    results_path="AutoML_Features",
    mode="Compete",
    total_time_limit=3600,
    golden_features=True,
    feature_discovery=True,
)
feature_search.fit(X_train, y_train)

Feature discovery is included in the base installation. In a small synthetic example, it generated length_mul_width, material_te (target encoding), and material_freq, among other columns. The saved report records their definitions.

Measured with 1.4.0b1, the same Linear algorithm, and the same validation split. The synthetic target includes a length × width interaction, so this illustrates how generated features can help a linear model. It is not a general benchmark. Reproduce this example.

Transformations are fitted inside training folds and reused for prediction. Discovery currently supports shuffled split and K-fold validation; custom, grouped, and time-ordered validation need a different workflow.

Golden features · Feature discovery · Feature selection

Compare classic, neural, and foundation models

Use familiar algorithms or add neural and pretrained models. AutoML compares their validation results.

Install the optional backend using the CPU or NVIDIA GPU setup instructions, then select the models you want to compare:

foundation_search = AutoML(
    results_path="AutoML_FoundationModels",
    mode="Compete",
    algorithms=["LightGBM", "Kumo", "TabICLv2"],
    total_time_limit=3600,
)
foundation_search.fit(X_train, y_train)

Model weights download on first use. Hardware, memory, task, and sample-weight support differ between backends. Standard CPU examples do not need these extras.

Kumo and TabICLv2 · RealMLP · TabM

Fairness aware training

Measure group differences and evaluate bias mitigation. Supply sensitive features separately and choose the fairness metric that fits your question. AutoML reports group metrics and can train reweighted candidates to try to meet the selected threshold.

# Binary classification; sensitive_train has one row per training example.
# Its columns identify the groups you want to evaluate.
fairness_search = AutoML(
    results_path="AutoML_Fairness",
    algorithms=["Linear", "LightGBM"],
    fairness_metric="demographic_parity_ratio",
    fairness_threshold=0.8,
)
fairness_search.fit(X_train, y_train, sensitive_features=sensitive_train)

This synthetic example uses two artificial groups. The ratio compares their positive prediction rates; closer to 1 means more similar rates. Mitigation improved this ratio but lowered accuracy, and the test ratio remained below 0.8. It does not establish fairness for a real application. Recorded setup and results.

Binary classification tutorial · Multiclass · Regression

Generate web apps for trained models

Let others make predictions through a web interface. Export a trained model as a Mercury app with inputs for one row or a CSV upload for batch predictions.

# Continue from the trained quickstart model.
automl.app(title="Iris species prediction")

The base package generates the files. Install the optional runtime to run them:

python -m pip install 'mljar-supervised[apps]==1.4.0rc6'

automl.local_app()  # Starts the app locally and opens your browser.

When you are ready to publish, use automl.publish_app() or host the generated files yourself. Publishing is a separate action; generating an app does not put it online.

Build a prediction app · Classification tutorial · Regression tutorial

Customize your workflow

Choose how models are trained, compared, and evaluated. Set the budget, algorithms, validation strategy, and metric for your problem.

Available modes

Modes provide defaults; you can override individual settings. The quickstart uses Explain. See modes and training stages for details.

Keep related rows together

For repeated measurements of the same machine, customer, or subject, use grouped validation. Pass split indices relative to your training rows:

from sklearn.model_selection import GroupKFold

folds = list(GroupKFold(n_splits=3).split(X_train, y_train, groups=train_groups))
grouped_model = AutoML(
    results_path="AutoML_Grouped",
    validation_strategy={"validation_type": "custom"},
    golden_features=False,
    feature_discovery=False,
)
grouped_model.fit(X_train, y_train, cv=folds)

Reserve a separate group-safe test set before this step. Run the complete grouped or time-ordered example.

Use your own metric

Pass a function accepting targets, predictions, and optional sample weights. AutoML minimizes its result:

import numpy as np

def underprediction_cost(y_true, y_predicted, sample_weight=None):
    error = np.asarray(y_true).ravel() - np.asarray(y_predicted).ravel()
    cost = np.where(error > 0, 2 * error, -error)
    return np.average(cost, weights=sample_weight)

custom_model = AutoML(
    results_path="AutoML_CustomMetric",
    ml_task="regression",
    eval_metric=underprediction_cost,
)

This example gives underestimates twice the cost of equal-sized overestimates. For a score where higher is better, return its negative value. Custom metric guide · Full API reference

Examples

Start with a question similar to yours. Each tutorial includes a standalone script, a notebook, dataset attribution, measured results, and real reports.

Predict a number from a CSV	Predict which customers may leave
Start here · Engineering · Regression	Start here · Business · Classification
Estimate concrete strength from ingredients and age. Learn to measure error in MPa and keep related measurements together.	Estimate churn probabilities from service usage. Understand missed customers, false alarms, and a fixed decision threshold.
Read the tutorial · Script · Notebook	Read the tutorial · Script · Notebook

Both scripts and notebooks passed on Python 3.11 and 3.12 with published mljar-supervised==1.4.0b1. Their tutorials record the environments, evaluation protocols, runtime, memory measurements, and reload checks. Results from one historical split are not promises about another dataset or machine.

Browse the gallery and advanced guides.

Installation

Use Python 3.11 or newer. We recommend Python 3.12. The install commands use RC6. Recorded tutorial results retain their original 1.4.0b1 version and environment details.

For Torch-based extras, choose a compatible CPU or CUDA PyTorch build first. See the installation guide for exact commands, aliases, platform limitations, and native-runtime compatibility checks. The base package does not require Torch or Mercury. Conda-forge releases are maintained separately.

FAQ

• How do I save and reload? Models are saved in results_path. Keep the complete directory; see save and load.
• Can I choose classification or regression explicitly? Set ml_task. See the API reference for supported values.
• How do I identify probability columns? Use predict_all() to inspect the class-labelled prediction columns. Their order matches predict_proba(); predict_all() also includes the predicted label.
• How is tuning configured? See AutoML stages and the API reference, including optuna_init_params for reusing Optuna parameters.

Documentation

Documentation website · Example gallery · API reference · Get help · Release notes · Report an issue

For a walkthrough with real outputs, follow the concrete-strength tutorial or customer-churn tutorial.

Contributing

Read the contribution guide and test instructions. Thanks to everyone who has contributed.

Cite

If you use MLJAR AutoML in your research, please cite:

@inproceedings{plonska2026mljar,
  title     = {{MLJAR AutoML}: Transparent and Fairness-Aware {AutoML} for Tabular Data with Automatic Documentation},
  author    = {P{\l}o{\'n}ska, Aleksandra and P{\l}o{\'n}ski, Piotr},
  booktitle = {Proceedings of the Fifth International Conference on Automated Machine Learning},
  series    = {Proceedings of Machine Learning Research},
  publisher = {PMLR},
  year      = {2026},
  note      = {To appear},
  url       = {https://openreview.net/forum?id=MeGWjXDu0q}
}

License

MLJAR AutoML is available under the MIT license. Example datasets and optional model weights have their own licenses, documented with their sources.

Built on the shoulders of giants. Meet the projects and people behind AutoML in our Credits.

Commercial support

For implementation or commercial support, contact MLJAR.

MLJAR

Created by MLJAR. Explore MLJAR Studio for a conversational notebook interface.