Dam Levels Data, ontologie et serveur MCP

Qu’est-ce que c’est

DamLevels-Data reconstitue l’état quotidien des 36 grands barrages de la Tunisie à partir des bulletins Situation des barrages que la Direction Générale des Barrages et des Grands Travaux Hydrauliques (DGBGTH) publie par l’intermédiaire de l’Observatoire National de l’Agriculture (ONAGRI) (onagri.nat.tn). Ces bulletins sont publics, mais n’existent que sous forme de PDF de trois pages dont la mise en page a changé au fil des ans. L’archive couvre la période du 2 juillet 2014 au 10 octobre 2025 : 3 985 dates de bulletin, 11 927 pages PDF et 129 390 valeurs quotidiennes de stock, chacune reliée au fichier, à la page, à la colonne et aux caractères imprimés dont elle provient. Le 10 octobre 2025, dernière date de l’archive, les 36 barrages contenaient 649,3 millions de m³, soit 27,4 % de leur capacité, et 18 d’entre eux étaient remplis à moins d’un quart ; le même jour en 2019, les 33 barrages alors publiés contenaient 1 392,8 millions de m³.

Elle est publiée sous forme d’un paquet ouvert — tableaux, provenance, indicateurs de qualité, couches SIG et l’ontologie DamLevels (DLO 0.3) — et d’un serveur MCP en lecture seule, grâce auquel un assistant IA peut répondre aux questions à partir de l’archive. Projet indépendant et non officiel, sans aucune affiliation avec la DGBGTH, l’ONAGRI ou le Ministère de l’Agriculture, ni approbation de leur part.

Du bulletin PDF à l’assistant IA

Le travail suit le modèle cinq étoiles des données ouvertes, d’un document sur le web vers les données liées, et ajoute une étape au-dessus : un serveur MCP que les assistants IA peuvent interroger.

Comment ça fonctionne

Des moteurs déterministes lisent la couche texte des PDF et les traits des tableaux — sans OCR ni ressaisie — de sorte qu’un même fichier donne toujours les mêmes valeurs. Les noms des barrages, imprimés en français et en arabe avec des graphies variables, sont rattachés à des identifiants stables (dam_id). Les valeurs manquantes restent manquantes : rien n’est interpolé, reporté ni remplacé par zéro. L’ontologie écrit ce que signifie réellement chaque colonne imprimée et le jour qu’elle décrit : les débits imprimés sur le bulletin du jour J portent sur le jour J−1, et l’une des deux colonnes « lâchers du jour » donne en fait les lâchers de l’année précédente.

Le serveur MCP expose dix outils en lecture seule — find_dam, list_dams, get_storage, get_fill, national_storage, compare_years, get_source, get_transfers, describe_variable et dataset_info. Il refuse les dates hors de l’archive et les saisies mal formées par une erreur explicite plutôt que par une réponse vide, utilise la capacité en vigueur à chaque date, marque les transferts de la page 3 comme PROBABLE, renvoie tous les candidats lorsqu’un nom ou un terme est ambigu, et joint à chaque réponse sa couverture, l’attribution de la source et ses réserves.

Cas d’usage

• Recherche en hydrologie et climat : comparer le stock d’un barrage au même jour calendaire sur onze ans, les jours manquants étant signalés comme manquants.
• Journalisme : vérifier un chiffre cité dans la presse en remontant au bulletin d’origine, jusqu’à la page, la colonne et les caractères imprimés.
• Politique publique : suivre la réserve nationale : 649 millions de m³, soit 27 % de la capacité, le 10 octobre 2025, avec 18 barrages sur 36 remplis à moins d’un quart.

Démo — exemple illustratif

{
"dam": { "dam_id": "sidisalem", "name_fr": "Sidi Salem" },
"date": "2025-10-10",
"storage_mm3": 137.196,
"capacity": { "status": "KNOWN", "capacity_mm3": 580.35 },
"fill_pct": 23.6, "printed_fill_pct": 23.6,
"source": {
  "source_file": "10-10-2025_1.pdf", "page": "1",
  "printed_text": "137,196",
  "bulletin_url": "https://www.onagri.nat.tn/uploads/barrages/BARRAGES-10-10-2025.pdf"
}
}

Statut et feuille de route

DamLevels-Data est open source et auto-hébergé : le serveur MCP s’exécute comme un processus stdio local à partir d’une copie du dépôt, sans endpoint distant. La version 1.1.2 est archivée sur Zenodo. Le dépôt GitHub est la source unique pour les données, l’installation et le code. Prochaines étapes prévues : enregistrer l’espace de noms de l’ontologie et publier le graphe complet, relier les barrages et les bassins versants à des jeux de données externes, publier la couche climatique des bassins versants (pluie, météorologie, humidité du sol), et résoudre avec l’éditeur les questions ouvertes sur les transferts de la page 3.

Rapport technique

Le rapport technique TD-TR-2026-04 (en anglais) documente chaque étape, du bulletin PDF aux données liées et au serveur MCP, avec ses preuves et ses limites, sous licence CC BY 4.0.

Version d’archive citable faisant foi : Nasfi, M. H., Boulaares, S., & Gasmi, T. (2026). DamLevels-Data: From PDF Bulletins to Linked, AI-Queryable Open Data on Tunisia’s Large Dams, 2014–2025. Technical report TD-TR-2026-04. tanitdata, Tunis. https://doi.org/10.5281/zenodo.23305079

Données et logiciel (version 1.1.2) : Nasfi, M. H., Boulaares, S., & Gasmi, T. (2026). DamLevels-Data: daily storage of Tunisia’s 36 large dams, 2014–2025. Zenodo. https://doi.org/10.5281/zenodo.23304326

Code source et données : github.com/tanitdata/DamLevels-Data