Metadata-Version: 2.4
Name: trust-free
Version: 3.0.0
Summary: TRUST - Decision Trees with Sparse Elastic Net leaves, Random Forest accuracy and automated explanations
Home-page: https://whiteboxlab.ai/
Author: Albert Dorador Chalar
Maintainer: TRUST Team
Maintainer-email: albert@whitebox.ai
License: Proprietary - Permissive Binary Only
Project-URL: Repository, https://github.com/adc-trust-ai/trust-free
Project-URL: Documentation, https://github.com/adc-trust-ai/trust-free/blob/main/MANUAL.md
Project-URL: Issue Tracker, https://github.com/adc-trust-ai/trust-free/issues
Keywords: machine learning,linear models,decision trees,random forest,regression,interpretable ml,explainable ai,ai safety,compliance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Education
Classifier: Natural Language :: English
Requires-Python: >=3.11,<3.13
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: celer>=0.7.4
Requires-Dist: ipython>=8.0.0
Requires-Dist: joblib>=1.2.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: numpy<2.0.0,>=1.23.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: plotly>=6.0.0
Requires-Dist: PyALE>=1.2.0
Requires-Dist: pydot>=4.0.1
Requires-Dist: scikit-learn>=1.7.1
Requires-Dist: scipy>=1.15.0
Requires-Dist: shap>=0.48.0
Requires-Dist: statsmodels>=0.14.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# trust-free <a href="https://adc-trust-ai.github.io/trust"><img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/TRUST_logo_500x500.png" align="right" height="128" alt="TRUST logo"/></a>

[![PyPI version](https://img.shields.io/pypi/v/trust-free.svg)](https://pypi.org/project/trust-free/)
[![Python](https://img.shields.io/pypi/pyversions/trust-free.svg)](https://pypi.org/project/trust-free/)
[![Downloads](https://static.pepy.tech/badge/trust-free)](https://pepy.tech/project/trust-free)
[![License](https://img.shields.io/badge/license-Proprietary-lightgrey.svg)](LICENSE.txt)
[![User Manual](https://img.shields.io/badge/docs-User_Manual-blue)](https://github.com/adc-trust-ai/trust-free/blob/main/MANUAL.md)


### Model. Explain. TRUST. All in one package.

## Overview

**trust-free** is a Python package for fitting interpretable regression 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](https://arxiv.org/abs/2506.15791) that introduced the TRUST algorithm, forthcoming in **Springer Nature (Lecture Notes in Artificial Intelligence)**.

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](https://www.kaggle.com/datasets/mirichoi0218/insurance) dataset from Kaggle:

<div align="center">
  <img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_explain_demo_compressed.gif"
       alt="explain() method"
       width="96%" />
  <br><br>
  <strong>TRUST™’s <code>explain()</code> method</strong> — Straightforward prediction explanations
</div>

<br>

<div align="center">
  <img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_compare_demo_compressed.gif"
       alt="compare() method"
       width="96%" />
  <br><br>
  <strong>TRUST™’s <code>compare()</code> method</strong> — Comprehensive head-to-head profile comparisons
</div>


### Proven Performance: Accuracy + Full Interpretability (60 Datasets)

| Model                   | **Test R² ↑** | **Interpretable?** |
|-------------------------|---------------|--------------------|
| **TRUST™**              | **0.67**      | ✅ Yes             |
| Random Forest (RF)      | 0.62          | ❌ No              |
| Lasso                   | 0.57          | ✅ Yes             |
| CART                    | 0.49          | ✅ Yes             |
| Node Harvest (NH)       | 0.47          | ✅ Yes             |
| M5' (Linear Model Tree) | 0.36          | ⚠️ Partially       |

> 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](https://arxiv.org/abs/2506.15791)

---

The package currently supports standard regression and experimental time-series regression tasks. Future releases will also tackle other tasks such as classification.

## 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 benchmark datasets
- **Full transparency**: Every prediction is auditable via tree path + leaf equation
- **Inclusive**: 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](https://news.dataelixir.com/t/t-69C03215CCA6CFF02540EF23F30FEDED)
- [Data Science Weekly](https://datascienceweekly.substack.com/p/data-science-weekly-issue-616)

### About this edition
- ℹ️ Free-tier 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 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
- 🚀 Need even more? We got you covered: Unlimited scale and [additional features](https://github.com/adc-trust-ai/trust-free/blob/main/trust-pro.md) in the forthcoming **trust-pro** edition

**Want early access to trust-pro?**  
- Join the [waitlist](https://forms.gle/Gsti4kZ7yG5ZTNqu7) (completely anonymous & GDPR-compliant)
- Star ⭐ the project's [GitHub repository](https://github.com/adc-trust-ai/trust-free) to stay updated!


## Installation

You can install this package using pip:

```bash
pip install trust-free
```
> 📦 **Note:** The package name on PyPI is `trust-free`, but the module you import in Python is `trust`: `from trust import TRUSTRegressor`.

### What's new in version 3.0.0? 5-20x faster training, new models in leaves (Adaptive or Relaxed Elastic Net), new Direct and Systemic Feature Importance, and more!

Check [CHANGELOG.md](https://github.com/adc-trust-ai/trust-free/blob/main/CHANGELOG.md) on the project's GitHub to see this and all past release notes.

### Platform Compatibility

| Platform / Environment   | OS & Arch         | Python    | Status      |
|--------------------------|-------------------|-----------|-------------|
| **macOS ARM64** (M1–M4)  | macOS 11+ ARM64   | 3.11–3.12 | ✅ Working  |
| **macOS Intel** (x86_64) | macOS 11+ Intel   | 3.11–3.12 | ✅ Working  |
| **Linux Intel/AMD**      | manylinux x86_64  | 3.11–3.12 | ✅ Working  |
| **Google Colab**         | Linux x86_64      | 3.12      | ✅ Working  |
| **Kaggle Notebooks**     | Linux x86_64      | 3.11      | ✅ Working* |
| **Linux ARM64**          | manylinux ARM64   | 3.11–3.12 | ✅ Working  |
| **Windows Intel/AMD**    | Windows 11 x86_64 | 3.11–3.12 | ✅ Working  |

*If Kaggle shows a dependency-compatibility issue message upon installation via %pip install trust-free you may safely ignore it and hit "Restart and run up to selected cell" (assuming your selected cell is the one installing trust-free).

For a fully reproducible development environment with all dependencies, see [SETUP.md](https://github.com/adc-trust-ai/trust-free/blob/main/SETUP.md).


## Usage

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

```python
from trust import TRUSTRegressor # 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
```

### 🧪 Example 1: Sparse Synthetic Regression (n=5000, p=20)
```python
X, y, coefs = make_regression(n_samples=5000, n_features=20, n_informative=10, coef=True, noise=0.1, random_state=123)
print(coefs)

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))
```

```python
# Estimate direct variable importance for your fitted model
model.importance("direct", filename="Synthetic")
```
<div align="center">
    <img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/Direct_Importance_plot_Synthetic.png" alt="varImp" width="50%" style="display: block; margin: auto;" />
</div>

```python
# Obtain a comprehensive prediction explanation for the first test observation
model.explain(X_test[0,:], mode="detailed", actual=y_test[0], filename="Synthetic") 
```
<div align="center">
<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_explain1.png" alt="Explain1" width="97%" style="display: block; margin: auto;" />

<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/Pie_chart_Synthetic.png" alt="PieChart" width="50%" style="display: block; margin: auto;" />
</div>


### 🩺 Example 2: Diabetes Dataset (n=442, p=10)
```python
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)
```
```python
# 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
```
<div align="center">
<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/tree_plot_Diabetes.png" alt="tree" width="50%" style="display: block; margin: auto;" />
</div>


```python
# 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")
```
<div align="center">
    <img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/Direct_Importance_plot_Diabetes.png" alt="varImp2" width="33.75%" />
    <img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/Systemic_Importance_plot_Diabetes.png" alt="varImp3" width="33.75%" />
    <img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/Impact_Propagation_Heatmap_Diabetes.png" alt="varImp3b" width="30.65%" />
</div>

<div align="center">
<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/ALE_plot_Diabetes.png" alt="ALEplot" width="99%" style="display: block; margin: auto;" />
</div>


```python
# Obtain a prediction explanation for the second observation
model_Diabetes.explain(Diabetes_X.iloc[1,:], aim="decrease", actual=Diabetes_y[1], filename="Diabetes")
```
<div align="center">
<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_explain2.png" alt="Explain2" width="97%" style="display: block; margin: auto;" />

<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_explain3a.png" alt="Explain3a" width="97%" style="display: block; margin: auto;" />

<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_explain3b.png" alt="Explain3b" width="97%" style="display: block; margin: auto;" />

<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_explain4.png" alt="Explain4" width="97%" style="display: block; margin: auto;" />
</div>


```python
# Compare the second and fourth observations head-to-head
model_Diabetes.compare(Diabetes_X.iloc[1,:], Diabetes_X.iloc[3,:], filename="Diabetes")
```
<div align="center">
<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_compare1.png" alt="Compare1" width="97%" style="display: block; margin: auto;" />

<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/Radar_chart_Diabetes.png" alt="Radar" width="50%" style="display: block; margin: auto;" />

<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_compare2.png" alt="Compare2" width="97%" style="display: block; margin: auto;" />

<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/Pie_charts_Diabetes.png" alt="Pies" width="97%" style="display: block; margin: auto;" />
</div>


### More Examples on Kaggle Datasets
- [Medical Insurance Charges (1.9M views, 383K downloads)](https://www.kaggle.com/datasets/mirichoi0218/insurance)
- [Life Satisfaction in the EU (own contribution)](https://www.kaggle.com/datasets/albertdorador/eu-life-satisfaction-eurostat-un-oecd)


## License

This software is provided under a Proprietary - Permissive Binary Only license.
For detailed terms, please refer to the [LICENSE.txt](https://github.com/adc-trust-ai/trust-free/blob/main/LICENSE.txt) file, which is also included with the distribution.

## More Information

For more details, documentation, and information about the full upcoming 'pro' version of the TRUST™ algorithm, 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

Copyright © 2025-2026 Albert Dorador Chalar. All rights reserved. TRUST™, Renet™ and TurboSolve™ are trademarks of Albert Dorador Chalar.
