📊Scénarios d'analyse

Étapes

1. Le serveur MCP Analyste expose tous les endpoints analytics comme des outils conversationnels. Tapez ces prompts directement dans Claude (avec le MCP connecté) pour déclencher les analyses correspondantes.

2. Prompts — Vue d'ensemble & métriques

   • « Quelles sont les métriques globales de l'importation 42 ? »

     → get_metrics

   • « Montre-moi l'évolution du nombre de posts par semaine »

     → get_timeseries (granularity=week)

   • « Quelle est la répartition par plateforme ? »

     → get_breakdown (by=platform)

   • « Répartition par langue sur les posts originaux »

     → get_breakdown (by=lang, post_types=[post])

3. Prompts — Comptes & mentions

   • « Qui sont les 10 comptes les plus actifs ? »

     → get_top_accounts (sort_by=post_count)

   • « Quels comptes ont généré le plus d'engagements ? »

     → get_top_accounts (sort_by=engagements)

   • « Qui sont les comptes les plus mentionnés dans les posts ? »

     → get_mentions

   • « Quels comptes ont été le plus cités (quote-tweets) ? »

     → get_top_quoted_accounts

   • « Quels comptes ont été le plus repartagés ? »

     → get_top_shared_accounts

   • « Montre-moi les posts de @elonmusk dans ce corpus »

     → search_posts (screen_names=[elonmusk])

4. Prompts — Hashtags, domaines & URLs

   • « Quels sont les hashtags les plus utilisés ? »

     → get_top_hashtags

   • « Quelles sources médias sont les plus partagées ? »

     → get_top_domains

   • « Quels articles ont été les plus relayés ? »

     → get_top_urls

   • « Quelles entités nommées (personnes, organisations, lieux) reviennent le plus ? »

     → get_top_ner

   • « Top 20 personnes (PER) mentionnées dans les posts »

     → get_top_ner (entity_types=[PER], limit=20)

5. Prompts — Analyse NLP : sentiment

   • « Quelle est la distribution des sentiments sur cette analyse ? »

     → get_sentiment_distribution (analyse_id=X)

   • « Quel est le sentiment cluster par cluster ? »

     → get_clusters_sentiment (analyse_id=X)

   • « Quel est le sentiment narratif par narratif ? »

     → get_narratives_sentiment (analyse_id=X)

   • « Montre-moi les posts positifs sur ce sujet »

     → search_posts (sentiments=[positive], analyse_id=X)

6. Prompts — Analyse NLP : clusters thématiques

   • « Quels sont les grands sujets du corpus ? »

     → get_topic_clusters (analyse_id=X)

   • « Comment évoluent les clusters dans le temps ? »

     → get_timeseries avec cluster_ids

   • « Quels comptes sont actifs dans le cluster 'GenAI' ? »

     → get_top_accounts (cluster_labels=[GenAI], analyse_id=X)

   • « Top hashtags dans le cluster 3 »

     → get_top_hashtags (cluster_ids=[3], analyse_id=X)

7. Prompts — Analyse NLP : narratifs & claims

   • « Quels sont les narratifs détectés dans cette analyse ? »

     → get_narratives (analyse_id=X)

   • « Quels claims (affirmations) reviennent le plus ? »

     → get_claims (analyse_id=X)

   • « Quels sont les grands sujets de narratifs ? »

     → get_narrative_topics (analyse_id=X)

   • « Comment évolue le narratif 'immigration' dans le temps ? »

     → get_narratives_timeseries (narrative_topics=[immigration])

   • « Quels sont les posts associés au narratif 5 ? »

     → search_posts (narrative_ids=[5], analyse_id=X)

   • « Quels comptes relaient le sujet 'économie' ? »

     → get_top_accounts (narrative_topics=[économie], analyse_id=X)

   • « Quelles entités NER sont associées au narratif 5 ? »

     → get_narratives_ner (analyse_id=X)

   • « Top organisations citées dans les claims de désinformation »

     → get_claims_ner (entity_types=[ORG], analyse_id=X)

8. Prompts — Coordination

   • « Y a-t-il des comportements coordonnés dans ce corpus ? »

     → get_coordination_clusters

   • « Quels sont les 10 clusters de coordination les plus actifs ? »

     → get_coordination_clusters (sort_by=cluster_engagements, limit=10)

   • « Montre-moi les posts du cluster de coordination 42 »

     → get_coordination_cluster_posts (coordination_cluster_ids=[42])

   • « Quel est le contenu original diffusé de façon coordonnée ? »

     → get_coordination_clusters — champ init_post de chaque cluster

9. Prompts — Référentiel narratifs & claims (CRUD)

   • « Quels sujets de narratifs sont configurés dans ce projet ? »

     → list_narrative_topics

   • « Liste tous les narratifs sur le thème 'immigration' »

     → list_narratives (topic=immigration)

   • « Quels narratifs existent sur l'économie ? »

     → list_narratives (topic=économie)

   • « Combien de claims contient le narratif 5 ? »

     → list_narratives — champ claims_count du narratif retourné

   • « Liste les claims du narratif 5 »

     → list_claims (narrative_id=5)

   • « Quels sont les claims sur le sujet 'désinformation' ? »

     → list_claims (topic=désinformation) — recherche via les narratifs correspondants

   • « Montre-moi les claims humains sur le thème 'santé' »

     → list_claims (topic=santé, claim_origin=human)

Étapes

1. Chaque scénario se décline en deux interfaces interchangeables :
   
   - SDS-API REST — base `/api/v1/sds/data/analytics/` — pour les intégrations frontend et les scripts.
   - MCP Analyste — serveur MCP distant interrogeable par un agent IA — pour les analyses conversationnelles.

2. Filtres communs à tous les scénarios

   Champ	Description	Exemple
   importation_ids	**Obligatoire.** Un ou plusieurs identifiants d'importation. Obtenir via `list_importations` (MCP) ou l'onglet Importations du dashboard.	[42, 43]
   from_date / to_date	Plage de dates des posts (ISO 8601). Permet de restreindre l'analyse à une période.	2025-01-01 / 2025-03-31
   post_types	Types de posts à inclure. **Défaut : `post` uniquement** (posts originaux). Valeurs possibles : `post`, `repost`, `quote`, `share`, `comment`.	["post"]
   langs	Filtrer par langue détectée (code ISO 639-1). Laisser vide = toutes les langues.	["fr", "en"]
   screen_names	Restreindre les résultats aux posts publiés par ces comptes. Utile pour analyser un sous-ensemble d'auteurs spécifiques.	["elonmusk", "bbcworld"]

Prérequis

• Avoir au moins une importation avec des données collectées.

Étapes

1. SDS-API : `GET /analytics/metrics`
   
   MCP : outil `get_metrics`

2. Paramètres

   Champ	Description	Exemple
   importation_ids	Obligatoire. Identifiant(s) de l'importation à analyser.	[42]
   from_date / to_date	Optionnel. Restreindre à une période.	2025-01-01 / 2025-03-31

Prérequis

• Avoir au moins une importation avec des données collectées.

Étapes

1. SDS-API : `GET /analytics/timeseries`
   
   MCP : outil `get_timeseries`

2. Paramètres

   Champ	Description	Exemple
   importation_ids	Obligatoire.	[42]
   granularity	Résolution temporelle : `day`, `week`, `month`. Défaut : `day`.	week
   fields	Métriques à inclure dans chaque point. Défaut : toutes. Valeurs possibles : `posts`, `engagements`, `reactions`, `shares`, `comments`, `quotes`, `views`, `accounts`.	["posts", "engagements"]
   analyse_id	Optionnel. Identifiant de l'analyse NLP. Requis si `cluster_ids` est fourni.	7
   cluster_ids	Optionnel. Restreindre la timeseries aux posts appartenant à un ou plusieurs clusters. Permet de comparer l'évolution de plusieurs thèmes sur la même période.	[3, 7]

Prérequis

• Avoir au moins une importation avec des données collectées.

Étapes

1. SDS-API : `GET /analytics/breakdown`
   
   MCP : outil `get_breakdown`

2. Paramètres

   Champ	Description	Exemple
   importation_ids	Obligatoire.	[42]
   by	Dimension d'agrégation. Valeurs : `platform`, `lang`, `type`.	platform

Prérequis

• Avoir au moins une importation avec des données collectées.

Étapes

1. SDS-API : `GET /analytics/accounts`
   
   MCP : outil `get_top_accounts`

2. Paramètres

   Champ	Description	Exemple
   importation_ids	Obligatoire.	[42]
   sort_by	Critère de tri. Valeurs : `post_count` (défaut), `engagements`, `followers`, `views`.	engagements
   platform	Optionnel. Restreindre à une plateforme.	Twitter
   min_followers / max_followers	Optionnel. Filtrer par tranche d'audience.	10000 / 500000
   narrative_ids	Optionnel. Restreindre aux comptes actifs dans ces narratifs (NLP requis).	[1, 2]
   narrative_topics	Optionnel. Filtrer par sujet de narratif (chaîne libre correspondant au champ `topic`).	["immigration"]
   limit / offset	Pagination. Défaut : 50 résultats.	20 / 0

Prérequis

• Avoir au moins une importation avec des données collectées.

Étapes

1. SDS-API : `GET /analytics/mentions`
   
   MCP : outil `get_mentions`

2. Paramètres

   Champ	Description	Exemple
   importation_ids	Obligatoire.	[42]
   sort_by	Critère de tri. Valeurs : `mention_count` (défaut), `engagements`, `followers`.	mention_count
   screen_names	Optionnel. Restreindre aux mentions présentes dans les posts de ces auteurs.	["journaliste1"]
   limit / offset	Pagination. Défaut : 50 résultats.	20 / 0

Prérequis

• Avoir au moins une importation avec des données collectées.

Étapes

1. SDS-API : `GET /analytics/top/hashtags`
   
   MCP : outil `get_top_hashtags`

2. Paramètres

   Champ	Description	Exemple
   importation_ids	Obligatoire.	[42]
   sort_by	Critère de tri. Valeurs : `posts` (défaut), `engagements`, `views`, `accounts`.	engagements
   limit / offset	Pagination. Défaut : 20 résultats.	50 / 0

Prérequis

• Avoir au moins une importation avec des données collectées.
• Les posts doivent contenir des URLs référencées dans la table `documents` (type `url`).

Étapes

1. SDS-API : `GET /analytics/top/domains`
   
   MCP : outil `get_top_domains`

2. Paramètres

   Champ	Description	Exemple
   importation_ids	Obligatoire.	[42]
   sort_by	Critère de tri. Valeurs : `posts` (défaut), `engagements`, `views`, `url_count`.	posts
   screen_names	Optionnel. Restreindre aux URLs partagées par ces comptes auteurs.	["compteA"]
   limit / offset	Pagination. Défaut : 20 résultats.	20 / 0

Prérequis

• Avoir au moins une importation avec des données collectées.
• Les posts doivent contenir des URLs référencées dans la table `documents` (type `url`).

Étapes

1. SDS-API : `GET /analytics/top/urls`
   
   *(non encore disponible dans le MCP)*

2. Paramètres

   Champ	Description	Exemple
   importation_ids	Obligatoire.	[42]
   sort_by	Critère de tri. Valeurs : `posts` (défaut), `engagements`, `views`, `accounts`.	engagements
   screen_names	Optionnel. Restreindre aux URLs partagées par ces comptes auteurs.	["compteA", "compteB"]
   limit / offset	Pagination. Défaut : 20 résultats.	20 / 0

Prérequis

• Avoir au moins une importation avec des données collectées.

Étapes

1. SDS-API : `GET /analytics/posts`
   
   MCP : outil `search_posts`

2. Paramètres

   Champ	Description	Exemple
   importation_ids	Obligatoire.	[42]
   sort_by	Critère de tri : `created_at` (défaut) ou `engagements`.	engagements
   screen_names	Optionnel. Restreindre aux posts de ces auteurs.	["compteA"]
   langs	Optionnel. Filtrer par langue.	["fr"]
   limit / offset	Pagination. Défaut : 50 résultats, max 500.	20 / 0

3. Filtres avancés (NLP requis) : `narrative_ids`, `claim_history_ids`, `narrative_topics` pour restreindre aux posts d'un narratif spécifique ; `sentiments` (ex. `["positive"]`) pour filtrer par tonalité émotionnelle détectée.

Prérequis

• Avoir au moins une importation avec des données collectées.
• Avoir créé une analyse NLP et lancé le pipeline Sentiment sur cette analyse.
• Disposer de l'`analyse_id` correspondant (via `list_analyses` dans le MCP ou l'onglet Analyses).

Étapes

1. SDS-API : `GET /analytics/sentiment`
   
   MCP : outil `get_sentiment_distribution`

2. Paramètres

   Champ	Description	Exemple
   importation_ids	Obligatoire.	[42]
   analyse_id	Obligatoire. Identifiant de l'analyse NLP avec les sentiments calculés.	7

Prérequis

• Avoir au moins une importation avec des données collectées.
• Avoir créé une analyse NLP et lancé le pipeline Clustering + Annotation sur cette analyse.
• Disposer de l'`analyse_id` correspondant.

Étapes

1. SDS-API : `GET /analytics/clusters`
   
   MCP : outil `get_topic_clusters`

2. Paramètres

   Champ	Description	Exemple
   importation_ids	Obligatoire.	[42]
   analyse_id	Obligatoire. Identifiant de l'analyse NLP avec le clustering calculé.	7
   from_date / to_date	Optionnel. Restreindre à une période pour analyser l'évolution thématique.	2025-01-01 / 2025-01-31

Prérequis

• Avoir au moins une importation avec des données collectées.

Étapes

1. 1

   Appeler `GET /analytics/metrics` pour obtenir les totaux en en-tête de dashboard.

2. 2

   Appeler `GET /analytics/timeseries?granularity=day&fields=posts,engagements` pour le graphique d'évolution.

3. 3

   Appeler `GET /analytics/breakdown?by=platform` puis `?by=lang` pour les camemberts de répartition.

4. 4

   Appeler `GET /analytics/accounts?sort_by=engagements&limit=10` pour le leaderboard des comptes.

5. 5

   Appeler `GET /analytics/top/hashtags?sort_by=posts&limit=20` pour le nuage de mots.

6. 6

   Appeler `GET /analytics/top/domains?sort_by=posts&limit=10` pour le top des sources.

7. Tous ces appels sont indépendants et peuvent être lancés en parallèle pour minimiser le temps de chargement.

Schéma

Prérequis

• Avoir au moins une importation avec des données collectées.
• Avoir créé une analyse NLP et lancé le pipeline NER.
• Disposer de l'`analyse_id` correspondant.

Étapes

1. SDS-API : `GET /analytics/top/ner`
   
   MCP : outil `get_top_ner`

2. Paramètres

   Champ	Description	Exemple
   importation_ids	Obligatoire.	[42]
   analyse_id	Obligatoire.	7
   entity_types	Optionnel. Filtrer par type : `PER` (personnes), `ORG` (organisations), `LOC` (lieux).	["PER", "ORG"]
   narrative_ids / narrative_topics	Optionnel. Restreindre aux entités des posts associés à ces narratifs.	[5]
   sort_by	Critère de tri : `posts` (défaut), `engagements`, `views`, `accounts`, `occurrences`.	occurrences

Prérequis

• Avoir lancé le pipeline Narratifs sur une analyse NLP.
• Disposer de l'`analyse_id`.

Étapes

1. SDS-API : `GET /analytics/narratives`, `/narratives/timeseries`, `/narratives/sentiment`, `/narratives/ner`
   
   MCP : outils `get_narratives`, `get_narratives_timeseries`, `get_narratives_sentiment`, `get_narratives_ner`

2. Paramètres principaux

   Champ	Description	Exemple
   analyse_id	Obligatoire pour tous les endpoints narratifs.	7
   sort_by	`posts`, `engagements`, `views`, `accounts`.	posts
   narrative_ids	Restreindre à ces narratifs dans les filtres posts/accounts/NER.	[1, 2]
   narrative_topics	Filtrer par sujet de narratif (chaîne libre correspondant au champ `topic`).	["immigration"]
   claim_history_ids	Filtrer par claim précis.	[10]

3. 1

   Appeler `/narratives` pour la liste des narratifs avec leurs métriques.

4. 2

   Appeler `/narratives/timeseries?granularity=day` pour l'évolution par narratif.

5. 3

   Appeler `/narratives/sentiment` pour croiser chaque narratif avec ses sentiments (positif/négatif/neutre).

6. 4

   Appeler `/narratives/ner` pour les entités nommées dominantes par narratif.

Prérequis

• Avoir au moins une importation avec des données collectées.
• Le pipeline de détection de coordination (join_document_document) doit avoir été exécuté.

Étapes

1. SDS-API : `GET /analytics/coordination-clusters`, `GET /analytics/coordination-clusters/posts`
   
   MCP : outils `get_coordination_clusters`, `get_coordination_cluster_posts`

2. Paramètres

   Champ	Description	Exemple
   importation_ids	Obligatoire.	[42]
   sort_by	`cluster_engagements` (défaut), `posts`, `accounts`, `cluster_views`.	posts
   post_types	Types de posts à inclure dans les composantes. Défaut : tous.	["post", "repost"]
   coordination_cluster_ids	(Pour /posts uniquement) Restreindre aux posts d'un cluster précis.	[42]

3. 1

   Appeler `GET /coordination-clusters?sort_by=posts&limit=20` pour identifier les clusters les plus actifs.

4. 2

   Examiner le champ `init_post` (texte du document initiateur) et `initiator_screen_name` pour comprendre l'origine de la coordination.

5. 3

   Appeler `GET /coordination-clusters/posts?coordination_cluster_ids=[X]` pour lister tous les posts d'un cluster spécifique et identifier les comptes participants.

Prérequis

• Des narratifs ont été créés dans l'interface d'administration SDS.
• Aucun `analyse_id` requis — ces endpoints sont indépendants du pipeline NLP.

Étapes

1. SDS-API : `GET /admin/narratives`, `GET /admin/claims`
   
   MCP : outils `list_narrative_topics`, `list_narratives`, `list_claims`
2. 1

   Appeler `list_narrative_topics` pour découvrir les grands thèmes (sujets distincts). Retourne une liste triée alphabétiquement.

3. Paramètres — list_narratives

   Champ	Description	Exemple
   topic	Filtre partiel insensible à la casse sur le champ `topic`. Ex. `immigration` retourne tous les narratifs dont le sujet contient ce mot.	immigration
   limit / offset	Pagination (défaut limit=100).	100 / 0

4. Paramètres — list_claims

   Champ	Description	Exemple
   narrative_id	Retourne directement les claims du narratif (prioritaire sur `topic`).	5
   topic	Recherche les claims en passant par les narratifs dont le sujet contient cette chaîne. Pratique pour « tous les claims sur la santé ».	santé
   claim_origin	Filtrer par origine : `human` (saisi manuellement) ou `llm` (généré par IA).	human
   limit / offset	Pagination (défaut limit=100).	100 / 0

5. 2

   Pour filtrer les claims par topic, `list_claims(topic=X)` effectue automatiquement deux appels : d'abord `list_narratives(topic=X)` pour récupérer les IDs, puis `list_claims` pour chaque narratif trouvé.