knowledge.py

# =========================================================
# KNOWLEDGE BASE - HACKATHON INDABAX CAMEROON 2026
# Source : Documents officiels + Starter Notebook + Notebooks équipe
# Généré automatiquement à partir de tous les fichiers fournis
# =========================================================

KNOWLEDGE_BASE = [

    # ── CONTEXTE GÉNÉRAL ─────────────────────────────────────────────────────
    {
        "category": "Contexte",
        "title": "But de la compétition IndabaX 2026",
        "content": (
            "Le hackathon IndabaX Cameroon 2026 a pour thème 'L'IA au service de la résilience climatique et sanitaire au Cameroun'. "
            "L'objectif principal est de construire un modèle d'intelligence artificielle capable d'anticiper plusieurs jours à l'avance "
            "les épisodes de dégradation de la qualité de l'air, pour permettre aux autorités sanitaires d'agir avant que les populations "
            "soient exposées. Il s'agit d'un concours de data science organisé par Deep Learning IndabaX Cameroon."
        )
    },
    {
        "category": "Contexte",
        "title": "Dataset IndabaX 2026 — Vue d'ensemble",
        "content": (
            "Le dataset contient 87 240 observations météorologiques quotidiennes pour 42 villes des 10 régions administratives du Cameroun, "
            "couvrant 6 ans de données continues (du 1er janvier 2020 au 20 décembre 2025). "
            "Chaque ligne représente une ville un jour donné. "
            "Les colonnes incluent : températures (max, min, moyenne, ressentie), précipitations, vent, ensoleillement, rayonnement solaire, "
            "évapotranspiration FAO, codes météo WMO et coordonnées GPS."
        )
    },
    {
        "category": "Contexte",
        "title": "Liste des 42 villes du dataset par région",
        "content": (
            "Adamaoua : Tibati, Tignere, Ngaoundere, Meiganga. "
            "Centre : Bafia, Akonolinga, Yaounde, Mbalmayo. "
            "Est : Bertoua, Abong-Mbang, Batouri, Yokadouma. "
            "Extrême-Nord : Maroua, Kousseri, Mokolo, Yagoua. "
            "Littoral : Edea, Nkongsamba, Loum. "
            "Nord : Garoua, Guider, Poli, Touboro. "
            "Nord-Ouest : Bamenda, Kumbo, Wum, Mbengwi. "
            "Ouest : Bafoussam, Dschang, Foumban, Mbouda. "
            "Sud : Ebolowa, Kribi, Sangmelima, Ambam. "
            "Sud-Ouest : Buea, Limbe, Kumba, Mamfe."
        )
    },

    # ── QUALITÉ DE L'AIR ─────────────────────────────────────────────────────
    {
        "category": "Qualité de l'air",
        "title": "Qu'est-ce que le PM2.5 et le pm25_proxy ?",
        "content": (
            "Le PM2.5 désigne les particules fines de diamètre inférieur à 2,5 micromètres — les plus dangereuses car elles pénètrent "
            "profondément dans les poumons. Dans le dataset IndabaX, 'pm25_proxy' est un indice calculé comme proxy car il n'existe pas "
            "de mesures directes de PM2.5 au sol. "
            "Formule du proxy : 0.35 × température_moyenne + 0.25 × rayonnement_solaire + 0.20 × evapotranspiration "
            "+ 8.0 × (vent < 5 km/h) + 5.0 × (pas de pluie) + 4.0 × (saison_sèche). "
            "Plus cette valeur est haute, plus la qualité de l'air est mauvaise."
        )
    },
    {
        "category": "Qualité de l'air",
        "title": "Seuils OMS et niveaux d'alerte PM2.5",
        "content": (
            "Niveaux de risque basés sur le pm25_proxy : "
            "Vert (Sain) : activités normales, air de bonne qualité. "
            "Jaune (Modéré) : prudence pour les asthmatiques et personnes sensibles. "
            "Orange (Alerte) : réduction des efforts physiques intenses recommandée. "
            "Rouge (Urgence/Dangereux) : air dangereux, port du masque recommandé, limitation des déplacements. "
            "Les KPI du dashboard calculent : ville la plus polluée, région la plus polluée, jour le plus critique, "
            "nombre de villes en zone dangereuse, et mois le plus pollué."
        )
    },
    {
        "category": "Qualité de l'air",
        "title": "5 mécanismes de dégradation de la qualité de l'air au Cameroun",
        "content": (
            "1. Accumulation (2-7 jours) : vent faible + absence de pluie → concentration croissante de PM2.5, PM10, CO, NO2. "
            "2. Réactions photochimiques (quelques heures) : fort ensoleillement + chaleur > 32°C → formation d'ozone troposphérique (O3) et smog. "
            "3. Transport d'aérosols désertiques (3-14 jours) : vent fort du Sahara via l'Harmattan → pic de particules minérales PM10 dans le Nord. "
            "4. Feux de brousse (1-5 jours) : saison sèche + pratiques agricoles → particules fines PM2.5 et fumée sur grandes distances. "
            "5. Inversion thermique (1-3 jours) : nuit froide + jour chaud en zone encaissée → emprisonnement des polluants en basse altitude. "
            "Le seul processus positif est le lessivage : la pluie nettoie naturellement l'atmosphère."
        )
    },
    {
        "category": "Qualité de l'air",
        "title": "Zones et villes à risque de pollution au Cameroun",
        "content": (
            "Grand Nord (Maroua, Garoua, Kousseri) : risque aérosols désertiques et harmattan, ~3 millions d'habitants, critique de novembre à mars. "
            "Littoral/Douala-Edea : pollution industrielle + trafic dense + humidité stagnante, ~4 millions d'habitants, critique de juillet à septembre. "
            "Yaoundé et plateau Centre : smog urbain + feux agricoles périurbains, ~3,5 millions d'habitants, critique de décembre à février. "
            "Adamaoua (Ngaoundéré) : feux de brousse + vent de vallée, ~1 million, critique de janvier à mars. "
            "Est forestier (Bertoua, Yokadouma) : fumée de brûlis agricole et déforestation, ~800 000 habitants, critique de novembre à avril."
        )
    },
    {
        "category": "Qualité de l'air",
        "title": "Impacts sanitaires de la mauvaise qualité de l'air",
        "content": (
            "Impacts sanitaires directs : maladies respiratoires aiguës (asthme, bronchites), irritations oculaires et cutanées, "
            "aggravation des pathologies cardiovasculaires, mortalité prématurée chez les enfants et personnes âgées, "
            "réduction de la capacité pulmonaire des travailleurs extérieurs. "
            "Impacts environnementaux : pluies acides dégradant les sols, dépôt de particules sur la végétation réduisant la photosynthèse, "
            "contamination des ressources en eau, accélération de la dégradation des forêts du bassin du Congo."
        )
    },

    # ── VARIABLES DU DATASET ─────────────────────────────────────────────────
    {
        "category": "Variables",
        "title": "Variables du dataset et leur influence sur la qualité de l'air",
        "content": (
            "CRITIQUE : wind_speed_10m_max (< 5 km/h = stagnation = accumulation polluants), precipitation_sum (pluie = lessivage naturel). "
            "TRÈS ÉLEVÉ : weather_code WMO (codes 06=brume sèche, 07=tempête sable, 40-49=brouillard, 95+=orage), "
            "temperature_2m_max (> 32°C = accélération réactions photochimiques), shortwave_radiation_sum (catalyse formation ozone). "
            "ÉLEVÉ : wind_gusts_10m_max (remise en suspension des particules), wind_direction_10m_dominant (Nord-Est = harmattan saharien), "
            "precipitation_hours (durée du lessivage), apparent_temperature_max (chaleur ressentie = vulnérabilité populations). "
            "MODÉRÉ-ÉLEVÉ : et0_fao_evapotranspiration (sol sec = poussières mobilisables), sunshine_duration (durée photochimique)."
        )
    },
    {
        "category": "Variables",
        "title": "Variables dérivées (feature engineering) à construire",
        "content": (
            "jours_sans_pluie_consecutifs : compte les jours consécutifs sans pluie — à partir de 5 jours = seuil d'alerte. "
            "cumul_pluie_7j : somme glissante 7 jours des précipitations — mesure l'effet mémoire du lessivage. "
            "indice_stagnation : (1/wind_speed) × (1 - précipitations normalisées) — score 0-10 de stagnation atmosphérique. "
            "amplitude_thermique : temp_max - temp_min — grande amplitude = instabilité = inversions thermiques nocturnes. "
            "ratio_ensoleillement : sunshine_duration / daylight_duration — potentiel photochimique réel de la journée. "
            "saison_locale : saison sèche (mois 11,12,1,2,3) ou saison des pluies — facteur organisateur le plus important. "
            "zone_climatique : équatorial, tropical soudanien, tropical sahélien, littoral. "
            "Lags temporels : valeurs de J-1 à J-7 pour vent, température — capturer l'inertie atmosphérique. "
            "is_dry_season : variable binaire encodant la saison sèche camerounaise."
        )
    },
    {
        "category": "Variables",
        "title": "Formule pm25_proxy du starter notebook",
        "content": (
            "Le pm25_proxy (variable cible) est calculé ainsi dans le starter notebook officiel : "
            "pm25_proxy = 0.35 × temperature_2m_mean + 0.25 × shortwave_radiation_sum + 0.20 × et0_fao_evapotranspiration "
            "+ 8.0 × is_no_wind (vent < 5 km/h) + 5.0 × is_no_rain (précipitations < 0.1 mm) + 4.0 × is_dry_season. "
            "Note : c'est une approximation. Le vrai PM2.5 peut être enrichi via NASA MERRA-2 ou OpenAQ."
        )
    },

    # ── MODÉLISATION ─────────────────────────────────────────────────────────
    {
        "category": "Modélisation",
        "title": "Algorithmes et stratégie de modélisation",
        "content": (
            "Baseline : Random Forest ou Régression logistique avec température max, vent, précipitations, sunshine. "
            "Intermédiaire : XGBoost ou LightGBM avec variables dérivées, saison et zone_climatique — métriques : MAE, RMSE, feature importance. "
            "Avancé : LSTM ou Transformer temporel sur séries temporelles complètes par ville — métriques : MAPE, CRPS, intervalles de confiance. "
            "Validation obligatoire avec TimeSeriesSplit (pas de shuffle aléatoire) pour respecter la chronologie. "
            "Optimisation des hyperparamètres avec Optuna ou GridSearchCV. "
            "Interprétabilité via SHAP Values — crucial pour expliquer les pics de pollution aux autorités sanitaires."
        )
    },
    {
        "category": "Modélisation",
        "title": "Variable cible — 3 approches possibles",
        "content": (
            "Approche A (Hackathon, recommandée) : indice de stagnation atmosphérique calculé entièrement depuis le dataset. Faisable immédiatement. "
            "Approche B : weather_code WMO (tempête de sable, brouillard, etc.) — variable déjà dans le dataset, lien direct avec événements extrêmes. "
            "Approche C (idéale) : PM2.5 réel depuis données satellitaires NASA MERRA-2 ou stations OpenAQ — nécessite données externes mais maximise l'impact réel. "
            "Pour le hackathon : utiliser l'approche A ou B. Pour un projet complet : enrichir avec l'approche C."
        )
    },
    {
        "category": "Modélisation",
        "title": "Features utilisées dans le modèle baseline du starter notebook",
        "content": (
            "Features du modèle officiel : temperature_2m_mean, temperature_2m_max, temperature_2m_min, precipitation_sum, "
            "wind_speed_10m_max, wind_gusts_10m_max, shortwave_radiation_sum, et0_fao_evapotranspiration, sunshine_ratio, "
            "temp_amplitude, is_no_wind, is_no_rain, is_dry_season, month_sin, month_cos, day_of_year, "
            "temp_lag1, temp_lag7, wind_lag1, temp_roll7, latitude, longitude, region_enc, city_enc. "
            "Encodage cyclique du mois : month_sin = sin(2π × mois/12), month_cos = cos(2π × mois/12)."
        )
    },

    # ── SAISONS ET CLIMATOLOGIE ───────────────────────────────────────────────
    {
        "category": "Climatologie",
        "title": "Saisons et saisonnalité au Cameroun",
        "content": (
            "Saison sèche au Cameroun : mois 11, 12, 1, 2, 3 (novembre à mars) — période critique pour la pollution. "
            "Saison des pluies : d'avril à octobre — la pluie nettoie l'atmosphère, lessivage naturel. "
            "Harmattan : vent froid et sec du Nord-Est entre novembre et mars, chargé de particules sahariennes, "
            "affecte principalement le Grand Nord (Maroua, Garoua, Kousseri) mais peut atteindre le Centre et le Littoral. "
            "Les températures suivent une saisonnalité annuelle régulière et ont montré une tendance à la hausse de 2020 à 2025. "
            "Les précipitations sont concentrées sur certains mois, avec les pics en juin-septembre pour le littoral "
            "et mars-octobre pour le Centre-Sud."
        )
    },
    {
        "category": "Climatologie",
        "title": "Zones climatiques du Cameroun et risques spécifiques",
        "content": (
            "Équatorial Guinéen (Yaoundé, Mbalmayo, Ebolowa, Kribi) : smog urbain, feux agricoles, humidité élevée. "
            "Équatorial Camerounais (Bafoussam, Dschang, Buea, Limbe) : brouillard volcanique Buea/Limbe, pollution d'altitude. "
            "Tropical Soudanien (Ngaoundéré, Bertoua, Meiganga) : feux de brousse en saison sèche, particules fines. "
            "Tropical Sahélien (Maroua, Garoua, Kousseri, Mokolo) : tempêtes de sable, aérosols désertiques, harmattan. "
            "Littoral Atlantique (Edéa, Nkongsamba) : pollution industrielle, humidité marine, inversion thermique."
        )
    },
    {
        "category": "Climatologie",
        "title": "Extrêmes climatiques observés dans le dataset",
        "content": (
            "Journées à fortes précipitations (> 20 mm) : plus fréquentes en saison des pluies (juin-septembre). "
            "Pics de température max ≥ 38°C : localisés principalement dans le Grand Nord (Maroua, Kousseri, Garoua). "
            "Rafales extrêmes de vent : définies au 95e percentile — rares mais concentrées sur certaines villes. "
            "Amplitude thermique (temp_max - temp_min) : plus grande dans les régions arides du Nord. "
            "La température ressentie (apparent_temperature) est souvent supérieure à la température réelle dans les régions humides, "
            "et inférieure dans les zones venteuses."
        )
    },

    # ── DASHBOARD ET KPIs ─────────────────────────────────────────────────────
    {
        "category": "Dashboard",
        "title": "15 KPIs du tableau de bord IndabaX 2026",
        "content": (
            "1. PM2.5 moyen national. 2. Ville la plus polluée. 3. Région la plus polluée. "
            "4. Jour le plus critique. 5. Niveau alerte national (code couleur OMS). "
            "6. % jours saison sèche critiques. 7. Mois le plus pollué. "
            "8. Nombre de villes en zone dangereuse. 9. Région la plus ventée. 10. Amplitude thermique maximale. "
            "11. Variable météo la plus corrélée au PM2.5. 12. Feature la plus importante du modèle ML. "
            "13. R² du meilleur modèle. 14. PM2.5 prédit à J+7 (Prophet). 15. Nombre de jours dangereux prévus."
        )
    },
    {
        "category": "Dashboard",
        "title": "Structure du tableau de bord — 5 pages",
        "content": (
            "Page 1 Accueil (Vue générale) : carte choroplèthe du Cameroun, évolution annuelle pm25_proxy 2020-2025, "
            "influence des précipitations sur PM2.5, top villes polluées, influence température sur PM2.5. "
            "Page 2 Analyse Spatiale : carte 42 villes colorée PM2.5, top 10 villes les plus polluées, distribution par région, température réelle vs ressentie. "
            "Page 3 Analyse Temporelle : évolution PM2.5 par mois/année, précipitations/vent par mois, double axe PM2.5/précipitations, décomposition Prophet. "
            "Page 4 Prédiction & Alertes : courbe Prophet avec IC 95%, tableau 7 jours à venir, carte alertes actives, réel vs prédit, comparaison R² modèles. "
            "Page 5 Facteurs Climatiques : feature importance top 20, matrice de corrélation, scatter rayonnement/vent vs PM2.5, résidus, bilan hydrique."
        )
    },
    {
        "category": "Dashboard",
        "title": "Outils techniques du projet",
        "content": (
            "Frontend dashboard : Streamlit avec graphiques Plotly Express et Plotly Graph Objects pour l'interactivité. "
            "Modèles ML : Random Forest, XGBoost, LightGBM, Decision Tree — optimisés avec Optuna. "
            "Prévision temporelle : Prophet avec régresseurs météo pour les prédictions à 7 jours. "
            "Backend API : FastAPI (Python) avec endpoints /api/kpi, /api/filters, /api/chat. "
            "Déploiement : Hugging Face Spaces. "
            "Validation : TimeSeriesSplit obligatoire pour respecter la chronologie des données."
        )
    },

    # ── RESSOURCES HYDRIQUES ─────────────────────────────────────────────────
    {
        "category": "Ressources hydriques",
        "title": "Bilan hydrique et agriculture au Cameroun",
        "content": (
            "Bilan hydrique = Précipitations - ET0 (évapotranspiration FAO). "
            "Bilan négatif certains mois = stress hydrique pour l'agriculture. "
            "L'évapotranspiration (et0_fao_evapotranspiration) augmente avec la température et le rayonnement solaire. "
            "Sol sec (ET0 élevé, précipitations nulles) = réservoir de particules fines mobilisables par le vent. "
            "Impact direct sur la qualité de l'air : plus le sol est aride, plus les aérosols minéraux sont en suspension."
        )
    },

    # ── SOURCES DE DONNÉES EXTERNES ──────────────────────────────────────────
    {
        "category": "Données externes",
        "title": "Sources de données externes recommandées",
        "content": (
            "NASA MERRA-2 / MODIS : données satellitaires PM2.5 et AOD — variable cible réelle ou feature de validation (gratuit). "
            "OpenAQ : mesures de stations au sol en Afrique — ground truth pour les villes équipées. "
            "FIRMS NASA (VIIRS/MODIS) : points de feux actifs — feature 'feux de brousse à moins de 50 km'. "
            "OSM / Données urbaines : densité de population, routes, industries — exposition différentielle des populations. "
            "Calendrier agricole : périodes de brûlis, pratiques locales — feature 'risque brûlis actif'."
        )
    },
]