trading-platform/docs/02-definicion-modulos/OQI-006-ml-signals/especificaciones/ET-ML-006-enhanced-range-predictor.md

id	title	type	epic	project	priority	status	created_date	updated_date	author
ET-ML-006	Enhanced Range Predictor	Especificacion Tecnica	OQI-006	trading-platform	P0	Implementado	2026-01-05	2026-01-05	ML-Specialist + Trading-Strategist

ET-ML-006: Enhanced Range Predictor

Resumen Ejecutivo

Sistema mejorado de prediccion de rangos de precio que utiliza:

• Factor de volatilidad como unidad base de prediccion
• Atencion diferenciada por sesion de trading y volatilidad
• Ensemble dual con modelo largo plazo (5 anos) y corto plazo (3 meses)
• Filtrado por ratio R:R minimo 2:1

---

Arquitectura

Diagrama de Componentes

                    +------------------+
                    |   OHLCV Data     |
                    +--------+---------+
                             |
              +--------------+--------------+
              |                             |
    +---------v---------+        +----------v----------+
    | CorrectedTargets  |        |  FeatureGenerator   |
    | (corrected_       |        |  (generate_         |
    |  targets.py)      |        |   features)         |
    +---------+---------+        +----------+----------+
              |                             |
              +-------------+---------------+
                            |
              +-------------v--------------+
              |      Sample Weighting      |
              |  +----------------------+  |
              |  | SampleWeighter       |  |
              |  | (movement magnitude) |  |
              |  +----------------------+  |
              |  | SessionVolatility    |  |
              |  | Weighter (session +  |  |
              |  | ATR weights)         |  |
              |  +----------------------+  |
              +-------------+--------------+
                            |
              +-------------v--------------+
              |   DualHorizonEnsemble      |
              |  +----------------------+  |
              |  | Long-term (5 years)  |  |
              |  | - XGBoost High       |  |
              |  | - XGBoost Low        |  |
              |  +----------------------+  |
              |  | Short-term (3 months)|  |
              |  | - XGBoost High       |  |
              |  | - XGBoost Low        |  |
              |  +----------------------+  |
              |  | Dynamic Weights      |  |
              |  | (performance-based)  |  |
              |  +----------------------+  |
              +-------------+--------------+
                            |
              +-------------v--------------+
              |  EnhancedRangePredictor    |
              |  - predict_single()        |
              |  - predict_batch()         |
              |  - get_trading_signal()    |
              +----------------------------+

---

Modulos Implementados

1. corrected_targets.py

Ubicacion: apps/ml-engine/src/data/corrected_targets.py

Proposito: Calcular targets de prediccion con formula corregida.

Formula:

target_high = MAX(high[t+1], high[t+2], ..., high[t+H]) - close[t]
target_low  = close[t] - MIN(low[t+1], low[t+2], ..., low[t+H])

Donde H = horizon_bars (default: 3)

Clases principales:

Clase	Proposito
CorrectedTargetConfig	Configuracion de horizonte, umbrales, factor base
CorrectedTargetBuilder	Constructor de targets
TargetResult	Resultado con arrays de targets y metricas

Configuracion:

CorrectedTargetConfig(
    horizon_bars=3,          # Horizonte en barras
    start_offset=1,          # Offset desde barra actual
    min_movement_usd=5.0,    # Movimiento minimo para validez
    normalize_by_atr=True,   # Normalizar por ATR
    min_rr_ratio=2.0,        # R:R minimo
    base_factor=5.0          # Factor base en USD
)

Outputs:

• target_high_usd: Target alto en USD
• target_low_usd: Target bajo en USD
• target_high_mult: Target alto en multiplos del factor
• target_low_mult: Target bajo en multiplos del factor
• rr_long, rr_short, rr_best: Ratios R:R
• direction: 1 (LONG), -1 (SHORT), 0 (NEUTRAL)
• is_valid: Mascara de muestras validas

---

2. sample_weighting.py

Ubicacion: apps/ml-engine/src/training/sample_weighting.py

Proposito: Ponderar muestras por magnitud de movimiento.

Clases principales:

Clase	Proposito
SampleWeightConfig	Configuracion de pesos
SampleWeighter	Calculador de pesos por movimiento

Configuracion:

SampleWeightConfig(
    min_movement_threshold=5.0,   # Umbral en USD
    large_movement_weight=3.0,    # Peso para movimientos grandes
    small_movement_weight=0.3,    # Peso para movimientos pequenos
    use_continuous_weighting=True,# Ponderacion continua
    weight_exponent=1.5,          # Exponente para peso continuo
    min_rr_ratio=2.0,             # R:R minimo
    min_weight=0.1,               # Peso minimo
    max_weight=10.0               # Peso maximo
)

Estrategia de ponderacion continua:

weight = (movement / threshold) ^ exponent

---

3. session_volatility_weighting.py

Ubicacion: apps/ml-engine/src/training/session_volatility_weighting.py

Proposito: Ponderar muestras por sesion de trading y volatilidad.

Sesiones de trading (UTC):

Sesion	Horas UTC	Peso
London/NY Overlap	13:00-16:00	2.0
London	08:00-16:00	1.5
New York	13:00-21:00	1.3
Tokyo/Asian	00:00-08:00	0.7
Off-hours	Resto	0.3

Ponderacion por ATR:

Condicion	Peso
ATR > Percentil 75 (alta volatilidad)	1.5
ATR < Percentil 25 (lateral/consolidacion)	0.3
Normal	1.0

Features de sesion generadas:

• is_london_session, is_ny_session, is_tokyo_session, is_overlap_session
• hour_sin, hour_cos (encoding ciclico)
• dow_sin, dow_cos (dia de semana ciclico)
• london_progress, ny_progress (progreso dentro de sesion)
• is_midweek, is_monday, is_friday

---

4. dual_horizon_ensemble.py

Ubicacion: apps/ml-engine/src/models/dual_horizon_ensemble.py

Proposito: Ensemble de dos modelos con diferentes horizontes temporales.

Arquitectura:

Modelo	Datos	Patrones	Parametros XGBoost
Largo plazo	5 anos	Estructurales, estacionalidad	depth=8, n_estimators=300, lr=0.05
Corto plazo	3 meses	Regimen actual, adaptacion	depth=5, n_estimators=150, lr=0.08

Pesos dinamicos:

• Inicial: 60% largo plazo, 40% corto plazo
• Se ajustan basado en MAE reciente
• Rango: [0.2, 0.8] para cada modelo

Reentrenamiento:

• Modelo corto plazo: cada 7 dias (configurable)
• Modelo largo plazo: manual/periodico

Configuracion:

DualHorizonConfig(
    long_term_years=5.0,
    short_term_months=3.0,
    initial_long_weight=0.6,
    initial_short_weight=0.4,
    use_dynamic_weights=True,
    weight_adjustment_lookback=100,
    weight_adjustment_rate=0.1,
    min_weight=0.2,
    max_weight=0.8,
    retrain_frequency_days=7
)

---

5. enhanced_range_predictor.py

Ubicacion: apps/ml-engine/src/models/enhanced_range_predictor.py

Proposito: Integrador principal que combina todos los componentes.

Pipeline:

OHLCV -> CorrectedTargets -> FeatureGeneration ->
       -> CombinedWeights -> DualHorizonEnsemble -> Prediction

Metodos principales:

Metodo	Proposito
fit(df_ohlcv, df_features)	Entrenar modelo completo
predict_single(features)	Prediccion individual
predict_batch(features)	Predicciones en lote
get_trading_signal(features, price)	Senal con entry/TP/SL
update_with_result()	Actualizar tracking de performance
retrain_short_term()	Reentrenar modelo corto plazo

Output de get_trading_signal():

{
    'action': 'LONG' | 'SHORT' | 'WAIT',
    'entry': 2650.00,
    'take_profit': 2660.00,
    'stop_loss': 2645.00,
    'rr_ratio': 2.5,
    'confidence': 0.75,
    'pred_high_usd': 10.0,
    'pred_low_usd': 5.0,
    'model_weights': {'long_term': 0.6, 'short_term': 0.4}
}

---

6. train_enhanced_model.py

Ubicacion: apps/ml-engine/scripts/train_enhanced_model.py

Proposito: Script CLI para entrenamiento y validacion.

Uso:

# Entrenamiento basico
python train_enhanced_model.py \
    --symbol XAUUSD \
    --timeframe 15m \
    --data-path data/ \
    --base-factor 5.0 \
    --horizon-bars 3

# Con validacion walk-forward
python train_enhanced_model.py \
    --symbol XAUUSD \
    --timeframe 15m \
    --validate \
    --n-splits 5

# Ver ayuda
python train_enhanced_model.py --help

Argumentos:

Argumento	Default	Descripcion
--symbol	XAUUSD	Simbolo de trading
--timeframe	15m	Timeframe de entrada
--data-path	data/	Directorio de datos
--output-path	models/	Directorio de salida
--base-factor	5.0	Factor de volatilidad en USD
--horizon-bars	3	Barras de horizonte
--min-rr	2.0	R:R minimo
--validate	False	Ejecutar validacion walk-forward
--n-splits	5	Numero de splits para validacion

Outputs:

• Modelo serializado en {output-path}/{symbol}_{timeframe}_enhanced/
• Reporte Markdown en {output-path}/training_report_{timestamp}.md
• Logs en {output-path}/logs/

---

Features Generadas

El script genera ~40 features automaticamente:

Retornos

• returns_1, returns_5, returns_15

Volatilidad

• volatility_5, volatility_20
• atr_14, atr_ratio
• range, range_pct, range_ma_5, range_ma_20, range_ratio

Medias Moviles

• price_vs_sma5, price_vs_sma20, sma5_vs_sma20

Indicadores Tecnicos

• rsi_14
• macd, macd_signal, macd_hist
• bb_width, bb_position
• momentum_5, momentum_10, momentum_20

Patrones de Vela

• body, body_pct
• upper_shadow, lower_shadow

Volumen (si disponible)

• volume_ratio

Posicion Relativa

• close_vs_high5
• adx_proxy

Features de Sesion

• is_london_session, is_ny_session, is_tokyo_session, is_overlap_session
• hour_sin, hour_cos, dow_sin, dow_cos
• london_progress, ny_progress
• is_midweek, is_monday, is_friday

---

Validacion Walk-Forward

El sistema incluye validacion walk-forward para evaluar robustez:

|--- Train 1 ---|--- Test 1 ---|
     |--- Train 2 ---|--- Test 2 ---|
          |--- Train 3 ---|--- Test 3 ---|
               ...

Metricas evaluadas:

• Numero de senales LONG/SHORT generadas
• Confianza promedio
• R:R ratio promedio
• Precision por split

---

Integracion

Con LLM Agent (OQI-007)

from models.enhanced_range_predictor import EnhancedRangePredictor

predictor = EnhancedRangePredictor.load('models/XAUUSD_15m_enhanced')
signal = predictor.get_trading_signal(features, current_price)

if signal['action'] != 'WAIT' and signal['confidence'] > 0.7:
    llm_context = f"""
    Senal ML: {signal['action']}
    Entry: {signal['entry']}, TP: {signal['take_profit']}, SL: {signal['stop_loss']}
    R:R: {signal['rr_ratio']:.1f}, Confianza: {signal['confidence']:.0%}
    """

Con Trading Agents

# En Atlas/Orion/Nova agent
signal = predictor.get_trading_signal(features, current_price)

if signal['action'] == 'LONG' and signal['rr_ratio'] >= 2.0:
    open_position(
        type='BUY',
        entry=signal['entry'],
        take_profit=signal['take_profit'],
        stop_loss=signal['stop_loss']
    )

---

Requisitos

Dependencias Python

xgboost>=2.0.0
pandas>=2.0.0
numpy>=1.24.0
scikit-learn>=1.3.0
loguru>=0.7.0
joblib>=1.3.0

Datos Requeridos

• Minimo 3 meses de datos OHLCV para modelo corto plazo
• Idealmente 5 anos para modelo largo plazo completo
• Formato: Parquet o CSV con columnas: open, high, low, close, volume

---

Metricas Esperadas

Metrica	Objetivo	Notas
MAE High	< 0.5 mult	En multiplos del factor
MAE Low	< 0.5 mult	En multiplos del factor
Win Rate	> 55%	Con filtro R:R >= 2:1
Senales validas	> 20%	Del total de muestras

---

Mejoras Futuras

1. Mas horizontes temporales: Scalping (6 candles), Swing (36 candles)
2. Features adicionales: Order flow, sentiment, correlaciones
3. Modelos alternativos: LightGBM, CatBoost para ensemble mas diverso
4. Autotuning: Optimizacion automatica de hiperparametros

---

Referencias

• RF-ML-001 - Prediccion de precios
• RF-ML-004 - Pipeline de entrenamiento
• ET-ML-002 - Modelos XGBoost
• ET-ML-003 - Feature engineering
• PLAN - Plan de ejecucion

---

Version: 1.0.0 Estado: Implementado Ultima actualizacion: 2026-01-05