rckrdmrd
a7cca885f0
Changes include: - Updated architecture documentation - Enhanced module definitions (OQI-001 to OQI-008) - ML integration documentation updates - Trading strategies documentation - Orchestration and inventory updates - Docker configuration updates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
384 lines
11 KiB
Markdown
384 lines
11 KiB
Markdown
# 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
|