# 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:**
- [x] Predicciones en multiplos del factor base (no USD absolutos)
- [x] Targets calculados con formula corregida: MAX/MIN de horizon
- [x] Pesos de muestra basados en magnitud de movimiento
- [x] Pesos por sesion: London/NY overlap > London > NY > Tokyo > off-hours
- [x] Pesos por volatilidad: Alta ATR > Normal > Baja (lateral)
- [x] Modelo dual: largo plazo (patrones estructurales) + corto plazo (adaptacion)
- [x] Filtro R:R ratio minimo 2:1 para oportunidades validas
- [x] 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
```bash
# 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:**
- [x] `corrected_targets.py` - Calculo de targets con formula corregida

**ML Engine - Training:**
- [x] `sample_weighting.py` - Ponderacion por magnitud de movimiento
- [x] `session_volatility_weighting.py` - Ponderacion por sesion y ATR

**ML Engine - Models:**
- [x] `dual_horizon_ensemble.py` - Ensemble de modelos largo/corto plazo
- [x] `enhanced_range_predictor.py` - Integrador principal

**ML Engine - Scripts:**
- [x] `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:**
```bash
cd apps/ml-engine
python -m src.training.sample_weighting
python -m src.training.session_volatility_weighting
```

**Criterios de exito:**
- [x] Tests de modulo ejecutan sin errores
- [x] 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:**
```bash
cd apps/ml-engine
python -m src.data.corrected_targets
```

**Criterios de exito:**
- [x] Targets siempre no-negativos
- [x] 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:**
```bash
cd apps/ml-engine
python -m src.models.dual_horizon_ensemble
```

**Criterios de exito:**
- [x] Ambos modelos entrenan correctamente
- [x] Pesos se ajustan dinamicamente
- [x] 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:**
```bash
cd apps/ml-engine
python -m src.models.enhanced_range_predictor
```

**Criterios de exito:**
- [x] Pipeline completo funciona
- [x] Predicciones en multiplos del factor
- [x] 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:**
```bash
python scripts/train_enhanced_model.py --help
python scripts/train_enhanced_model.py --symbol XAUUSD --timeframe 15m --validate
```

**Criterios de exito:**
- [x] CLI funcional con todos los argumentos
- [x] Reporte generado correctamente
- [x] 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:**
- [x] Documentos siguen templates estandar
- [x] 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:**
- [x] Codigo documentado con docstrings
- [x] Comentarios inline en secciones complejas

**Post-ejecucion:**
- [x] PLAN-ENHANCED-RANGE-PREDICTOR.md (este documento)
- [x] 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:

- [x] Todos los ciclos ejecutados exitosamente
- [x] 6 modulos creados y funcionales
- [x] Documentacion completa segun estandares
- [ ] Inventarios actualizados
- [x] Sin errores de ejecucion
- [x] Tests de modulo pasan
- [x] 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