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 for LightGBM/XGBoost:
brew install libomp
Installation
📦 From PyPI (recommended)
Install the latest stable release:
pip install lecrapaud
Or pin a specific version:
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:
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:
pip install git+https://github.com/PierreGallet/lecrapaud.git
Or clone the repository and install locally:
git clone https://github.com/PierreGallet/lecrapaud.git
cd lecrapaud
pip install .
Quick Start
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
Contributing
Contributions are welcome! Here's how to get started.
Development Setup
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
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
- Open an issue first to discuss the change you'd like to make
- Fork the repo and create a branch from
main:feat/your-featurefor new featuresfix/your-bugfixfor bug fixesdocs/your-changefor documentation
- Write or update tests when changing behavior
- Run the test suite before submitting:
make test
- Open a Pull Request against
mainwith a clear description
Commit Convention
We use Conventional Commits. 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. 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à.
Une seule commande : make db-up. Elle s'adapte à ce qui tourne déjà.
| Situation | Ce qu'elle fait |
|---|---|
| rien n'écoute sur 3306 | démarre le conteneur de ce dépôt, puis crée les bases |
| un serveur répond déjà sur 3306 | n'y touche pas, y ajoute les bases manquantes |
Le second cas couvre aussi bien un MySQL personnel préexistant qu'un serveur mutualisé entre plusieurs dépôts. Relancer la commande ne détruit jamais de données : les créations sont idempotentes.
docker-compose.dev.yml déclare un seul serveur MySQL hébergeant les
deux bases, et non deux conteneurs comme précédemment. Serveur en
utf8mb4 / utf8mb4_unicode_ci.
| Cible | Effet |
|---|---|
make db-up |
prépare les bases, quel que soit ce qui tourne déjà |
make db-down |
arrête le conteneur de ce dépôt (sans effet s'il n'en a pas créé) |
make test-db-setup dépend de db-up : rien à démarrer à la main avant les
tests.
Ports et bases
| Service | Port | Bases |
|---|---|---|
| mysql | 3306 | lecrapaud_dev · lecrapaud_test |
Le port standard, et non un port décalé : le script détecte un serveur existant au lieu d'essayer de l'éviter. Les deux bases vivent dans le même serveur, donc une seule connexion suffit dans un client graphique.
Le conteneur n'écoute que sur 127.0.0.1, jamais 0.0.0.0.
Utilise
127.0.0.1, jamaislocalhost: le client MySQL traitelocalhostcomme une socket Unix et ignore le port.
Viser une base distante
Toutes les variables restent surchargeables : renseigner les endpoints dans
.env suffit à pointer une base distante, sans toucher au Makefile.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file lecrapaud-2.10.0.tar.gz.
File metadata
- Download URL: lecrapaud-2.10.0.tar.gz
- Upload date:
- Size: 303.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b4c5d1698aaf3cc5156ffdee631d9ae893bed7a5e7655ff8e8fe16776c2b30f0
|
|
| MD5 |
862cdf0851bf15dbc49669305b6994f9
|
|
| BLAKE2b-256 |
89ea1da37098e83356b8202a14659033a8f08f3c05294d7083d97006607bd37c
|
File details
Details for the file lecrapaud-2.10.0-py3-none-any.whl.
File metadata
- Download URL: lecrapaud-2.10.0-py3-none-any.whl
- Upload date:
- Size: 359.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
aaf5ef255931f3b6014002c2fbd5a6557e31389c382211d15471d90db9441e65
|
|
| MD5 |
f3bc08c6900f0237d0ab39e78a97a412
|
|
| BLAKE2b-256 |
95b8803b0441a3b1ba65e68a50dea90433483414b7452628eebd52e4c0967eb0
|
