tradermonty/theme-detector

Theme Detector

Visão Geral

Esta skill detecta e ranqueia temas de mercado em tendência analisando momentum intersetorial, volume e sinais de amplitude. Ela identifica tanto temas de alta (momentum ascendente) quanto de baixa (pressão descendente), avalia a maturidade do ciclo de vida (Emergente/Acelerando/Em Tendência/Maduro/Exaustivo) e fornece uma pontuação de confiança combinando dados quantitativos com análise narrativa.

Modelo de Pontuação Tridimensional:

1. Theme Heat (0-100): Força neutra em direção do tema (momentum, volume, taxa de tendência de alta, amplitude)
2. Lifecycle Maturity: Classificação de estágio (Emergente / Acelerando / Em Tendência / Maduro / Exaustivo) baseada em duração, agrupamento de extremos, valuation e proliferação de ETFs
3. Confidence (Baixo / Médio / Alto): Confiabilidade da detecção, combinando amplitude quantitativa com confirmação narrativa. A saída do script é limitada a Médio; a etapa de confirmação narrativa via WebSearch do Claude pode elevar para Alto.
4. Stock Leadership: Evidência opcional de varreduras diárias de hits de 5D+20%, EP9M, expansão de faixa, novas máximas e ações com alto RS. Quando fornecida, é incorporada ao Theme Heat v2; quando ausente, reduz a cobertura de confiança, mas não força a liderança a zero.
5. Theme Match Quality: Especificidade da correspondência do tema a partir da participação da indústria, hits explícitos de cestas de ações, confirmação de ETF proxy e pontuações narrativas offline opcionais. Isso é qualidade de evidência, não uma recomendação de negociação.

Principais Características:

• Detecção de temas intersetoriais usando dados da indústria FINVIZ
• Pontuação ciente de direção (temas de alta e baixa)
• Avaliação de maturidade do ciclo de vida para identificar trades lotados vs. emergentes
• Pontuação de proliferação de ETFs (mais ETFs = tema mais maduro/lotado)
• Integração com painel de tendência de alta para avaliação de 3 pontos
• Evidência de liderança no nível da ação via --scan-hits
• Qualidade de correspondência de temas via cestas de ações explícitas e confirmação de ETF proxy
• Evidência de candidatos a líderes ranqueados por movimento anormal/volume/faixa/métricas RS, com capitalização de mercado mostrada apenas como um balde de risco
• Histórico de temas e métricas de aceleração via --history-file
• Modo de operação dupla: FINVIZ Elite (rápido) ou scraping público (mais lento, limitado)
• Confirmação narrativa baseada em WebSearch para os principais temas

---

Quando Usar Esta Skill

Gatilhos Explícitos:

• "Quais temas de mercado estão em tendência agora?"
• "Quais setores estão quentes/frios?"
• "Detecte temas atuais do mercado"
• "Quais são as narrativas de alta/baixa mais fortes?"
• "IA/energia limpa/defesa ainda é um tema forte?"
• "Para onde a rotação setorial está indo?"
• "Mostre-me oportunidades de investimento temático"

Gatilhos Implícitos:

• Usuário quer entender mudanças na narrativa ampla do mercado
• Usuário está procurando ideias de ETFs temáticos ou alocação setorial
• Usuário pergunta sobre trades lotados ou temas de ciclo tardio
• Usuário quer saber quais temas estão emergindo vs. exaustos

Quando NÃO Usar:

• Análise de ações individuais (use us-stock-analysis)
• Mergulho profundo em setor específico com leitura de gráfico (use sector-analyst)
• Rebalanceamento de portfólio (use portfolio-manager)
• Investimento em dividendos/renda (use value-dividend-screener)

---

Pré-requisitos

Obrigatório:

• Python 3.9+ com dependências principais.

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

Fallback Cron / Python misto: Se o python3 ativo for mais antigo que 3.10, ou um venv Hermes mais novo não tiver as dependências de ciência de dados, execute o detector através do uv com um interpretador moderno explícito e dependências temporárias em vez de editar o ambiente no meio do cron:

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/

Use isso como uma solução alternativa de configuração, não como evidência de que o detector está quebrado; ainda relate ressalvas de dados FINVIZ/FMP/API separadamente.

Chaves de API Opcionais:

FINVIZ Elite (recomendado para cobertura completa da indústria e velocidade):

export FINVIZ_API_KEY=sua_chave_finviz_elite_aqui

FMP API (opcional, para dados de valuation P/E):

export FMP_API_KEY=sua_chave_fmp_aqui

Os requisitos incluem finvizfinance, PyYAML, pandas/numpy, requests e yfinance porque a execução normal em modo público importa ou usa cada um deles.

Sem FINVIZ Elite, a skill usa scraping público do FINVIZ (limitado a ~20 ações por indústria, limites de taxa mais lentos).

---

Fluxo de Trabalho

Passo 1: Verificar Ambiente

Verifique se as chaves de API estão configuradas (consulte Pré-requisitos):

# Verificar chave da API FINVIZ Elite (opcional, mas recomendado)
echo $FINVIZ_API_KEY

# Verificar chave da API FMP (opcional)
echo $FMP_API_KEY

Passo 2: Executar Script de Detecção de Temas

Execute o script de detecção principal:

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

Opções do Script:

# Execução completa (modo FINVIZ público, nenhuma chave de API necessária)
python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

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

# Com chave da API FMP para dados aprimorados de ações
python3 skills/theme-detector/scripts/theme_detector.py \
  --fmp-api-key $FMP_API_KEY \
  --output-dir reports/

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

# Modo FINVIZ explícito
python3 skills/theme-detector/scripts/theme_detector.py \
  --finviz-mode public \
  --output-dir reports/

# Adicionar evidência de liderança estilo 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/

Contrato de entrada de scan-hit: --scan-hits aceita JSON, JSONL ou CSV. Linhas podem ser pré-rotuladas com scan_type / scan_types, ou linhas brutas com campos como symbol, return_5d, change_pct, volume, avg_volume_50d, relative_volume, true_range, atr_20, atr_expansion, close_location, industry, sector e theme_guess. Uma linha bruta pode se expandir em vários hits quando satisfaz múltiplas regras.

Regras de varredura iniciais:

• five_day_20pct: return_5d >= 20
• ep9m: volume >= 9.000.000, relative_volume >= 2,0 e change_pct >= 4
• range_expansion: change_pct >= 4, true_range / atr_20 >= 1,5 ou atr_expansion >= 1,5 e close_location >= 0,75
• new_high: new_high / is_new_high explícito, ou evidência de máxima de 52 semanas
• high_rs: rs_rating >= 90 ou relative_strength normalizado >= 0,90

Contrato de entrada de narrative-score: --narrative-scores é uma entrada JSON offline, não uma chamada WebSearch ao vivo. Aceita {"Nome do Tema": 82} ou {"themes": {"Nome do Tema": {"narrative_keyword_score": 82}}}. A ausência de entrada narrativa deixa narrative_keyword_score como null e reduz theme_match_coverage; não falha a execução.

Tempo de Execução Esperado:

• Modo FINVIZ Elite: ~2-3 minutos (14+ temas)
• Modo FINVIZ Público: ~5-8 minutos (scraping com limite de taxa)

Passo 3: Ler e Interpretar Resultados da Detecção

O script gera dois arquivos de saída:

• theme_detector_YYYY-MM-DD_HHMMSS.json - Dados estruturados para uso programático
• theme_detector_YYYY-MM-DD_HHMMSS.md - Relatório legível por humanos

Leia a saída JSON para entender os resultados quantitativos:

# Encontrar o relatório mais recente
ls -lt reports/theme_detector_*.json | head -1

# Ler a saída JSON
cat reports/theme_detector_YYYY-MM-DD_HHMMSS.json

Passo 4: Realizar Confirmação Narrativa via WebSearch

Para os 5 principais temas (por pontuação Theme Heat), execute consultas WebSearch para confirmar a força narrativa:

Padrão de Pesquisa:

"[nome do tema] ações mercado [mês atual] [ano atual]"
"[nome do tema] momentum setorial [mês atual] [ano atual]"

Avaliar sinais narrativos:

• Narrativa forte: Múltiplos grandes veículos cobrindo o tema, upgrades de analistas, catalisadores de política
• Narrativa moderada: Alguma cobertura, sentimento misto, nenhum catalisador claro
• Narrativa fraca: Pouca cobertura, ou tom predominantemente contrário/cético

Atualize os níveis de Confiança com base nas descobertas:

• Alto Quantitativo + Narrativa Forte = Alta confiança
• Alto Quantitativo + Narrativa Fraca = Média confiança (possível divergência de momentum)
• Baixo Quantitativo + Narrativa Forte = Média confiança (narrativa pode liderar o preço)
• Baixo Quantitativo + Narrativa Fraca = Baixa confiança

Passo 5: Analisar Resultados e Fornecer Recomendações

Referencie cruzadamente os resultados da detecção com bases de conhecimento:

Documentos de Referência a Consultar:

1. references/cross_sector_themes.md - Definições de temas e indústrias constituintes
2. references/thematic_etf_catalog.md - Opções de exposição a ETFs por tema
3. references/theme_detection_methodology.md - Detalhes do modelo de pontuação
4. references/finviz_industry_codes.md - Referência de classificação da indústria

Estrutura de Análise:

Para Temas Quentes de Alta (Heat >= 70, Direção = Alta):

• Identificar estágio do ciclo de vida (Emergente = oportunidade, Maduro/Exaustivo = cautela)
• Listar indústrias com melhor desempenho dentro do tema
• Recomendar ETFs proxy para exposição
• Sinalizar se a proliferação de ETFs é alta (aviso de trade lotado)

Para Temas Quentes de Baixa (Heat >= 70, Direção = Baixa):

• Identificar indústrias sob pressão
• Avaliar se o momentum de baixa está acelerando ou desacelerando
• Recomendar estratégias de hedge ou setores a evitar
• Observar oportunidades potenciais de reversão à média se o ciclo de vida for Maduro/Exaustivo

Para Temas Emergentes (Heat 40-69, Ciclo de Vida = Emergente):

• Estes podem representar sinais precoces de rotação
• Recomendar monitoramento com lista de observação
• Identificar eventos catalisadores que possam acelerar o tema

Para Temas Exaustos (Heat >= 60, Ciclo de Vida = Exaustivo):

• Alertar sobre risco de trade lotado
• Alta contagem de ETFs confirma participação excessiva de varejo
• Considerar posicionamento contrário ou redução de exposição

Passo 6: Gerar Relatório Final

Apresente o relatório final ao usuário usando a estrutura de modelo de relatório:

# Relatório de Detecção de Temas
**Data:** AAAA-MM-DD
**Modo:** FINVIZ Elite / Público
**Temas Analisados:** N
**Qualidade dos Dados:** [observar quaisquer limitações]

## Painel de Temas
[Tabela de temas principais com Heat, Direção, Ciclo de Vida, Confiança]

## O Que Mudou Hoje
[Temas recém-emergentes, maior aceleração de Heat, novos clusters EP9M, temas em desaparecimento]

## Evidência de Liderança
[Contagens de 5D+20%, EP9M, expansão de faixa, novas máximas, alto RS e símbolos de líderes]

## Detalhes dos Temas de Alta
[Análise detalhada dos temas de alta classificados por Heat]

## Detalhes dos Temas de Baixa
[Análise detalhada dos temas de baixa classificados por Heat]

## Resumo de Todos os Temas
[Tabela de classificação completa de temas]

## Rankings da Indústria
[Indústrias com melhor e pior desempenho]

## Taxas de Tendência de Alta do Setor
[Agregação no nível do setor se dados de tendência de alta estiverem disponíveis]

## Notas de Metodologia
[Breve explicação do modelo de pontuação]

Salve o relatório no diretório reports/.

---

Saída

A skill gera dois arquivos de saída no diretório reports/:

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

Relatório Markdown (theme_detector_YYYY-MM-DD_HHMMSS.md):

• Painel de Temas com classificações ordenáveis
• Seções de detalhes de temas de Alta/Baixa
• Rankings de desempenho da indústria
• Resumo da taxa de tendência de alta do setor
• Notas de metodologia

Principais Campos de Saída (por tema):

Campo	Descrição
heat	Força do tema neutra em direção 0-100
direction	"bullish" (LIDER) ou "bearish" (RETARDATÁRIO)
stage	Emergente / Acelerando / Em Tendência / Maduro / Exaustivo
confidence	Baixo / Médio / Alto (script limita a Médio; WebSearch pode elevar)
representative_stocks	Principais símbolos de ações para o tema
stock_details	Objetos de métricas de ações opcionais para os representantes selecionados
proxy_etfs	Símbolos de ETFs temáticos (comprimento = contagem de ETFs; maior = mais lotado)