tradermonty/theme-detector

Theme Detector

Überblick

Dieses Skill erkennt und bewertet Trendthemen des Marktes, indem es sektorübergreifende Momentum-, Volumen- und Breitensignale analysiert. Es identifiziert sowohl bullische (Aufwärtsdynamik) als auch bärische (Abwärtsdruck) Themen, bewertet die Reife des Lebenszyklus (Emerging/Accelerating/Trending/Mature/Exhausting) und liefert einen Konfidenzwert, der quantitative Daten mit narrativer Analyse kombiniert.

3-dimensionales Bewertungsmodell:

1. Theme Heat (0-100): Richtungsneutrale Stärke des Themas (Momentum, Volumen, Aufwärtstrend-Verhältnis, Breite)
2. Lebenszyklus-Reife: Stufenklassifizierung (Emerging / Accelerating / Trending / Mature / Exhausting) basierend auf Dauer, Extrem-Clustering, Bewertung und ETF-Verbreitung
3. Konfidenz (Niedrig / Mittel / Hoch): Zuverlässigkeit der Erkennung, die quantitative Breite mit narrativer Bestätigung kombiniert. Die Skriptausgabe ist auf Mittel begrenzt; der narrative Bestätigungsschritt von Claude's WebSearch kann auf Hoch erhöhen.
4. Aktienführung: Optionaler täglicher Scan-Treffer-Nachweis von 5D+20%, EP9M, Range-Expansion, neuen Hochs und High-RS-Aktien. Falls vorhanden, wird dies in Theme Heat v2 integriert; falls nicht, senkt es die Konfidenzabdeckung, erzwingt aber keine Führung auf Null.
5. Themenübereinstimmungsqualität: Spezifität der Themenübereinstimmung anhand von Branchenbeteiligung, expliziten Aktienkorb-Treffern, Proxy-ETF-Bestätigung und optionalen Offline-Narrativwerten. Dies ist die Nachweisqualität, keine Handelsempfehlung.

Hauptfunktionen:

• Sektorübergreifende Themenerkennung unter Verwendung von FINVIZ-Branchendaten
• Richtungsbewusste Bewertung (bullische und bärische Themen)
• Bewertung der Lebenszyklus-Reife zur Identifizierung von überfüllten vs. aufkommenden Trades
• ETF-Verbreitungsbewertung (mehr ETFs = reiferes/überfüllteres Thema)
• Integration mit Aufwärtstrend-Dashboard für 3-Punkt-Bewertung
• Nachweis der Aktienführung auf Einzeltitelebene über --scan-hits
• Themenübereinstimmungsqualität über explizite Aktienkörbe und Proxy-ETF-Bestätigung
• Führungskandidaten-Nachweis, eingestuft nach abnormalen Bewegungen/Volumen/Range/RS-Metriken, mit Marktkapitalisierung nur als Risikoeimer gezeigt
• Themenhistorie und Beschleunigungsmetriken über --history-file
• Dualmodus-Betrieb: FINVIZ Elite (schnell) oder öffentliches Scraping (langsamer, eingeschränkt)
• WebSearch-basierte narrative Bestätigung für Top-Themen

---

Wann dieses Skill verwenden

Explizite Auslöser:

• "Welche Marktthemen sind gerade im Trend?"
• "Welche Sektoren sind heiß/kalt?"
• "Erkenne aktuelle Marktthemen"
• "Was sind die stärksten bullischen/bärischen Narrative?"
• "Ist KI/Saubere Energie/Verteidigung immer noch ein starkes Thema?"
• "Wohin steuert die Sektorrotation?"
• "Zeige mir thematische Investitionsmöglichkeiten"

Implizite Auslöser:

• Der Benutzer möchte breite Veränderungen im Marktnarrativ verstehen
• Der Benutzer sucht nach Ideen für thematische ETFs oder Sektorallokation
• Der Benutzer fragt nach überfüllten Trades oder Spätzyklus-Themen
• Der Benutzer möchte wissen, welche Themen im Entstehen begriffen oder erschöpft sind

Wann NICHT verwenden:

• Einzelaktienanalyse (verwende stattdessen us-stock-analysis)
• Spezifische Sektor-Tiefenanalyse mit Chartlesen (verwende stattdessen sector-analyst)
• Portfolio-Neuausrichtung (verwende stattdessen portfolio-manager)
• Dividenden-/Einkommensinvestitionen (verwende stattdessen value-dividend-screener)

---

Voraussetzungen

Erforderlich:

• Python 3.9+ mit Kernabhängigkeiten.

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

Cron / gemischter Python-Fallback: Wenn das aktive python3 älter als 3.10 ist, oder eine neuere Hermes-Venue die Data-Science-Abhängigkeiten nicht hat, führen Sie den Detektor durch uv mit einem expliziten modernen Interpreter und temporären Abhängigkeiten aus, anstatt die Umgebung während Cron zu bearbeiten:

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/

Verwenden Sie dies als Einrichtungsumgehung, nicht als Beweis dafür, dass der Detektor defekt ist; melden Sie FINVIZ/FMP/API-Daten-Einschränkungen separat.

Optionale API-Schlüssel:

FINVIZ Elite (empfohlen für vollständige Branchenabdeckung und Geschwindigkeit):

export FINVIZ_API_KEY=ihr_finviz_elite_api_schluessel_hier

FMP API (optional, für KGV-Bewertungsdaten):

export FMP_API_KEY=ihr_fmp_api_schluessel_hier

Die Anforderungen umfassen finvizfinance, PyYAML, pandas/numpy, requests und yfinance, da die normale öffentliche Ausführung diese importiert oder verwendet.

Ohne FINVIZ Elite verwendet das Skill öffentliches FINVIZ-Scraping (begrenzt auf ~20 Aktien pro Branche, langsamere Ratenbegrenzungen).

---

Arbeitsablauf

Schritt 1: Umgebung überprüfen

Stellen Sie sicher, dass API-Schlüssel konfiguriert sind (siehe Voraussetzungen):

# FINVIZ Elite API-Schlüssel überprüfen (optional, aber empfohlen)
echo $FINVIZ_API_KEY

# FMP API-Schlüssel überprüfen (optional)
echo $FMP_API_KEY

Schritt 2: Themenerkennungsskript ausführen

Führen Sie das Hauptskript aus:

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

Skript-Optionen:

# Vollständiger Lauf (öffentlicher FINVIZ-Modus, kein API-Schlüssel erforderlich)
python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

# Mit FINVIZ Elite API-Schlüssel
python3 skills/theme-detector/scripts/theme_detector.py \
  --finviz-api-key $FINVIZ_API_KEY \
  --output-dir reports/

# Mit FMP API-Schlüssel für verbesserte Aktiendaten
python3 skills/theme-detector/scripts/theme_detector.py \
  --fmp-api-key $FMP_API_KEY \
  --output-dir reports/

# Benutzerdefinierte Grenzwerte
python3 skills/theme-detector/scripts/theme_detector.py \
  --max-themes 5 \
  --max-stocks-per-theme 10 \
  --output-dir reports/

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

# Stockbee/Pradeep-ähnlichen Führungsnachweis hinzufügen
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/

Scan-Treffer-Eingabevertrag: --scan-hits akzeptiert JSON, JSONL oder CSV. Zeilen können mit scan_type / scan_types vorab beschriftet sein, oder Rohzeilen mit Feldern wie symbol, return_5d, change_pct, volume, avg_volume_50d, relative_volume, true_range, atr_20, atr_expansion, close_location, industry, sector und theme_guess. Eine Rohzeile kann sich in mehrere Treffer aufteilen, wenn sie mehrere Regeln erfüllt.

Erste Scan-Regeln:

• five_day_20pct: return_5d >= 20
• ep9m: volume >= 9,000,000, relative_volume >= 2.0 und change_pct >= 4
• range_expansion: change_pct >= 4, true_range / atr_20 >= 1.5 oder atr_expansion >= 1.5 und close_location >= 0.75
• new_high: explizites new_high / is_new_high oder 52-Wochen-Hoch-Nachweis
• high_rs: rs_rating >= 90 oder normalisiertes relative_strength >= 0.90

Narrativwert-Eingabevertrag: --narrative-scores ist eine Offline-JSON-Eingabe, kein Live-WebSearch-Aufruf. Es akzeptiert entweder {"Themenname": 82} oder {"themes": {"Themenname": {"narrative_keyword_score": 82}}}. Fehlende Narrativeingabe belässt narrative_keyword_score als null und reduziert theme_match_coverage; es führt nicht zum Fehlschlagen des Laufs.

Erwartete Ausführungszeit:

• FINVIZ Elite-Modus: ~2-3 Minuten (14+ Themen)
• Öffentlicher FINVIZ-Modus: ~5-8 Minuten (ratenbegrenztes Scraping)

Schritt 3: Erkennungsergebnisse lesen und parsen

Das Skript erzeugt zwei Ausgabedateien:

• theme_detector_YYYY-MM-DD_HHMMSS.json - Strukturierte Daten zur programmatischen Nutzung
• theme_detector_YYYY-MM-DD_HHMMSS.md - Menschlich lesbarer Bericht

Lesen Sie die JSON-Ausgabe, um die quantitativen Ergebnisse zu verstehen:

# Den neuesten Bericht finden
ls -lt reports/theme_detector_*.json | head -1

# Die JSON-Ausgabe lesen
cat reports/theme_detector_YYYY-MM-DD_HHMMSS.json

Schritt 4: Narrative Bestätigung über WebSearch durchführen

Führen Sie für die Top-5-Themen (nach Theme Heat-Wert) WebSearch-Abfragen durch, um die Narrativstärke zu bestätigen:

Suchmuster:

"[Themenname] Aktien Markt [aktueller Monat] [aktuelles Jahr]"
"[Themenname] Sektor Momentum [aktueller Monat] [aktuelles Jahr]"

Narrative Signale bewerten:

• Starkes Narrativ: Mehrere große Medien berichten über das Thema, Analysten-Upgrades, politische Katalysatoren
• Mäßiges Narrativ: Einige Berichterstattung, gemischte Stimmung, kein klarer Katalysator
• Schwaches Narrativ: Wenig Berichterstattung oder überwiegend konträre/skeptische Töne

Konfidenzstufen basierend auf den Ergebnissen aktualisieren:

• Quantitativ Hoch + Narrativ Stark = Hohe Konfidenz
• Quantitativ Hoch + Narrativ Schwach = Mittlere Konfidenz (mögliche Momentum-Divergenz)
• Quantitativ Niedrig + Narrativ Stark = Mittlere Konfidenz (Narrativ könnte Preis anführen)
• Quantitativ Niedrig + Narrativ Schwach = Niedrige Konfidenz

Schritt 5: Ergebnisse analysieren und Empfehlungen geben

Querverweise mit Wissensdatenbanken:

Referenzdokumente zur Konsultation:

1. references/cross_sector_themes.md - Themendefinitionen und konstituierende Branchen
2. references/thematic_etf_catalog.md - ETF-Expositionsoptionen nach Thema
3. references/theme_detection_methodology.md - Details zum Bewertungsmodell
4. references/finviz_industry_codes.md - Branchenklassifikationsreferenz

Analyserahmen:

Für Heiße Bullische Themen (Heat >= 70, Richtung = Bullisch):

• Lebenszyklusstadium identifizieren (Emerging = Gelegenheit, Mature/Exhausting = Vorsicht)
• Bestperformende Branchen innerhalb des Themas auflisten
• Proxy-ETFs für die Exposition empfehlen
• Hinweis, wenn die ETF-Verbreitung hoch ist (Warnung vor überfülltem Trade)

Für Heiße Bärische Themen (Heat >= 70, Richtung = Bärisch):

• Branchen unter Druck identifizieren
• Bewerten, ob die bärische Dynamik beschleunigt oder verlangsamt
• Absicherungsstrategien oder zu vermeidende Sektoren empfehlen
• Potenzielle Mean-Reversion-Gelegenheiten notieren, wenn der Lebenszyklus Mature/Exhausting ist

Für Aufkommende Themen (Heat 40-69, Lebenszyklus = Emerging):

• Diese können frühe Rotationssignale darstellen
• Überwachung mit einer Watchlist empfehlen
• Katalysatorereignisse identifizieren, die das Thema beschleunigen könnten

Für Erschöpfte Themen (Heat >= 60, Lebenszyklus = Exhausting):

• Vor überfülltem Trade-Risiko warnen
• Hohe ETF-Anzahl bestätigt übermäßige Retail-Beteiligung
• Konträre Positionierung oder Reduzierung der Exposition in Betracht ziehen

Schritt 6: Abschlussbericht erstellen

Dem Benutzer den Abschlussbericht mit der Berichtsvorlagenstruktur präsentieren:

# Theme Detection Report
**Datum:** YYYY-MM-DD
**Modus:** FINVIZ Elite / Öffentlich
**Analysierte Themen:** N
**Datenqualität:** [etwaige Einschränkungen vermerken]

## Theme Dashboard
[Tabelle der Top-Themen mit Heat, Richtung, Lebenszyklus, Konfidenz]

## Was sich heute geändert hat
[Neu aufkommende Themen, größte Heat-Beschleunigung, neue EP9M-Cluster, nachlassende Themen]

## Führungsnachweis
[5D+20%, EP9M, Range-Expansion, neue Hochs, High-RS-Zählungen und Führungssymbole]

## Details zu bullischen Themen
[Detaillierte Analyse bullischer Themen, sortiert nach Heat]

## Details zu bärischen Themen
[Detaillierte Analyse bärischer Themen, sortiert nach Heat]

## Zusammenfassung aller Themen
[Vollständige Themenrangliste]

## Branchenrankings
[Best- und schlechtestperformende Branchen]

## Sektor-Aufwärtstrend-Verhältnisse
[Sektor-Ebene-Aggregation, falls Aufwärtstrend-Daten verfügbar]

## Methodik-Hinweise
[Kurze Erklärung des Bewertungsmodells]

Speichern Sie den Bericht im Verzeichnis reports/.

---

Ausgabe

Das Skill erzeugt zwei Ausgabedateien im Verzeichnis reports/:

JSON-Ausgabe (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": "AI & Machine Learning",
    "top_bearish": "Regional Banks"
  },
  "themes": {
    "all": [
      {
        "name": "AI & Machine Learning",
        "direction": "bullish",
        "heat": 85.3,
        "maturity": 42.1,
        "stage": "Accelerating",
        "confidence": "Medium",
        "heat_label": "Hot",
        "industries": ["Software - Infrastructure", "Semiconductors"],
        "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": {...}
}

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

• Theme Dashboard mit sortierbaren Ranglisten
• Bullische/Bärische Themen-Detailabschnitte
• Branchenleistungsrankings
• Zusammenfassung der Sektor-Aufwärtstrend-Verhältnisse
• Methodik-Hinweise

Wichtige Ausgabefelder (pro Thema):

Feld	Beschreibung
heat	0-100 richtungsneutrale Themenstärke
direction	"bullish" (LEAD) oder "bearish" (LAG)
stage	Emerging / Accelerating / Trending / Mature / Exhausting
confidence	Niedrig / Mittel / Hoch (Skript begrenzt auf Mittel; WebSearch kann erhöhen)
representative_stocks	Top-Ticker-Symbole für das Thema
stock_details	Optionale Aktienmetrikobjekte für die ausgewählten Vertreter
proxy_etfs	Thematische ETF-Ticker (Länge = ETF-Anzahl; höher = überfüllter)

---

Fehlerbehebung

Häufige Probleme:

1. Skript läuft in öffentlichem Modus sehr langsam:

   • FINVIZ Elite-Abonnement wird empfohlen. Reduzieren Sie --max-themes auf 3-5.

2. Fehler bei der FINVIZ Elite-API:

   • Überprüfen Sie, ob $FINVIZ_API_KEY korrekt gesetzt ist.
   • Verwenden Sie echo $FINVIZ_API_KEY, um zu überprüfen, ob es definiert ist.
   • Wenn Sie Fehler bei der Ratenbegrenzung sehen, fügen Sie Ratenbegrenzungsverzögerungen hinzu oder versuchen Sie es später erneut.

3. Keine Themen gefunden:

   • Überprüfen Sie, ob der Markt geöffnet ist (nachbörsliche Daten können begrenzt sein).
   • Stellen Sie sicher, dass die Internetverbindung aktiv ist.
   • Niedrige Volatilitätsmärkte erzeugen möglicherweise nicht genügend Signal für eine Erkennung. In diesem Fall die Berichterstellung auf Fokusgruppen oder Proxy-ETF-Rotation umstellen.

4. JSON-Parsing-Fehler:

   • Überprüfen Sie, ob der Bericht vollständig generiert wurde.
   • Suchen Sie nach Fehlermeldungen während der Skriptausführung.

5. Hohe Konfidenz wird nie ausgegeben:

   • Das Skript begrenzt die Konfidenz auf Mittel. WebSearch narrative Bestätigung ist erforderlich, um auf Hoch zu erhöhen.

6. Narrative Bestätigung schlägt fehl oder ist unklar:

   • Auf Themen-Euphemismen prüfen („KI & Machine Learning" statt nur „Technologie").
   • Verwenden Sie einen aktuellen Monat im Suchmuster, um aktuelle Relevanz sicherzustellen.
   • Erwägen Sie die Suche nach Unterbranchen des Themas, falls es zu breit ist (z. B. "Großsprache-Modelle" anstatt "KI").

---

Externe Abhängigkeiten

• FINVIZ (finvizfinance - Elite-API oder öffentliches Scraping)
• yfinance (für ETF-Preisdaten)
• FMP API (optional, für KGV-Bewertungsdaten)

---

Sicherheitshinweise

• API-Schlüssel nicht in Versionskontrolle einchecken (verwenden Sie Umgebungsvariablen)
• Ratenbegrenzungen einhalten (insbesondere mit öffentlichem FINVIZ-Scraping)
• Keine nicht öffentlichen Finanzdaten preisgeben

---

Siehe auch

• sector-analyst - Für tiefgehende Sektor-Chart-Analyse
• us-stock-analysis - Für Mustererkennung auf Einzeltitelebene
• portfolio-manager - Für Neugewichtung des Portfolios