tradermonty/vcp-screener

VCP Screener - Patrón de Contracción de Volatilidad de Minervini

Filtra acciones del S&P 500 para el Patrón de Contracción de Volatilidad (VCP) de Mark Minervini, identificando acciones en tendencia alcista de Etapa 2 con volatilidad contrayéndose cerca de puntos de pivote de ruptura.

Cuándo Usarlo

• El usuario solicita un screener VCP o configuraciones estilo Minervini
• El usuario quiere encontrar patrones de base apretada / contracción de volatilidad
• El usuario solicita escaneo de acciones de impulso en Etapa 2
• El usuario busca candidatos a ruptura con riesgo definido
• El usuario pide "encuentra cada VCP histórica en " o quiere estudiar las configuraciones VCP pasadas de un ticker con resultados futuros (--history --ticker SYM)

Requisitos Previos

• Clave API de FMP (configurar la variable de entorno FMP_API_KEY o pasar --api-key)
• El nivel gratuito (250 llamadas/día) es suficiente para el filtrado predeterminado (top 100 candidatos)
• Se recomienda el nivel de pago para el filtrado completo del S&P 500 (--full-sp500)

Flujo de Trabajo

Paso 1: Preparar y Ejecutar el Filtrado

Ejecuta el script del screener VCP:

# Predeterminado: S&P 500, top 100 candidatos
python3 skills/vcp-screener/scripts/screen_vcp.py --output-dir skills/vcp-screener/scripts

# Universo personalizado
python3 skills/vcp-screener/scripts/screen_vcp.py --universe AAPL NVDA MSFT AMZN META --output-dir skills/vcp-screener/scripts

# S&P 500 completo (nivel de API de pago)
python3 skills/vcp-screener/scripts/screen_vcp.py --full-sp500 --output-dir skills/vcp-screener/scripts

Modo Estricto (configuración pura de Minervini)

Solo devuelve acciones con valid_vcp=True Y execution_state en (Pre-breakout, Breakout):

python3 skills/vcp-screener/scripts/screen_vcp.py --strict --output-dir reports/

Modo histórico de un solo ticker

Recorre el historial de varios años de un ticker, detecta cada VCP que se haya formado y adjunta estadísticas de resultado futuro (ruptura / stop alcanzado / tiempo de espera, días hasta el resultado, ganancia máxima, pérdida máxima) por detección. Útil para estudio de patrones y contexto de backtesting, no es un screener en tiempo real.

# Predeterminado: escanea ~5 años (1260 días de negociación), paso de 5 días, ventana de resultado de 60 días
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history --ticker FIX --output-dir reports/

# Longitud de escaneo personalizada: 750 días de negociación (~3 años), ventana de resultado de 90 días
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history 750 --ticker TSLA \
  --stride-days 5 --outcome-days 90 \
  --output-dir reports/

# Escaneo largo: 10 años (2520 días de negociación)
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history 2520 --ticker NVDA --output-dir reports/

Salidas (con marca de tiempo):

• vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.json — línea de tiempo de detecciones con carga completa del analizador + forward_outcome por detección + estadísticas resumidas.
• vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.md — línea de tiempo legible para humanos.

Banderas específicas del modo:

Parámetro	Predeterminado	Rango	Efecto
--history [DAYS]	(desactivado) / 1260 si está vacío	100-5040	Habilita el modo histórico; opcionalmente especifica la ventana de escaneo en días de negociación (requiere --ticker)
--ticker SYM	—	—	Ticker a escanear
--stride-days	5	1-60	Paso en días de negociación entre posiciones del cursor "a fecha de"
--outcome-days	60	5-252	Ventana futura evaluada por detección

Notas:

• Dos llamadas a la API de FMP por escaneo (historial del ticker + SPY), no 100+ como el pipeline transversal.
• marketCap y percentil absoluto de RS reflejan el ticker de forma aislada, no contra el universo de filtrado en vivo; usa este informe para estudio de patrones, no para dimensionamiento de cartera.
• Las detecciones se deduplican por (T1_high_date, last_low_date, pivot) para que la misma VCP no se reporte repetidamente a medida que el cursor envejece.

Ajuste Avanzado (para backtesting)

Ajusta los parámetros de detección VCP para investigación y backtesting:

python3 skills/vcp-screener/scripts/screen_vcp.py \
  --min-contractions 3 \
  --t1-depth-min 12.0 \
  --breakout-volume-ratio 2.0 \
  --trend-min-score 90 \
  --atr-multiplier 1.5 \
  --output-dir reports/

Parámetro	Predeterminado	Rango	Efecto
--min-contractions	2	2-4	Más alto = menos patrones pero de mayor calidad
--t1-depth-min	10.0%	1-50	Más alto = excluye correcciones iniciales superficiales
--breakout-volume-ratio	1.5x	0.5-10	Más alto = confirmación de volumen más estricta
--trend-min-score	85	0-100	Más alto = filtro de Etapa 2 más estricto
--atr-multiplier	1.5	0.5-5	Más bajo = detección de oscilaciones más sensible
--contraction-ratio	0.70	0.1-1	Más bajo = requiere contracciones más ajustadas
--min-contraction-days	5	1-30	Más alto = duración mínima de contracción más larga
--lookback-days	120	30-365	Más largo = encuentra patrones más antiguos
--max-sma200-extension	50.0%	—	Umbral de distancia SMA200 para estado Sobreextendido y penalización
--wide-and-loose-threshold	15.0%	—	Profundidad de contracción final por encima de la cual se activa la bandera wide-and-loose
--strict	desactivado	—	Modo estricto de Minervini: solo Pre-breakout o Breakout con VCP válido

Paso 2: Revisar Resultados

1. Lee los informes JSON y Markdown generados
2. Carga references/vcp_methodology.md para contexto de interpretación de patrones
3. Carga references/scoring_system.md para orientación sobre umbrales de puntuación

Paso 3: Presentar Análisis

Para cada candidato principal, presenta:

• Calidad (composite_score / calificación) — ¿qué tan bien formado está el patrón VCP?
• Estado de Ejecución (execution_state) — ¿es comprable ahora? (Pre-breakout / Breakout = accionable)
• Tipo de Patrón (pattern_type) — VCP de libro / VCP-adyacente / Post-ruptura / Líder Extendido / Dañado
• Marcador ★ si se aplicó un Límite de Estado (la puntuación bruta fue reducida)
• Detalles de contracción (profundidades y ratios T1/T2/T3)
• Configuración de trading: precio pivote, stop-loss, porcentaje de riesgo
• Ratio de agotamiento de volumen y puntuación de volumen de ruptura
• Rango de fuerza relativa

Paso 4: Proporcionar Orientación Accionable

Por Estado de Ejecución (filtro principal):

• Pre-breakout / Breakout: El patrón está en la ventana de entrada activa — aplica dimensionamiento basado en calificación
• Post-ruptura temprana: La ruptura está en marcha pero por encima de la entrada ideal — tamaño reducido o esperar un retroceso
• Extendido / Sobreextendido: Operación perdida — añadir a la lista de seguimiento para la próxima base
• Dañado / Inválido: Configuración invalidada — no entrar

Por Calificación (secundario, después de que el estado confirme accionabilidad):

• VCP de libro (90+): Comprar en el pivote con dimensionamiento agresivo (1.5-2x)
• VCP fuerte (80-89): Comprar en el pivote con dimensionamiento estándar (1x)
• VCP buena (70-79): Comprar con confirmación de volumen por encima del pivote (0.75x)
• En desarrollo (60-69): Añadir a la lista de seguimiento, esperar una contracción más ajustada
• VCP débil/sin VCP (<60): Solo monitorear o saltar

Pipeline de 3 Fases

1. Pre-Filtro - Filtrado basado en cotizaciones (precio, volumen, posición a 52 semanas) ~101 llamadas API
2. Plantilla de Tendencia - Filtro de Etapa 2 de 7 puntos con historiales de 260 días ~100 llamadas API
3. Detección VCP - Análisis de patrones, puntuación, generación de informes (sin llamadas API adicionales)

Salida

• vcp_screener_YYYY-MM-DD_HHMMSS.json - Resultados estructurados
• vcp_screener_YYYY-MM-DD_HHMMSS.md - Informe legible para humanos

Recursos

• references/vcp_methodology.md - Teoría VCP y explicación de la Plantilla de Tendencia
• references/scoring_system.md - Umbrales de puntuación y pesos de componentes
• references/fmp_api_endpoints.md - Puntos finales de API y límites de tasa