tradermonty/theme-detector

Détecteur de Thèmes

Aperçu

Cette compétence détecte et classe les thèmes de marché tendances en analysant la dynamique intersectorielle, le volume et les signaux de largeur de marché. Elle identifie à la fois les thèmes haussiers (momentum à la hausse) et baissiers (pression à la baisse), évalue la maturité du cycle de vie (Émergent/Accélération/Tendance/Mature/Épuisant) et fournit un score de confiance combinant des données quantitatives avec une analyse narrative.

Modèle d'Évaluation Tridimensionnel:

1. Force du Thème (0-100) : Force direction-neutre du thème (momentum, volume, ratio de tendance haussière, largeur de marché)
2. Maturité du Cycle de Vie : Classification de l'étape (Émergent / Accélération / Tendance / Mature / Épuisant) basée sur la durée, le regroupement des extrêmes, la valorisation et la prolifération des ETF
3. Confiance (Faible / Moyen / Élevé) : Fiabilité de la détection, combinant la largeur de marché quantitative avec la confirmation narrative. La sortie du script est plafonnée à Moyen ; l'étape de confirmation narrative via WebSearch de Claude peut l'élever à Élevé.
4. Leadership des Actions : Preuve facultative de scans quotidiens pour +20% sur 5 jours, EP9M, expansion de gamme, nouveaux hauts et actions à RS élevée. Lorsqu'elle est fournie, elle est intégrée dans la Force du Thème v2 ; lorsqu'elle est absente, elle réduit la couverture de confiance mais ne force pas le leadership à zéro.
5. Qualité de Correspondance du Thème : Spécificité de la correspondance du thème à partir de la participation sectorielle, des hits explicites de paniers d'actions, de la confirmation par ETF proxy et des scores narratifs hors ligne facultatifs. Il s'agit de la qualité des preuves, pas d'une recommandation de transaction.

Fonctionnalités Clés:

• Détection de thèmes intersectoriels utilisant les données sectorielles FINVIZ
• Notation directionnelle (thèmes haussiers et baissiers)
• Évaluation de la maturité du cycle de vie pour identifier les transactions encombrées par rapport aux émergentes
• Score de prolifération des ETF (plus d'ETF = thème plus mature/encombré)
• Intégration avec le tableau de bord de tendance haussière pour une évaluation en 3 points
• Preuve de leadership au niveau des actions via --scan-hits
• Qualité de correspondance du thème via des paniers d'actions explicites et une confirmation par ETF proxy
• Preuve de candidats leaders classés par mouvement anormal/volume/gamme/métriques RS, avec la capitalisation boursière présentée uniquement comme un compartiment de risque
• Historique des thèmes et métriques d'accélération via --history-file
• Mode de fonctionnement double : FINVIZ Elite (rapide) ou scraping public (plus lent, limité)
• Confirmation narrative basée sur WebSearch pour les meilleurs thèmes

---

Quand Utiliser Cette Compétence

Déclencheurs Explicites:

• "Quels sont les thèmes de marché tendances en ce moment ?"
• "Quels secteurs sont chauds/froids ?"
• "Détecter les thèmes de marché actuels"
• "Quels sont les narratifs haussiers/baissiers les plus forts ?"
• "L'IA/l'énergie propre/la défense est-elle toujours un thème fort ?"
• "Où va la rotation sectorielle ?"
• "Montre-moi des opportunités d'investissement thématiques"

Déclencheurs Implicites:

• L'utilisateur veut comprendre les changements de narratif de marché larges
• L'utilisateur cherche des idées d'allocation sectorielle ou d'ETF thématiques
• L'utilisateur s'interroge sur les transactions encombrées ou les thèmes de fin de cycle
• L'utilisateur veut savoir quels thèmes émergent par rapport à ceux qui sont épuisés

Quand NE PAS Utiliser:

• Analyse d'actions individuelles (utiliser us-stock-analysis à la place)
• Plongée approfondie dans un secteur spécifique avec lecture de graphiques (utiliser sector-analyst à la place)
• Rééquilibrage de portefeuille (utiliser portfolio-manager à la place)
• Investissement de dividendes/revenu (utiliser value-dividend-screener à la place)

---

Prérequis

Requis:

• Python 3.9+ avec les dépendances principales.

  pip install -r skills/theme-detector/requirements.txt
  

Solution de repli Cron / Python mixte: Si le python3 actif est plus ancien que 3.10, ou si un venv Hermes plus récent manque des dépendances de science des données, exécutez le détecteur via uv avec un interpréteur moderne explicite et des dépendances temporaires au lieu de modifier l'environnement en plein cron :

uv run --python 3.12 \
  --with requests --with beautifulsoup4 --with lxml \
  --with pandas --with numpy --with yfinance \
  --with finvizfinance --with PyYAML \
  python skills/theme-detector/scripts/theme_detector.py \
  --finviz-api-key "$FINVIZ_API_KEY" \
  --fmp-api-key "$FMP_API_KEY" \
  --output-dir reports/

Utilisez ceci comme une solution de contournement d'installation, pas comme une preuve que le détecteur est cassé ; signalez toujours les limitations FINVIZ/FMP/API-données séparément.

Clés API Facultatives:

FINVIZ Elite (recommandé pour une couverture sectorielle complète et la rapidité) :

export FINVIZ_API_KEY=your_finviz_elite_api_key_here

API FMP (facultatif, pour les données de valorisation ratio P/E) :

export FMP_API_KEY=your_fmp_api_key_here

Les exigences incluent finvizfinance, PyYAML, pandas/numpy, requests et yfinance car l'exécution en mode public normal importe ou utilise chacun d'eux.

Sans FINVIZ Elite, la compétence utilise le scraping public FINVIZ (limité à ~20 actions par secteur, limites de débit plus lentes).

---

Flux de Travail

Étape 1 : Vérifier l'Environnement

Vérifiez que les clés API sont configurées (voir Prérequis) :

# Vérifier la clé API FINVIZ Elite (facultatif mais recommandé)
echo $FINVIZ_API_KEY

# Vérifier la clé API FMP (facultatif)
echo $FMP_API_KEY

Étape 2 : Exécuter le Script de Détection de Thèmes

Exécutez le script de détection principal :

python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

Options du Script :

# Exécution complète (mode FINVIZ public, aucune clé API requise)
python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

# Avec clé API FINVIZ Elite
python3 skills/theme-detector/scripts/theme_detector.py \
  --finviz-api-key $FINVIZ_API_KEY \
  --output-dir reports/

# Avec clé API FMP pour des données boursières améliorées
python3 skills/theme-detector/scripts/theme_detector.py \
  --fmp-api-key $FMP_API_KEY \
  --output-dir reports/

# Limites personnalisées
python3 skills/theme-detector/scripts/theme_detector.py \
  --max-themes 5 \
  --max-stocks-per-theme 10 \
  --output-dir reports/

# Mode FINVIZ explicite
python3 skills/theme-detector/scripts/theme_detector.py \
  --finviz-mode public \
  --output-dir reports/

# Ajouter des preuves de leadership de style Stockbee/Pradeep
python3 skills/theme-detector/scripts/theme_detector.py \
  --scan-hits data/theme_scan_hits_YYYY-MM-DD.json \
  --narrative-scores data/theme_narrative_scores_YYYY-MM-DD.json \
  --history-file reports/theme_detector_history.json \
  --as-of-date YYYY-MM-DD \
  --output-dir reports/

Contrat d'entrée des hits de scan : --scan-hits accepte du JSON, JSONL ou CSV. Les lignes peuvent être pré-étiquetées avec scan_type / scan_types, ou des lignes brutes avec des champs tels que symbol, return_5d, change_pct, volume, avg_volume_50d, relative_volume, true_range, atr_20, atr_expansion, close_location, industry, sector et theme_guess. Une ligne brute peut se développer en plusieurs hits lorsqu'elle satisfait à plusieurs règles.

Règles de scan initiales :

• five_day_20pct : return_5d >= 20
• ep9m : volume >= 9,000,000, relative_volume >= 2.0 et change_pct >= 4
• range_expansion : change_pct >= 4, true_range / atr_20 >= 1.5 ou atr_expansion >= 1.5, et close_location >= 0.75
• new_high : new_high / is_new_high explicite, ou preuve de plus haut sur 52 semaines
• high_rs : rs_rating >= 90 ou relative_strength normalisé >= 0.90

Contrat d'entrée des scores narratifs : --narrative-scores est une entrée JSON hors ligne, pas un appel WebSearch en direct. Il accepte soit {"Nom du Thème": 82} soit {"themes": {"Nom du Thème": {"narrative_keyword_score": 82}}}. L'absence d'entrée narrative laisse narrative_keyword_score comme null et réduit theme_match_coverage ; elle n'échoue pas l'exécution.

Temps d'Exécution Estimé :

• Mode FINVIZ Elite : ~2-3 minutes (14+ thèmes)
• Mode FINVIZ Public : ~5-8 minutes (scraping limité en débit)

Étape 3 : Lire et Analyser les Résultats de Détection

Le script génère deux fichiers de sortie :

• theme_detector_YYYY-MM-DD_HHMMSS.json - Données structurées pour une utilisation programmatique
• theme_detector_YYYY-MM-DD_HHMMSS.md - Rapport lisible par l'humain

Lisez la sortie JSON pour comprendre les résultats quantitatifs :

# Trouver le dernier rapport
ls -lt reports/theme_detector_*.json | head -1

# Lire la sortie JSON
cat reports/theme_detector_YYYY-MM-DD_HHMMSS.json

Étape 4 : Effectuer une Confirmation Narrative via WebSearch

Pour les 5 premiers thèmes (par score de Force du Thème), exécutez des requêtes WebSearch pour confirmer la force narrative :

Modèle de Recherche :

"[nom du thème] actions marché [mois en cours] [année en cours]"
"[nom du thème] momentum sectoriel [mois en cours] [année en cours]"

Évaluer les signaux narratifs :

• Narratif fort : Plusieurs médias majeurs couvrant le thème, mises à niveau par les analystes, catalyseurs politiques
• Narratif modéré : Une certaine couverture, sentiment mitigé, pas de catalyseur clair
• Narratif faible : Peu de couverture, ou ton majoritairement à contre-courant/sceptique

Mettez à jour les niveaux de Confiance en fonction des résultats :

• Quantitatif Élevé + Narratif Fort = Confiance Élevée
• Quantitatif Élevé + Narratif Faible = Confiance Moyenne (possible divergence de momentum)
• Quantitatif Faible + Narratif Fort = Confiance Moyenne (le narratif peut précéder le prix)
• Quantitatif Faible + Narratif Faible = Confiance Faible

Étape 5 : Analyser les Résultats et Fournir des Recommandations

Croisez les résultats de détection avec les bases de connaissances :

Documents de Référence à Consulter :

1. references/cross_sector_themes.md - Définitions des thèmes et secteurs constitutifs
2. references/thematic_etf_catalog.md - Options d'exposition ETF par thème
3. references/theme_detection_methodology.md - Détails du modèle de notation
4. references/finviz_industry_codes.md - Référence de classification sectorielle

Cadre d'Analyse :

Pour les Thèmes Haussiers Chauds (Force >= 70, Direction = Haussière) :

• Identifier l'étape du cycle de vie (Émergent = opportunité, Mature/Épuisant = prudence)
• Lister les secteurs les plus performants au sein du thème
• Recommander des ETF proxy pour l'exposition
• Signaler si la prolifération des ETF est élevée (avertissement de transaction encombrée)

Pour les Thèmes Baissiers Chauds (Force >= 70, Direction = Baissière) :

• Identifier les secteurs sous pression
• Évaluer si le momentum baissier s'accélère ou décélère
• Recommander des stratégies de couverture ou des secteurs à éviter
• Noter les opportunités potentielles de retour à la moyenne si le cycle de vie est Mature/Épuisant

Pour les Thèmes Émergents (Force 40-69, Cycle de Vie = Émergent) :

• Ceux-ci peuvent représenter des signaux de rotation précoce
• Recommander un suivi avec une liste de surveillance
• Identifier les événements catalyseurs qui pourraient accélérer le thème

Pour les Thèmes Épuisés (Force >= 60, Cycle de Vie = Épuisant) :

• Avertir du risque de transaction encombrée
• Un nombre élevé d'ETF confirme une participation excessive des particuliers
• Envisager un positionnement à contre-courant ou une réduction de l'exposition

Étape 6 : Générer le Rapport Final

Présentez le rapport final à l'utilisateur en utilisant la structure du modèle de rapport :

# Rapport de Détection de Thèmes
**Date :** AAAA-MM-JJ
**Mode :** FINVIZ Elite / Public
**Thèmes Analysés :** N
**Qualité des Données :** [noter les éventuelles limitations]

## Tableau de Bord des Thèmes
[Tableau des meilleurs thèmes avec Force, Direction, Cycle de Vie, Confiance]

## Ce Qui a Changé Aujourd'hui
[Nouveaux thèmes émergents, plus grande accélération de la force, nouveaux clusters EP9M, thèmes en voie de disparition]

## Preuves de Leadership
[Comptes +20% sur 5 jours, EP9M, expansion de gamme, nouveaux hauts, RS élevée et symboles leaders]

## Détail des Thèmes Haussiers
[Analyse détaillée des thèmes haussiers triés par Force]

## Détail des Thèmes Baissiers
[Analyse détaillée des thèmes baissiers triés par Force]

## Résumé de Tous les Thèmes
[Tableau de classement complet des thèmes]

## Classements Sectoriels
[Secteurs les plus performants et les moins performants]

## Ratios de Tendance Haussière Sectoriels
[Agrégation au niveau sectoriel si les données de tendance haussière sont disponibles]

## Notes Méthodologiques
[Bref explicatif du modèle de notation]

Enregistrez le rapport dans le répertoire reports/.

---

Sortie

La compétence génère deux fichiers de sortie dans le répertoire reports/ :

Sortie JSON (theme_detector_YYYY-MM-DD_HHMMSS.json) :

{
  "report_type": "theme_detector",
  "generated_at": "2026-04-18 10:30:00",
  "metadata": {
    "generated_at": "2026-04-18 10:30:00",
    "data_mode": "full",
    "finviz_mode": "elite",
    "fmp_available": true,
    "max_themes": 14,
    "max_stocks_per_theme": 5,
    "data_sources": {
      "finviz_industries": 152,
      "yfinance_stocks": 68,
      "etf_volume": 24
    }
  },
  "summary": {
    "total_themes": 14,
    "bullish_count": 8,
    "bearish_count": 6,
    "top_bullish": "IA & Apprentissage Automatique",
    "top_bearish": "Banques Régionales"
  },
  "themes": {
    "all": [
      {
        "name": "IA & Apprentissage Automatique",
        "direction": "bullish",
        "heat": 85.3,
        "maturity": 42.1,
        "stage": "Accélération",
        "confidence": "Moyen",
        "heat_label": "Chaud",
        "industries": ["Logiciels - Infrastructure", "Semi-conducteurs"],
        "representative_stocks": ["NVDA", "MSFT"],
        "stock_details": [{"symbol": "NVDA"}, {"symbol": "MSFT"}],
        "proxy_etfs": ["BOTZ", "ROBO"],
        "theme_match_score": 78.4,
        "theme_match_components": {
          "industry_match_score": 84.2,
          "static_stock_hit_score": 80.0,
          "proxy_etf_momentum_score": 70.0,
          "narrative_keyword_score": null
        },
        "leader_candidates": [
          {
            "symbol": "NVDA",
            "leader_score": 91.2,
            "scan_types": ["ep9m", "range_expansion"],
            "risk_bucket": "mega"
          }
        ],
        "theme_origin": "seed"
      }
    ],
    "bullish": [...],
    "bearish": [...],
    "match_ranked": [...]
  },
  "industry_rankings": {
    "top": [...],
    "bottom": [...]
  },
  "sector_uptrend": {...},
  "data_quality": {...}
}

Rapport Markdown (theme_detector_YYYY-MM-DD_HHMMSS.md) :

• Tableau de Bord des Thèmes avec classements triables
• Sections de détail des thèmes Haussiers/Baissiers
• Classements de performance sectorielle
• Résumé du ratio de tendance haussière sectoriel
• Notes méthodologiques

Champs de Sortie Clés (par thème) :

Champ	Description
heat	Force du thème direction-neutre 0-100
direction	"bullish" (LEAD) ou "bearish" (LAG)
stage	Émergent / Accélération / Tendance / Mature / Épuisant
confidence	Faible / Moyen / Élevé (le script plafonne à Moyen ; WebSearch peut élever)
representative_stocks	Principaux symboles boursiers pour le thème
stock_details	Objets de métriques boursières facultatives pour les représentants sélectionnés
proxy_etfs	Symboles ETF thématiques (longueur = nombre d'ETF ; plus élevé = thème plus encombré)
leader_candidates	Actions avec preuve de leadership anormal (par scan)
leader_score	Score combiné 0-100 (moyenne pondérée des scores de scan individuels)
risk_bucket	micro / small / mid / large / mega (basé sur la capitalisation boursière, uniquement comme avertissement de risque)
theme_match_score	Score de qualité de correspondance du thème 0-100
theme_match_components	Décomposition en correspondance sectorielle, hit de panier d'actions, momentum ETF proxy et score narratif
maturity	Score numérique de maturité 0-100
etf_count	Nombre d'ETF suivis (proxy de la participation de détail et de l'encombrement)