# ✈️ Flight Search Agent

**Auteur :** Saad Bendahou  
**Contexte :** Projet académique - Deep Learning / Intelligence Artificielle  
**Année :** 2025

---

## 📋 Description

Flight Search Agent est un agent conversationnel intelligent développé pour la recherche et la réservation de vols. Le projet utilise le protocole **MCP (Model Context Protocol)** pour exposer des outils de recherche standardisés, intègre **Google Gemini API** pour la compréhension du langage naturel, et l'**API Amadeus** pour récupérer des données de vols réelles en temps réel.

L'interface web moderne est développée avec **FastAPI** et offre une expérience utilisateur immersive avec un arrière-plan animé et des étiquettes de villes flottantes.

### 🎯 Caractéristiques principales

- ✅ **Recherche de vols intelligente** entre différentes villes (Maroc, Europe, Monde)
- ✅ **Compréhension du langage naturel** : dates relatives ("demain", "la semaine prochaine")
- ✅ **Google Gemini API** : LLM rapide et efficace (gemini-2.5-flash)
- ✅ **Protocole MCP** : Exposition d'outils de recherche standardisés
- ✅ **Intégration API Amadeus** : Données de vols réelles et professionnelles
- ✅ **Interface FastAPI** : Interface web moderne avec HTML/CSS/JS personnalisé
- ✅ **Multilingue** : Support Français et Anglais
- ✅ **Parsing de dates** : Conversion automatique de dates naturelles
- ✅ **Validation stricte** : L'application ne démarre que si les APIs sont configurées

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                         UTILISATEUR                              │
│                    (Interface Web FastAPI)                       │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    app_fastapi.py                                 │
│              - Endpoint / : Page HTML                             │
│              - Endpoint /chat : API REST                          │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                  gemini_agent.py                                  │
│         - GeminiFlightAgent : Agent principal                     │
│         - Compréhension du langage naturel                        │
│         - Extraction des paramètres (origine, destination, date)   │
│         - Formatage des réponses                                  │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    flight_data.py                                 │
│         - search_flights() : Fonction principale                  │
│         - Gestion des données de vols                             │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    amadeus_api.py                                │
│         - search_flights_amadeus() : Recherche réelle             │
│         - get_airport_code() : Conversion ville → code IATA       │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    date_parser.py                                │
│         - parse_date_with_context() : Parsing dates naturelles   │
│         - get_current_date_info() : Informations date actuelle    │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    mcp_server.py (Optionnel)                      │
│         - Serveur MCP pour intégration avec Cursor/Claude        │
│         - Exposition des mêmes outils via protocole MCP          │
└─────────────────────────────────────────────────────────────────┘
```

### Flux de données

1. **Utilisateur** envoie une requête via l'interface web
2. **FastAPI** reçoit la requête et appelle `gemini_agent.chat()`
3. **Gemini Agent** analyse la requête et extrait les paramètres
4. **Flight Data** appelle `amadeus_api.search_flights_amadeus()`
5. **Amadeus API** retourne les données de vols réelles
6. **Gemini Agent** formate la réponse de manière conviviale
7. **FastAPI** retourne la réponse formatée à l'utilisateur

---

## 📁 Structure du Projet

```
Flight_Search_Agent/
├── app_fastapi.py              # Application FastAPI principale
├── gemini_agent.py            # Agent Gemini + logique conversation
├── amadeus_api.py             # Intégration API Amadeus
├── flight_data.py             # Gestion des données de vols
├── date_parser.py             # Parseur de dates naturelles
├── mcp_server.py              # Serveur MCP (optionnel)
├── mcp_config.json            # Configuration MCP
│
├── templates/                 # Templates HTML
│   └── index.html             # Interface web principale
│
├── static/                     # Fichiers statiques
│   └── Bg.jpg                 # Image de fond
│
├── requirements.txt           # Dépendances Python
├── .gitignore                 # Fichiers ignorés par Git
├── .env                       # Variables d'environnement (non versionné)
└── README.md                  # Documentation
```

---

## 🛠️ Installation

### Prérequis

- **Python 3.10+**
- **Clés API** :
  - **Google Gemini API** : [Google AI Studio](https://makersuite.google.com/app/apikey)
  - **Amadeus API** : [Amadeus for Developers](https://developers.amadeus.com/)

### 1. Cloner le projet

```bash
git clone <repository-url>
cd Flight_Search_Agent
```

### 2. Installer les dépendances

```bash
pip install -r requirements.txt
```

### 3. Configurer les variables d'environnement

Créez un fichier `.env` à la racine du projet :

```env
GEMINI_API_KEY=votre_cle_gemini_ici
AMADEUS_CLIENT_ID=votre_client_id_ici
AMADEUS_CLIENT_SECRET=votre_client_secret_ici
```

**Important :** L'application ne démarrera **PAS** si ces variables ne sont pas configurées ou si elles contiennent des valeurs placeholder.

### 4. Obtenir les clés API

#### Google Gemini API (Gratuit)
1. Allez sur [Google AI Studio](https://makersuite.google.com/app/apikey)
2. Connectez-vous avec votre compte Google
3. Cliquez sur "Create API Key"
4. Copiez votre clé API

#### Amadeus API (Gratuit pour développeurs académiques)
1. Allez sur [Amadeus for Developers](https://developers.amadeus.com/)
2. Créez un compte gratuit (compte académique/non-lucratif)
3. Créez une nouvelle application
4. Copiez votre **Client ID** et **Client Secret**

---

## 💻 Utilisation

### Lancer l'application FastAPI

```bash
python app_fastapi.py
```

L'application sera accessible sur : **http://localhost:8000**

### Utiliser le serveur MCP (Optionnel)

Pour intégrer avec Cursor/Claude Desktop :

```bash
python mcp_server.py
```

Puis configurez votre client MCP avec :

```json
{
  "mcpServers": {
    "flight-search": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "C:\\path\\to\\Flight_Search_Agent"
    }
  }
}
```

---

## 🎯 Exemples de Requêtes

L'agent comprend des requêtes en langage naturel :

```
"Je veux un vol de Casablanca à Paris demain"
"Trouve-moi un vol Marrakech - Bruxelles pour le 20 décembre"
"Quels vols sont disponibles de Rabat à Londres la semaine prochaine?"
"Vol pas cher de Fès à Barcelone le 15 janvier"
```

---

## 🌍 Villes Supportées

### Maroc 🇲🇦
- Casablanca (CMN)
- Marrakech (RAK)
- Rabat (RBA)
- Fès (FEZ)
- Tanger (TNG)
- Agadir (AGA)

### Europe 🇪🇺
- Paris (CDG/ORY)
- Londres (LHR)
- Madrid (MAD)
- Barcelone (BCN)
- Bruxelles (BRU)
- Amsterdam (AMS)

### Autres 🌍
- Dubaï (DXB)
- Istanbul (IST)
- Montréal (YUL)
- New York (JFK)
- Washington (DCA)

---

## 🔧 Technologies Utilisées

- **FastAPI** - Framework web moderne et rapide
- **Google Gemini API** - LLM rapide et efficace (gemini-2.5-flash)
- **Amadeus API** - API professionnelle de recherche de vols
- **MCP (Model Context Protocol)** - Protocole d'exposition d'outils
- **Python 3.10+** - Langage de développement
- **Jinja2** - Moteur de templates HTML
- **HTML/CSS/JavaScript** - Interface web personnalisée

---

## 📋 Tools MCP Disponibles

### 1. `search_flights`
Recherche des vols entre deux villes avec date.

**Paramètres :**
- `origin` : Ville de départ (ex: "Casablanca", "CMN")
- `destination` : Ville d'arrivée (ex: "Paris", "CDG")
- `date` : Date de voyage au format YYYY-MM-DD

### 2. `parse_date`
Convertit une date naturelle en format ISO.

**Paramètres :**
- `date_expression` : Date en langage naturel (ex: "demain", "le 20 décembre")

### 3. `get_current_date`
Retourne la date actuelle et références.

### 4. `list_airports`
Liste les aéroports disponibles.

---

## 🐛 Dépannage

### Erreur "APIs non configurées"
- Vérifiez que le fichier `.env` existe et contient les bonnes clés
- Vérifiez que les clés ne sont pas des placeholders
- L'application ne démarre **PAS** sans APIs configurées

### Erreur "GEMINI_API_KEY not found"
- Vérifiez que vous avez défini la variable d'environnement `GEMINI_API_KEY`
- Obtenez votre clé sur [Google AI Studio](https://makersuite.google.com/app/apikey)

### Erreur "AMADEUS_CLIENT_ID not found"
- Vérifiez que vous avez défini les variables `AMADEUS_CLIENT_ID` et `AMADEUS_CLIENT_SECRET`
- Créez un compte sur [Amadeus for Developers](https://developers.amadeus.com/)

### Erreur de dépendances
```bash
pip install -r requirements.txt
```

### L'API Amadeus retourne une erreur
- Vérifiez que vous utilisez l'environnement "test" (par défaut)
- Vérifiez les limites de votre compte Amadeus (gratuit pour développeurs)
- Vérifiez que les codes d'aéroport sont corrects

---

## 📝 Notes de Développement

### Validation des APIs
L'application valide strictement la présence des APIs au démarrage. Si les clés sont manquantes ou contiennent des valeurs placeholder, l'application lève une exception et ne démarre pas.

### Gestion des erreurs
- Les erreurs API sont capturées et retournées de manière conviviale à l'utilisateur
- L'historique de conversation est maintenu pour améliorer les réponses
- Les dates relatives sont automatiquement converties en format ISO

### Interface utilisateur
- Arrière-plan avec image de ciel et nuages
- Étiquettes de villes flottantes avec animations
- Chat transparent avec bordures visibles
- Barre d'astuces rabattable depuis le haut
- Heure locale mise à jour en temps réel

---

## 📄 Licence

Ce projet est développé dans un contexte académique et non-lucratif.

---

## 👤 Auteur

**Saad Bendahou**  
Projet académique - Deep Learning / Intelligence Artificielle  
Année 2025

---

## 🙏 Remerciements

- **Google** pour l'API Gemini
- **Amadeus** pour l'API de recherche de vols (compte académique)
- La communauté open-source Python

---

**Développé avec ❤️ pour l'apprentissage et la recherche académique**