Metadata-Version: 2.4
Name: parleml-mli
Version: 0.8.0
Summary: ML Interpretability toolkit: target-class profiling, rule extraction, and reporting
Author-email: ParleML <support@parleml.com>
License-Expression: LicenseRef-ParleML-Terms
Project-URL: Homepage, https://parleml.com
Project-URL: Documentation, https://parleml.com/help/mli/
Project-URL: Terms of use, https://parleml.com/help/legal/terms/
Project-URL: Third-party notices, https://parleml.com/legal/
Keywords: machine-learning,profiling,clustering,tree-ensemble,shap,archetypes,similar-cases
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: NOTICE.txt
Requires-Dist: parleml-ml4==0.8.0
Requires-Dist: numpy>=2.0
Requires-Dist: pandas>=2.2
Requires-Dist: scipy>=1.13
Requires-Dist: scikit-learn>=1.7
Requires-Dist: plotly>=5.24
Requires-Dist: umap-learn>=0.5.5
Requires-Dist: tqdm>=4.66
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: fg-data-profiling<5,>=4.20
Requires-Dist: numba>=0.60
Requires-Dist: networkx>=3.0
Requires-Dist: shap>=0.46
Requires-Dist: catboost>=1.2.5
Requires-Dist: lightgbm>=4.5
Requires-Dist: xgboost>=3.1
Requires-Dist: pyarrow>=23
Requires-Dist: optuna>=4.0
Requires-Dist: optuna-integration>=4.0
Requires-Dist: wordcloud>=1.9.3
Requires-Dist: fairlearn>=0.11
Requires-Dist: utilsforecast
Requires-Dist: interpret-core>=0.7.8
Requires-Dist: imodels>=1.4
Requires-Dist: graphviz>=0.20
Requires-Dist: statsmodels>=0.14
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Requires-Dist: jsonschema>=4.21; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
Requires-Dist: black>=24.0; extra == "docs"
Dynamic: license-file

# parleml-mli

**mli** is the interpretation library of [ParleML](https://parleml.com), the machine learning
platform built to be driven by AI agents. It explains fitted models and the data behind them: who
the model flags and why, which rules it learned, how good and how trustworthy it is. Free to use,
including commercial use.

```bash
pip install parleml-mli
```

```python
from parleml_mli import ExplanationsConfig, ProfilingConfig, RulesConfig, fit_profiler

result = fit_profiler(
    model=clf, X=X_train, y=y_train,
    target_mask=(y_train == 1),             # the rows to profile: here, the positives
    X_test=X_test, y_test=y_test,           # held-out rows for the model evaluation
    X_holdout=X_test, y_holdout=y_test,     # held-out rows for the rules' Test numbers
    config=ProfilingConfig(rules=RulesConfig(), explanations=ExplanationsConfig()),
)
result.summary_df   # one row per archetype: size, lift, key signatures
result.save("out/profiling_result.joblib")
```

`fit_profiler` returns a `ProfilingResult` with the analyses you asked for. For a scorer you can't
open, or for stored predictions, use `monitor_predictions`.

## What it computes

| Capability | Entry point | What you get |
| --- | --- | --- |
| Behavioural archetypes | `fit_profiler` | Clusters of the target rows in tree-leaf or SHAP space, with signatures and similar cases |
| Rule extraction | `extract_rules` | IF-THEN rules from supported trees, with Train and, given held-out rows, Test metrics |
| Global explanations | `explain` | PDP, ALE, interactions, surrogate, importance, drift, fairness and the error tree |
| EDA and leakage | `compute_eda` | Distributions, associations, missing values, outliers and suspicious features; no model needed |
| Evaluation and label noise | `parleml_mli.evaluation` | Metrics, calibration, business-cost views, and rows worth a second look |
| Trust summary | `compute_trust_summary` | Diagnostic tiles from the evidence you have; missing evidence never shows as a pass |
| Model cards | `build_model_card` | A structured model card with regulatory crosswalks |
| Bring-your-own predictions | `monitor_predictions` | The model-agnostic analyses from a scorer you can't open |

It reads models from [`parleml-ml4`](https://pypi.org/project/parleml-ml4/), which it installs,
and models trained elsewhere. LightGBM, XGBoost, CatBoost, scikit-learn tree ensembles, EBM,
RuleFit and scikit-learn linear models get the full analysis; any other model with `predict` or
`predict_proba` gets the model-agnostic one through `monitor_predictions`.

## Installation

Python 3.11, 3.12 or 3.13 on Windows or Linux (x86-64). The wheels are compiled, so pip picks the
one for your platform; on macOS, run ParleML in Docker. Tree plots need the Graphviz `dot`
program on your PATH (a system package, not a Python one).

## Documentation

- [The mli documentation](https://parleml.com/help/mli/): installation, quickstart, guides and the
  API reference.
- [ParleML](https://parleml.com) and [its manual](https://parleml.com/help/): the platform, and the
  Interpretation tabs built on mli. The same documentation ships with ParleML under `/help`.

Questions: support@parleml.com.

## Licence

Free to use, including commercial use, under the [ParleML terms of use](https://parleml.com/help/legal/terms/)
(`LICENSE.txt` in this package). Third-party material this package contains is listed in
`NOTICE.txt`; every ParleML notice is at [parleml.com/legal](https://parleml.com/legal/).

Exported scoring packages may be sold and distributed with the required ParleML runtime
unchanged. Selling ParleML or charging for access to its platform is not permitted.
