theme-detector

テーマ検出器

概要

このスキルは、セクター横断的なモメンタム、出来高、広がりのシグナルを分析して、上昇中の市場テーマを検出し、順位付けします。強気（上昇モメンタム）と弱気（下落圧力）の両方のテーマを特定し、ライフサイクルの成熟度（新興／加速／トレンド／成熟／衰退）を評価して、定量データとナラティブ分析を組み合わせた信頼度スコアを提示します。

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

1. テーマの勢い（0～100）：テーマの方向性に依存しない強さ（モメンタム、出来高、上昇トレンド比率、広がり）
2. ライフサイクルの成熟度：継続期間、極端な値の集中、バリュエーション、ETF の増加に基づく段階分類（新興／加速／トレンド／成熟／衰退）
3. 信頼度（低／中／高）：定量的な広がりとナラティブによる裏付けを組み合わせた、検出の信頼性。スクリプト出力は「中」が上限です。Claude の WebSearch によるナラティブ確認のステップで「高」に引き上げられます。
4. 銘柄のリーダーシップ：5D+20%、EP9M、レンジ拡大、新高値、高 RS 銘柄から得られる、任意の日次スキャンヒットの証拠です。提供された場合はテーマの勢い v2 に反映されます。提供されない場合、信頼度のカバレッジは低下しますが、リーダーシップがゼロになるわけではありません。
5. テーマの一致品質：業界の参加、明示的な銘柄バスケットのヒット、プロキシ ETF による裏付け、任意のオフラインのナラティブスコアに基づく、テーマの一致の具体性です。これは証拠の品質を示すものであり、売買の推奨ではありません。

主な機能：

• FINVIZ の業界データを使用したセクター横断的なテーマ検出
• 方向性を考慮したスコアリング（強気と弱気のテーマ）
• 混雑した取引と新興の取引を特定するためのライフサイクル成熟度の評価
• ETF 増加スコアリング（ETF が多いほど、テーマが成熟または混雑している）
• 3 点評価のための uptrend-dashboard との連携
• --scan-hits による銘柄レベルのリーダーシップの証拠
• 明示的な銘柄バスケットとプロキシ ETF による裏付けを通じたテーマの一致品質
• 異常な値動き／出来高／レンジ／RS 指標で順位付けしたリーダー候補の証拠。時価総額はリスク分類としてのみ表示
• --history-file によるテーマ履歴と加速指標
• 2 つの動作モード：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（オプション。P/E 比率の評価データ用）：

export FMP_API_KEY=your_fmp_api_key_here

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

FINVIZ Elite がない場合、このスキルは公開 FINVIZ スクレイピングを使用します（業界あたり約 20 銘柄までに制限され、レート制限により処理が遅くなります）。

---

ワークフロー

ステップ 1：環境を確認する

API キーが設定されていることを確認してください（「前提条件」を参照）。

# Verify FINVIZ Elite API key (optional but recommended)
echo $FINVIZ_API_KEY

# Verify FMP API key (optional)
echo $FMP_API_KEY

ステップ 2：テーマ検出スクリプトを実行する

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

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

スクリプトのオプション：

# Full run (public FINVIZ mode, no API key required)
python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

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

# With FMP API key for enhanced stock data
python3 skills/theme-detector/scripts/theme_detector.py \
  --fmp-api-key $FMP_API_KEY \
  --output-dir reports/

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

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

# Add Stockbee/Pradeep-style leadership evidence
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 出力を読み、定量的な結果を確認してください。

# Find the latest report
ls -lt reports/theme_detector_*.json | head -1

# Read the JSON output
cat reports/theme_detector_YYYY-MM-DD_HHMMSS.json

ステップ 4：WebSearch でナラティブを確認する

Theme Heat スコアの上位 5 テーマについて、ナラティブの強さを確認するために WebSearch クエリを実行します。

検索パターン：

"[theme name] stocks market [current month] [current year]"
"[theme name] sector momentum [current month] [current year]"

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

• 強いナラティブ：複数の大手メディアがテーマを取り上げており、アナリストによる格上げや政策上の追い風がある
• 中程度のナラティブ：一定の報道はあるものの、センチメントはまちまちで、明確な触媒がない
• 弱いナラティブ：報道が少ない、または主に逆張り・懐疑的な論調である

調査結果に基づいて信頼度を更新します。

• 定量評価が高く、ナラティブが強い = 信頼度 高
• 定量評価が高く、ナラティブが弱い = 信頼度 中（モメンタムの乖離の可能性）
• 定量評価が低く、ナラティブが強い = 信頼度 中（価格に先行してナラティブが生まれている可能性）
• 定量評価が低く、ナラティブが弱い = 信頼度 低

ステップ 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、方向 = 強気）の場合：

• ライフサイクルの段階を特定します（Emerging = 機会、Mature/Exhausting = 注意）
• テーマ内でパフォーマンス上位の業種を列挙します
• エクスポージャーを得るための代理ETFを推奨します
• ETF の乱立が多い場合は警告します（取引の混雑に注意）

弱気の注目テーマ（ヒート >= 70、方向 = 弱気）の場合：

• 圧力を受けている業種を特定します
• 弱気のモメンタムが加速しているか、減速しているかを評価します
• ヘッジ戦略または回避すべきセクターを推奨します
• ライフサイクルが Mature/Exhausting の場合は、平均回帰の可能性に言及します

新興テーマ（ヒート 40-69、ライフサイクル = Emerging）の場合：

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

消耗したテーマ（ヒート >= 60、ライフサイクル = Exhausting）の場合：

• 取引の混雑リスクについて警告します
• ETF 数の多さは、個人投資家の過剰な参加を裏付けます
• 逆張りのポジショニング、またはエクスポージャーの削減を検討します

ステップ 6：最終レポートを生成する

レポートテンプレートの構成に従って、ユーザーに最終レポートを提示します。

# Theme Detection Report
**Date:** YYYY-MM-DD
**Mode:** FINVIZ Elite / Public
**Themes Analyzed:** N
**Data Quality:** [note any limitations]

## Theme Dashboard
[Top themes table with Heat, Direction, Lifecycle, Confidence]

## What Changed Today
[Newly emerging themes, largest heat acceleration, new EP9M clusters, fading themes]

## Leadership Evidence
[5D+20%, EP9M, range expansion, new highs, high-RS counts and leader symbols]

## Bullish Themes Detail
[Detailed analysis of bullish themes sorted by Heat]

## Bearish Themes Detail
[Detailed analysis of bearish themes sorted by Heat]

## All Themes Summary
[Complete theme ranking table]

## Industry Rankings
[Top performing and worst performing industries]

## Sector Uptrend Ratios
[Sector-level aggregation if uptrend data available]

## Methodology Notes
[Brief explanation of scoring model]

レポートを 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	Emerging / Accelerating / Trending / Mature / Exhausting
confidence	Low / Medium / High（スクリプトでは Medium が上限です。WebSearch によって引き上げられる場合があります）
representative_stocks	テーマを代表する上位のティッカーシンボル
stock_details	選択された代表銘柄の、任意の株式指標オブジェクト
proxy_etfs	テーマ別ETFのティッカー（長さ = ETF 数。多いほど取引が混雑しています）
theme_match_score	業種、株式バスケットのヒット、代理ETFによる確認、および任意の説明文入力に基づく 0-100 の証拠品質スコア
theme_match_components	テーマとの一致を説明する、確認可能なサブスコア
leader_candidates	テーマの証拠に基づくランキング順のシンボル。エントリー／ストップ／無効化のガイダンスではありません
fresh_leadership_symbols	EP9M、レンジ拡大、または高値更新の証拠がある、今回の実行で検出されたシンボル
extended_symbols	5D+20% の証拠がある、今回の実行で検出されたシンボル。過度な上昇の証拠としてのみ使用します
theme_origin	"seed"（YAML 設定由来）または "discovered"（自動クラスタリング由来）

---

リソース

スクリプトディレクトリ（scripts/）

主なスクリプト：

• theme_detector.py - メインのオーケストレーター スクリプト

  • 業界データの収集、テーマの分類、スコアリングを調整します
  • JSON + Markdown の出力を生成します
  • 使用方法：python3 theme_detector.py [options]

• theme_classifier.py - 業界を複数セクターにまたがるテーマにマッピングします

  • cross_sector_themes.md からテーマ定義を読み込みます
  • テーマレベルで集計したスコアを計算します
  • 構成業界から方向性（強気／弱気）を判定します
  • 表示マッピング：「bullish」→「LEAD」、「bearish」→「LAG」（report_generator.py::_direction_label() を参照）

• finviz_industry_scanner.py - FINVIZ の業界データを収集します

  • Elite モード：業界ごとの全銘柄データを含む CSV エクスポート
  • Public モード：レート制限付きの Web スクレイピング
  • 抽出項目：パフォーマンス、出来高、変化率、平均出来高、時価総額

• calculators/lifecycle_calculator.py - ライフサイクルの成熟度を評価します

  • 期間スコアリング、極端度のクラスタリング、バリュエーション分析
  • thematic_etf_catalog.md に基づく ETF の増加度スコアリング
  • ステージ分類：Emerging / Accelerating / Trending / Mature / Exhausting

• report_generator.py - レポート出力を生成します

  • テンプレートから Markdown レポートを生成します
  • JSON の構造化出力
  • テーマダッシュボードのフォーマット

参照ディレクトリ（references/）

ナレッジベース：

• cross_sector_themes.md - 業界、ETF、銘柄、照合基準を含むテーマ定義
• thematic_etf_catalog.md - テーマごとの件数を含む包括的なテーマ別 ETF カタログ
• finviz_industry_codes.md - FINVIZ の業界とフィルターコードの完全な対応表
• theme_detection_methodology.md - 3D スコアリングモデルの技術ドキュメント

アセットディレクトリ（assets/）

• report_template.md - プレースホルダー形式を使用したレポート生成用 Markdown テンプレート

---

取引所カレンダーとリプレイ

検出器を実行する前に、requirements.txt をインストールしてください。--as-of-date は厳密な YYYY-MM-DD の上限日で、上昇トレンドの鮮度チェックとプロバイダーの履歴期間の両方に使用されます。FINVIZ、気配値、プロフィール、上昇トレンドの入力データは PIT スナップショットではなくライブデータであるため、現在の日付以外の --as-of-date を指定すると処理は失敗します。鮮度の判定では XNYS の取引日を数え、将来の日付が付与されたソース行は除外します。

重要な注意事項

FINVIZ モードの違い

機能	Elite モード	Public モード
業界の網羅範囲	約145の全業界	約145の全業界
業界あたりの銘柄数	全銘柄	約20銘柄（1ページ目）
レート制限	リクエスト間に0.5秒	リクエスト間に2.0秒
データの鮮度	リアルタイム	15分遅延
API キーが必要	はい（$39.50/月）	いいえ
実行時間	約2～3分	約5～8分

方向性の判定ロジック

テーマの方向性は、構成業界の相対順位の多数決によって判定されます。

1. 業界のランキング：約145の全業界を、複数の時間軸のモメンタムスコアで順位付けします
2. 順位に基づく方向性：ランキング上位半分の業界を「bullish」、下位半分を「bearish」に分類します
3. テーマの多数決：_majority_direction() が各テーマ内の bullish と bearish の業界数を数え、多数派を採用します

表示マッピング：「bullish」→ LEAD、「bearish」→ LAG（report_generator.py::_direction_label() を参照）

LEAD テーマは、その構成業界が相対的にアウトパフォームしていることを示します。LAG テーマでも絶対リターンがプラスの場合があります。これは相対的なアンダーパフォームを示すものであり、空売りシグナルではありません。

既知の制限事項

1. サバイバーシップバイアス：現在上場している銘柄と ETF のみを分析します
2. 遅延：FINVIZ のデータは日中の値動きに対して15分遅れる場合があります（Public モード）
3. テーマの境界：複数のテーマに当てはまる銘柄があります。分類には主要業界を使用します
4. ETF の増加：カタログは固定されており、ごく新しい ETF が反映されない場合があります
5. ナラティブスコアリング：WebSearch ベースであり、本質的に主観的です
6. Public モードの制限：業界あたり約20銘柄のため、小型株のシグナルを見逃す場合があります

免責事項

この分析は、教育および情報提供のみを目的としています。

• 投資助言ではありません
• 過去のテーマ別トレンドは、将来のパフォーマンスを保証するものではありません
• テーマの検出はモメンタムを特定するものであり、ファンダメンタル価値を示すものではありません
• 投資判断を行う前に、ご自身で調査してください

---

バージョン： 1.0 最終更新日： 2026-02-16 API 要件： FINVIZ Elite（推奨）またはパブリックモード（無料）；FMP API は任意 実行時間： モードに応じて約 2～8 分 出力形式： JSON + Markdown 対象テーマ： セクター横断型テーマ 14 件以上