trust-free

Model. Explain. TRUST. All in one package.

Overview

trust-free is a Python package for fitting interpretable regression and classification models using Transparent, Robust, and Ultra-Sparse Trees (TRUST) — a new generation of Linear Model Trees (LMTs) with Random-Forest (RF) accuracy and intuitive explanations. The core methods are based on the PRICAI 2025 paper (Springer Nature, Lecture Notes in Artificial Intelligence) that introduced the TRUST algorithm.

It includes a state-of-the-art explainability suite, providing comprehensive, automatically-generated explanation reports. To see it in action, here are two 15-second demos showcasing the explain() and compare() methods applied to the famous Medical Insurance Charges dataset from Kaggle:

TRUST’s explain() method — Straightforward prediction explanations

TRUST’s compare() method — Comprehensive head-to-head profile comparisons

Proven Performance: Accuracy + Full Interpretability (60 Datasets)

In the table above, TRUST is the only fully interpretable model statistically above 0.6 test R² across varied benchmark datasets — and 6× sparser than M5' (17 vs 109 coefficients on average).
Source: PRICAI 2025 (Springer LNAI)

See full benchmarks in the PRICAI 2025 paper

The package currently supports standard regression, multiclass classification, as well as experimental time-series regression tasks.

Key Advantages: RF Accuracy ⟡ Tree Transparency ⟡ Linear Interpretability

• Hybrid power: Trees to capture non-linearity & interactions + sparse linear models (Adaptive or Relaxed Elastic Net) in leaves
• Superior accuracy: RF-level accuracy, proven on 60 regression and 15 classification benchmarks
• Full transparency: Every prediction is auditable via tree path + leaf equation
• Inclusive: Regression explanation reports written in natural language accessible to all audiences
• Compliant by design: 100% Compliant with the EU AI Act and the OECD AI Principles — ideal for high-stakes domains like finance and healthcare

Media

• Data Elixir
• Data Science Weekly

About this edition

• ℹ️ Dataset Limits: ≤ 5,000 rows and ≤ 20 columns (intended for proof-of-concept, R&D and teaching)
• ✅ Full Functionality: All core features are fully functional within these bounds
• ✅ Standalone Tools: Relaxed Net (Renet™), Adaptive Logistic Regression (AdaLogit™), Adaptive Net, TurboSolve™ (fast OLS/ridge solver), Direct & Systemic Feature Importance
• ⭐ No-Limit Utilities: TurboSolve™, Feature Importance methods, and our open-source Synthetic Dataset Generators (Toeplitz, Block-Correlated) can be used without restriction as standalone tools

Star ⭐ the project's GitHub repository and stay updated!

Installation

You can install this package using pip:

pip install trust-free

📦 Note: The package name on PyPI is trust-free, but the module you import in Python is trust: e.g. from trust import TRUSTRegressor.

What's new in this version? Cross-platform Python 3.13 support.

Check CHANGELOG.md on the project's GitHub to see this and all past release notes.

Platform Compatibility

*If Kaggle shows a dependency-compatibility error message upon installation via %pip install trust-free you may safely ignore it and simply restart your kernel: click Run, then Restart & clear cell outputs.

For a fully reproducible development environment with all dependencies, see SETUP.md.

Usage

Here are four simple examples showing how to use the trust-free package:

from trust import TRUSTRegressor, AdaLogitCV # note the import name is trust, not trust-free
from sklearn.datasets import make_regression
from sklearn.model_selection import train_test_split
from sklearn.metrics import r2_score, mean_squared_error, roc_auc_score

🧪 Example 1: Sparse Synthetic Regression (n=5000, p=20)

X, y, coefs = make_regression(n_samples=5000, n_features=20, n_informative=10, coef=True, noise=0.1, random_state=123)
print(coefs)

# Make Train-Test split
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=123)

# Instantiate and fit your model
model = TRUSTRegressor().fit(X_train, y_train)

# Predict and print results
y_pred = model.predict(X_test)
print("Predictions:", y_pred[:5])
print("True y values:", y_test[:5])
print("test R\u00B2:", r2_score(y_test, y_pred))

# Estimate direct variable importance for your fitted model
model.importance("direct", filename="Synthetic")

# Obtain a comprehensive prediction explanation for the first test observation
model.explain(X_test[0,:], mode="detailed", actual=y_test[0], filename="Synthetic") 

🩺 Example 2: Diabetes Dataset (n=442, p=10)

import pandas as pd
from sklearn import datasets
from sklearn.preprocessing import LabelEncoder

Diabetes = pd.DataFrame(datasets.load_diabetes().data)
Diabetes.columns = datasets.load_diabetes().feature_names
diab_target = datasets.load_diabetes().target
Diabetes.insert(len(Diabetes.columns), "Disease_marker", diab_target)
Diabetes_X = Diabetes.iloc[:,:-1]
# Binary encoding (0/1) for 'sex'
le = LabelEncoder()
Diabetes_X.loc[:, 'sex'] = le.fit_transform(Diabetes_X['sex']).astype(str)
Diabetes_y = Diabetes.iloc[:,-1]
model_Diabetes = TRUSTRegressor(max_depth=1).fit(Diabetes_X,Diabetes_y)
y_pred_TRUST = model_Diabetes.predict(Diabetes_X)

# Tree plotting requires Graphviz to be installed in your system path
# You can use e.g. Homebrew: brew install graphviz or Conda: conda install -c conda-forge graphviz
model_Diabetes.plot_tree("Diabetes") #will save "tree_plot_Diabetes.png" in your working directory

# Obtain direct and systemic variable importance (with impact propagation heatmap) as well as ALE plots for all features
model_Diabetes.importance("direct", filename="Diabetes")
model_Diabetes.importance("systemic", filename="Diabetes")

# Obtain a prediction explanation for the second observation
model_Diabetes.explain(Diabetes_X.iloc[1,:], aim="decrease", actual=Diabetes_y[1], filename="Diabetes")

# Compare the second and fourth observations head-to-head
model_Diabetes.compare(Diabetes_X.iloc[1,:], Diabetes_X.iloc[3,:], filename="Diabetes")

🆎 Example 3: Sparse Synthetic Classification (n=1000, p=20)

from trust.datasets import generate_block_corr_data_binY
X, y, beta, nonzero_ix, zero_ix = generate_block_corr_data_binY(n=1000, p=20, signal_scale=2.0, pi=0.5, random_state=0)

# Make Train-Test split
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=123)

# Instantiate and fit your model (scikit-learn compatible)
ALR = AdaLogitCV(l1_ratios=(0.95,), class_weight="balanced", scoring="neg_log_loss").fit(X_train, y_train)
print("Estimated coefficients:", np.round(ALR.coef_[0]))
print("True coefficients:", beta)

# Predict and print results
ALR_predictions = ALR.predict_proba(X_test)[:, 1]
print("Predictions:", np.round(ALR_predictions[:5],2))
print("True y values:", y_test[:5])
print("AdaLogit Test AUC =", round(roc_auc_score(y_test, ALR_predictions), 2))

📊 Example 4: 1-Permutation Feature Importance (n=100, p=10)

pip install --quiet tabicl # Only if tabicl is not installed yet
from tabicl import TabICLRegressor
from trust import FeatureImportance, datasets

X, y, coefs = datasets.make_block_correlated_regression(n_samples=100, n_features=10, n_informative=5, noise=1.0, rho=0.5, random_state=123)
model = TabICLRegressor().fit(X, y)
fi = FeatureImportance().fit(model.predict, X, y)
rel_importance = fi.direct_importance() # An order of magnitude faster than classical PFI
linear_scores = np.abs(coefs) / np.sum(np.abs(coefs))
print("Underlying linear model feature importance scores:", np.round(linear_scores, 2))
print("TabICL feature importance scores:", np.round(rel_importance, 2))
print("Underlying linear model feature importance directions:", np.sign(coefs))
print("TabICL feature importance directions:", fi.directions)

More Examples on Kaggle Datasets

• Medical Insurance Charges (2.1M views, 450K downloads)
• Life Satisfaction in the EU (own contribution)

License

For detailed terms, please refer to the LICENSE.txt file, which is also included with the distribution.

More Information

For more details and documentation visit:

https://github.com/adc-trust-ai/trust-free

Further technical details about TRUST™, Renet™ and our novel variable importance algorithms can be found in our preprints on arXiv:

https://www.arxiv.org/abs/2506.15791

https://arxiv.org/abs/2602.11107

https://arxiv.org/abs/2512.13892

Built with ❤️ by ADC at Whiteboxlab - Copyright © 2025-2026 Albert Dorador Chalar. All rights reserved. TRUST™, Renet™, AdaLogit™, and TurboSolve™ are trademarks of Albert Dorador Chalar.