trading-platform/docs/02-definicion-modulos/OQI-006-ml-signals/implementacion/PLAN-ENHANCED-RANGE-PREDICTOR.md

PLAN DE EJECUCION: ML-ENHANCED-001 - Enhanced Range Predictor

Agente: ML-Specialist-Agent + Trading-Strategist Tipo de tarea: Feature Prioridad: P0 Fecha creacion: 2026-01-05 Relacionado con: [RF-ML-001], [RF-ML-004], [ET-ML-002], [ET-ML-003]

---

VERIFICACION DE CATALOGO

OBLIGATORIO: Verificar @CATALOG_INDEX antes de implementar
Comando: grep -i "range-predictor" shared/catalog/CATALOG-INDEX.yml

Funcionalidades a verificar:

Funcionalidad	Aplica?	Catalogo	Accion
auth/login	No	@CATALOG_AUTH	N/A
sesiones	No	@CATALOG_SESSION	N/A
rate-limit	No	@CATALOG_RATELIMIT	N/A
notificaciones	No	@CATALOG_NOTIFY	N/A
multi-tenant	No	@CATALOG_TENANT	N/A
feature-flags	No	@CATALOG_FLAGS	N/A
websocket	No	@CATALOG_WS	N/A
pagos	No	@CATALOG_PAYMENTS	N/A

Resultado: No aplica catalogo - Modulos ML especificos del proyecto

---

OBJETIVO

Implementar un sistema mejorado de prediccion de rangos de precio basado en:

• Factor de volatilidad como unidad base (5 USD para XAUUSD)
• Atencion por sesion de trading y volatilidad
• Ensemble dual de horizontes (5 anos largo plazo + 3 meses corto plazo)
• Filtrado por ratio R:R minimo 2:1

Criterios de Aceptacion:

• Predicciones en multiplos del factor base (no USD absolutos)
• Targets calculados con formula corregida: MAX/MIN de horizon
• Pesos de muestra basados en magnitud de movimiento
• Pesos por sesion: London/NY overlap > London > NY > Tokyo > off-hours
• Pesos por volatilidad: Alta ATR > Normal > Baja (lateral)
• Modelo dual: largo plazo (patrones estructurales) + corto plazo (adaptacion)
• Filtro R:R ratio minimo 2:1 para oportunidades validas
• Script de entrenamiento CLI completo

---

ANALISIS PREVIO

Contexto

• El RangePredictor existente predice en USD absolutos
• No considera diferencias por sesion de trading ni volatilidad
• No distingue entre movimientos laterales y trending
• Usa un solo modelo sin adaptacion temporal

Estado Actual (Pre-implementacion)

• RangePredictor en models/range_predictor_factor.py - parcialmente implementado
• MovementMagnitudePredictor - problemas de rendimiento
• TPSLClassifier - accuracy 68%
• Sin ponderacion por sesion ni volatilidad

Problema Resuelto

• Predicciones mas precisas enfocadas en oportunidades de alto valor
• Menor ruido de mercados laterales
• Adaptacion a regimen actual del mercado
• Senales con ratio R:R favorable (minimo 2:1)

Anti-Duplicacion

# Comandos ejecutados para verificar no-duplicacion
grep -rn "sample_weighting" apps/ml-engine/src/
grep -rn "session_volatility" apps/ml-engine/src/
grep -rn "dual_horizon" apps/ml-engine/src/

# Resultado: No existe - Modulos nuevos

---

DISENO DE SOLUCION

Approach Seleccionado

Sistema modular con 5 componentes independientes que se integran en un predictor unificado.

Alternativas consideradas:

1. Modificar RangePredictor existente - Descartado por alta complejidad y riesgo de regresion
2. Modelo unico con todas las features - Descartado por dificultad de mantenimiento

Componentes Creados

ML Engine - Data:

• corrected_targets.py - Calculo de targets con formula corregida

ML Engine - Training:

• sample_weighting.py - Ponderacion por magnitud de movimiento
• session_volatility_weighting.py - Ponderacion por sesion y ATR

ML Engine - Models:

• dual_horizon_ensemble.py - Ensemble de modelos largo/corto plazo
• enhanced_range_predictor.py - Integrador principal

ML Engine - Scripts:

• train_enhanced_model.py - Script CLI de entrenamiento

---

CICLOS DE EJECUCION

Ciclo 1: Modulos de Ponderacion

Duracion estimada: 2 horas Objetivo: Crear sistema de pesos para muestras de entrenamiento

Tareas:

1. Implementar SampleWeighter con ponderacion por magnitud
2. Implementar SessionVolatilityWeighter con pesos por sesion
3. Crear features de sesion (hour_sin, hour_cos, etc.)

Artefactos generados:

• apps/ml-engine/src/training/sample_weighting.py
• apps/ml-engine/src/training/session_volatility_weighting.py

Validacion:

cd apps/ml-engine
python -m src.training.sample_weighting
python -m src.training.session_volatility_weighting

Criterios de exito:

• Tests de modulo ejecutan sin errores
• Distribucion de pesos correcta por sesion

---

Ciclo 2: Targets Corregidos

Duracion estimada: 1 hora Objetivo: Implementar formula de targets correcta

Tareas:

1. Implementar CorrectedTargetBuilder
2. Formula: target_high = MAX(high[t+1:t+H]) - close[t]
3. Formula: target_low = close[t] - MIN(low[t+1:t+H])
4. Calculo de R:R ratios

Artefactos generados:

• apps/ml-engine/src/data/corrected_targets.py

Validacion:

cd apps/ml-engine
python -m src.data.corrected_targets

Criterios de exito:

• Targets siempre no-negativos
• R:R ratios calculados correctamente

---

Ciclo 3: Ensemble Dual Horizon

Duracion estimada: 2 horas Objetivo: Crear modelo ensemble con dos horizontes temporales

Tareas:

1. Modelo largo plazo (5 anos): patrones estructurales
2. Modelo corto plazo (3 meses): adaptacion a regimen actual
3. Ajuste dinamico de pesos por rendimiento
4. Reentrenamiento periodico del modelo corto

Artefactos generados:

• apps/ml-engine/src/models/dual_horizon_ensemble.py

Validacion:

cd apps/ml-engine
python -m src.models.dual_horizon_ensemble

Criterios de exito:

• Ambos modelos entrenan correctamente
• Pesos se ajustan dinamicamente
• Serialización/deserializacion funciona

---

Ciclo 4: Predictor Integrado

Duracion estimada: 2 horas Objetivo: Integrar todos los componentes

Tareas:

1. EnhancedRangePredictor integrando todos los modulos
2. Pipeline: OHLCV -> Targets -> Features -> Weights -> Ensemble -> Prediccion
3. get_trading_signal() con entry/TP/SL
4. Confianza basada en acuerdo entre modelos

Artefactos generados:

• apps/ml-engine/src/models/enhanced_range_predictor.py

Validacion:

cd apps/ml-engine
python -m src.models.enhanced_range_predictor

Criterios de exito:

• Pipeline completo funciona
• Predicciones en multiplos del factor
• Senales de trading generadas

---

Ciclo 5: Script de Entrenamiento

Duracion estimada: 1 hora Objetivo: CLI para entrenamiento y validacion

Tareas:

1. Argumentos CLI (--symbol, --timeframe, --base-factor, etc.)
2. Walk-forward validation
3. Generacion de reporte en Markdown
4. Guardado de modelo

Artefactos generados:

• apps/ml-engine/scripts/train_enhanced_model.py

Validacion:

python scripts/train_enhanced_model.py --help
python scripts/train_enhanced_model.py --symbol XAUUSD --timeframe 15m --validate

Criterios de exito:

• CLI funcional con todos los argumentos
• Reporte generado correctamente
• Modelo guardado y cargable

---

Ciclo 6: Documentacion

Duracion estimada: 1 hora Objetivo: Documentar segun estandares

Tareas:

1. Este documento PLAN
2. Especificacion tecnica ET-ML-006
3. Actualizar _MAP.md de OQI-006
4. Actualizar inventarios si aplica

Artefactos generados:

• docs/.../PLAN-ENHANCED-RANGE-PREDICTOR.md
• docs/.../ET-ML-006-enhanced-range-predictor.md

Validacion:

• Documentos siguen templates estandar
• Referencias actualizadas

---

DEPENDENCIAS

Depende de:

• [OQI-006]: Arquitectura ML existente
• [RF-ML-001]: Prediccion de precios

Bloquea:

• [OQI-007]: LLM Agent puede usar estas predicciones mejoradas

Requerimientos externos:

• Datos historicos OHLCV (5 anos para modelo largo plazo)
• XGBoost >= 2.0
• Python >= 3.11

---

RIESGOS IDENTIFICADOS

Riesgo	Probabilidad	Impacto	Mitigacion
Datos insuficientes para 5 anos	Media	Alto	Usar datos disponibles, ajustar horizon
Overfitting modelo corto plazo	Media	Medio	Regularizacion, depth bajo, retrain periodico
Pesos extremos en sesiones	Baja	Medio	Normalizacion a media=1
Performance lenta en prediccion	Baja	Medio	Modelos optimizados, cache

---

ESTIMACIONES

Tiempo total estimado: 10 horas

Desglose:

• Analisis: 1h
• Desarrollo: 7h
• Testing: 1h
• Documentacion: 1h
• Buffer (15%): 1.5h

Recursos necesarios:

• Agentes: ML-Specialist, Trading-Strategist
• Herramientas: Python, XGBoost, Pandas

---

DOCUMENTACION GENERADA

Durante ejecucion:

• Codigo documentado con docstrings
• Comentarios inline en secciones complejas

Post-ejecucion:

• PLAN-ENHANCED-RANGE-PREDICTOR.md (este documento)
• ET-ML-006-enhanced-range-predictor.md
• Actualizacion de _MAP.md
• Reporte de entrenamiento (generado por script)

---

CRITERIOS DE EXITO

La tarea se considera COMPLETADA cuando:

• Todos los ciclos ejecutados exitosamente
• 6 modulos creados y funcionales
• Documentacion completa segun estandares
• Inventarios actualizados
• Sin errores de ejecucion
• Tests de modulo pasan
• Cumple estandares de codigo

---

ARCHIVOS CREADOS

Archivo	Tipo	Lineas	Proposito
src/training/sample_weighting.py	Python	345	Ponderacion por magnitud
src/training/session_volatility_weighting.py	Python	422	Ponderacion por sesion/ATR
src/data/corrected_targets.py	Python	441	Targets con formula corregida
src/models/dual_horizon_ensemble.py	Python	452	Ensemble largo/corto plazo
src/models/enhanced_range_predictor.py	Python	510	Integrador principal
scripts/train_enhanced_model.py	Python	380	CLI de entrenamiento

Total: ~2,550 lineas de codigo

---

ARCHIVOS MODIFICADOS (Integracion v2.0)

Archivo	Cambios	Proposito
src/models/range_predictor.py	+80 lineas	Integracion sample/session weighting
src/models/movement_magnitude_predictor.py	+90 lineas	Integracion sample/session weighting
src/models/amd_detector_ml.py	+100 lineas	Integracion sample/session weighting

Cambios en modelos existentes:

• Import de modulos de weighting con fallback graceful
• Nuevos parametros: use_sample_weighting, use_session_weighting
• Metodo compute_sample_weights() para calculo combinado
• Modificacion de fit()/train() para usar sample_weight en XGBoost

Total adicional: ~270 lineas de codigo

---

REFERENCIAS

Documentacion del proyecto:

• RF-ML-001: docs/02-definicion-modulos/OQI-006-ml-signals/requerimientos/RF-ML-001-predicciones.md
• ET-ML-002: docs/02-definicion-modulos/OQI-006-ml-signals/especificaciones/ET-ML-002-modelos.md
• Vision: docs/00-vision-general/VISION-PRODUCTO.md

Templates usados:

• TEMPLATE-PLAN.md: orchestration/templates/TEMPLATE-PLAN.md

---

Version: 1.0 Ultima actualizacion: 2026-01-05 Estado: Completado