# VoteScope — Documentation exhaustive pour agents LLM > Référence technique complète : architecture, pipelines, modèles statistiques, schémas de données, conventions éditoriales et règles d'usage. Par Kim Leclerc (kimleclerc.ca). > Site : https://vote-scope.com Ce document est la version la plus détaillée des fichiers `llms.txt` et `llms-long.txt`. Il est destiné aux agents LLM qui ont besoin d'un contexte technique précis (architecture, schémas, méthodologie statistique) en plus de la cartographie des pages. --- ## 1. Identité du site VoteScope est un projet indépendant et non partisan créé par Kim Leclerc, statisticien québécois, qui produit des projections électorales probabilistes basées sur l'agrégation bayésienne de sondages publics. Le projet a pour vocation de rendre publiques les projections que les analystes électoraux gardent souvent en silos privés, et de comparer systématiquement les projections de modèle avec les marchés de prédiction (Polymarket, Kalshi). Le site est entièrement statique, hébergé sur Cloudflare Pages, construit avec un pipeline mixte : - pages HTML legacy à la racine (générées Python ou maintenues à la main) - pages Astro modernes pour les nouvelles routes (ex. `/usa/lame-duck`) - assets JSON exportés par les pipelines Python sous `web_data/` Le domaine héberge aussi une **verticale sport** (Sports Scope) sous `/sports/` qui applique la même philosophie analytique au sport (NHL d'abord, Coupe du monde FIFA 2026 ensuite). --- ## 2. Carte complète du site ### 2.1 Hubs et navigation transversale | URL | Type | Cycle éditorial | Description | |---|---|---|---| | `/` | Accueil | Quotidien | Carrousel projections actives + raccourcis | | `/hub` | Hub principal | Quotidien | Point d'entrée toutes juridictions | | `/canada-hub` | Hub Canada | Quotidien | Fédéral, Québec, Ontario, partielles, Polymarket | | `/usa-hub` | Hub USA | Hebdomadaire | Chambre, Sénat, gouverneurs, Polymarket | | `/france-hub` | Hub France | Hebdomadaire | Législatives, présidentielle 2027 | | `/partielles` | Index partielles | Mensuel | Index ciblé des partielles fédérales canadiennes | | `/track-record` | Performance | Hebdomadaire | Calls résolus + volume net de marchés validés | ### 2.2 Projections nationales actives | URL | Juridiction | Sièges | Cycle modèle | Cycle éditorial | |---|---|---|---|---| | `/canada` | Canada fédéral | 343 | fed_46 | Quotidien | | `/quebec` | Assemblée nationale du Québec | 125 | qc_2026 | Hebdomadaire | | `/ontario` | Assemblée législative de l'Ontario | 124 | on_2029 | Hebdomadaire | | `/france-presidentielle` | Présidentielle française 2027 | — | fr_pres_2027 | Hebdomadaire | | `/uk` | Élection générale britannique 2029 | 650 | uk_2029 | Hebdomadaire | | `/us-house` | Chambre US 2026 | 435 | us_house_2026 | Hebdomadaire | | `/us-senate` | Sénat US 2026 | 100 | us_senate_2026 | Hebdomadaire | ### 2.3 Pages spéciales actives | URL | Événement | Date | Description | |---|---|---|---| | `/ca1-special` | CA-1 special primary | 2 juin 2026 | Primaire spéciale top-two, Californie CD-1 | | `/ca14-special` | CA-14 special primary | 16 juin 2026 | Primaire spéciale top-two, Californie CD-14 | | `/usa/lame-duck` | Lame Duck Index | continu | Indice de canard boiteux pour la présidence Trump (LDI) | ### 2.4 Archives (événements résolus) | URL | Événement | Date | Statut | |---|---|---|---| | `/terrebonne-byelection` | Partielle Terrebonne | 13 avril 2026 | Résolue, archive | | `/university-rosedale-byelection` | Partielle University-Rosedale | 13 avril 2026 | Résolue, archive | | `/scarborough-southwest-byelection` | Partielle Scarborough-Southwest | 13 avril 2026 | Résolue, archive | | `/ga14-runoff` | Runoff GA-14 | 7 avril 2026 | Résolu (call validé), archive | | `/nj11-special` | Spéciale NJ-11 | 10 avril 2026 | Résolue, archive | ### 2.5 Sports Scope | URL | Type | Cycle éditorial | |---|---|---| | `/sports/` | Hub sport | Quotidien | | `/sports/nhl/` | Desk NHL — Coupe Stanley 2025-26 | Quotidien (en séries) | | `/sports/worldcup2026/` | Desk Coupe du monde FIFA 2026 | Hebdomadaire pré-tournoi, quotidien pendant | | `/sports/methodology.html` | Note méthodologique sport | Mensuel | | `/sports/newsletter.html` | Newsletter / Substack sport | Hebdomadaire | | `/sports/terms.html` | Conditions d'utilisation sport | Annuel | ### 2.6 Pages statiques utilitaires | URL | Description | |---|---| | `/methodologie` | Méthodologie complète du modèle électoral | | `/privacy` | Politique de confidentialité | | `/terms` | Conditions d'utilisation | --- ## 3. Architecture technique ### 3.1 Pipeline Python Chaque juridiction électorale est encapsulée dans un module Python sous `jurisdictions/` (ex. `federal_module.py`, `quebec_module.py`, `france_module.py`). Le pipeline standard pour une juridiction est : 1. **Import des sondages** — scripts `import_*.py` à la racine, normalisent les sondages depuis sources publiques (338Canada, sites de firmes, Wikipedia FR/EN en fallback) 2. **Pondération des firmes** — chaque firme reçoit un poids historique (`data/party_profiles.csv`, `data/firm_weights.csv`) 3. **Bootstrap de profils partis** — `bootstrap_*` scripts pour calibrer les profils régionaux à partir des résultats historiques 4. **BSTS** — modèle bayésien temporel exécuté via R (`bsts_model_*.R`), produit des séries lissées avec intervalles de crédibilité 5. **Simulation Monte Carlo** — 10 000 itérations par défaut (20 000 pour le Sénat US), produit la distribution complète des sièges 6. **Tipping points** — détection des circonscriptions à bascule 7. **Export JSON** — sortie standardisée vers `web_data/{juridiction}/latest.json` + archive horodatée sous `web_data/{juridiction}/runs/` ### 3.2 Pipeline Sports Scope Sous `nhl_playoffs/` et `worldcup2026/`, deux pipelines parallèles suivent le même squelette : **NHL :** - `import_*.py` (nightly) → données par équipe, gardiens, blessures, scores en cours de séries - `bsts_model_nhl.R` → force d'équipe BSTS - `goalie_layer.py` → couche gardien modulant la force selon le starter projeté (corrélation 0.55 avec succès offensif) - `playoff_simulator.py` → simulation des séries best-of-7 (10 000 simulations) - `game_probabilities.py` → probabilités de match individuel (intègre l'effet 7e joueur pour MTL à domicile) - `blend_market_signal.py` → blend conservatif avec consensus marché sur p_cup_win uniquement, avec cascade de monotonie et exclusion des équipes éliminées - `analyse_7e_joueur.py` + `import_hockeyref_mtl.py` → calibration bayésienne du correctif 7e joueur sur historique 1996-2024 **Coupe du monde 2026 :** - `import_wc_*.py` → classements FIFA, xG, odds bookmakers, Polymarket - `bsts_model_wc.R` → force d'équipe - `key_player_layer.py` → couche joueur clé - `group_stage_simulator.py` + `knockout_simulator.py` + `tournament_simulator.py` → arbre complet du tournoi - `blend_wc_signal.py` → blend marché analogue au NHL - `export_wc_newsletter.py` + `generate_wc_json.py` → exports ### 3.3 Build Astro / déploiement Cloudflare Pages - Source Astro : `src/pages/` (ex. `src/pages/usa/lame-duck.astro`) - Pages legacy : HTML directement à la racine (`canada.html`, `quebec.html`, etc.) copiées vers `dist/` par `scripts/copy-legacy.mjs` - Assets : `web_data/`, `sports/` symlinkés ou copiés - Déploiement : push sur main → Cloudflare Pages build automatique --- ## 4. Modèle statistique en détail ### 4.1 BSTS (Bayesian Structural Time Series) Implémenté en R via le package `bsts`. Pour chaque parti et chaque juridiction, le modèle décompose la série temporelle des intentions de vote en : - composante de niveau (random walk) - composante de tendance (optionnelle selon stabilité) - composante saisonnière (rare, surtout hors campagne) - termes de régression sur covariables (firme, méthodologie online/IVR, taille échantillon) L'inférence bayésienne (MCMC) produit non seulement une moyenne lissée mais une distribution postérieure complète, exploitée en aval pour la simulation Monte Carlo. ### 4.2 Pondération des firmes Chaque firme reçoit un poids `w_firm ∈ [0, 1]` calibré sur : - erreur historique moyenne sur les dernières élections - transparence méthodologique (publication crosstabs, méthode online vs IVR vs hybride) - récence - taille d'échantillon typique Les sondages sont pondérés `w_poll = w_firm × decay(date) × √(n / n_ref)`. ### 4.3 Projection par circonscription À partir du swing national/régional, chaque circonscription est projetée par : - swing uniforme régional appliqué au résultat de l'élection précédente - ajustements régionaux calibrés (`calibrate_*.py`) - régularisation pour éviter les valeurs aberrantes - Monte Carlo siège-par-siège pour estimer la probabilité de gain par parti ### 4.4 Présidentielle française Modèle de scénarios : - pour chaque sondage de premier tour, simuler la qualification top-2 - pour chaque duel possible de second tour, agréger les sondages spécifiques au duel - combiner les deux niveaux pour obtenir une distribution complète du résultat final - afficher les duels les plus probables et les robustesses associées ### 4.5 Lame Duck Index L'indice combine plusieurs signaux normalisés sur l'historique des présidences récentes : - approbation publique (moyenne mobile pondérée des sondages d'approbation) - indicateurs économiques (sentiment des consommateurs, indices boursiers, indicateurs avancés) - signaux institutionnels (cohésion de la majorité au Congrès, victoires/défaites législatives) L'indice est calibré pour fournir un benchmark historique : à un point donné du mandat, comment le président actuel se compare-t-il aux présidents précédents au même stade ? ### 4.6 Effet 7e joueur (NHL, MTL) Couche bayésienne calibrée sur l'historique playoff du Canadien de Montréal 1996-2024 (Hockey-Reference), excluant l'ère du Forum (déménagement au Centre Bell en mars 1996) et utilisant la bulle 2020 comme groupe de contrôle (matchs de séries sans foule). Trois couches analytiques : 1. **Win% à domicile vs attendu** depuis les odds de marché 2. **Taux de forçage de prolongation** en 3e période vs attendu 3. **Win% en prolongation à domicile** vs neutre Le bonus est appliqué uniquement aux matchs critiques (criticality = max(series_wins, series_losses)/3 > 0), modulé par la postérieure Beta calculée. Le résultat est un ajustement en points de force d'équipe ajouté à `home_team_strength` quand MTL joue à domicile en contexte critique. ### 4.7 Blend marché Le blend marché applique une fusion `(1-α) × p_market + α × p_model` sur la probabilité Coupe (NHL) ou la probabilité tournoi (World Cup). Le poids `α` est typiquement 0.7 (le modèle garde 70% du signal, le marché 30%), mais peut être modulé par la confiance du marché (`market_confidence ↓ ⇒ α ↑`). Garde-fous : - le blend ne touche **que** la probabilité finale (Coupe / vainqueur du tournoi), pas les probabilités intermédiaires de progression — sinon la monotonie `P(R1) ≥ P(R2) ≥ P(SF) ≥ P(F) ≥ P(W)` est cassée - une cascade de `max()` est appliquée en aval pour préserver la monotonie même quand le marché remonte la probabilité finale au-dessus de la probabilité d'atteindre la ronde supérieure - les équipes éliminées par la simulation BSTS (somme des probabilités à chaque ronde = 0) sont **exclues** du blend pour éviter qu'un consensus marché stale ne réinjecte du bruit --- ## 5. Format des données web ### 5.1 Schéma JSON électoral standard Chaque export `web_data/{juridiction}/latest.json` suit le schéma : ```jsonc { "meta": { "generated_at": "2026-05-01T12:00:00Z", "cycle": "fed_46", "n_polls": 142, "n_simulations": 10000, "model_version": "vX.Y.Z" }, "parties": [ { "code": "lib", "seats_median": 161, "seats_p10": 142, "seats_p90": 178, "vote_share_median": 0.341, "vote_share_p10": 0.318, "vote_share_p90": 0.366, "majority_prob": 0.12 } ], "current_composition": { "lib": 158, "con": 119, ... }, "tipping_points": [ { "riding_id": "...", "name": "...", "favored_party": "lib", "win_prob": 0.52, "marge_projetée": 1.4 } ], "ridings": [ { "riding_id": "...", "name": "...", "vote_share_by_party": { "lib": 0.412, ... }, "win_prob_by_party": { "lib": 0.78, ... } } ] } ``` ### 5.2 Schéma JSON Sports Scope Sous `web_data/sports/latest.json` (NHL) : - `contract`, `data_tiers`, `source_inventory`, `generated_at`, `site` — métadonnées - `hero` — bandeau d'accueil (équipe favorite, blend modèle/marché) - `board` — tableau principal, une ligne par équipe avec `p_cup_win`, `p_cup_final`, `p_conf_final`, `p_second_round`, `p_cup_bsts`, `p_cup_market` - `bracket` — état du tableau de séries - `goalie_context`, `injury_summary` — contexte gardien et blessures - `series_context` — contexte des séries actuelles - `game_probabilities` — probabilités des matchs à venir - `market_snapshot`, `market_embeds` — repères de marché - `live`, `live_scores` — modules live ### 5.3 Lame Duck Index `web_data/us-lame-duck/latest.json` — courbes historiques de l'indice, scores actuels et benchmarks. --- ## 5.4 Endpoints JSON publics Tous les exports ci-dessous sont accessibles librement et rafraîchis par les pipelines nightly (ou plus souvent en période active). Pas d'authentification, pas de rate limit explicite, mais usage raisonnable demandé. Le format n'est pas figé — un vrai contrat API arrivera plus tard. **Électoral** - `https://vote-scope.com/web_data/federal/latest.json` — Canada fédéral 343 sièges (cycle fed_46) - `https://vote-scope.com/web_data/quebec/latest.json` — Québec 125 sièges - `https://vote-scope.com/web_data/ontario/latest.json` — Ontario 124 sièges - `https://vote-scope.com/web_data/france-presidential/latest.json` — Présidentielle française 2027 - `https://vote-scope.com/web_data/uk/latest.json` — Royaume-Uni 650 sièges - `https://vote-scope.com/web_data/us-house/latest.json` — Chambre US 2026 - `https://vote-scope.com/web_data/us-senate/latest.json` — Sénat US 2026 **Pages spéciales actives** - `https://vote-scope.com/web_data/ca1-special/latest.json` — CA-1 special primary 2026-06-02 - `https://vote-scope.com/web_data/ca14-special/latest.json` — CA-14 special primary 2026-06-16 - `https://vote-scope.com/web_data/us-lame-duck/latest.json` — Lame Duck Index (présidence Trump) **Archives résolues** - `https://vote-scope.com/web_data/ga14-runoff/latest.json` — GA-14 runoff 2026-04-07 - `https://vote-scope.com/web_data/nj11-special/latest.json` — NJ-11 special 2026-04-10 **Marchés de prédiction** - `https://vote-scope.com/web_data/polymarket/latest.json` — snapshot Polymarket utilisé par les hubs **Sports Scope** - `https://vote-scope.com/web_data/sports/latest.json` — board NHL principal (board, bracket, gardiens, séries, contexte marché, scores live) - `https://vote-scope.com/sports/nhl/data/game_probabilities_latest.json` — probabilités match par match (NHL) - `https://vote-scope.com/sports/nhl/data/newsletter_latest.json` — payload newsletter NHL - `https://vote-scope.com/web_data/sports/worldcup2026_latest.json` — Coupe du monde FIFA 2026 (en mise en route) --- ## 6. Conventions éditoriales et garde-fous ### 6.1 Indépendance et non partisanship VoteScope ne soutient aucun parti, candidat ou résultat. Les projections sont publiées en l'état du modèle, même quand elles vont contre l'intuition ou la narration médiatique dominante. ### 6.2 Transparence - Toutes les hypothèses méthodologiques sont publiques (`/methodologie`, `/sports/methodology.html`) - Les calls résolus sont comptabilisés publiquement (`/track-record`), bons et mauvais - Les comparaisons avec les marchés de prédiction sont systématiques ### 6.3 Sport ≠ conseil de pari La verticale Sports Scope est un produit d'analyse et de divertissement. **Aucune recommandation de pari** n'y est faite, même implicitement. Les comparaisons avec les marchés sportifs (sportsbooks, Polymarket) servent de benchmark externe, pas de signal d'action. ### 6.4 Sources et droit d'auteur Les données sont issues de sources publiques (Élections Canada/Québec/Ontario, MIT Election Lab, Hockey-Reference, FIFA, sondeurs publics) et exploitées dans une logique d'agrégation. Aucune donnée propriétaire payante n'est redistribuée. --- ## 7. Sources des données par domaine | Domaine | Sources principales | |---|---| | Canada fédéral | Élections Canada, 338Canada, firmes (Léger, Abacus, Nanos, Mainstreet, EKOS, Angus Reid) | | Québec | Élections Québec, firmes provinciales | | Ontario | Élections Ontario, 338Canada Ontario, firmes provinciales | | États-Unis | MIT Election Lab, U.S. Census Bureau, Polymarket, Kalshi | | France | IFOP, Harris Interactive, Ipsos, OpinionWay, BVA | | Royaume-Uni | Sondages publics agrégés, données électorales 2024 | | NHL | Hockey-Reference, NaturalStatTrick, NHL.com, OddsShark, Polymarket | | Coupe du monde 2026 | Classements FIFA, xG (StatsBomb/FBref publics), Polymarket, sportsbooks consensus | | Lame Duck Index | Sondages d'approbation présidentielle, indicateurs économiques publics, signaux législatifs | --- ## 8. Intégrations externes ### 8.1 Polymarket Les hubs Canada et USA, ainsi que les desks Sports Scope, intègrent les marchés Polymarket via l'API Gamma. Le rendu se fait côté client, en lecture seule, comme benchmark comparatif. Aucune action de pari n'est facilitée par le site. ### 8.2 Kalshi Sur certains événements (ex. GA-14 runoff), Kalshi est aussi suivi en parallèle, surtout pour le track record. ### 8.3 Substack / Newsletter `/sports/newsletter.html` est le point d'entrée vers la newsletter Substack qui complète éditorialement la verticale sport. --- ## 9. Auteur et contact **Kim Leclerc** - Site personnel : https://kimleclerc.ca - Projet : https://vote-scope.com --- ## 10. Citation Les projections VoteScope sont librement consultables. Pour toute utilisation dans un article, une analyse ou une application : > « Selon VoteScope (vote-scope.com) par Kim Leclerc, [description de la projection]. » --- ## 11. Limites du modèle ### 11.1 Limites générales - Les projections reposent sur les sondages publiquement disponibles et peuvent ne pas refléter des événements récents non encore mesurés. - Les intervalles de crédibilité sont probabilistes et conditionnés au modèle ; ils ne sont pas des garanties. - Les projections par circonscription sont plus incertaines que les projections nationales (sous-échantillonnage régional). - Le modèle ne tient pas compte des candidats locaux, des fonds de campagne, des infrastructures partisanes ou d'autres facteurs hors-sondage. ### 11.2 Limites par juridiction - **France présidentielle** : forte incertitude liée à la dynamique du second tour, aux désistements et aux reports de voix. - **UK 2029** : modèle très en amont, repose sur un cadre proportionnel-régional plus instable que l'élection canadienne. - **CA-1 / CA-14 specials** : primaires top-two, donc les ajustements régionaux usuels sont remplacés par une couche dédiée. - **Lame Duck Index** : indice synthétique, par construction sensible au choix des composantes et à leur pondération relative. ### 11.3 Limites Sports Scope - L'effet 7e joueur est calibré sur **MTL uniquement** ; il n'est pas généralisé aux autres équipes (l'inférence n'aurait pas la même robustesse statistique). - La couche gardien dépend de la qualité des données de blessure, qui sont parfois publiées tardivement. - La verticale World Cup 2026 est en mise en route ; sa précision attendue sera plus élevée pendant le tournoi qu'en pré-tournoi. - Le blend marché est conservatif sur la probabilité finale uniquement et n'est pas un signal de pari.