tradermonty/theme-detector

테마 감지기

개요

이 스킬은 교차 섹터 모멘텀, 거래량, 폭 신호를 분석하여 트렌딩 시장 테마를 감지하고 순위를 매깁니다. 강세(상승 모멘텀) 및 약세(하락 압력) 테마를 모두 식별하고, 라이프사이클 성숙도(신흥/가속/트렌딩/성숙/소멸)를 평가하며, 정량적 데이터와 내러티브 분석을 결합한 신뢰도 점수를 제공합니다.

3차원 점수 모델:

1. 테마 열기 (0-100): 테마의 방향 중립적 강도(모멘텀, 거래량, 상승 추세 비율, 폭)
2. 라이프사이클 성숙도: 지속 기간, 극단값 클러스터링, 밸류에이션, ETF 증가율에 기반한 단계 분류 (신흥 / 가속 / 트렌딩 / 성숙 / 소멸)
3. 신뢰도 (낮음 / 중간 / 높음): 감지의 신뢰성으로, 정량적 폭과 내러티브 확인을 결합합니다. 스크립트 출력은 중간으로 제한되며; Claude의 WebSearch 내러티브 확인 단계를 통해 높음으로 상향될 수 있습니다.
4. 주식 리더십: 선택 사항으로 5D+20%, EP9M, 범위 확장, 신고가, 높은 RS 주식의 일일 스캔 적중 증거입니다. 제공되면 테마 열기 v2에 혼합되며; 없으면 신뢰도 범위를 낮추지만 리더십을 0으로 강제하지는 않습니다.
5. 테마 일치 품질: 산업 참여, 명시적 주식 바스켓 적중, 대리 ETF 확인, 선택적 오프라인 내러티브 점수로부터의 테마 일치 특이성입니다. 이는 증거 품질이며, 거래 추천이 아닙니다.

주요 기능:

• FINVIZ 산업 데이터를 사용한 교차 섹터 테마 감지
• 방향 인식 점수 매기기 (강세 및 약세 테마)
• 혼잡한 거래 대 신흥 거래를 식별하기 위한 라이프사이클 성숙도 평가
• ETF 증가율 점수 매기기 (ETF가 많을수록 더 성숙/혼잡한 테마)
• 3점 평가를 위한 uptrend-dashboard와의 통합
• --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 (선택 사항, P/E 비율 밸류에이션 데이터용):

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단계: 감지 결과 읽기 및 구문 분석

스크립트는 두 개의 출력 파일을 생성합니다:

• 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 쿼리를 실행하여 내러티브 강도를 확인합니다:

검색 패턴:

"[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, 방향 = 강세):

• 라이프사이클 단계 식별 (신흥 = 기회, 성숙/소멸 = 주의)
• 테마 내 최고 성과 산업 나열
• 익스포저를 위한 대리 ETF 추천
• ETF 증가율이 높은 경우 플래그 지정 (혼잡한 거래 경고)

뜨거운 약세 테마 (열기 >= 70, 방향 = 약세):

• 압박을 받는 산업 식별
• 약세 모멘텀이 가속화 중인지 둔화 중인지 평가
• 헤징 전략 또는 피해야 할 섹터 추천
• 라이프사이클이 성숙/소멸인 경우 잠재적 평균 회귀 기회 기록

신흥 테마 (열기 40-69, 라이프사이클 = 신흥):

• 이는 조기 로테이션 신호를 나타낼 수 있음
• 관심 목록으로 모니터링 권장
• 테마를 가속화할 수 있는 촉매 이벤트 식별

소멸 테마 (열기 >= 60, 라이프사이클 = 소멸):

• 혼잡한 거래 위험에 대해 경고
• 높은 ETF 수는 과도한 소매 참여를 확인함
• 반대 포지셔닝 또는 익스포저 감소 고려

6단계: 최종 보고서 생성

보고서 템플릿 구조를 사용하여 최종 보고서를 사용자에게 제시합니다:

# 테마 감지 보고서
**날짜:** YYYY-MM-DD
**모드:** FINVIZ Elite / 공개
**분석된 테마:** N
**데이터 품질:** [제한 사항 기록]

## 테마 대시보드
[열기, 방향, 라이프사이클, 신뢰도가 포함된 상위 테마 표]

## 오늘 변경된 사항
[새롭게 신흥 테마, 가장 큰 열기 가속화, 새로운 EP9M 클러스터, 약화되는 테마]

## 리더십 증거
[5D+20%, EP9M, 범위 확장, 신고가, 높은 RS 개수 및 리더 심볼]

## 강세 테마 상세
[열기로 정렬된 강세 테마의 상세 분석]

## 약세 테마 상세
[열기로 정렬된 약세 테마의 상세 분석]

## 모든 테마 요약
[전체 테마 순위 표]

## 산업 순위
[최고 및 최저 성과 산업]

## 섹터 상승 추세 비율
[상승 추세 데이터를 사용할 수 있는 경우 섹터 수준 집계]

## 방법론 노트
[점수 모델에 대한 간략한 설명]

보고서를 reports/ 디렉토리에 저장합니다.

---

출력

스킬은 reports/ 디렉토리에 두 개의 출력 파일을 생성합니다:

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": {...}
}

마크다운 보고서 (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 개수; 높을수록 더 혼잡함)