tradermonty/theme-detector

Theme Detector - Detector de Temas del Mercado

Descripción General

Esta habilidad detecta y clasifica las tendencias temáticas del mercado mediante el análisis de señales de momento, volumen y amplitud entre sectores. Identifica tanto temas alcistas (momento alcista) como bajistas (presión bajista), evalúa la madurez del ciclo de vida (Emergente/Acelerando/En Tendencia/Maduro/Agotado) y proporciona una puntuación de confianza que combina datos cuantitativos con análisis narrativos.

Modelo de Puntuación Tridimensional:

1. Calor del Tema (0-100): Fuerza del tema independiente de la dirección (momento, volumen, ratio de tendencia alcista, amplitud)
2. Madurez del Ciclo de Vida: Clasificación de etapas (Emergente / Acelerando / En Tendencia / Maduro / Agotado) basada en duración, agrupación extrema, valoración y proliferación de ETF
3. Confianza (Baja / Media / Alta): Fiabilidad de la detección, que combina amplitud cuantitativa con confirmación narrativa. El script limita la puntuación a Media; el paso de confirmación narrativa WebSearch de Claude puede elevarla a Alta.
4. Liderazgo de Acciones: Evidencia opcional de escaneos diarios de hits de 5D+20%, EP9M, expansión de rango, nuevos máximos y acciones de alto RS. Cuando se proporciona, se integra en el Calor del Tema v2; cuando está ausente, reduce la cobertura de la confianza pero no fuerza el liderazgo a cero.
5. Calidad de Coincidencia Temática: Especificidad de la coincidencia del tema en función de la participación de la industria, los aciertos explícitos en la canasta de acciones, la confirmación de ETF proxy y las puntuaciones narrativas offline opcionales. Esto es calidad de evidencia, no una recomendación de negociación.

Características Clave:

• Detección de temas intersectoriales utilizando datos de industria de FINVIZ
• Puntuación con conciencia de dirección (temas alcistas y bajistas)
• Evaluación de la madurez del ciclo de vida para identificar operaciones saturadas vs. emergentes
• Puntuación de proliferación de ETF (más ETF = tema más maduro/saturado)
• Integración con el panel de control de uptrend para evaluación en 3 puntos
• Evidencia de liderazgo a nivel de acciones mediante --scan-hits
• Calidad de coincidencia temática mediante canastas de acciones explícitas y confirmación de ETF proxy
• Evidencia de candidatos líderes clasificados por movimiento anormal/volumen/rango/métricas de RS, con capitalización de mercado mostrada solo como un grupo de riesgo
• Historial de temas y métricas de aceleración mediante --history-file
• Modo de operación dual: FINVIZ Elite (rápido) o scraping público (más lento, limitado)
• Confirmación narrativa basada en WebSearch para los temas principales

---

Cuándo Usar Esta Habilidad

Disparadores Explícitos:

• "¿Qué temas del mercado están en tendencia ahora mismo?"
• "¿Qué sectores están calientes/fríos?"
• "Detectar temas actuales del mercado"
• "¿Cuáles son las narrativas alcistas/bajistas más fuertes?"
• "¿Sigue siendo la IA/energía limpia/defensa un tema fuerte?"
• "¿Hacia dónde se dirige la rotación sectorial?"
• "Muéstrame oportunidades de inversión temática"

Disparadores Implícitos:

• El usuario quiere comprender los cambios amplios en la narrativa del mercado
• El usuario busca ideas de ETF temáticos o asignación sectorial
• El usuario pregunta sobre operaciones saturadas o temas de ciclo tardío
• El usuario quiere saber qué temas están emergiendo vs. agotados

Cuándo NO Usar:

• Análisis de acciones individuales (usar us-stock-analysis en su lugar)
• Inmersión profunda en un sector específico con lectura de gráficos (usar sector-analyst en su lugar)
• Reequilibrio de cartera (usar portfolio-manager en su lugar)
• Inversión en dividendos/ingresos (usar value-dividend-screener en su lugar)

---

Requisitos Previos

Requeridos:

• Python 3.9+ con dependencias principales.

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

Solución temporal / Python mixto: Si el python3 activo es anterior a 3.10, o un Hermes venv más nuevo carece de las dependencias de ciencia de datos, ejecute el detector a través de uv con un intérprete moderno explícito y dependencias temporales en lugar de editar el entorno durante el 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 esto como una solución temporal de configuración, no como evidencia de que el detector está roto; informe cualquier problema con los datos de FINVIZ/FMP/API por separado.

Claves API Opcionales:

FINVIZ Elite (recomendado para cobertura completa de industria y velocidad):

export FINVIZ_API_KEY=su_clave_api_finviz_elite_aqui

FMP API (opcional, para datos de valoración de ratio P/E):

export FMP_API_KEY=su_clave_api_fmp_aqui

Los requisitos incluyen finvizfinance, PyYAML, pandas/numpy, requests y yfinance porque la ejecución en modo público normal importa o utiliza cada uno de ellos.

Sin FINVIZ Elite, la habilidad utiliza scraping público de FINVIZ (limitado a ~20 acciones por industria, límites de tasa más lentos).

---

Flujo de Trabajo

Paso 1: Verificar el Entorno

Compruebe que las claves API estén configuradas (consulte Requisitos Previos):

# Verificar la clave API de FINVIZ Elite (opcional pero recomendada)
echo $FINVIZ_API_KEY

# Verificar la clave API de FMP (opcional)
echo $FMP_API_KEY

Paso 2: Ejecutar el Script de Detección de Temas

Ejecute el script de detección principal:

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

Opciones del Script:

# Ejecución completa (modo FINVIZ público, no se requiere clave API)
python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

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

# Con clave API de FMP para datos mejorados de acciones
python3 skills/theme-detector/scripts/theme_detector.py \
  --fmp-api-key $FMP_API_KEY \
  --output-dir reports/

# Límites 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/

# Añadir evidencia de liderazgo al 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 acepta JSON, JSONL o CSV. Las filas pueden estar preetiquetadas con scan_type / scan_types, o filas sin procesar con campos como symbol, return_5d, change_pct, volume, avg_volume_50d, relative_volume, true_range, atr_20, atr_expansion, close_location, industry, sector y theme_guess. Una fila sin procesar puede expandirse en múltiples hits cuando cumple múltiples reglas.

Reglas de escaneo inicial:

• five_day_20pct: return_5d >= 20
• ep9m: volume >= 9,000,000, relative_volume >= 2.0 y change_pct >= 4
• range_expansion: change_pct >= 4, true_range / atr_20 >= 1.5 o atr_expansion >= 1.5, y close_location >= 0.75
• new_high: new_high / is_new_high explícito, o evidencia de máximo de 52 semanas
• high_rs: rs_rating >= 90 o relative_strength >= 0.90 normalizado

Contrato de entrada de narrative-score: --narrative-scores es una entrada JSON offline, no una llamada WebSearch en vivo. Acepta {"Nombre del Tema": 82} o {"themes": {"Nombre del Tema": {"narrative_keyword_score": 82}}}. La falta de entrada narrativa deja narrative_keyword_score como null y reduce theme_match_coverage; no falla la ejecución.

Tiempo de Ejecución Esperado:

• Modo FINVIZ Elite: ~2-3 minutos (14+ temas)
• Modo FINVIZ público: ~5-8 minutos (scraping con límite de tasa)

Paso 3: Leer y Analizar los Resultados de la Detección

El script genera dos archivos de salida:

• theme_detector_YYYY-MM-DD_HHMMSS.json - Datos estructurados para uso programático
• theme_detector_YYYY-MM-DD_HHMMSS.md - Informe legible para humanos

Lea la salida JSON para comprender los resultados cuantitativos:

# Buscar el informe más reciente
ls -lt reports/theme_detector_*.json | head -1

# Leer la salida JSON
cat reports/theme_detector_YYYY-MM-DD_HHMMSS.json

Paso 4: Realizar Confirmación Narrativa mediante WebSearch

Para los 5 temas principales (por puntuación de Calor del Tema), ejecute consultas de WebSearch para confirmar la fuerza narrativa:

Patrón de Búsqueda:

"[nombre del tema] acciones mercado [mes actual] [año actual]"
"[nombre del tema] sector momento [mes actual] [año actual]"

Evaluar señales narrativas:

• Narrativa fuerte: Múltiples medios importantes cubriendo el tema, mejoras de analistas, catalizadores políticos
• Narrativa moderada: Cierta cobertura, sentimiento mixto, sin catalizador claro
• Narrativa débil: Poca cobertura, o tono predominantemente contrario/eséptico

Actualice los niveles de Confianza según los hallazgos:

• Cuantitativo Alto + Narrativa Fuerte = Alta confianza
• Cuantitativo Alto + Narrativa Débil = Media confianza (posible divergencia de momento)
• Cuantitativo Bajo + Narrativa Fuerte = Media confianza (la narrativa puede adelantarse al precio)
• Cuantitativo Bajo + Narrativa Débil = Baja confianza

Paso 5: Analizar Resultados y Proporcionar Recomendaciones

Cruce los resultados de la detección con las bases de conocimiento:

Documentos de Referencia a Consultar:

1. references/cross_sector_themes.md - Definiciones de temas e industrias constituyentes
2. references/thematic_etf_catalog.md - Opciones de exposición a ETF por tema
3. references/theme_detection_methodology.md - Detalles del modelo de puntuación
4. references/finviz_industry_codes.md - Referencia de clasificación industrial

Marco de Análisis:

Para Temas Alcisitas Calientes (Calor >= 70, Dirección = Alcista):

• Identificar la etapa del ciclo de vida (Emergente = oportunidad, Maduro/Agotado = precaución)
• Listar las industrias con mejor rendimiento dentro del tema
• Recomendar ETF proxy para exposición
• Señalar si la proliferación de ETF es alta (advertencia de operación saturada)

Para Temas Bajistas Calientes (Calor >= 70, Dirección = Bajista):

• Identificar industrias bajo presión
• Evaluar si el momento bajista se está acelerando o desacelerando
• Recomendar estrategias de cobertura o sectores a evitar
• Notar posibles oportunidades de reversión a la media si el ciclo de vida es Maduro/Agotado

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

• Estos pueden representar señales tempranas de rotación
• Recomendar monitoreo con lista de seguimiento
• Identificar eventos catalizadores que podrían acelerar el tema

Para Temas Agotados (Calor >= 60, Ciclo de Vida = Agotado):

• Advertir sobre el riesgo de operación saturada
• El alto recuento de ETF confirma la participación minorista excesiva
• Considerar posicionamiento contrario o reducir exposición

Paso 6: Generar Informe Final

Presente el informe final al usuario utilizando la estructura de plantilla de informe:

# Informe de Detección de Temas
**Fecha:** AAAA-MM-DD
**Modo:** FINVIZ Elite / Público
**Temas Analizados:** N
**Calidad de Datos:** [nota sobre limitaciones]

## Panel de Temas
[Tabla de temas principales con Calor, Dirección, Ciclo de Vida, Confianza]

## Lo que Cambió Hoy
[Temas recién emergentes, mayor aceleración de calor, nuevos grupos EP9M, temas en desvanecimiento]

## Evidencia de Liderazgo
[Contadores de 5D+20%, EP9M, expansión de rango, nuevos máximos, alto RS y símbolos de líderes]

## Detalle de Temas Alcisitas
[Análisis detallado de temas alcistas ordenados por Calor]

## Detalle de Temas Bajistas
[Análisis detallado de temas bajistas ordenados por Calor]

## Resumen de Todos los Temas
[Tabla de clasificación completa de temas]

## Clasificaciones de Industria
[Industrias con mejor y peor rendimiento]

## Ratios de Tendencia Alcista por Sector
[Agregación a nivel de sector si hay datos de uptrend disponibles]

## Notas de Metodología
[Breve explicación del modelo de puntuación]

Guarde el informe en el directorio reports/.

---

Salida

La habilidad genera dos archivos de salida en el directorio reports/:

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

Informe Markdown (theme_detector_YYYY-MM-DD_HHMMSS.md):

• Panel de Temas con clasificaciones ordenables
• Secciones de detalle de temas Alcisitas/Bajistas
• Clasificaciones de rendimiento de industria
• Resumen de ratio de tendencia alcista por sector
• Notas de metodología

Campos Clave de Salida (por tema):

Campo	Descripción
heat	Fuerza del tema independiente de la dirección (0-100)
direction	"bullish" (LIDER) o "bearish" (RETRASO)
stage	Emergente / Acelerando / En Tendencia / Maduro / Agotado
confidence	Baja / Media / Alta (el script limita a Media; WebSearch puede elevar)
representative_stocks	Principales símbolos de cotización para el tema
stock_details	Objetos opcionales de métricas de acciones para los representantes seleccionados
proxy_etfs	Símbolos de ETF temáticos (longitud = recuento de ETF; más alto = tema más saturado)
theme_match_score	Puntuación de calidad de coincidencia temática (0-100)
leader_candidates	Lista de candidatos a líder con puntuación, tipos de escaneo y grupo de riesgo