stockbee-episodic-pivot-analyzer

Stockbee Episodic Pivot Analyzer

カタリストの質と価格／出来高の確認の両方を使って、1日目のエピソディック・ピボット（EP）候補を分類します。このスキルは候補の質を分析するものであり、売買を実行するエンジンではありません。

使用する場面

• ユーザーが Pradeep Bonde／Stockbee 方式の EP 候補を求めている場合
• ユーザーが決算、ガイダンス、M&A、FDA、アナリスト、契約、製品、ショートスクイーズ、テーマ／ニュースイベントを提示した場合
• ACTIONABLE_DAY1 候補と DELAYED_EP_WATCH 銘柄を分けたい場合
• 有望な決算／ガイダンス EP を pead-screener に渡したい場合
• カタリスト分析と stockbee-momentum-burst-screener の価格／出来高出力を組み合わせたい場合

前提条件

• Python 3.10+
• オプション：OHLCV の補完用 FMP API キー
• 以下のいずれか：
  • カタリスト／イベントの JSON
  • earnings-trade-analyzer の JSON 出力
  • カタリスト JSON と stockbee-momentum-burst-screener の JSON 補完データ
• このスキル自体はニュースの取得や発見を行いません。カタリストが提示されていない場合は、まずユーザーが希望するニュース調査またはリサーチの手順でイベント／ニュースの背景情報を収集してください。

ワークフロー

ステップ 1：候補の入力データを準備する

以下の入力モードを 1 つ以上使用します。

モード A — カタリスト／イベント JSON：

{
  "events": [
    {
      "symbol": "ABC",
      "event_date": "2026-04-25",
      "catalyst_type": "guidance_raise",
      "headline": "ABC raises FY guidance after record demand",
      "summary": "Management raised revenue and EPS guidance."
    }
  ]
}

モード B — 決算パイプライン：

earnings-trade-analyzer が出力した JSON を使用します。

モード C — 価格／出来高の補完：

stockbee-momentum-burst-screener の JSON レポートを渡すと、日次上昇率、出来高、終値の位置、およびリスク距離の各フィールドを再利用できます。

ステップ 2：アナライザーを実行する

# Catalyst JSON + offline OHLCV
python3 skills/stockbee-episodic-pivot-analyzer/scripts/analyze_ep.py \
  --events-json data/catalysts.json \
  --prices-json data/daily_ohlcv.json \
  --output-dir reports/

# Earnings pipeline input
python3 skills/stockbee-episodic-pivot-analyzer/scripts/analyze_ep.py \
  --earnings-json reports/earnings_trade_analyzer_YYYY-MM-DD_HHMMSS.json \
  --output-dir reports/

# Catalyst JSON + Stockbee momentum enrichment
python3 skills/stockbee-episodic-pivot-analyzer/scripts/analyze_ep.py \
  --events-json data/catalysts.json \
  --momentum-json reports/stockbee_momentum_burst_YYYY-MM-DD_HHMMSS.json \
  --output-dir reports/

FMP による補完（任意）：

export FMP_API_KEY=your_key
python3 skills/stockbee-episodic-pivot-analyzer/scripts/analyze_ep.py \
  --events-json data/catalysts.json \
  --max-api-calls 200 \
  --output-dir reports/

ステップ 3：出力を確認する

候補ごとに、以下を提示します。

• state：ACTIONABLE_DAY1、DAY1_WATCH、DELAYED_EP_WATCH、CATALYST_WATCH、または REJECT
• ep_type：EARNINGS_EP、GUIDANCE_EP、FDA_EP、M_AND_A_EP、STORY_EP など
• カタリストの品質スコアとその理由
• 価格／レンジの拡大、出来高ショック、終値位置の質
• EP 当日安値までのリスク
• pead_handoff と delayed_ep_watch のフラグ

ステップ 4：引き継ぎルール

• ACTIONABLE_DAY1：取引を判断する前に technical-analyst と position-sizer に渡します。
• DAY1_WATCH：日中／翌日のウォッチリストに残し、チャートでの確認を求めます。
• DELAYED_EP_WATCH：1日目は追いかけず、落ち着いた押し目または新たなレンジの形成を監視します。
• CATALYST_WATCH：カタリストは重要である可能性がありますが、価格／出来高による確認がまだ十分ではありません。
• REJECT：この候補情報を根拠に取引しないでください。
• pead_handoff=true の決算／ガイダンス EP は、週足の陰線／遅行反応を監視するため pead-screener に渡せます。

出力

• stockbee_episodic_pivot_YYYY-MM-DD_HHMMSS.json — 構造化された EP スコアリングレポート
• stockbee_episodic_pivot_YYYY-MM-DD_HHMMSS.md — 人が読める候補レポート

リソース

• references/ep_methodology.md — Stockbee の EP 解釈とセットアップ分類
• references/catalyst_quality.md — カタリストの分類と品質スコアリング
• references/handoff_rules.md — 後続ワークフローへの引き継ぎと確認ルール

共通 FMP クライアント

ライブ FMP アクセスでは、同梱の生成済み scripts/fmp_client.py を使用します。これは FMP の実行開始時にのみ読み込まれるため、オフラインモードは requests がなくても動作します。CLI キーと環境変数の優先順位、API 呼び出し予算、および成功時の出力形式は維持されます。リクエストでは安定したエンドポイントのみを使用します。安定エンドポイントへのリクエストが拒否された場合、空の結果になった場合、または失敗した場合でも、廃止済みの v3 URL にはフォールバックしません。共通クライアントは、キーがそのまま、または URL エンコードされた形で出力に含まれるのを防ぎ、不正な JSON は 1 回再試行します。また、429 の場合は 60 秒待機して最大 1 回再試行し、レート制限が繰り返された場合は停止します。