ai-lab-transformers-playground/POSTMAN_GUIDE.md

# 📮 Collection Postman - AI Lab API

## 📋 Overview

Cette collection Postman complète contient tous les endpoints de l'API AI Lab avec des exemples prêts à utiliser pour tester chaque pipeline NLP.

## 📁 Fichiers inclus

-   **`AI_Lab_API.postman_collection.json`** - Collection principale avec tous les endpoints
-   **`AI_Lab_API.postman_environment.json`** - Environnement avec variables configurables
-   **`POSTMAN_GUIDE.md`** - Ce guide d'utilisation

## 🚀 Installation et Configuration

### 1. Importer dans Postman

1. Ouvrez Postman
2. Cliquez sur **Import** (bouton en haut à gauche)
3. Sélectionnez **Upload Files**
4. Importez les deux fichiers :
    - `AI_Lab_API.postman_collection.json`
    - `AI_Lab_API.postman_environment.json`

### 2. Configurer l'environnement

1. Cliquez sur l'icône **Settings** (⚙️) en haut à droite
2. Sélectionnez **"AI Lab API Environment"**
3. Modifiez `base_url` si nécessaire (par défaut : `http://localhost:8000`)

### 3. Démarrer l'API

Avant d'utiliser Postman, assurez-vous que l'API est démarrée :

```bash
# Dans le dossier du projet
python -m src.main --mode api
# ou
poetry run python src/main.py --mode api --host 0.0.0.0 --port 8000
```

## 📊 Structure de la Collection

### 🏠 Core Endpoints

-   **Root** - Informations générales de l'API
-   **Health Check** - Statut de l'API et pipelines chargés

### 💭 Sentiment Analysis

-   **Analyze Sentiment - Positive** - Test avec texte positif
-   **Analyze Sentiment - Negative** - Test avec texte négatif
-   **Analyze Sentiment - Custom Model** - Test avec modèle personnalisé
-   **Batch Sentiment Analysis** - Traitement par lot

### 🏷️ Named Entity Recognition

-   **Extract Entities - People & Organizations** - Entités personnes/organisations
-   **Extract Entities - Geographic** - Entités géographiques
-   **Batch NER Processing** - Traitement par lot

### ❓ Question Answering

-   **Simple Q&A** - Questions simples
-   **Technical Q&A** - Questions techniques

### 🎭 Fill Mask

-   **Fill Simple Mask** - Masques simples
-   **Fill Technical Mask** - Masques techniques
-   **Batch Fill Mask** - Traitement par lot

### 🛡️ Content Moderation

-   **Check Safe Content** - Contenu sûr
-   **Check Potentially Toxic Content** - Contenu potentiellement toxique
-   **Batch Content Moderation** - Traitement par lot

### ✍️ Text Generation

-   **Generate Creative Text** - Génération créative
-   **Generate Technical Text** - Génération technique
-   **Batch Text Generation** - Traitement par lot

### 🧪 Testing & Examples

-   **Complete Pipeline Test** - Test complet
-   **Error Handling Test - Empty Text** - Gestion d'erreurs (texte vide)
-   **Error Handling Test - Invalid Model** - Gestion d'erreurs (modèle invalide)

## 🔧 Utilisation Avancée

### Variables d'environnement disponibles

| Variable          | Description               | Valeur par défaut       |
| ----------------- | ------------------------- | ----------------------- |
| `base_url`        | URL de base de l'API      | `http://localhost:8000` |
| `api_version`     | Version de l'API          | `1.0.0`                 |
| `timeout`         | Timeout des requêtes (ms) | `30000`                 |
| `default_*_model` | Modèles par défaut        | Voir environnement      |

### Personnalisation des modèles

Vous pouvez tester différents modèles en modifiant le champ `model_name` dans le body des requêtes :

```json
{
	"text": "Your text here",
	"model_name": "cardiffnlp/twitter-roberta-base-sentiment-latest"
}
```

### Tests automatiques

Chaque requête inclut des tests automatiques :

-   ✅ Temps de réponse < 30 secondes
-   ✅ Header Content-Type présent
-   ✅ Logs automatiques dans la console

## 📈 Exemples d'utilisation

### 1. Test rapide de l'API

1. Exécutez **"Health Check"** pour vérifier que l'API fonctionne
2. Testez **"Analyze Sentiment - Positive"** pour un premier test

### 2. Test complet d'un pipeline

1. Commencez par un test simple (ex: sentiment positif)
2. Testez avec un modèle personnalisé
3. Testez le traitement par lot
4. Testez la gestion d'erreurs

### 3. Benchmark de performance

1. Utilisez **"Batch Text Generation"** avec plusieurs prompts
2. Surveillez les temps de réponse dans l'onglet Tests
3. Ajustez le timeout si nécessaire

## 🐛 Dépannage

### API non accessible

-   Vérifiez que l'API est démarrée sur le bon port
-   Modifiez `base_url` dans l'environnement si nécessaire

### Erreurs 422 (Validation Error)

-   Vérifiez le format JSON du body
-   Assurez-vous que les champs requis sont présents

### Erreurs 503 (Service Unavailable)

-   Pipeline non chargé - vérifiez les logs de l'API
-   Redémarrez l'API si nécessaire

### Timeouts

-   Augmentez la valeur `timeout` dans l'environnement
-   Certains modèles peuvent être lents au premier chargement

## 🎯 Bonnes Pratiques

1. **Démarrez toujours par Health Check** pour vérifier l'état de l'API
2. **Utilisez l'environnement** pour centraliser la configuration
3. **Consultez les logs** dans la console Postman pour déboguer
4. **Testez progressivement** : simple → personnalisé → batch → erreurs
5. **Documentez vos tests** en ajoutant des descriptions aux requêtes

## 🔗 Liens Utiles

-   **Documentation Swagger** : http://localhost:8000/docs (quand l'API est active)
-   **Documentation ReDoc** : http://localhost:8000/redoc
-   **Schéma OpenAPI** : http://localhost:8000/openapi.json

---

**Happy Testing! 🚀**