SmartStay Intelligence

Système IA de Revenue Management Hôtelier — Projet Fil Rouge Simplon Maghreb

Hôtel pilote : The Hickstead Hotel (52 chambres) — Bolney, West Sussex, Angleterre
Client : UNO Hotels
Données : Propriétaires réelles (PMS, Budget, Compset, TripAdvisor) — pas Kaggle

Aperçu

SmartStay Intelligence est un système end-to-end de revenue management alimenté par l'IA. Il prédit le taux d'occupation, recommande des tarifs dynamiques, explique chaque décision via SHAP, et analyse le sentiment des avis clients avec NLP.

Métrique	Valeur
Précision opérationnelle	88%
MAE opérationnel	0.12 (12pp)
Lignes d'entraînement	638 (Avr 2024 – Déc 2025)
Dates prédites	307 (2026)
Avis TripAdvisor analysés	686 (2004–2026)

Stack Technique

Couche	Technologies
Backend	FastAPI · PostgreSQL (port 5433) · JWT Auth
Modèles IA	LightGBM · Random Forest · Prophet · VADER NLP
Frontend	Next.js 14 (App Router) · Tailwind CSS · Recharts
Orchestration	Apache Airflow · Docker · DAG quotidien 06:00 UTC
MLOps	MLflow · pytest · GitHub Actions CI/CD
NLP & Insights	VADER Sentiment · Google Gemini 1.5 Flash · Apify

Structure du Projet

smartstay-intelligence/
├── backend/
│   ├── app/
│   │   ├── api/v1/endpoints/     # Routes FastAPI
│   │   ├── models/               # SQLAlchemy models
│   │   ├── schemas/              # Pydantic schemas
│   │   ├── services/             # Business logic
│   │   ├── db/                   # Session & init
│   │   └── main.py
│   └── .env                      # Variables d'environnement
├── scripts/
│   ├── 01_load_occupancy.py      # Parse exports PMS
│   ├── 02_load_budget.py         # Parse fichier budget Excel
│   ├── 03_load_compset.py        # Parse données compétiteurs
│   ├── 04_clean_pickup.py        # Nettoyage fichiers BOB pickup
│   ├── 05_build_training_matrix.py
│   ├── 06_build_prediction_matrix.py
│   ├── 07_train_model.py         # Entraînement GBM + RF ensemble
│   ├── 07b_prophet.py            # Entraînement Prophet
│   ├── 07_train_model_mlflow.py  # Wrapper MLflow (ne modifie pas 07)
│   ├── 08_evaluate_model.py      # MAE, accuracy metrics
│   ├── 09_airflow_dag.py         # DAG Airflow
│   ├── daily_rescore.py          # Rescore journalier (importé par Airflow)
│   ├── 11_shap_explainability.py
│   ├── 12_prophet_seasonality.py
│   └── 13_sentiment_analysis.py
├── data/
│   ├── raw/                      # Données brutes (non versionnées)
│   ├── processed/                # Matrices d'entraînement/prédiction
│   ├── models/                   # gbm_model.joblib, rf_model.joblib
│   ├── prediction/               # predictions_2026.csv, model_metrics.json
│   ├── shap/                     # shap_values.csv, shap_summary.json
│   ├── prophet/                  # seasonality_*.json
│   └── sentiment/                # reviews_scored.csv, sentiment_summary.json
├── airflow/
│   ├── dags/
│   └── Dockerfile
├── tests/
│   ├── conftest.py
│   ├── test_api.py               # Tests endpoints FastAPI
│   ├── test_model.py             # Sanity checks modèles ML
│   └── test_pipeline.py         # Intégrité fichiers pipeline
├── .github/workflows/
│   └── ci.yml                    # GitHub Actions CI
└── mlruns/                       # MLflow tracking (local)

Installation & Démarrage

Prérequis

Python 3.11+
uv (gestionnaire de paquets)
PostgreSQL 15+
Docker & Docker Compose (pour Airflow)
Node.js 18+ (pour le frontend)

1. Cloner le repo

git clone https://github.com/Khaoula1025/SmartStayAi.git
cd SmartStayAi

2. Installer les dépendances Python

uv sync

3. Configurer les variables d'environnement

Créer backend/.env :

DB_USER=postgres
DB_PASSWORD=0000
DB_HOST=localhost
DB_PORT=5433
DB_NAME=SmartStayAi
secret=votre_secret_jwt

GOOGLE_API_KEY=votre_cle_google
APIFY_TOKEN=votre_token_apify

AIRFLOW_ADMIN_USER=admin
AIRFLOW_ADMIN_PASSWORD=admin123
AIRFLOW_FERNET_KEY=<genere>
AIRFLOW_SECRET_KEY=<genere>
AIRFLOW_DB=airflow

4. Initialiser la base de données

# Créer la DB dans PostgreSQL
createdb -U postgres SmartStayAi

# Initialiser les tables
uv run python -c "
import sys; sys.path.insert(0, 'backend')
from app.db.session import engine, Base
Base.metadata.create_all(bind=engine)
print('Tables créées')
"

5. Lancer le pipeline de données

# Exécuter les scripts dans l'ordre
$env:PYTHONUTF8=1  # Windows uniquement
uv run python scripts/01_load_occupancy.py
uv run python scripts/02_load_budget.py
uv run python scripts/03_load_compset.py
uv run python scripts/04_clean_pickup.py
uv run python scripts/05_build_training_matrix.py
uv run python scripts/06_build_prediction_matrix.py
uv run python scripts/07_train_model.py
uv run python scripts/07b_prophet.py
uv run python scripts/08_evaluate_model.py
uv run python scripts/11_shap_explainability.py
uv run python scripts/12_prophet_seasonality.py
uv run python scripts/13_sentiment_analysis.py

6. Démarrer le backend FastAPI

cd backend
uv run uvicorn app.main:app --reload --port 8000

API disponible sur http://localhost:8000
Documentation Swagger : http://localhost:8000/docs

7. Démarrer le frontend Next.js

# Dans le répertoire du projet Next.js
npm run dev

Frontend disponible sur http://localhost:3000

8. Démarrer Airflow (optionnel)

docker compose --env-file ./backend/.env up -d

Interface Airflow : http://localhost:8080

API Endpoints

Méthode	Endpoint	Description
`GET`	`/health`	Santé de l'API
`POST`	`/api/v1/auth/login`	Authentification JWT
`GET`	`/api/v1/dashboard/`	KPIs & tendances
`GET`	`/api/v1/predictions/`	Prédictions 2026
`GET`	`/api/v1/analytics/model/metrics`	Métriques du modèle
`GET`	`/api/v1/analytics/model/history`	Historique des runs
`GET`	`/api/v1/analytics/seasonality/yearly`	Saisonnalité mensuelle
`GET`	`/api/v1/analytics/seasonality/weekly`	Saisonnalité hebdomadaire
`GET`	`/api/v1/explain/summary`	Importance globale SHAP
`GET`	`/api/v1/explain/{date}`	Explication SHAP par date
`GET`	`/api/v1/sentiment/summary`	Résumé sentiment
`GET`	`/api/v1/sentiment/insights`	Rapport Gemini AI

Modèles IA

Ensemble Champion (GBM 60% + RF 40%)

Entraînement : 638 lignes (Avr 2024 – Déc 2025)
Features     : 13 (month, dow, cs_adr, b_adr, season, ...)
MAE opérationnel : 0.1196 (12pp)
Précision    : 88.0% (±10pp threshold)

Top features (SHAP) :

month — 32% (saisonnalité mensuelle dominante)
cs_adr — 17% (tarif concurrent)
b_adr — 15% (tarif budget)

Insight clé : Bank holidays, événements culturels et locaux → impact SHAP quasi nul.

Prophet (Saisonnalité)

Juillet : +27.3pp (pic estival)
Janvier : -49.4pp (creux hivernal)
Mardi : +14.6pp meilleur jour (segment corporate)
Dimanche : -35.9pp pire jour
Ramp-up hôtel : 17.8% → 70.6% en 20 mois

VADER NLP + Gemini AI (Sentiment)

686 avis TripAdvisor (2004–2026)
Score compound moyen : 79.8%
92.1% positifs | 7.6% négatifs
⚠️ Déclin fin 2025 : Juil 25 = 7.7%, Déc 25 = 20.9%

MLflow

# Lancer l'interface MLflow
mlflow ui

# Ouvrir http://localhost:5000
# Expérience : smartstay_training

Pour tracker un run d'entraînement :

$env:PYTHONUTF8=1
uv run python scripts/07_train_model_mlflow.py

Tests

$env:PYTHONUTF8=1  # Windows uniquement
uv run pytest tests/ -v

Fichier	Tests	Couverture
`test_api.py`	Endpoints + auth JWT	Routes FastAPI
`test_model.py`	Sanity checks ML	Modèles joblib
`test_pipeline.py`	Intégrité fichiers	Outputs pipeline

Coverage actuelle : 58%

CI/CD

GitHub Actions déclenché sur chaque push :

Spin-up PostgreSQL 15 (container)
Écriture du .env CI
Création tables + seed utilisateur test
pytest tests/test_api.py -v

Voir .github/workflows/ci.yml

Pages Frontend

Route	Description
`/`	Landing page
`/login`	Authentification
`/dashboard`	KPIs, tendance demande, BOB quality
`/forecast`	Prévisions 60 jours + bande IC + tarifs
`/rates`	Rate Decisions + tooltip SHAP "Pourquoi ?"
`/analytics`	Accuracy + Saisonnalité (Prophet)
`/pipeline`	Architecture + statut pipeline
`/sentiment`	KPIs NLP + rapport Gemini AI + avis

Design system : Navy #1C2B4A · Gold #C9A84C · Surface #F7F8FC

Variables d'Environnement

Variable	Description
`DB_USER`	Utilisateur PostgreSQL
`DB_PASSWORD`	Mot de passe PostgreSQL
`DB_HOST`	Hôte PostgreSQL
`DB_PORT`	Port PostgreSQL (5433 local, 5432 CI)
`DB_NAME`	Nom de la base (`SmartStayAi`)
`secret`	Clé secrète JWT
`GOOGLE_API_KEY`	Clé API Google (Gemini)
`APIFY_TOKEN`	Token Apify (scraping TripAdvisor)

Licence

Projet académique — Simplon Maghreb · Mars 2026
Données propriétaires UNO Hotels — usage interne uniquement

Name		Name	Last commit message	Last commit date
Latest commit History 63 Commits
.github/workflows		.github/workflows
airflow		airflow
backend		backend
config		config
data		data
frontend		frontend
logs/airflow		logs/airflow
mlruns/1/models		mlruns/1/models
noteboooks		noteboooks
scripts		scripts
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.python-version		.python-version
README.md		README.md
docker-compose.yml		docker-compose.yml
mlflow.db		mlflow.db
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Repository files navigation

SmartStay Intelligence

Aperçu

Stack Technique

Structure du Projet

Installation & Démarrage

Prérequis

1. Cloner le repo

2. Installer les dépendances Python

3. Configurer les variables d'environnement

4. Initialiser la base de données

5. Lancer le pipeline de données

6. Démarrer le backend FastAPI

7. Démarrer le frontend Next.js

8. Démarrer Airflow (optionnel)

API Endpoints

Modèles IA

Ensemble Champion (GBM 60% + RF 40%)

Prophet (Saisonnalité)

VADER NLP + Gemini AI (Sentiment)

MLflow

Tests

CI/CD

Pages Frontend

Variables d'Environnement

Licence

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

SmartStay Intelligence

Aperçu

Stack Technique

Structure du Projet

Installation & Démarrage

Prérequis

1. Cloner le repo

2. Installer les dépendances Python

3. Configurer les variables d'environnement

4. Initialiser la base de données

5. Lancer le pipeline de données

6. Démarrer le backend FastAPI

7. Démarrer le frontend Next.js

8. Démarrer Airflow (optionnel)

API Endpoints

Modèles IA

Ensemble Champion (GBM 60% + RF 40%)

Prophet (Saisonnalité)

VADER NLP + Gemini AI (Sentiment)

MLflow

Tests

CI/CD

Pages Frontend

Variables d'Environnement

Licence

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages