Metadata-Version: 2.4
Name: parleml-ml4
Version: 0.8.0
Summary: ParleML's training engine: AutoML on AutoGluon with leakage-safe feature engineering, calibration and forecasting
Author-email: ParleML <support@parleml.com>
License-Expression: LicenseRef-ParleML-Terms
Project-URL: Homepage, https://parleml.com
Project-URL: Documentation, https://parleml.com/help/ml4/
Project-URL: Terms of use, https://parleml.com/help/legal/terms/
Project-URL: Third-party notices, https://parleml.com/legal/
Classifier: Development Status :: 3 - Alpha
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: autogluon.tabular[tabicl]==1.6.3
Requires-Dist: torch>=2.2
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.25
Requires-Dist: lightgbm>=4.7
Requires-Dist: catboost>=1.2.10
Requires-Dist: rapidfuzz
Requires-Dist: disposable-email-domains
Requires-Dist: tldextract
Requires-Dist: pycountry
Requires-Dist: user-agents
Requires-Dist: phonenumbers
Requires-Dist: usaddress
Requires-Dist: pgeocode
Requires-Dist: geoip2
Requires-Dist: skrub
Requires-Dist: imbalanced-learn
Requires-Dist: category-encoders>=2.9.0
Requires-Dist: kmeans1d>=0.5.0
Requires-Dist: imodels>=2.0.4
Requires-Dist: mlxtend<0.26,>=0.23.4
Requires-Dist: scipy>=1.11
Requires-Dist: scikit-learn>=1.7
Requires-Dist: interpret-core>=0.7.8
Requires-Dist: pyod>=1.1
Requires-Dist: litellm>=1.40
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff==0.15.21; extra == "dev"
Requires-Dist: pandas-stubs<2.4,>=2.3; extra == "dev"
Provides-Extra: stateless
Requires-Dist: names-dataset; extra == "stateless"
Requires-Dist: parleml-ml4[embeddings]; extra == "stateless"
Provides-Extra: forecasting
Requires-Dist: utilsforecast; extra == "forecasting"
Requires-Dist: statsforecast>=2.0; extra == "forecasting"
Requires-Dist: statsmodels>=0.14; extra == "forecasting"
Requires-Dist: hierarchicalforecast; extra == "forecasting"
Requires-Dist: lightgbm; extra == "forecasting"
Requires-Dist: xgboost>=2.0; extra == "forecasting"
Requires-Dist: mlforecast<2,>=1.1; extra == "forecasting"
Requires-Dist: optuna>=3.0; extra == "forecasting"
Requires-Dist: holidays; extra == "forecasting"
Provides-Extra: forecasting-autogluon
Requires-Dist: autogluon.timeseries==1.6.3; extra == "forecasting-autogluon"
Provides-Extra: ltr
Requires-Dist: lightgbm>=4.7; extra == "ltr"
Requires-Dist: catboost>=1.2.10; extra == "ltr"
Requires-Dist: optuna>=3.0; extra == "ltr"
Provides-Extra: embeddings
Requires-Dist: sentence-transformers; extra == "embeddings"
Provides-Extra: unsupervised
Requires-Dist: umap-learn>=0.5.7; extra == "unsupervised"
Requires-Dist: parleml-ml4[embeddings]; extra == "unsupervised"
Provides-Extra: mlops
Requires-Dist: mlflow-skinny>=2.10; extra == "mlops"
Provides-Extra: realtime
Requires-Dist: treelite>=4.0; extra == "realtime"
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-ml4

**ml4** is the training engine of [ParleML](https://parleml.com), the machine learning platform
built to be driven by AI agents. It turns a table into a deployable model: feature engineering,
training on [AutoGluon](https://auto.gluon.ai), then calibration, thresholds and honesty checks.
Free to use, including commercial use.

```bash
pip install parleml-ml4
```

```python
import parleml_ml4

cfg = parleml_ml4.Ml4Config()
cfg.data.target_column = "churned"                     # the column you want to predict
model = parleml_ml4.AutoSupervised(cfg).fit(train_df)  # plan features, train, calibrate
risk = model.predict_proba(new_customers)              # one column per class
model.save("out/churn")
```

`fit` returns a `FittedPipeline`: the trained model plus everything it needs to score new rows,
with the scikit-learn `predict` / `predict_proba` interface.

## One entry point per kind of work

| Task | Entry point |
| --- | --- |
| Classification and regression | `parleml_ml4.AutoSupervised` |
| Time-series forecasting | `parleml_ml4.forecasting.Forecaster` |
| Anomaly detection | `parleml_ml4.unsupervised.AnomalyDetector` |
| Clustering | `parleml_ml4.unsupervised.ClusteringDetector` |
| Recommendation (next best product) | `parleml_ml4.recommendation.Recommender` |
| Learning-to-rank | `parleml_ml4.ltr.LTRRanker` |
| Association rules (market basket) | `parleml_ml4.association.AssociationMiner` |

## What it adds to AutoGluon

- **Leakage-safe feature engineering.** Domain parsers (IP and geography, emails, names, user
  agents, addresses, postal codes, phone, card, IBAN and VAT numbers, dates), target encodings,
  interactions and text encoders. Target-aware features are refitted inside every fold.
- **A post-fit layer.** Calibration, decision-threshold tuning, prediction intervals and a check
  against a constant baseline, refittable without retraining.
- **Regulated models.** Glass-box models (GLM, scorecard, RuleFit, EBM), derived monotonic
  constraints, and presets such as `regulated_glassbox` and `regulated_monotonic`.
- **Forecasting with four backends.** Statistical, tree, the Chronos foundation model and
  AutoGluon-TimeSeries, with per-series validation and conformal intervals.
- **Hyperparameter search with one owner you choose:** ml4's Optuna search, AutoGluon's, or good
  defaults with no search.

Its partner [`parleml-mli`](https://pypi.org/project/parleml-mli/) explains the models ml4 builds.

## 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. The core includes AutoGluon Tabular,
PyTorch, the tree boosters, the glass-box models, association mining and anomaly detection.
Add extras for the rest:

| Extra | Enables |
| --- | --- |
| `forecasting` | Forecasting (statsforecast and the tree backend's search) |
| `forecasting-autogluon` | AutoGluon-TimeSeries and Chronos; install together with `forecasting` |
| `unsupervised` | UMAP and text embeddings for clustering |
| `ltr` | Hyperparameter search for learning-to-rank |
| `embeddings` | Local neural text embeddings (`sentence-transformers`) |
| `mlops` | MLflow logging and registration |
| `realtime` | The Treelite fast-scoring accelerator |

```bash
pip install "parleml-ml4[forecasting,forecasting-autogluon]"
```

PyTorch comes from PyPI: the CPU build on Windows, the CUDA build on Linux. For a CPU-only Linux
install, run `pip install torch --index-url https://download.pytorch.org/whl/cpu` first.

IP geolocation reads MaxMind GeoLite2 databases, which you download yourself and point
`MAXMIND_DB_DIR` at; they are not shipped, for licensing reasons.

## Documentation

- [The ml4 documentation](https://parleml.com/help/ml4/): installation, quickstart, guides, every
  configuration parameter and the API reference.
- [ParleML](https://parleml.com) and [its manual](https://parleml.com/help/): the platform, and
  using its models from Python. 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.
