tradermonty/theme-detector

テーマ検出器

概要

このスキルは、クロスセクターのモメンタム、出来高、および市場の幅シグナルを分析することで、トレンド市場テーマを検出・ランク付けします。上昇モメンタム（強気）と下降圧力（弱気）の両方のテーマを特定し、ライフサイクル成熟度（新出現/加速/トレンド/成熟/消耗）を評価し、定量データとナラティブ分析を組み合わせた信頼度スコアを提供します。

3次元スコアリングモデル：

1. テーマ熱度 (0-100)：方向中立なテーマの強さ（モメンタム、出来高、上昇トレンド比率、ブレス）
2. ライフサイクル成熟度：期間、極端値クラスタリング、バリュエーション、ETF普及数に基づくステージ分類（新出現 / 加速 / トレンド / 成熟 / 消耗）
3. 信頼度（低 / 中 / 高）：検出の信頼性で、定量的なブレスとナラティブ確認を組み合わせます。スクリプト出力は「中」で上限設定。ClaudeのWebSearchによるナラティブ確認ステップで「高」に引き上げ可能。
4. 株式リーダーシップ：オプションで、5D+20%、EP9M、レンジ拡大、新高値、高RS銘柄からの日次スキャンヒット証拠。提供された場合はテーマ熱度v2に統合されます。欠如している場合は信頼度カバレッジを低下させますが、リーダーシップをゼロに強制しません。
5. テーママッチ品質：業界参加、明示的な銘柄バスケットヒット、プロキシETF確認、オプションのオフラインナラティブスコアによるテーママッチの具体性。これは証拠の品質であり、取引推奨ではありません。

主な機能：

• FINVIZ業界データを使用したクロスセクターテーマ検出
• 方向認識スコアリング（強気および弱気テーマ）
• 混雑した取引 vs. 新興取引を特定するためのライフサイクル成熟度評価
• ETF普及数スコアリング（ETFが多いほどテーマが成熟/混雑していることを示す）
• 3点評価のための上昇トレンドダッシュボードとの統合
• --scan-hits による株式レベルのリーダーシップ証拠
• 明示的な銘柄バスケットとプロキシETF確認によるテーママッチ品質
• 異常値動き/出来高/レンジ/RS指標でランク付けされたリーダー候補証拠。時価総額はリスクバケットとしてのみ表示
• --history-file によるテーマ履歴と加速指標
• デュアルモード動作：FINVIZ Elite（高速）またはパブリックスクレイピング（低速、制限あり）
• トップテーマに対するWebSearchベースのナラティブ確認

---

このスキルを使用するタイミング

明示的なトリガー：

• 「今、どの市場テーマがトレンドですか？」
• 「どのセクターが熱い/冷えていますか？」
• 「現在の市場テーマを検出してください」
• 「最も強い強気/弱気のナラティブは何ですか？」
• 「AI/クリーンエネルギー/防衛はまだ強いテーマですか？」
• 「セクターローテーションはどこに向かっていますか？」
• 「テーマ別投資の機会を見せてください」

暗黙的なトリガー：

• ユーザーが広範な市場ナラティブの変化を理解したい場合
• ユーザーがテーマ別ETFやセクター配分のアイデアを探している場合
• ユーザーが混雑した取引や後期サイクルのテーマについて尋ねた場合
• ユーザーが新興テーマと消耗テーマのどちらかを知りたい場合

使用すべきでない場合：

• 個別株分析（代わりに us-stock-analysis を使用）
• チャートリーディングを用いた特定セクターの詳細分析（代わりに sector-analyst を使用）
• ポートフォリオリバランス（代わりに portfolio-manager を使用）
• 配当/インカム投資（代わりに value-dividend-screener を使用）

---

前提条件

必須：

• Python 3.9+ とコア依存関係。

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

Cron / 混合Pythonフォールバック： アクティブな python3 が3.10より古い場合、または新しいHermes venvにデータサイエンス依存関係がない場合、環境をcron中に編集する代わりに、明示的な最新インタプリタと一時的な依存関係を使用して uv 経由で検出器を実行します。

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/

これはセットアップの回避策として使用し、検出器が壊れている証拠として使用しないでください。FINVIZ/FMP/APIデータの注意事項は別途報告してください。

オプションのAPIキー：

FINVIZ Elite（業界全体のカバレッジと速度に推奨）：

export FINVIZ_API_KEY=your_finviz_elite_api_key_here

FMP API（オプション、PERatioバリュエーションデータ用）：

export FMP_API_KEY=your_fmp_api_key_here

要件には finvizfinance、PyYAML、pandas/numpy、requests、yfinance が含まれます。通常のパブリックモード実行では各ライブラリをインポートまたは使用するためです。

FINVIZ Eliteがない場合、スキルはパブリックFINVIZスクレイピング（業界あたり約20銘柄に制限、レート制限が遅い）を使用します。

---

ワークフロー

ステップ 1: 環境の確認

APIキーが設定されていることを確認します（前提条件を参照）：

# FINVIZ Elite APIキーを確認（オプションですが推奨）
echo $FINVIZ_API_KEY

# FMP APIキーを確認（オプション）
echo $FMP_API_KEY

ステップ 2: テーマ検出スクリプトの実行

メイン検出スクリプトを実行します：

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

スクリプトオプション：

# フル実行（パブリックFINVIZモード、APIキー不要）
python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

# FINVIZ Elite APIキーを使用
python3 skills/theme-detector/scripts/theme_detector.py \
  --finviz-api-key $FINVIZ_API_KEY \
  --output-dir reports/

# FMP APIキーを使用して株式データを拡張
python3 skills/theme-detector/scripts/theme_detector.py \
  --fmp-api-key $FMP_API_KEY \
  --output-dir reports/

# カスタム制限
python3 skills/theme-detector/scripts/theme_detector.py \
  --max-themes 5 \
  --max-stocks-per-theme 10 \
  --output-dir reports/

# 明示的なFINVIZモード
python3 skills/theme-detector/scripts/theme_detector.py \
  --finviz-mode public \
  --output-dir reports/

# 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/

スキャンヒット入力契約： --scan-hits はJSON、JSONL、またはCSVを受け入れます。行は scan_type / scan_types で事前ラベル付けされているか、 symbol、return_5d、change_pct、volume、avg_volume_50d、relative_volume、true_range、atr_20、atr_expansion、close_location、industry、sector、theme_guess などのフィールドを持つ生の行である可能性があります。生の行は、複数のルールを満たす場合に複数のヒットに展開される可能性があります。

初期スキャンルール：

• five_day_20pct：return_5d >= 20
• ep9m：volume >= 9,000,000、relative_volume >= 2.0、および change_pct >= 4
• range_expansion：change_pct >= 4、true_range / atr_20 >= 1.5 または atr_expansion >= 1.5、および close_location >= 0.75
• new_high：明示的な new_high / is_new_high、または52週高値の証拠
• high_rs：rs_rating >= 90 または正規化された relative_strength >= 0.90

ナラティブスコア入力契約： --narrative-scores はオフラインJSON入力であり、ライブWebSearch呼び出しではありません。{"Theme Name": 82} または {"themes": {"Theme Name": {"narrative_keyword_score": 82}}} の形式を受け入れます。ナラティブ入力がない場合、narrative_keyword_score は null のままになり、theme_match_coverage が低下します。実行は失敗しません。

予想実行時間：

• FINVIZ Eliteモード：約2～3分（14以上のテーマ）
• パブリックFINVIZモード：約5～8分（レート制限スクレイピング）

ステップ 3: 検出結果の読み取りと解析

スクリプトは2つの出力ファイルを生成します：

• theme_detector_YYYY-MM-DD_HHMMSS.json - プログラムによる使用のための構造化データ
• theme_detector_YYYY-MM-DD_HHMMSS.md - 人間が読めるレポート

JSON出力を読み取って定量的な結果を理解します：

# 最新のレポートを見つける
ls -lt reports/theme_detector_*.json | head -1

# JSON出力を読み取る
cat reports/theme_detector_YYYY-MM-DD_HHMMSS.json

ステップ 4: WebSearchによるナラティブ確認

上位5つのテーマ（テーマ熱度スコア順）について、WebSearchクエリを実行してナラティブの強さを確認します：

検索パターン：

"[テーマ名] 株式 市場 [現在の月] [現在の年]"
"[テーマ名] セクター モメンタム [現在の月] [現在の年]"

ナラティブシグナルの評価：

• 強いナラティブ：複数の主要メディアがテーマを報道、アナリストの格上げ、政策触媒
• 中程度のナラティブ：ある程度の報道、混合センチメント、明確な触媒なし
• 弱いナラティブ：ほとんど報道がない、または主に逆張り/懐疑的なトーン

発見に基づいて信頼度レベルを更新します：

• 定量的高 + ナラティブ強い = 高 信頼度
• 定量的高 + ナラティブ弱い = 中 信頼度（モメンタムダイバージェンスの可能性）
• 定量的低 + ナラティブ強い = 中 信頼度（ナラティブが価格をリードする可能性あり）
• 定量的低 + ナラティブ弱い = 低 信頼度

ステップ 5: 結果の分析と推奨事項の提供

検出結果をナレッジベースとクロスリファレンスします：

参照すべきドキュメント：

1. references/cross_sector_themes.md - テーマ定義と構成業界
2. references/thematic_etf_catalog.md - テーマ別ETFエクスポージャーオプション
3. references/theme_detection_methodology.md - スコアリングモデルの詳細
4. references/finviz_industry_codes.md - 業界分類リファレンス

分析フレームワーク：

強い強気テーマ（熱度 >= 70、方向 = 強気）の場合：

• ライフサイクルステージを特定（新出現 = 好機、成熟/消耗 = 注意）
• テーマ内のトップパフォーマンス業界をリスト
• エクスポージャーのためのプロキシETFを推奨
• ETF普及数が多い場合にフラグを立てる（混雑取引の警告）

強い弱気テーマ（熱度 >= 70、方向 = 弱気）の場合：

• 圧力を受けている業界を特定
• 弱気モメンタムが加速しているか減速しているかを評価
• ヘッジ戦略または避けるべきセクターを推奨
• ライフサイクルが成熟/消耗である場合、平均回帰の機会に注意

新興テーマ（熱度 40-69、ライフサイクル = 新出現）の場合：

• これらは初期のローテーションシグナルを表す可能性があります
• ウォッチリストでの監視を推奨
• テーマを加速させる可能性のある触媒イベントを特定

消耗テーマ（熱度 >= 60、ライフサイクル = 消耗）の場合：

• 混雑取引リスクについて警告
• ETF数が多いことは過剰な個人参加を確認
• 逆張りポジションまたはエクスポージャー削減を検討

ステップ 6: 最終レポートの生成

レポートテンプレート構造を使用して、最終レポートをユーザーに提示します：

# テーマ検出レポート
**日付：** YYYY-MM-DD
**モード：** FINVIZ Elite / パブリック
**分析テーマ数：** N
**データ品質：** [制限事項に注意]

## テーマダッシュボード
[熱度、方向、ライフサイクル、信頼度を含む上位テーマ表]

## 本日の変更点
[新たに出現したテーマ、最大の熱度加速、新しいEP9Mクラスター、衰退しているテーマ]

## リーダーシップ証拠
[5D+20%、EP9M、レンジ拡大、新高値、高RSカウントとリーダー銘柄]

## 強気テーマの詳細
[熱度順にソートされた強気テーマの詳細分析]

## 弱気テーマの詳細
[熱度順にソートされた弱気テーマの詳細分析]

## 全テーマサマリー
[完全なテーマランキング表]

## 業界ランキング
[トップパフォーマンスおよびワーストパフォーマンスの業界]

## セクター上昇トレンド比率
[上昇トレンドデータが利用可能な場合のセクターレベルの集計]

## 方法論ノート
[スコアリングモデルの簡単な説明]

レポートを reports/ ディレクトリに保存します。

---

出力

スキルは reports/ ディレクトリに2つの出力ファイルを生成します：

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": "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レポート（theme_detector_YYYY-MM-DD_HHMMSS.md）：

• 並べ替え可能なランキング付きテーマダッシュボード
• 強気/弱気テーマの詳細セクション
• 業界パフォーマンスランキング
• セクター上昇トレンド比率のサマリー
• 方法論ノート

主要出力フィールド（テーマごと）：

フィールド	説明
heat	0-100の方向中立なテーマの強さ
direction	"bullish" (LEAD) または "bearish" (LAG)
stage	新出現 / 加速 / トレンド / 成熟 / 消耗
confidence	低 / 中 / 高（スクリプトは「中」で上限設定、WebSearchで引き上げ可能）
representative_stocks	テーマのトップティッカーシンボル
stock_details	選択された代表銘柄のオプションの株式メトリックオブジェクト
proxy_etfs	テーマ別ETFティッカー（長さ = ETF数、多いほど混雑）

...（以下、翻訳のため省略）