Metadata-Version: 2.4
Name: kabena
Version: 2.1.1
Summary: K-ABENA : exclusion compensée d'échantillons par perte — même modèle, ~28% de calcul en moins (estimateur Horvitz-Thompson sans biais).
Author-email: Jean-Francois Bonbhel <bonbhel@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Bonbhel/kabena-ml
Project-URL: Documentation, https://github.com/Bonbhel/kabena-ml/tree/main/tutorials
Project-URL: Tutorials, https://github.com/Bonbhel/kabena-ml/tree/main/tutorials
Project-URL: Reproducibility, https://github.com/Bonbhel/kabena-ml/tree/main/validation
Project-URL: Preprint, https://arxiv.org/abs/2607.05903
Project-URL: Changelog, https://github.com/Bonbhel/kabena-ml/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Bonbhel/kabena-ml/issues
Keywords: machine-learning,selective-backpropagation,sample-selection,horvitz-thompson,sgd
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.22
Provides-Extra: sklearn
Requires-Dist: scikit-learn>=1.3; extra == "sklearn"
Provides-Extra: torch
Requires-Dist: torch>=2.3; (sys_platform != "darwin" or platform_machine == "arm64") and extra == "torch"
Requires-Dist: torch<2.3,>=2.0; (sys_platform == "darwin" and platform_machine == "x86_64") and extra == "torch"
Requires-Dist: numpy<2,>=1.22; (sys_platform == "darwin" and platform_machine == "x86_64") and extra == "torch"
Provides-Extra: tensorflow
Requires-Dist: tensorflow>=2.15; extra == "tensorflow"
Provides-Extra: huggingface
Requires-Dist: transformers>=4.40; extra == "huggingface"
Requires-Dist: datasets>=2.19; extra == "huggingface"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: scikit-learn>=1.3; extra == "dev"
Dynamic: license-file

# kabena — K-ABENA (v2.1.0)

[![PyPI](https://img.shields.io/pypi/v/kabena.svg)](https://pypi.org/project/kabena/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://pypi.org/project/kabena/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/Bonbhel/kabena-ml/blob/main/LICENSE)
[![Preprint](https://img.shields.io/badge/preprint-PDF-red.svg)](https://github.com/Bonbhel/kabena-ml/blob/main/paper/KABENA_v3_preprint.pdf)

**Même modèle, ~28 % de calcul en moins.** K-ABENA exclut à chaque époque une
partie des exemples déjà appris et fait *voter chaque exemple conservé au nom
des dispensés* (repondération Horvitz-Thompson) : le gradient reste
design-unbiased — preuves et mesures dans le
[preprint](https://github.com/Bonbhel/kabena-ml/blob/main/paper/KABENA_v3_preprint.pdf).

## La promesse : 2 lignes

**EN —** Note: the threshold *K* from the paper is **not** a constructor
argument — it is recomputed internally at every `select()` call. The knob
you tune is `k_percentile` (default `40.0`).

**FR —** Note : le seuil *K* du papier n'est **pas** un argument du
constructeur — il est recalculé en interne à chaque appel de `select()`.
ßLe réglage accessible est `k_percentile` (défaut `40.0`).

```python
from kabena import Kabena
kb = Kabena()                                   # 1. défauts du preprint (v3, N=0.3)

for epoch in range(E):
    losses = per_sample_loss(model, X, y)
    active, w = kb.select(losses, y=y)          # 2. masque + poids HT
    model.fit(X[active], y[active], sample_weight=w[active])

print(kb.last_gain_)                            # fraction de calcul économisée
```

PyTorch : `KabenaTorch().reduce(losses)` · Keras : callback `KabenaKeras` ·
Hugging Face : `KabenaTrainer`.

## Trois paramètres, pas un de plus

| Paramètre | Défaut | Rôle |
|---|---|---|
| `N` | `0.3` | proportion de mineures conservées (budget) |
| `strategy` | `"auto"` | `auto`(=v3) / `v3` / `v2` / `v1` — bascule transparente |
| `seed` | `None` | reproductibilité du tirage |

`v2` = mode régularisé optionnel (garde-fou automatique hors zone de
validité) · `v1` = compatibilité 1.x.

## Tutoriels — 4 familles × 3 niveaux

| Famille | Niveau 1 (notebook) | Niveau 2 (script) | Niveau 3 (MLOps) |
|---|---|---|---|
| ML classique (logistique, SVM, softmax) | [notebook](https://github.com/Bonbhel/kabena-ml/blob/main/tutorials/classic_ml/niveau1_notebook.ipynb) | [script](https://github.com/Bonbhel/kabena-ml/blob/main/tutorials/classic_ml/niveau2_script.py) | [train + serve + Docker](https://github.com/Bonbhel/kabena-ml/tree/main/tutorials/classic_ml/niveau3_mlops) |
| MLP / ANN (PyTorch **et** TF/Keras) | [notebook](https://github.com/Bonbhel/kabena-ml/blob/main/tutorials/mlp/niveau1_notebook.ipynb) | [PyTorch](https://github.com/Bonbhel/kabena-ml/blob/main/tutorials/mlp/niveau2_script_pytorch.py) · [TensorFlow](https://github.com/Bonbhel/kabena-ml/blob/main/tutorials/mlp/niveau2_script_tensorflow.py) | [pipeline TorchScript](https://github.com/Bonbhel/kabena-ml/tree/main/tutorials/mlp/niveau3_mlops) |
| CNN (PyTorch **et** TF/Keras) | [notebook](https://github.com/Bonbhel/kabena-ml/blob/main/tutorials/cnn/niveau1_notebook.ipynb) | [PyTorch](https://github.com/Bonbhel/kabena-ml/blob/main/tutorials/cnn/niveau2_script_pytorch.py) · [TensorFlow](https://github.com/Bonbhel/kabena-ml/blob/main/tutorials/cnn/niveau2_script_tensorflow.py) | [SavedModel / TF Serving](https://github.com/Bonbhel/kabena-ml/tree/main/tutorials/cnn/niveau3_mlops) |
| Transformer / NLP (Hugging Face) | [notebook](https://github.com/Bonbhel/kabena-ml/blob/main/tutorials/transformer_nlp/niveau1_notebook.ipynb) | [DistilBERT](https://github.com/Bonbhel/kabena-ml/blob/main/tutorials/transformer_nlp/niveau2_script_huggingface.py) | [fine-tune + serve](https://github.com/Bonbhel/kabena-ml/tree/main/tutorials/transformer_nlp/niveau3_mlops) |

## Reproduire le preprint (Reproducibility)

Chaque table du papier a son script seedé dans
[`validation/`](https://github.com/Bonbhel/kabena-ml/tree/main/validation) :

| Table du preprint | Script |
|---|---|
| Table 1 — jeux réels, parité à coût réduit | [`table1_real_datasets.py`](https://github.com/Bonbhel/kabena-ml/blob/main/validation/table1_real_datasets.py) |
| Table 2 — déséquilibre extrême 0,17 % | [`table2_extreme_imbalance.py`](https://github.com/Bonbhel/kabena-ml/blob/main/validation/table2_extreme_imbalance.py) |
| Table 3 — moments du gradient, bruit | [`table3_moments_noise.py`](https://github.com/Bonbhel/kabena-ml/blob/main/validation/table3_moments_noise.py) |
| Table 4 — rivaux à budget égal (tests de permutation) | [`table4_rivals.py`](https://github.com/Bonbhel/kabena-ml/blob/main/validation/table4_rivals.py) |
| §Sensitivity — grille K × N | [`table5_sensitivity.py`](https://github.com/Bonbhel/kabena-ml/blob/main/validation/table5_sensitivity.py) |

```bash
python validation/run_all.py          # les 5 tables (QUICK=1 pour un smoke test <2 min)
python experiments/playground.py --regime fraude --strategy v3   # bac à sable
```

## Installation

**EN —** `pip install kabena` (core: numpy only, works with numpy 1.22 → 2.x).
Framework extras: `pip install 'kabena[torch]'` (note the quotes — required by
zsh, the default macOS shell). On Intel Macs, torch stops at 2.2.2 and the
extra automatically pins `numpy<2` accordingly; on every other platform the
extra installs torch ≥ 2.3, which supports NumPy 2.

**FR —** `pip install kabena` (cœur : numpy seul, compatible numpy 1.22 → 2.x).
Extras framework : `pip install 'kabena[torch]'` (guillemets obligatoires sous
zsh, le shell par défaut sur Mac). Sur Mac Intel, torch s'arrête à 2.2.2 et
l'extra épingle automatiquement `numpy<2` en conséquence ; sur toute autre
plateforme, l'extra installe torch ≥ 2.3, compatible NumPy 2.


```bash
pip install kabena                     # coeur (numpy seul)
pip install "kabena[sklearn]"          # + helpers scikit-learn
pip install "kabena[torch]"            # + intégration PyTorch
pip install "kabena[tensorflow]"       # + intégration Keras
pip install "kabena[huggingface]"      # + KabenaTrainer
```

Licence MIT — © Jean-François Bonbhel ·
[Changelog](https://github.com/Bonbhel/kabena-ml/blob/main/CHANGELOG.md) ·
[Issues](https://github.com/Bonbhel/kabena-ml/issues)
