Metadata-Version: 2.4
Name: regrelio
Version: 0.1.2
Summary: Outil automatisé pour l'évaluation textuelle et la comparaison de Modèles de Langage (LLMs)
Author: Thomas
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Drescargot/regrelio
Project-URL: Repository, https://github.com/Drescargot/regrelio
Project-URL: Issues, https://github.com/Drescargot/regrelio/issues
Keywords: llm,nlp,evaluation,benchmark,regression,fine-tuning,quantization,ml
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rapidfuzz>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: llm
Requires-Dist: torch>=2.0.0; extra == "llm"
Requires-Dist: transformers>=4.30.0; extra == "llm"
Requires-Dist: accelerate>=0.20.0; extra == "llm"
Provides-Extra: quant
Requires-Dist: bitsandbytes>=0.40.0; extra == "quant"
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.20.0; extra == "dashboard"
Requires-Dist: matplotlib>=3.7.0; extra == "dashboard"
Requires-Dist: numpy>=1.23.0; extra == "dashboard"
Requires-Dist: pandas>=1.5.0; extra == "dashboard"
Provides-Extra: all
Requires-Dist: torch>=2.0.0; extra == "all"
Requires-Dist: transformers>=4.30.0; extra == "all"
Requires-Dist: accelerate>=0.20.0; extra == "all"
Requires-Dist: bitsandbytes>=0.40.0; extra == "all"
Requires-Dist: streamlit>=1.20.0; extra == "all"
Requires-Dist: matplotlib>=3.7.0; extra == "all"
Requires-Dist: numpy>=1.23.0; extra == "all"
Requires-Dist: pandas>=1.5.0; extra == "all"
Dynamic: license-file

# 🧪 Regrelio

Un outil puissant et automatisé pour l'évaluation textuelle et la comparaison de Modèles de Langage (LLMs).
Destiné aux chercheurs et ingénieurs ML, **Regrelio** permet d'identifier les régressions de performance (catastrophic forgetting) lors du fine-tuning, d'évaluer l'impact des techniques de quantification (quantization) et de monitorer l'évolution de vos modèles via un dashboard interactif.

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](#)
[![CI](https://github.com/Drescargot/regrelio/actions/workflows/ci.yml/badge.svg)](https://github.com/Drescargot/regrelio/actions/workflows/ci.yml)

## 🎯 Pourquoi cet outil ?

Lors de l'entraînement (Fine-Tuning, DPO, RLHF) d'un LLM pour spécialiser ses compétences, il est fréquent qu'il "oublie" ses capacités générales (raisonnement, code, logique mathématique).
Ce projet permet de :
1. **Comparer un modèle de base et un modèle fine-tuné** sur un ensemble configurable de benchmarks (JSON).
2. **Scanner la dégradation liée à la quantification** (fp16 vs 8bit vs 4bit).
3. **Bloquer une pipeline CI/CD** (via des seuils configurables et un *golden benchmark*) en cas de régression critique.
4. **Visualiser les résultats** grâce à une interface Streamlit intuitive.

## ✨ Fonctionnalités clés

- ⚖️ **Comparaison A/B Automatique** : Évaluez Base vs Fine-tuned avec génération locale (`compare.py main`).
- 🧮 **Scan Quantization** : Mesurez le compromis entre perte de performance et gain de vitesse (TPS) sur différentes quantifications fp16, 8bit, et 4bit.
- 👨‍⚖️ **LLM-as-a-Judge & Exact Match** : Supporte l'évaluation par règles strictes (regex, rapidfuzz), exécution de code isolée via subprocess + timeout (non sandboxée), et LLM externe agissant comme juge (via OpenAI ou Ollama).
- 🚀 **Intégration CI/CD** : Détection de régression avec marge d'erreur, et "Golden Gate" limitant le déploiement.
- 📈 **Dashboard Streamlit Local** : Affichez et analysez graphiquement les différences de metrics et temps de réponse.
- ⚡ **Optimisation** : Générations en batch batching, hashing SHA-256 pour caching local et gestion de timeouts.

## 📁 Structure du Projet

```text
regrelio/
├── benchmarks/         # Outils d'évaluation sous forme JSON (golden, reasoning, code...)
├── dashboard/          # Application front-end interactive (Streamlit)
│   └── app.py
├── metrics/            # Algorithmes de matching exact, fuzzy, et exécution
│   ├── judge.py        # LLM-as-a-Judge (OpenAI / Ollama Local)
│   └── scorer.py       # Metrics classiques et execution de code
├── models/             
│   └── loader.py       # Pipeline HuggingFace (BitsAndBytes, Accelerate, Torch)
├── results/            # Fichiers de dump (JSON, MD et données de cache)
└── compare.py          # Point d'Entrée CLI Typer 
```

## 🛠️ Installation

### Option rapide (PyPI)

```bash
# Installe tout (LLM + quantization + dashboard)
pip install regrelio[all]
```

Autres variantes utiles :

```bash
# Juste le coeur (sans LLM)
pip install regrelio

# LLM (torch + transformers)
pip install regrelio[llm]

# LLM + quantization
pip install regrelio[llm,quant]

# Dashboard uniquement
pip install regrelio[dashboard]
```

### Option dev (depuis le repo)

```bash
# 1. Cloner le repository
git clone https://github.com/Drescargot/regrelio.git
cd regrelio

# 2. Créer un environnement virtuel
python -m venv .venv
source .venv/bin/activate  # Sous Windows: .venv\Scripts\activate

# 3. Installer les dépendances
pip install --upgrade pip
pip install -e .[llm,quant,dashboard,dev]
```
*Note : Un GPU NVIDIA avec support CUDA est fortement recommandé.*

## 🚀 Utilisation

L'outil repose sur la CLI multi-commandes `compare.py`. Voici un tableau récapitulatif des commandes en fonction de ce que vous souhaitez accomplir :

### 🎯 Que souhaitez-vous faire ? (Guide Rapide)

| Objectif / Cas d'usage | Commande Complète | Description |
|------------------------|-------------------|-------------|
| **Comparer 2 modèles (A/B Test)** | `regrelio main --base-model "X" --ft-model "Y"` | Détecte les régressions entre un modèle de base et son fine-tune via Exact Match. |
| **Évaluation Sémantique (LLM Judge)** | `regrelio main --judge --judge-backend ollama` | Utilise un LLM (Ollama ou OpenAI) pour noter des réponses abstraites (résumé, traduction). |
| **Sécuriser une CI/CD (Golden Gate)** | `regrelio main --strict-golden` | Échoue le pipeline (Exit Code 1) si un benchmark critique (golden) régresse ou est raté. |
| **Analyser l'impact Quantization** | `regrelio scan-quantization --model "X" --modes "fp16,8bit,4bit"` | Mesure le compromis entre perte de score et gain de vitesse (TPS) de la quantification. |
| **Explorer les données (Dashboard)** | `regrelio serve` | Interface graphique Streamlit interactive pour visualiser les deltas et performances. |

---

### 1. Détail : Comparaison Base vs Fine-Tuned (A/B Test)

Générez un rapport détaillé comparant un modèle base et un tune.
En cas de régression forte (par défaut configurable) ou si le `--strict-golden` est activé, un Exit Code `1` est envoyé (pratique pour vos CI/CD).

```bash
regrelio main \
  --base-model "TinyLlama/TinyLlama-1.1B-Chat-v1.0" \
  --ft-model "MonSuperModele-FineTune-1.1B" \
  --benchmarks "reasoning,code,golden"
```

> **💡 Note pour les modèles privés :** Vous pouvez tout à fait utiliser des modèles propriétaires téléchargés ou entraînés localement sans accès à internet. Il suffit de donner le chemin vers le dossier contenant le modèle (ex: `--base-model "./mes_poids/model_v1" --ft-model "/mnt/data/model_v2_finetuned"`).

**Options notables:**
- `--batch-size N` : Parallélisez la génération localement.
- `--cache` : Active le cache des résultats inférés pour itérer vite.
- `--judge` : Active l'évaluation sémantique complexe par appel externe (OpenAI/Ollama).

### 2. LLM-as-a-Judge (Évaluation sémantique)

Pour exploiter LLM as a Judge au lieu d'Exact Matchs traditionnels sur des tâches abstraites :

```bash
regrelio main --judge \
  --judge-backend openai \
  --judge-model gpt-4o-mini \
  --judge-types summary,translation,tone
```

*(Identique avec un backend Local via `ollama`)*

### 3. Scan Dégradation de Quantization

Visualisez ce que coûte réellement la quantification (Loss vs Vitesse TPS) : 

```bash
regrelio scan-quantization \
  --model Qwen/Qwen2-1.5B \
  --modes "fp16,8bit,4bit" \
  --benchmarks "reasoning,code"
```

### 4. Lancer le Dashboard interactif Streamlit

Ouvrez une interface visuelle pour explorer en détail les révisions générées.

```bash
regrelio serve --results-dir results --port 8501
```

## 📝 Créer ses propres benchmarks

Insérez simplement un JSON dans `/benchmarks`. 
*Exemple (`benchmarks/math.json`)* :

```json
[
  {
    "id": "m01",
    "type": "math",
    "prompt": "Combien font 7 + 5 ? Réponds uniquement le nombre.",
    "expected_answer": "12"
  }
]
```

## 🤝 Contribution & Support
Les Pull Requests (nouveaux scoreurs, optimisations vLLM) sont les bienvenues. N'hésitez pas à ouvrir un Ticket !

## 📜 Licence
Apache 2.0
