Metadata-Version: 2.4
Name: lecrapaud
Version: 2.8.0
Summary: Framework for machine and deep learning, with regression, classification and time series analysis
License: Apache License
License-File: LICENSE
Author: Pierre H. Gallet
Requires-Python: ==3.12.*
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Provides-Extra: all
Provides-Extra: boosting
Provides-Extra: deep
Provides-Extra: explain
Provides-Extra: hpo
Provides-Extra: openai
Requires-Dist: alembic (>=1.18.4)
Requires-Dist: catboost (>=1.2.10)
Requires-Dist: category-encoders (>=2.9.0)
Requires-Dist: ftfy (>=6.3.1)
Requires-Dist: hyperopt (>=0.2.7)
Requires-Dist: joblib (>=1.5.3)
Requires-Dist: lecrapaud[deep] ; extra == "all"
Requires-Dist: lecrapaud[hpo] ; extra == "all"
Requires-Dist: lightgbm (>=4.6.0)
Requires-Dist: lime (>=0.2.0.1)
Requires-Dist: matplotlib (>=3.10.9)
Requires-Dist: mlxtend (>=0.23.4,<0.24)
Requires-Dist: numpy (>=1.26,<2.3)
Requires-Dist: openai (>=2.37.0)
Requires-Dist: pandas (>=2.2.3,<3)
Requires-Dist: pillow (>=12.2.0)
Requires-Dist: psycopg2-binary (>=2.9.12)
Requires-Dist: pyarrow (>=14.0.0)
Requires-Dist: pydantic (>=2.13.4)
Requires-Dist: pymysql (>=1.2.0)
Requires-Dist: python-dotenv (>=1.2.2)
Requires-Dist: pytorch-lightning (>=2.6.1) ; extra == "deep"
Requires-Dist: pytorch-tabnet (>=4.1.0) ; extra == "deep"
Requires-Dist: ray[tune] (>=2.55.1) ; extra == "hpo"
Requires-Dist: requests (>=2.34.2)
Requires-Dist: rtdl-revisiting-models (>=0.0.2) ; extra == "deep"
Requires-Dist: safetensors (>=0.7.0) ; extra == "deep"
Requires-Dist: scikit-learn (>=1.6.1)
Requires-Dist: scipy (>=1.17.1)
Requires-Dist: seaborn (>=0.13.2)
Requires-Dist: sentry-sdk (>=2.60.0)
Requires-Dist: setuptools (<81)
Requires-Dist: shap (>=0.51.0)
Requires-Dist: sqlalchemy (>=2.0.49)
Requires-Dist: statsmodels (>=0.14.6)
Requires-Dist: tabulate (>=0.10.0)
Requires-Dist: tiktoken (>=0.13.0)
Requires-Dist: torch (>=2.12.0) ; extra == "deep"
Requires-Dist: tqdm (>=4.67.3)
Requires-Dist: xgboost (>=3.2.0)
Description-Content-Type: text/markdown

<div align="center">

<img src="https://em-content.zobj.net/source/apple/129/frog-face_1f438.png" width=120 alt="crapaud"/>

## 🐸 LeCrapaud

**An all-in-one machine learning framework**

[![PyPI version](https://badge.fury.io/py/lecrapaud.svg)](https://badge.fury.io/py/lecrapaud)
[![Python versions](https://img.shields.io/pypi/pyversions/lecrapaud.svg)](https://pypi.org/project/lecrapaud)
[![Documentation](https://img.shields.io/badge/docs-lecrapaud.pierregallet.com-green)](https://lecrapaud.pierregallet.com)

</div>

---

LeCrapaud is a high-level Python library for end-to-end machine learning on tabular and time series data. It handles feature engineering, model selection, training, and prediction in one command.

### Key Features

- 🔄 **End-to-end ML pipeline** — feature engineering, preprocessing, feature selection, hyperparameter optimization, and training in a single `fit()` call
- 🤖 **11+ models** — from Linear Regression to XGBoost, LightGBM, CatBoost, and deep learning architectures (LSTM, GRU, TCN, Transformer)
- 🎯 **Automated feature selection** — ensemble of 10+ methods (Chi2, ANOVA, Mutual Information, SHAP, RFE, etc.)
- ⚡ **Hyperparameter optimization** — HyperOpt (TPE) and Ray Tune with cross-validation support
- 🔍 **Explainability** — built-in SHAP, LIME, feature importance, and tree visualization
- 🗄️ **Experiment tracking** — every experiment is stored in the database (PostgreSQL or MySQL) with full reproducibility
- 🧩 **Modular** — use the full pipeline or individual components (FeatureEngineer, FeaturePreprocessor, FeatureSelector) in sklearn-compatible pipelines

## Why LeCrapaud?

Most ML tools solve **one piece** of the puzzle. LeCrapaud handles the **entire workflow** in a single `fit()` call.

| | LeCrapaud | MLflow | scikit-learn | Auto-sklearn / TPOT |
|---|:---:|:---:|:---:|:---:|
| Feature engineering | ✅ Automated (Fourier dates, target encoding, imputation) | ❌ Manual | ❌ Manual | ❌ Generic only |
| Feature selection | ✅ Ensemble of 10+ methods with voting | ❌ Manual | ❌ One method at a time | ⚠️ Implicit |
| Hyperparameter optimization | ✅ HyperOpt + Ray Tune | ❌ Manual | ⚠️ GridSearchCV | ✅ Built-in |
| Multi-target support | ✅ Native (regression + classification) | ❌ | ❌ | ❌ |
| Deep learning models | ✅ LSTM, GRU, TCN, Transformer | ❌ | ⚠️ MLP only | ❌ |
| Time series support | ✅ Fourier features, temporal CV, RNNs | ❌ | ⚠️ Basic | ❌ |
| Explainability | ✅ SHAP + LIME + feature importance | ❌ | ⚠️ Feature importance only | ❌ |
| Experiment tracking | ✅ Full artifacts in PostgreSQL/MySQL | ✅ Tracking server | ❌ | ❌ |
| Reproducibility | ✅ Reload any experiment with `get(id=...)` | ✅ | ❌ | ⚠️ |
| sklearn compatibility | ✅ fit/transform pattern | ❌ | ✅ Native | ✅ |

**In short:**

- **MLflow** tracks experiments but doesn't train models or engineer features — you still write all the ML code yourself
- **scikit-learn** provides building blocks but requires manual pipeline composition, no experiment tracking, and limited model support
- **AutoML tools** (auto-sklearn, TPOT) automate model selection but act as black boxes with no feature engineering transparency, no explainability, and no time series support
- **LeCrapaud** combines automated feature engineering, ensemble feature selection, hyperparameter optimization, multi-target training, explainability, and experiment tracking — all in one `fit()` call, while remaining transparent and customizable

## Prerequisites

- **Python 3.12** (strictly required)
- **PostgreSQL** or **MySQL** database for experiment storage
- **macOS only** — [libomp](https://formulae.brew.sh/formula/libomp) for LightGBM/XGBoost:
  ```sh
  brew install libomp
  ```

## Installation

### 📦 From PyPI (recommended)

Install the latest stable release:

```sh
pip install lecrapaud
```

Or pin a specific version:

```sh
pip install lecrapaud==2.5.0
```

### ⚡ Optional extras

The base install ships **scikit-learn, gradient boosting (CatBoost, XGBoost,
LightGBM) and explainability (SHAP, LIME)** — enough to train, tune and explain
a model with nothing else. Two heavy feature sets are opt-in:

| Extra | Install | What it adds |
|---|---|---|
| `deep` | `pip install 'lecrapaud[deep]'` | TabNet, FT-Transformer and the 11 recurrent/transformer architectures (PyTorch + Lightning) |
| `hpo` | `pip install 'lecrapaud[hpo]'` | The Ray Tune optimisation backend (`LECRAPAUD_OPTIMIZATION_BACKEND=ray`). The default backend, HyperOpt, is core |
| `all` | `pip install 'lecrapaud[all]'` | Both |

Requesting a model or backend whose extra is missing raises an error naming
exactly what to install — nothing fails silently or at import time.

### 🗄️ Database

LeCrapaud persists experiments, models and artifacts to a database. Point it at
one with `DB_URI` (PostgreSQL or MySQL), or `DB_USER`/`DB_PASSWORD`/`DB_HOST`/
`DB_PORT`/`DB_NAME`.

**With no configuration at all**, it falls back to a local SQLite store at
`~/.lecrapaud/lecrapaud.db` so you can try it out immediately, and says so on
startup. Move that store to a real database whenever you are ready:

```python
from lecrapaud.db import export_to
export_to("postgresql://user:pass@host:5432/lecrapaud")
```

The fallback triggers **only** when no database variable is set at all — a
partial or wrong configuration still fails loudly, so a broken deploy is never
silently redirected to a local file. Set `LECRAPAUD_NO_SQLITE_FALLBACK=1` to
disable it entirely.

### 🔧 From source

Install the latest development version directly from GitHub:

```sh
pip install git+https://github.com/PierreGallet/lecrapaud.git
```

Or clone the repository and install locally:

```sh
git clone https://github.com/PierreGallet/lecrapaud.git
cd lecrapaud
pip install .
```

## Quick Start

```python
from lecrapaud import LeCrapaud

LeCrapaud.set_uri("mysql+pymysql://user:password@host:port/dbname")

lc = LeCrapaud(
    experiment_name="my_experiment",
    target_numbers=[1],
    target_clf=[1],
    models_idx=["lgb", "xgb"],
)

lc.fit(data)
predictions = lc.predict(new_data)
# eval scores (when new_data has TARGET columns): lc.regression_scores / lc.classification_scores
```

## Documentation

Full documentation available at **[lecrapaud.pierregallet.com](https://lecrapaud.pierregallet.com)**

## Contributing

Contributions are welcome! Here's how to get started.

### Development Setup

```sh
git clone https://github.com/PierreGallet/lecrapaud.git
cd lecrapaud
python3.12 -m venv .venv
source .venv/bin/activate
make install
```

Development tooling lives in [PEP 735](https://peps.python.org/pep-0735/)
dependency groups, not in the runtime dependencies — so `pip install lecrapaud`
never pulls a linter, a test runner or a doc builder:

| Group | Contents | Install |
|---|---|---|
| `dev` | black, flake8, pylint, mypy, bandit, safety, poetry, pipdeptree | default |
| `test` | pytest, pytest-cov, pytest-mock, coverage | default |
| `docs` | mkdocs + material, mkdocstrings, gen-files, literate-nav, section-index | `uv sync --group docs` |
| `notebook` | ipykernel, ipywidgets | `uv sync --group notebook` |

A bare `uv sync` gives you `dev` + `test`. Add a runtime dependency in
`requirements.in`; add tooling in the matching `requirements-<group>.in`, and
`make install` routes it to the right place.

### Workflow

1. **Open an issue** first to discuss the change you'd like to make
2. **Fork the repo** and create a branch from `main`:
   - `feat/your-feature` for new features
   - `fix/your-bugfix` for bug fixes
   - `docs/your-change` for documentation
3. **Write or update tests** when changing behavior
4. **Run the test suite** before submitting:
   ```sh
   make test
   ```
5. **Open a Pull Request** against `main` with a clear description

### Commit Convention

We use [Conventional Commits](https://www.conventionalcommits.org/). Every commit message and PR title must follow this format:

```
type: short description
```

| Type | Usage |
|------|-------|
| `feat:` | New feature |
| `fix:` | Bug fix |
| `docs:` | Documentation only |
| `refactor:` | Code change that neither fixes a bug nor adds a feature |
| `test:` | Adding or updating tests |
| `perf:` | Performance improvement |
| `ci:` | CI/CD changes |
| `chore:` | Maintenance tasks |

Examples:
```
feat: add catboost model support
fix: handle missing target column in predict
docs: update getting started guide
```

### Guidelines

- Keep PRs focused and small — one concern per PR
- Update documentation when APIs change
- Follow the existing code style
- All tests must pass before merging

## License

LeCrapaud is licensed under the [Apache License 2.0](LICENSE). You are free to use, modify, and distribute this software in compliance with the license terms.

---

Pierre Gallet 2025

## Bases locales (Docker)

Prérequis : **Docker** (Desktop ou OrbStack). Rien d'autre — ni serveur ni
client Homebrew. Les cibles Make exécutent les clients (`psql`, `createdb`,
`mysql`…) **dans les conteneurs**, qui les embarquent déjà.

`docker-compose.dev.yml` déclare deux conteneurs MySQL : un pour le dev
(volume nommé, les données survivent à `make db-down`) et un pour les tests
(sans volume, jetable). Serveur en `utf8mb4` / `utf8mb4_unicode_ci`.

| Cible | Effet |
|---|---|
| `make db-up` | démarre les conteneurs et attend les healthchecks |
| `make db-down` | arrête (les données de dev sont conservées) |

`make test-db-setup` dépend de `db-up` : rien à démarrer à la main avant les
tests.

### Ports

Ports décalés par rapport aux valeurs par défaut (5432 / 3306 / 6379), pour
ne pas entrer en conflit avec un serveur déjà installé sur la machine.

| Service | Dev | Test |
|---|---|---|
| mysql | 3309 | 3310 |

Les conteneurs n'écoutent que sur `127.0.0.1`, jamais `0.0.0.0`.

### Viser une base distante

Toutes les variables restent surchargeables : renseigner les endpoints dans
`.env` suffit à pointer une base distante, sans toucher au Makefile.

