<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==0.31.7
```

### 🔧 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, scores_reg, scores_clf = lc.predict(new_data)
```

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

### 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
