---
library_name: transformers
pipeline_tag: text-classification
tags:
  - email
  - text-classification
language:
  - en
---

## mailSort

Repo minimal (Python) pour **entraîner, évaluer et publier** un modèle de classification multi-classes d’e-mails à partir du dataset Hugging Face [`FlowRank/labeled_emails`](https://huggingface.co/datasets/FlowRank/labeled_emails).

Le script principal est `mailsort.train` (Transformers `Trainer`).

### Prérequis

- Python géré par `uv` (ce repo est prévu pour être lancé avec `uv run`)
- (Optionnel) un GPU CUDA si tu veux accélérer l’entraînement
- (Optionnel) un token HF si tu veux publier sur le Hub

### Installation

`uv` installe/synchronise automatiquement les dépendances la première fois.

```bash
uv sync
```

### Entraîner + évaluer (train + test)

Par défaut, le script charge le dataset **depuis le Hub** et utilise ses splits `train` et `test`.
L’évaluation se fait à chaque epoch, puis une évaluation finale est exécutée à la fin.
Les artefacts (modèle, tokenizer) sont sauvegardés dans `outputs/` (ou le dossier passé via `--output-dir`).

```bash
uv run python -m mailsort.train \
  --dataset-id FlowRank/labeled_emails \
  --model-name distilbert-base-uncased \
  --hub-model-id FlowRank/mailSort \
  --num-train-epochs 2
```

### Tester / évaluer uniquement

Le script n’a pas (encore) de mode “eval-only”.
Le **minimum** pour faire uniquement une passe rapide est de mettre `--num-train-epochs 0` (ce qui évite l’entraînement) et de garder la phase `evaluate`.

```bash
uv run python -m mailsort.train --num-train-epochs 0
```

### Évaluer sur le split `test` du dataset (recommandé)

Après ton entraînement dans `outputs/`, tu peux évaluer proprement sur le **split `test`** de `FlowRank/labeled_emails` :

```bash
uv run python -m mailsort.eval --model outputs --dataset-id FlowRank/labeled_emails --split test
```

(Optionnel) Pour un test rapide :

```bash
uv run python -m mailsort.eval --model outputs --split test --max-samples 200
```

### Publier sur le Hub (FlowRank/mailSort)

Le push se fait automatiquement si la variable d’environnement `HF_TOKEN` (ou `HUGGINGFACE_HUB_TOKEN`) est définie.

```bash
export HF_TOKEN="..."
uv run python -m mailsort.train --hub-model-id FlowRank/mailSort
```

### Publier via Git (README à la racine + artefacts dans `model/`)

Pour avoir un repo Hugging Face “complet” (doc + poids) tout en gardant une structure propre, on met :

- `README.md` à la racine (documentation + model card)
- les artefacts (config, poids, tokenizer) dans `model/`

Hugging Face pourra charger le modèle via `subfolder="model"`.

1) Préparer le dossier `model/` à partir de `outputs/` :

```bash
uv run python -m mailsort.prepare_model --outputs-dir outputs --model-dir model
```

2) Commit + push vers le repo Hugging Face `FlowRank/mailSort` :

```bash
git add README.md model
git commit -m "Add model artifacts under model/ + docs"
git push
```

### Inférence (utiliser le modèle publié)

```python
from transformers import AutoModelForSequenceClassification, AutoTokenizer, pipeline

tok = AutoTokenizer.from_pretrained("FlowRank/mailSort", subfolder="model")
model = AutoModelForSequenceClassification.from_pretrained("FlowRank/mailSort", subfolder="model")
clf = pipeline("text-classification", model=model, tokenizer=tok, truncation=True)
text = "Subject: Insurance claim\n\nBody: Hello, I need to update my policy..."
print(clf(text))
```