Metadata-Version: 2.4
Name: helm-xai
Version: 0.2.0rc4
Summary: HELM : explications adaptées au profil pour la modération de contenus, avec interface locale et extension tabulaire expérimentale
Author-email: Kossi Folly <follyametepkossi@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Kossi Folly
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/KossiFO/helm-xai
Project-URL: Issues, https://github.com/KossiFO/helm-xai/issues
Project-URL: Releases, https://github.com/KossiFO/helm-xai/releases
Keywords: xai,explainability,content-moderation,toxicity,lime,shap,bandit
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
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
Classifier: Natural Language :: French
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2,>=1.24
Requires-Dist: scipy>=1.11
Requires-Dist: scikit-learn>=1.3
Requires-Dist: pandas>=2.0
Requires-Dist: lime>=0.2.0.1
Requires-Dist: shap<0.50,>=0.43
Provides-Extra: text
Requires-Dist: torch>=2.1; extra == "text"
Requires-Dist: transformers<5,>=4.35; extra == "text"
Requires-Dist: tokenizers>=0.15; extra == "text"
Requires-Dist: protobuf<5; extra == "text"
Provides-Extra: ui
Requires-Dist: fastapi<1,>=0.115; extra == "ui"
Requires-Dist: uvicorn<1,>=0.30; extra == "ui"
Requires-Dist: platformdirs<5,>=4; extra == "ui"
Provides-Extra: ig
Requires-Dist: captum>=0.7; extra == "ig"
Provides-Extra: anchors
Requires-Dist: anchor-exp>=0.0.2; extra == "anchors"
Requires-Dist: spacy<4,>=3.7; extra == "anchors"
Provides-Extra: notebook
Requires-Dist: ipywidgets<9,>=8; extra == "notebook"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == "viz"
Requires-Dist: seaborn>=0.13; extra == "viz"
Provides-Extra: models
Requires-Dist: helm-xai[text]; extra == "models"
Requires-Dist: accelerate>=0.24; extra == "models"
Requires-Dist: sentencepiece>=0.1.99; extra == "models"
Requires-Dist: datasets>=2.14; extra == "models"
Provides-Extra: dev
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: httpx<1,>=0.27; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: all
Requires-Dist: helm-xai[anchors,ig,models,notebook,text,ui,viz]; extra == "all"
Dynamic: license-file

# HELM — explications adaptées au profil

HELM (`helm-xai`) est une bibliothèque Python d’explicabilité pour la classification
de textes, en particulier la modération de contenus. Elle propose des explications
adaptées aux profils utilisateur, modérateur, expert technique et régulateur.
Une extension expérimentale prend en charge les classifieurs tabulaires.

## Installation

Python **3.10 à 3.12**. Pour installer la bibliothèque et son interface locale :

```bash
python -m pip install "helm-xai[ui]==0.2.0rc4"
helm-ui
```

Le navigateur ouvre `http://127.0.0.1:8767/`. Choisir un profil, saisir un commentaire
et cliquer sur **Expliquer**. La wheel inclut l’interface ; Node.js n’est pas requis.
Pour un autre port : `helm-ui --port 8771`. Arrêter le serveur avec Ctrl+C.

Le modèle de démonstration est entraîné sur **12 phrases synthétiques**. Il permet
d’essayer le parcours, mais ne constitue pas un détecteur de toxicité validé.
L’interface utilise les poids des modèles de texte déjà présents dans le cache
local ; elle ne les télécharge pas.

## Utilisation Python

```python
from helm import HELMPipeline, UserProfile
from helm.ui.models import DemoModel

pipeline = HELMPipeline(model_name="demo", model=DemoModel().load())
resultat = pipeline.explain(
    "Merci pour cette réponse utile",
    user_profile=UserProfile.END_USER,
    evaluate=True, num_features=8, evaluation_k=3,
)
print(resultat.prediction)
print(resultat.formatted_output.summary)
```

Le profil désigne le destinataire de l’explication ; il est choisi explicitement.
HELM ne déduit pas le profil de la personne à partir de son commentaire.

## Fonctionnalités

- Sélection et présentation d’explications par profil, avec backends effectivement exécutés identifiés.
- Attributions, règles locales et recherches de contrefactuels, selon les méthodes et dépendances disponibles.
- Interface locale avec historique, export JSON et avis liés à chaque explication individuelle.
- Extension `TabularHELM` pour les modèles scikit-learn avec `predict_proba`, variables numériques et catégorielles, classement des scores et sorties HTML par profil.

Les analyses restent dans le dossier de données utilisateur `helm-xai` de la
machine qui lance le serveur. `helm-ui --data-dir ./mes-analyses` permet de le changer.

## Dépendances optionnelles

| Extra | Usage |
|---|---|
| `ui` | Interface locale |
| `text` | Modèles de texte avec PyTorch et Transformers |
| `ig` | Integrated Gradients via Captum |
| `anchors` | Backend Anchors natif |
| `notebook` | Widgets Jupyter |
| `dev` | Outils de test et de construction |

Pour un modèle de texte et ces explicateurs :
`python -m pip install "helm-xai[text,ig,anchors,notebook]==0.2.0rc4"`.
Les poids des modèles sont à obtenir séparément, selon leurs licences.

## Documentation et exemples

- [API et fonctionnement](https://github.com/KossiFO/helm-xai/blob/codex/publication/implementation_v2/README.md)
- [Exemple tabulaire synthétique](https://github.com/KossiFO/helm-xai/blob/codex/publication/examples/tabular_usage.py)
- [Développement et tests](https://github.com/KossiFO/helm-xai/blob/codex/publication/docs/DEVELOPPEMENT.md)
- [Notes de version](https://github.com/KossiFO/helm-xai/blob/codex/publication/docs/RELEASE_0.2.0rc4_v1_2026-10-05.md)

## Périmètre et licence

**Version candidate de recherche.** Les tests logiciels vérifient les parcours et
les calculs sur des cas contrôlés ; ils ne constituent pas une validation humaine.
L’extension tabulaire est expérimentale et la compatibilité Databricks reste à
vérifier sur le Runtime cible. L’interface locale n’est pas un service d’étude hébergé.

Les explications décrivent le comportement du modèle, sans établir de causalité.
Les scores de méthodes différentes ne sont pas moyennés. Les métriques de fidélité
ne mesurent pas la satisfaction des utilisateurs.

Code sous [licence MIT](https://github.com/KossiFO/helm-xai/blob/codex/publication/LICENSE).
Les bibliothèques et modèles tiers conservent leurs licences respectives.
