Add GitHub Actions workflow for Panel app deployment to Hugging Face Spaces with path-based triggers, VS Code project color customization, and comprehensive KPI health check drill-down documentation including group-based filtering, SLA benchmarking, timeline visualization, and complaint sites roadmap

.github/workflows/kpi_analysis.yml

@@ -0,0 +1,55 @@
+name: Sync Panel (kpi_analysis) to Hugging Face
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "panel_app/**"
+      - "process_kpi/**"
+      - "utils/**"
+      - "data/**"
+      - "physical_db/**"
+      - "hf_spaces/kpi_analysis/**"
+      - ".github/workflows/kpi_analysis.yml"
+
+  workflow_dispatch:
+
+jobs:
+  sync-panel-to-hub:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: false
+
+      - name: Build Space bundle
+        run: |
+          rm -rf hf_space
+          mkdir -p hf_space
+
+          # Space root files
+          cp -r hf_spaces/kpi_analysis/* hf_space/
+
+          # App code + shared modules
+          cp -r panel_app hf_space/
+          cp -r process_kpi hf_space/
+          cp -r utils hf_space/
+
+          # Data files needed by the app
+          cp -r data hf_space/
+          cp -r physical_db hf_space/
+
+      - name: Push bundle to Hugging Face Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          cd hf_space
+          git init
+          git config user.name "github-actions"
+          git config user.email "[email protected]"
+          git add -A
+          git commit -m "Deploy Panel Space" || true
+          git branch -M main
+          git remote add hf https://DavMelchi:[email protected]/spaces/DavMelchi/kpi_analysis
+          git push --force hf main

.github/workflows/main.yml

@@ -2,6 +2,22 @@ name: Sync 2 to Hugging Face hub
 on:
   push:
     branches: [main]
+    paths:
+      - "app.py"
+      - "apps/**"
+      - "assets/**"
+      - "queries/**"
+      - "utils/**"
+      - "process_kpi/**"
+      - "data/**"
+      - "physical_db/**"
+      - ".streamlit/**"
+      - "requirements.txt"
+      - "README.md"
+      - "!.github/workflows/kpi_analysis.yml"
+      - "!hf_spaces/**"
+      - "!panel_app/**"
+      - "!process_kpi/kpi_health_check/**"
 
   # to run this workflow manually from the Actions tab
   workflow_dispatch:

.vscode/settings.json

@@ -0,0 +1,51 @@
+{
+    "projectColors.mainColor": "#1e22fa",
+    "window.title": "${rootName}${separator}${profileName}${separator}${appName}${separator}${activeEditorShort}${dirty}",
+    "workbench.colorCustomizations": {
+        "statusBarItem.warningBackground": "#1e22fa",
+        "statusBarItem.warningForeground": "#ffffff",
+        "statusBarItem.warningHoverBackground": "#1e22fa",
+        "statusBarItem.warningHoverForeground": "#ffffff90",
+        "statusBarItem.remoteBackground": "#1e22fa",
+        "statusBarItem.remoteForeground": "#ffffff",
+        "statusBarItem.remoteHoverBackground": "#1e22fa",
+        "statusBarItem.remoteHoverForeground": "#ffffff90",
+        "statusBar.background": "#1e22fa",
+        "statusBar.foreground": "#ffffff",
+        "statusBar.border": "#1e22fa",
+        "statusBar.debuggingBackground": "#1e22fa",
+        "statusBar.debuggingForeground": "#ffffff",
+        "statusBar.debuggingBorder": "#1e22fa",
+        "statusBar.noFolderBackground": "#1e22fa",
+        "statusBar.noFolderForeground": "#ffffff",
+        "statusBar.noFolderBorder": "#1e22fa",
+        "statusBar.prominentBackground": "#1e22fa",
+        "statusBar.prominentForeground": "#ffffff",
+        "statusBar.prominentHoverBackground": "#1e22fa",
+        "statusBar.prominentHoverForeground": "#ffffff90",
+        "focusBorder": "#1e22fa99",
+        "progressBar.background": "#1e22fa",
+        "textLink.foreground": "#5e62ff",
+        "textLink.activeForeground": "#6b6fff",
+        "selection.background": "#1115ed",
+        "list.highlightForeground": "#1e22fa",
+        "list.focusAndSelectionOutline": "#1e22fa99",
+        "button.background": "#1e22fa",
+        "button.foreground": "#ffffff",
+        "button.hoverBackground": "#2b2fff",
+        "tab.activeBorderTop": "#2b2fff",
+        "pickerGroup.foreground": "#2b2fff",
+        "list.activeSelectionBackground": "#1e22fa4d",
+        "panelTitle.activeBorder": "#2b2fff",
+        "activityBar.activeBorder": "#1e22fa",
+        "activityBarBadge.foreground": "#ffffff",
+        "activityBarBadge.background": "#1e22fa"
+    },
+    "projectColors.isActivityBarColored": false,
+    "projectColors.isProjectNameColored": false,
+    "projectColors.isStatusBarColored": false,
+    "projectColors.isTitleBarColored": false,
+    "projectColors.setWindowTitle": false,
+    "projectColors.name": "OML_DB",
+    "projectColors.isActiveItemsColored": true
+}

documentations/kpi_health_check_drilldown_graphs_plan.md

@@ -0,0 +1,247 @@
+# KPI Health Check – Plan final UX Drill-down (Graphes / Groupes KPI / SLA) – V2
+
+## Objectifs
+
+- Rendre le drill-down **plus lisible** pour analyser rapidement un site.
+- Permettre une vue “site” où les KPI sont **regroupés par nature** (success rate, fails, throughput, traffic, availability, etc.).
+- Garder une interaction **Plotly native**: légende cliquable pour masquer/afficher des KPI individuellement.
+- Ajouter un **benchmark** basé sur les SLA/règles (quand c’est pertinent) sans mélanger des KPI hétérogènes.
+
+## Non-objectifs (scope control)
+
+- Pas de clustering/ML automatique des KPI.
+- Pas de refonte globale de l’UI (on reste dans la section drill-down existante).
+- Pas de comparaison multi-sites sur cette itération (site unique, plus lisible).
+
+## Contraintes / invariants
+
+- Ne pas casser les fonctionnalités existantes:
+  - sélection KPI (`kpi_select`), comparaison multi-KPI (`kpi_compare_select`), normalisation, export drill-down.
+  - cache des figures et guard anti-récursion déjà en place.
+- Les KPI n’ont pas tous la même unité: éviter les graphes qui mélangent des échelles incompatibles.
+- Modularité: éviter d’alourdir `panel_app/kpi_health_check_panel.py`. La logique “métier” de drill-down (groupes, sélection KPI, benchmark, figures) doit être extraite en modules.
+
+## Modularité / architecture (production)
+
+Objectif: garder `panel_app/kpi_health_check_panel.py` comme couche d’orchestration (widgets + callbacks) et déplacer la logique testable dans des modules dédiés.
+
+Découpage proposé:
+
+- `process_kpi/kpi_health_check/kpi_groups.py`
+  - classification KPI -> groupe
+  - résolution collisions + règles de priorité
+  - sélection top-N (perfs)
+
+- `process_kpi/kpi_health_check/benchmarks.py`
+  - calcul des métriques SLA (median_recent, %BAD recent)
+  - calcul quantiles population (si bonus)
+
+- `panel_app/kpi_health_check_drilldown_plots.py`
+  - construction des figures Plotly (trend annoté, timeline BAD)
+  - conventions `legendgroup` + styles
+
+Note: le découpage exact peut être ajusté selon ce qui est le plus simple à tester, mais la contrainte “pas un gros fichier” est un invariant.
+
+## Définitions
+
+- **KPI “tracé”**: KPI qui apparaît comme une trace Plotly (ligne/markers).
+- **Groupe KPI**: catégorie sémantique (success rate / fails / traffic / etc.) utilisée pour filtrer/organiser.
+- **Benchmark SLA**: comparaison au seuil `sla` des rules, alignée avec la logique `is_bad()`.
+
+## 1) Groupes KPI “par nature” (meilleure option)
+
+### Proposition retenue
+
+- Ajouter un widget: **`kpi_group_select`** (Select / Autocomplete / Radio) avec:
+  - `All (selected KPIs)`
+  - `Success rate (>= SLA / proche 100%)`
+  - `Fails / Drop / Block (<= SLA / proche 0)`
+  - `Throughput / Debit`
+  - `Traffic / Volume`
+  - `Availability / Dispo`
+  - `Latency / Delay`
+  - `Other`
+
+- Ajouter un widget: **`kpi_group_mode`** (Select):
+  - `Filter KPI list only (recommended)`
+  - `Add top-N KPIs from group to compare`
+
+### Comment on conserve la sélection individuelle via Plotly
+
+- Le graphe “Trend (site)” affichera plusieurs traces (1 trace = 1 KPI).
+- Les traces seront **groupées** dans la légende via `legendgroup`.
+- La légende Plotly permet:
+  - click: hide/show trace
+  - double-click: isolate trace
+
+=> L’utilisateur peut afficher un groupe complet puis isoler un KPI d’un click.
+
+### Méthode de classification (règles)
+
+#### Source of truth + résolution des collisions (production-grade)
+
+- **Priorité 1 (future-proof)**: overrides explicites (si on ajoute plus tard un mapping KPI->groupe dans un fichier/profil).
+- **Priorité 2**: indices issus des rules (direction + présence SLA) quand disponibles.
+- **Priorité 3**: heuristiques sur le nom du KPI (regex).
+
+Règle: **un KPI appartient à 0..1 groupe**. Si plusieurs regex matchent, on prend le premier match selon l’ordre de priorité défini ci-dessous.
+
+Patterns initiaux (ajustables):
+
+- Success rate: `cssr|success|attach|setup|erab|rrc|\basr\b|\bsr\b`
+- Fails/Drop/Block: `drop|fail|block|reject|deny|accessibility.*fail|retention.*fail`
+- Throughput/debit: `throughput|thp|debit|dl.*rate|ul.*rate|bitrate`
+- Traffic: `traffic|volume|erl|payload|gbytes|gb`
+- Availability: `availability|avail|unavailability|unavail|dispo|disponibil|uptime`
+- Latency: `latency|delay|\brt\b|rtt`
+
+Note: on évite de matcher `sr` trop largement (trop de faux positifs). `sr` est uniquement accepté sous forme de mot (`\bsr\b`).
+
+## 1.1) Garde-fous performance (obligatoire en prod)
+
+- Ajouter un paramètre interne `max_kpis_in_plot` (recommandé: 12).
+- Si la liste de KPI à tracer dépasse `max_kpis_in_plot`:
+  - on réduit à top-N selon `% BAD days (recent)` calculé via `is_bad()`.
+  - si égalité, tri secondaire: variance recent ou `anomaly_score` si disponible.
+
+## 2) Trend “annoté” (lisibilité)
+
+### Ajouts sur le graphe trend
+
+Pour le KPI sélectionné (ou pour chaque KPI tracé quand affichage en groupe):
+
+- **Baseline médiane** (ligne horizontale)
+- **Bande de seuil relatif** (baseline ± `rel_threshold_pct`)
+- **SLA** si présent (ligne horizontale)
+- **Points colorés** par jour:
+  - OK vs BAD selon `is_bad()`
+- **Shading des fenêtres**:
+  - baseline window
+  - recent window
+
+Règle: le status OK/BAD doit être **strictement cohérent** avec l’engine (utiliser `is_bad()` et les mêmes paramètres `rel_threshold_pct`, `sla`, `direction`).
+
+### Mode groupe
+
+- Si le groupe contient plusieurs KPI:
+  - par défaut (recommended): le groupe **filtre** la liste de KPI proposée à l’utilisateur; le graphe trace `kpi_select` + `kpi_compare_select`.
+  - option alternative: `Add top-N KPIs from group to compare` ajoute automatiquement top-N KPI au `kpi_compare_select` (avec limite `max_kpis_in_plot`).
+
+## 3) Timeline “BAD days / streak”
+
+- Ajouter un sous-graphe (subplot) ou un second panneau:
+  - une barre par jour: 0/1 BAD
+  - annotations: longueur de streak et seuil `min_consecutive_days`
+
+Objectif: expliquer rapidement le passage DEGRADED -> PERSISTENT.
+
+## 4) Benchmark basé sur SLA (et option population)
+
+### Benchmark SLA (demandé)
+
+- Pour chaque KPI tracé:
+  - afficher la **ligne SLA** si `sla` est un nombre.
+  - afficher une métrique synthèse (annotation ou mini-table):
+    - `% BAD days (recent)` basé sur `is_bad()`.
+    - `median_recent` vs `sla`.
+
+Cas direction:
+
+- `higher_is_better`: BAD si (valeur trop basse vs baseline et/ou < SLA selon la règle `is_bad`).
+- `lower_is_better`: BAD si (valeur trop haute vs baseline et/ou > SLA selon la règle `is_bad`).
+
+### Option “population benchmark” (bonus)
+
+- Afficher `p50` et `p90` (ou p10/p90 selon direction) sur l’ensemble des sites (ou sur la même City)
+- Important:
+  - uniquement pour un KPI à la fois (ou normalisation obligatoire)
+
+## 5) UX / Layout proposé
+
+Dans la section Drill-down:
+
+- Ligne 1: `site_select`, `rat_select`
+- Ligne 2: `kpi_select`, `kpi_compare_select`, `kpi_compare_norm`
+- Ligne 3 (nouveau): `kpi_group_select`, `kpi_group_mode`, (option) `benchmark_mode`
+- Plots:
+  - Trend annoté (grand)
+  - Timeline BAD (petit, dessous)
+  - Heatmap / Histogram (déjà existants)
+
+## 6) Impact code (zones à modifier)
+
+- `panel_app/kpi_health_check_panel.py`
+  - Ajout widgets (group + benchmark options)
+  - Orchestration `_update_site_view`:
+    - récupérer les dataframes filtrées
+    - appeler les fonctions des modules (group selection / benchmark / plot building)
+    - pousser les figures dans les panes
+  - Cache: intégrer les nouveaux paramètres dans `_drilldown_cache_key`.
+
+- `process_kpi/kpi_health_check/kpi_groups.py`
+  - nouvelle logique de groupe KPI + top-N
+
+- `process_kpi/kpi_health_check/benchmarks.py`
+  - nouveaux calculs benchmark SLA (+ population optionnel)
+
+- `panel_app/kpi_health_check_drilldown_plots.py`
+  - builders Plotly (trend annoté + timeline BAD)
+
+Paramètres à ajouter dans la cache key:
+
+- `kpi_group_select.value`
+- `kpi_group_mode.value`
+- `benchmark_mode.value`
+- `max_kpis_in_plot`
+
+Persistance profil (si on valide):
+
+- `kpi_group_selected`
+- `kpi_group_mode`
+- `benchmark_mode`
+- `max_kpis_in_plot` (si exposé)
+
+- Optionnel (si on veut isoler la logique):
+  - nouveau module utilitaire `process_kpi/kpi_health_check/kpi_groups.py` (mais on peut rester inline pour v1).
+
+## 7) Critères d’acceptation
+
+- Quand je sélectionne un site/RAT:
+  - je vois un trend lisible avec baseline/seuil/SLA
+  - je peux masquer/afficher des KPI dans la légende
+- Quand je choisis un groupe:
+  - le graphe affiche les KPI du groupe (selon mode)
+  - la légende permet d’isoler un KPI
+- Le benchmark SLA apparaît seulement si SLA existe.
+- Aucun effet de bord sur export / cache / callbacks.
+
+## 7.1) Risques & mitigations
+
+- Noms KPI hétérogènes (vendors) => fallback `Other` + regex ajustables.
+- Trop de KPI à tracer => `max_kpis_in_plot` + top-N.
+- SLA incohérents (NaN/texte) => ignorer SLA et afficher seulement baseline/seuil.
+
+## 8) Ordre de livraison (recommandé)
+
+1. Ajouter widgets groupes + logique de sélection KPI (garde-fous perf)
+2. Trend annoté (baseline + seuil + SLA)
+3. Timeline BAD/streak
+4. Population benchmark (optionnel)
+
+## Definition of Done (DoD)
+
+- Démo: 1 site 2G + 1 site 3G + 1 site LTE.
+- Vérifier que:
+  - double-clic tables => drill-down OK.
+  - cache drill-down fonctionne (pas de lag, pas de rerender inutile).
+  - export drill-down OK.
+
+## Questions à valider
+
+- Quels groupes minimum tu veux (liste finale) ?
+- En mode groupe, tu veux:
+  - tracer tous les KPI du groupe ? ou
+  - limiter à ceux cochés dans `Compare KPIs` ? (recommandé)
+- Pour le benchmark:
+  - SLA uniquement (demandé)
+  - +option population (bonus) ?

documentations/kpi_health_check_improvement_roadmap.md

@@ -0,0 +1,301 @@
+# KPI Health Check (Panel) — Plan d’amélioration (Roadmap)
+
+## 0) Objectif
+
+Consolider l’app **KPI Health Check** pour une utilisation “NPO / exploitation” plus fluide et plus actionnable.
+
+Axes demandés:
+
+- **[A] Exploitation / priorisation** (alert pack, ops queue, snapshot/delta, RCA hints)
+- **[B] Visualisation** (map des sites, corrélation KPI)
+
+Décision prise:
+
+- **“Complaint sites only” = UI + export Excel (les deux)**
+
+Non-scope:
+
+- Génération PDF / evidence pack (optionnel, non prioritaire).
+
+## 0.1) Principes (invariants)
+
+- **Compatibilité**: ne pas casser l’existant (tables, drill-down, export principal).
+- **Performance**: éviter les recalculs inutiles (réutiliser caches/versions déjà en place dans l’UI).
+- **Robustesse données**: gérer proprement `NO_DATA`, colonnes manquantes, coordonnées absentes.
+- **Export Excel**: garder des noms d’onglets **stables** (important pour les utilisateurs qui automatisent).
+
+---
+
+## 1) État actuel (déjà en place)
+
+### 1.1 Flux de l’app
+
+- Upload KPI **2G/3G/LTE** (CSV/ZIP)
+- Normalisation `date_only`, `site_code`, enrichissement éventuel `City/Lat/Lon`
+- Construction + édition des **rules** (`direction`, `sla`)
+- Health-check: `OK / DEGRADED / PERSISTENT_DEGRADED / RESOLVED / NO_DATA`
+- Synthèses:
+  - `Site_Summary`
+  - `MultiRAT_Summary` (score criticité)
+  - `Top_Anomalies` (score anomaly)
+- Drill-down: trend + heatmap + histogram
+- Export Excel (Datasets / KPI Rules / Summary / Status / MultiRAT / Top)
+- Gestion: presets + profiles
+- Filtre existant: checkbox **Only complaint sites** (filtre les tables multi-rat / top anomalies)
+
+### 1.2 Fichiers “source of truth”
+
+- UI:
+  - `panel_app/kpi_health_check_panel.py`
+- Export:
+  - `process_kpi/kpi_health_check/export.py`
+- Calculs:
+  - `process_kpi/kpi_health_check/engine.py`
+  - `process_kpi/kpi_health_check/multi_rat.py`
+
+---
+
+## 2) Roadmap (ordre recommandé)
+
+### Phase 1 — Complaint sites only (UI + Export) (priorité haute)
+
+#### 2.1 UI: onglet dédié “Complaint sites only”
+
+But: ne plus dépendre d’un filtre à cocher; fournir un écran prêt à l’emploi.
+
+Contenu onglet:
+
+- `MultiRAT Summary (Complaint)`
+- `Top Anomalies (Complaint)`
+- Optionnel: un petit “mini résumé” (counts)
+
+Spécifications:
+
+- Les tables doivent être **toujours** filtrées sur `is_complaint_site == True`.
+- Les interactions existantes restent:
+  - double-click (ou click) pour appliquer le drill-down (`_handle_double_click` + `_apply_drilldown_selection`).
+
+Implémentation (point d’intégration):
+
+- Créer 2 nouveaux `Tabulator` dans `kpi_health_check_panel.py`, alimentés par une fonction de refresh dédiée.
+- Réutiliser la logique existante de flag `is_complaint_site` déjà posée dans `_apply_complaint_flags()`.
+
+Critères d’acceptation:
+
+- Après `Run health check`, l’onglet affiche uniquement les complaint sites.
+- Les filtres “city / min score / top RAT / status” ne doivent pas casser l’onglet.
+- Si la liste plaintes est vide/non trouvée, l’onglet reste vide (ou affiche un message) **sans erreur**.
+
+#### 2.2 Export Excel: feuilles “Complaint sites only”
+
+But: avoir un export directement partageable “ops / plaintes”.
+
+Feuilles proposées:
+
+- `Complaint_MultiRAT`
+- `Complaint_Top_Anomalies`
+
+Option bonus (si utile):
+
+- `Complaint_Ops_Queue` (par site) = tri par criticité pondérée trafic si dispo.
+
+Implémentation (point d’intégration):
+
+- Étendre `process_kpi/kpi_health_check/export.py`:
+  - soit en ajoutant de nouveaux paramètres optionnels,
+  - soit en ajoutant des dfs supplémentaires en fin de liste (compatibilité).
+- Dans `kpi_health_check_panel.py`, construire les df “complaint only” à partir de `current_multirat_df` / `current_top_anomalies_df` ou des raw (selon besoin) et les fournir à l’export.
+
+Critères d’acceptation:
+
+- L’export contient les 2 feuilles complaint.
+- Les feuilles complaint restent vides si aucune liste plaintes n’est chargée et aucun fichier `data/complaint_sites.*` n’est trouvé.
+- Les noms d’onglets restent < 31 caractères et sans caractères invalides (contrainte Excel).
+
+---
+
+### Phase 2 — Ops Queue + Alert Pack (priorité haute)
+
+#### 2.3 “Ops Queue” (table unique priorisée)
+
+But: une table de travail qui regroupe le besoin exploitation:
+
+- 1 ligne par site
+- priorité = criticité (pondérée trafic si dispo)
+- infos clés: `impacted_rats`, `persistent_kpis_total`, `degraded_kpis_total`, `resolved_kpis_total`, `is_complaint_site`, trafic
+
+Implémentation:
+
+- Construire `ops_queue_df` à partir de `current_multirat_raw` (qui contient déjà scores + flags).
+- Ajouter un onglet UI “Ops Queue” + une feuille Excel.
+
+#### 2.4 “Alert Pack” export court
+
+But: un export “prêt à envoyer” (résumé + ops queue + top anomalies) sans l’exhaustivité.
+
+- Nouveau bouton export, ou une option dans l’export existant.
+
+---
+
+### Phase 3 — Snapshot + Delta (priorité haute)
+
+#### 2.5 Snapshot de run
+
+But: figer un run (résultats + paramètres + rules) pour audit et comparaison.
+
+Format recommandé:
+
+- `json` (simple) ou `parquet` (plus robuste pour gros volumes). Pour MVP: JSON.
+
+Contenu snapshot (proposition):
+
+- `snapshot_version`: int
+- `created_at`: ISO datetime
+- `profile_config`: dict (baseline/recent/thr/min streak + filtres)
+- `rules_df`: list[dict] (records)
+- `multirat_df`: list[dict]
+- `top_anomalies_df`: list[dict]
+
+UI:
+
+- `FileDownload` “Save snapshot”
+- `FileInput` “Load snapshot”
+
+#### 2.6 Delta entre runs
+
+But: sortir les variations entre snapshot chargé et run courant:
+
+- `New degraded`
+- `Still degraded`
+- `Resolved`
+- `Severity up / down`
+
+Sorties:
+
+- onglet UI “Delta”
+- feuille Excel “Delta”
+
+---
+
+### Phase 4 — Visualisation (Map + Corrélation) (priorité moyenne)
+
+#### 2.7 Map des sites dégradés
+
+But: voir des clusters (zone / ville) et naviguer vers le drill-down.
+
+Pré-requis:
+
+- `Latitude` / `Longitude` disponibles (normalisation ou physical db).
+
+Affichage:
+
+- Plotly `scatter_mapbox` (style `open-street-map`) ou `scatter_geo`
+- Couleur = status (ou degraded/persistent)
+- Taille = criticité (weighted si dispo)
+
+Interaction:
+
+- click point => sélection site dans drill-down
+
+#### 2.8 KPI Correlation Explorer
+
+But: RCA rapide sur un site/RAT.
+
+- Matrice corrélation des KPI sélectionnés (Pearson/Spearman)
+- fenêtre: `recent` / `baseline` / `full filtered range`
+- sortie: heatmap Plotly (`px.imshow`)
+
+---
+
+## 3) RCA Hints (bonus mais très utile)
+
+Objectif: rendre `Top_Anomalies` plus actionnable.
+
+Ajouts colonnes:
+
+- `delta_pct`
+- `sla_breached`
+- `reason` (texte)
+- `data_quality_flag`
+
+Ces colonnes peuvent être calculées:
+
+- lors de la génération de `Top_Anomalies` (dans `multi_rat.py`),
+- ou côté Panel lors du refresh (plus rapide à itérer).
+
+---
+
+## 4) Découpage technique (recommandé)
+
+Pour éviter d’alourdir `kpi_health_check_panel.py`:
+
+- `process_kpi/kpi_health_check/snapshot.py`
+  - save/load snapshot + validation version
+  - compute delta
+
+- `process_kpi/kpi_health_check/ops_queue.py`
+  - build ops queue df
+
+- `panel_app/kpi_health_check_maps.py`
+  - build map figure
+
+- `process_kpi/kpi_health_check/correlation.py`
+  - build correlation matrix
+
+---
+
+## 4.1) Qualité des données & garde-fous (à intégrer dès Sprint 1)
+
+- **Validation d’inputs**:
+  - dataset vide / pas de `date_only` / pas de `site_code`
+  - aucun point dans la `analysis_range`
+- **Validation complaint list**:
+  - parsing robuste (csv/txt/xlsx déjà prévu)
+  - normalisation des codes site (cast int + extraction regex si besoin)
+- **Fail-safe**: si `is_complaint_site` n’existe pas, ne pas crasher (considérer `False`).
+
+## 4.2) Performance / mémoire (à surveiller)
+
+- Limiter le volume affiché dans les tables (ex: top N) quand nécessaire.
+- Éviter les copies inutiles de DataFrames lors des refresh.
+- Garder les calculs lourds dans `process_kpi/*` et l’UI comme orchestration.
+
+## 4.3) Tests rapides (smoke tests) / DoD
+
+Minimum avant de considérer une phase “done”:
+
+- Charger un petit sample 2G/3G/LTE et exécuter `Load` + `Run` sans erreur.
+- Vérifier:
+  - export Excel principal
+  - export complaint
+  - double-click tables => drill-down
+  - aucun crash si complaint list absente
+
+---
+
+## 5) Critères de réussite globaux
+
+- **Exploitation**: obtenir une liste priorisée + top anomalies complaint en < 1 minute.
+- **Partage**: export Excel avec onglets complaint + delta.
+- **Visualisation**: map cliquable et corrélation sur drill-down.
+
+---
+
+## 6) Plan de livraison (sprints)
+
+- Sprint 1: Complaint UI tab + Export complaint sheets
+- Sprint 2: Ops Queue + Alert Pack
+- Sprint 3: Snapshot + Delta
+- Sprint 4: Map + Correlation explorer
+- Sprint 5 (option): RCA hints (reason/tags)
+
+---
+
+## 7) Risques & mitigations
+
+- **Volumes importants** (beaucoup de sites/KPI/jours):
+  - mitigation: top-N dans certaines vues + pagination Tabulator + éviter les figures avec trop de traces.
+- **Coordonnées manquantes** (pas de Lat/Lon):
+  - mitigation: la map doit être optionnelle et afficher un message clair si données insuffisantes.
+- **Excel / automatisation utilisateur** (noms d’onglets attendus):
+  - mitigation: ajouter les nouveaux onglets sans renommer les existants.

documentations/kpi_health_check_map_v2_plan.md

@@ -0,0 +1,120 @@
+# KPI Health Check – Map v2 (Mode exploitation + recherche)
+
+## Objectif
+
+Améliorer l’onglet **Map** pour l’exploitation quotidienne (≈ 0–3000 sites) avec:
+
+- Vue géographique lisible immédiatement (zoom/centrage automatique)
+- Encodage visuel orienté actions (status + criticité)
+- Recherche rapide (site_code / City) + navigation vers le drill-down
+- Performance stable (pas de lag, pas de sur-affichage de labels)
+
+## Non-objectifs
+
+- RCA hints / tags automatiques (Sprint 5)
+- Clustering avancé “maison” (geohash/grid) si non indispensable
+- Historique temporel sur la map
+
+## UX / Fonctionnel
+
+### A. Encodage visuel
+
+- **Taille**: criticité (déjà en place)
+- **Couleur**: status dominant du site (ex: `PERSISTENT_DEGRADED`, `DEGRADED`, `RESOLVED`, `NO_DATA`)
+- **Label**: `site_code` (déjà en place) limité à un Top-N configurable
+
+### B. Fit bounds (centrage auto)
+
+- Bouton (ou comportement automatique) “Fit to points”
+- À chaque refresh map, centrer/zoomer sur l’ensemble des points affichés (après filtres)
+
+### C. Filtres Map (mode exploitation)
+
+Widgets simples dans l’onglet Map:
+- **Top N sites** (par score) + option “All”
+- **Only complaint sites** (reprend le bool déjà existant dans le sidebar)
+- **RAT impacted** (2G/3G/LTE/Any) basé sur `impacted_rats`
+- Option: “Only persistent” (status)
+
+### D. Recherche (rapide)
+
+- Champ `Search` (texte):
+  - accepte `site_code` (entier) ou `City` (substring)
+  - résultat:
+    - si `site_code` trouvé: centre la map sur le site + sélectionne le site (drill-down)
+    - si `City`: filtre/centre sur les sites de la ville + propose une petite liste (Top 20) cliquable
+
+### E. Interaction
+
+- Click point => drill-down (déjà en place)
+- Option: bouton “Open Drill-down” à côté des infos (si on ajoute un mini panneau résumé)
+
+## Données / Hypothèses
+
+- Les coords sont présentes via `Latitude/Longitude` (venant du `physical_db`)
+- `current_multirat_raw` contient:
+  - `site_code`
+  - scores (`criticality_score_weighted` ou `criticality_score`)
+  - `impacted_rats`
+  - compteurs persistent/degraded/resolved
+- Les status par RAT existent dans `current_status_df` (par `site_code`, `RAT`, `status`)
+
+## Plan d’implémentation (Map v2)
+
+### 1) Calcul du status dominant
+
+- À partir de `current_status_df`, agréger par `site_code`:
+  - règle: `PERSISTENT_DEGRADED` > `DEGRADED` > `RESOLVED` > `OK` > `NO_DATA`
+  - produire une colonne `dominant_status`
+- Merge dans le DF map
+
+### 2) Color mapping
+
+- Définir une palette stable:
+  - `PERSISTENT_DEGRADED` -> rouge foncé
+  - `DEGRADED` -> rouge/orange
+  - `RESOLVED` -> vert
+  - `OK` -> bleu
+  - `NO_DATA` -> gris
+- Appliquer via `px.scatter_mapbox(..., color='dominant_status')` + `category_orders`
+
+### 3) Fit bounds
+
+- Calculer `lat_min/max`, `lon_min/max` sur les points affichés
+- Utiliser `fig.update_layout(mapbox=dict(bounds=...))` ou `center/zoom` estimé
+- Ajouter un bouton “Fit to points” si on veut éviter un recentrage automatique trop agressif
+
+### 4) Recherche
+
+- Widget `AutocompleteInput` ou `TextInput` + bouton `Go`
+- Si nombre:
+  - set `site_select` + centre map
+- Si texte:
+  - filtrer sur `City` et afficher une liste cliquable (Tabulator ou Select)
+
+### 5) Filtres Map
+
+- Implémenter filtres (TopN / complaint / RAT impacted / status) avant rendu
+- Ajouter widgets correspondants dans l’onglet Map
+
+### 6) Tests / Critères de réussite
+
+- 3000 sites: refresh map < 2s (hors 1er chargement)
+- Search par `site_code`: centre + drill-down correct
+- Search par `City`: restreint l’affichage et fit bounds
+- Les labels restent limités (Top-N)
+
+## Risques / Points d’attention
+
+- Trop de texte (labels) => perf (mitigation: Top-N déjà fait)
+- Fit bounds automatique peut “bouger” la map trop souvent (mitigation: bouton / toggle)
+- `dominant_status` doit être robuste même si `current_status_df` vide
+
+## Estimation
+
+- Status dominant + colors: 45–90 min
+- Fit bounds: 20–40 min
+- Recherche: 1–2 h
+- Filtres map: 1–2 h
+
+Total: ~3–6 h selon niveau de polish.

hf_spaces/kpi_analysis/Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.11-slim
+
+RUN useradd -m -u 1000 user
+WORKDIR /app
+
+COPY --chown=user:user requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt
+
+COPY --chown=user:user . /app
+
+USER user
+EXPOSE 7860
+
+CMD [
+  "panel",
+  "serve",
+  "panel_app/panel_portal.py",
+  "--address",
+  "0.0.0.0",
+  "--port",
+  "7860",
+  "--allow-websocket-origin",
+  "*",
+  "--num-procs",
+  "1",
+  "--log-level",
+  "info"
+]

hf_spaces/kpi_analysis/README.md

@@ -0,0 +1,11 @@
+---
+title: KPI Analysis (Panel)
+emoji: "📊"
+colorFrom: blue
+colorTo: red
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+This Space runs the Panel portal located at `panel_app/panel_portal.py`.

hf_spaces/kpi_analysis/requirements.txt

@@ -0,0 +1,6 @@
+panel>=1.4
+bokeh>=3.4
+pandas>=2.0
+numpy>=1.23
+plotly>=5.0
+xlsxwriter>=3.0