---
title: "Análisis de Modelos ML - Vuelta 1"
version: "1.1.0"
date: "2026-01-06"
status: "Completed"
author: "ML-Specialist + Orquestador"
epic: "OQI-006"
tags: ["ml", "analysis", "models", "attention", "factors"]
---

# ANÁLISIS DE MODELOS ML - VUELTA 1

## 1. RESUMEN EJECUTIVO

Este documento presenta el análisis detallado de los modelos de Machine Learning existentes en el proyecto trading-platform (Trading Platform), identificando problemas, brechas y proponiendo soluciones para alcanzar el objetivo de **80%+ de acierto** en predicciones de movimientos fuertes con gestión de riesgo **2:1 o 3:1 (TP:SL)**.

### Objetivos del Análisis
1. Redefinir documentación y alcances de cada modelo
2. Implementar sistema de atención con factores dinámicos (ATR-based)
3. Separar modelos por activo y temporalidad (5m, 15m)
4. Diseñar arquitectura de metamodelo
5. Definir APIs y Frontend para visualización

---

## 2. INVENTARIO DE MODELOS EXISTENTES

### 2.1 Modelos de Predicción de Rangos

| Modelo | Archivo | Propósito | Estado |
|--------|---------|-----------|--------|
| `RangePredictor` | `range_predictor.py` | Predice ΔHigh/ΔLow con XGBoost | ✅ Funcional |
| `RangePredictorFactor` | `range_predictor_factor.py` | Predice multiplicadores de factor base | ✅ Funcional |
| `EnhancedRangePredictor` | `enhanced_range_predictor.py` | Integra weighting + dual horizon | ✅ Funcional |
| `MovementMagnitudePredictor` | `movement_magnitude_predictor.py` | Predice movimiento en USD | ✅ Funcional |

### 2.2 Modelos de Atención y Volatilidad

| Modelo | Archivo | Propósito | Estado |
|--------|---------|-----------|--------|
| `VolatilityBiasedSelfAttention` | `volatility_attention.py` | Attention con bias de volatilidad (PyTorch) | ✅ Funcional |
| `VolatilityRangePredictor` | `volatility_attention.py` | Transformer con attention de volatilidad | ✅ Funcional |
| `DynamicFactorWeighter` | `dynamic_factor_weighting.py` | Weighting dinámico con softplus | ✅ Funcional |

### 2.3 Modelos de Estrategia

| Modelo | Archivo | Propósito | Estado |
|--------|---------|-----------|--------|
| `AMDDetector` | `amd_detector.py` | Detecta fases AMD (reglas) | ✅ Funcional |
| `AMDDetectorML` | `amd_detector_ml.py` | Clasificador XGBoost de fases | ✅ Funcional |
| `SignalGenerator` | `signal_generator.py` | Genera señales de trading | ✅ Funcional |
| `TPSLClassifier` | `tp_sl_classifier.py` | Clasifica TP/SL óptimos | ✅ Funcional |

### 2.4 Ensembles

| Modelo | Archivo | Propósito | Estado |
|--------|---------|-----------|--------|
| `DualHorizonEnsemble` | `dual_horizon_ensemble.py` | Ensemble 5 años + 3 meses | ✅ Funcional |
| `StrategyEnsemble` | `strategy_ensemble.py` | Combina múltiples estrategias | ⚠️ Parcial |

---

## 3. PROBLEMAS IDENTIFICADOS

### 3.1 CRÍTICO: Factores Hardcodeados

**Ubicación**: `range_predictor_factor.py:598-601`

```python
SYMBOLS = {
    'XAUUSD': {'base': 2650.0, 'volatility': 0.0012, 'factor': 2.5},
    'EURUSD': {'base': 1.0420, 'volatility': 0.0004, 'factor': 0.0003},
}
```

**Impacto**:
- Solo 2 activos soportados
- Factores estáticos no se adaptan a cambios de mercado
- No escalable a 100+ activos

**Solución Propuesta**:
- Usar `compute_factor_median_range()` de `volatility_attention.py`
- Rolling median con window de 200 y shift(1) para evitar leakage
- Factor automático por activo basado en ATR/mediana

### 3.2 ALTO: Sin Separación por Activo/Temporalidad

**Estado Actual**:
- Modelos mezclan datos de múltiples activos
- No hay especialización por timeframe

**Impacto**:
- Diferentes activos tienen diferentes características
- Estrategias no son universales
- Ruido en las predicciones

**Solución Propuesta**:
```
models/
├── XAUUSD/
│   ├── 5m/
│   │   ├── range_predictor.joblib
│   │   ├── movement_predictor.joblib
│   │   └── attention_transformer.pt
│   └── 15m/
│       ├── range_predictor.joblib
│       └── ...
├── EURUSD/
│   └── ...
└── BTCUSDT/
    └── ...
```

### 3.3 ALTO: Sistema de Atención No Integrado

**Estado Actual**:
- `volatility_attention.py` existe pero NO está integrado con todos los modelos
- `DynamicFactorWeighter` existe pero es independiente
- XGBoost no usa atención directamente

**Impacto**:
- Modelos dan igual peso a ruido y señales
- No priorizan movimientos significativos

**Solución Propuesta**:
1. Usar `weight_smooth()` para sample_weight en XGBoost
2. Integrar `VolatilityRangePredictor` (PyTorch) como modelo alternativo
3. Crear pipeline unificado de atención

### 3.4 MEDIO: No Hay Metamodelo

**Estado Actual**:
- Cada modelo predice independientemente
- No hay síntesis de predicciones

**Impacto**:
- Decisiones basadas en modelo individual
- No aprovecha diversidad de enfoques

**Solución Propuesta**:
- Metamodelo que combine:
  - RangePredictor
  - MovementMagnitudePredictor
  - AMDDetector
  - VolatilityAttention
- Ponderación dinámica basada en performance reciente

### 3.5 MEDIO: Frontend Incompleto

**Estado Actual**:
- MLDashboard existe pero muestra solo señales básicas
- No hay página de histórico
- No hay visualización por modelo

**Impacto**:
- Difícil evaluar performance de modelos
- No hay herramientas de análisis visual

**Solución Propuesta**:
1. Página "ML Real-time" - Predicciones en vivo
2. Página "ML Historical" - Análisis de período pasado
3. API por modelo o unificada

---

## 4. ANÁLISIS DE SISTEMA DE ATENCIÓN

### 4.1 Implementación Actual

**Archivo**: `volatility_attention.py`

```python
# Factor dinámico (rolling median con shift para evitar leakage)
f_t = rolling_median(High - Low, window=200).shift(1)

# Multiplicador de movimiento
m_t = (High_t - Low_t) / f_t

# Peso con softplus (suave)
w_t = log1p(exp(beta * (m - 1))) / beta

# Interpretación:
# m < 1 → w ≈ 0 (ruido, ignorar)
# m = 1 → w ≈ 0 (movimiento típico)
# m = 2 → w ≈ 1 (2x normal, atención)
# m = 3 → w ≈ 2 (3x normal, alta atención)
```

### 4.2 Propuesta de Mejora para Atención

**Requisito del Usuario**:
> "si la variación es de 10 el peso sería de 2 y si la variación es de 15 el peso sería de 3, pero si la variación es menor a 5 el peso sea casi nulo"

**Ejemplo para XAUUSD** (factor base ≈ 5 USD):

| Variación | Multiplicador | Peso | Interpretación |
|-----------|---------------|------|----------------|
| < 5 USD | m < 1 | ~0 | Ruido, ignorar |
| 5 USD | m = 1 | ~0 | Normal |
| 10 USD | m = 2 | ~1-2 | Buena señal |
| 15 USD | m = 3 | ~2-3 | Excelente señal |

**Código Actualizado**:
```python
def compute_attention_weight(variation_usd: float, factor: float) -> float:
    """
    Calcula peso de atención basado en variación y factor del activo.

    Args:
        variation_usd: Variación en USD (ej: 10.5)
        factor: Factor base del activo (ej: 5.0 para XAUUSD)

    Returns:
        Peso de atención (0-3)
    """
    m = variation_usd / factor

    if m < 1.0:
        return 0.0  # Ruido

    # Softplus suave
    beta = 4.0
    w = np.log1p(np.exp(beta * (m - 1))) / beta

    return min(w, 3.0)  # Cap en 3
```

### 4.3 Cálculo Dinámico del Factor

**En lugar de hardcodear**, usar ATR o mediana rolling:

```python
class DynamicFactorCalculator:
    def __init__(self, window: int = 200):
        self.window = window
        self._factors = {}  # Cache por símbolo

    def get_factor(self, df: pd.DataFrame, symbol: str) -> float:
        """Calcula factor dinámico basado en mediana de rangos"""
        range_col = df['high'] - df['low']
        factor = range_col.rolling(self.window).median().iloc[-1]
        self._factors[symbol] = factor
        return factor

    def update_factor(self, symbol: str, new_range: float):
        """Actualización incremental del factor"""
        # Exponential moving average para adaptación
        alpha = 2 / (self.window + 1)
        self._factors[symbol] = alpha * new_range + (1 - alpha) * self._factors.get(symbol, new_range)
```

---

## 5. ARQUITECTURA PROPUESTA

### 5.1 Estructura de Modelos por Activo/Temporalidad

```
ml-engine/
├── models/
│   ├── base/                    # Clases base
│   │   ├── range_predictor.py
│   │   ├── movement_predictor.py
│   │   └── attention_model.py
│   ├── trained/                 # Modelos entrenados
│   │   ├── XAUUSD/
│   │   │   ├── 5m/
│   │   │   │   ├── config.yaml
│   │   │   │   ├── range_xgb.joblib
│   │   │   │   ├── movement_xgb.joblib
│   │   │   │   └── attention_transformer.pt
│   │   │   └── 15m/
│   │   │       └── ...
│   │   ├── EURUSD/
│   │   │   └── ...
│   │   └── BTCUSDT/
│   │       └── ...
│   └── metamodel/               # Metamodelo
│       ├── ensemble.py
│       └── weights.yaml
```

### 5.2 Arquitectura del Metamodelo

```
┌─────────────────────────────────────────────────────────────┐
│                     METAMODELO                               │
├─────────────────────────────────────────────────────────────┤
│  Inputs (por activo/timeframe):                             │
│  ├── RangePredictor.predict() → (pred_high, pred_low)      │
│  ├── MovementPredictor.predict() → (high_usd, low_usd)     │
│  ├── AMDDetector.detect() → phase                          │
│  └── AttentionModel.predict() → (high, low, attention)     │
├─────────────────────────────────────────────────────────────┤
│  Fusion Layer:                                              │
│  ├── Weighted average basado en performance reciente        │
│  ├── Confidence aggregation                                 │
│  └── Conflict resolution                                    │
├─────────────────────────────────────────────────────────────┤
│  Output:                                                    │
│  ├── final_direction: LONG | SHORT | NEUTRAL               │
│  ├── final_high_pred: float                                │
│  ├── final_low_pred: float                                 │
│  ├── confidence: float (0-1)                               │
│  ├── suggested_tp: float                                    │
│  ├── suggested_sl: float                                    │
│  └── rr_ratio: float                                        │
└─────────────────────────────────────────────────────────────┘
```

### 5.3 APIs Propuestas

**Opción A: API Unificada** (Recomendada)

```
GET /api/ml/predictions/{symbol}?timeframe=15m
POST /api/ml/predictions/batch

Response:
{
  "symbol": "XAUUSD",
  "timeframe": "15m",
  "timestamp": "2026-01-06T10:30:00Z",
  "models": {
    "range_predictor": {
      "pred_high": 2658.5,
      "pred_low": 2652.0,
      "confidence": 0.72
    },
    "movement_predictor": {
      "high_usd": 8.5,
      "low_usd": 3.0,
      "asymmetry": 2.83
    },
    "amd_detector": {
      "phase": "ACCUMULATION",
      "confidence": 0.68
    },
    "attention_model": {
      "pred_high": 2659.0,
      "pred_low": 2651.5,
      "attention_weight": 2.1
    }
  },
  "metamodel": {
    "direction": "LONG",
    "pred_high": 2658.7,
    "pred_low": 2651.8,
    "confidence": 0.75,
    "suggested_tp": 2658.7,
    "suggested_sl": 2651.8,
    "rr_ratio": 2.83
  }
}
```

### 5.4 Frontend: 2 Páginas

**Página 1: ML Real-time** (`/ml/realtime`)
- Dashboard con cards por activo
- Predicciones actualizadas cada 30 segundos
- Indicadores visuales de dirección/confianza
- Gráfico de velas con overlays de predicciones

**Página 2: ML Historical** (`/ml/historical`)
- Selector de rango de fechas
- Tabla de predicciones pasadas
- Métricas de acierto por modelo
- Gráfico de equity curve (backtesting visual)
- Sin refresh automático

---

## 6. MÉTRICAS OBJETIVO

### 6.1 Métricas de Predicción

| Métrica | Objetivo | Actual* | Gap |
|---------|----------|---------|-----|
| Win Rate (movimientos fuertes) | ≥ 80% | ~55-65% | -15-25% |
| R:R Ratio promedio | ≥ 2:1 | ~1.5:1 | -0.5 |
| Profit Factor | ≥ 1.5 | ~1.2 | -0.3 |
| Sharpe Ratio | ≥ 1.0 | ~0.7 | -0.3 |
| Max Drawdown | ≤ 20% | ~25% | +5% |

*Estimado basado en backtests previos

### 6.2 Criterios de Señal Válida

```python
def is_valid_signal(prediction) -> bool:
    """
    Criterios para considerar una señal válida:
    1. Confidence ≥ 0.7
    2. R:R ratio ≥ 2.0
    3. Attention weight ≥ 1.5 (movimiento significativo)
    4. AMD phase no es MANIPULATION
    """
    return (
        prediction.confidence >= 0.7 and
        prediction.rr_ratio >= 2.0 and
        prediction.attention_weight >= 1.5 and
        prediction.amd_phase != 'MANIPULATION'
    )
```

---

## 7. PLAN DE IMPLEMENTACIÓN - VUELTA 1

### Fase 1.1: Refactorización de Factores (Prioridad ALTA)
- [ ] Eliminar factores hardcodeados de `range_predictor_factor.py`
- [ ] Integrar `DynamicFactorCalculator` en todos los modelos
- [ ] Crear `config/symbols.yaml` con metadatos de activos
- [ ] Tests de regresión

### Fase 1.2: Separación por Activo/Temporalidad
- [ ] Crear estructura de directorios `trained/{symbol}/{timeframe}/`
- [ ] Modificar `train()` para guardar modelos separados
- [ ] Modificar `predict()` para cargar modelo correcto
- [ ] Pipeline de reentrenamiento por activo

### Fase 1.3: Integración de Atención
- [ ] Crear `AttentionWeightedModel` wrapper
- [ ] Integrar `weight_smooth()` en sample_weight de XGBoost
- [ ] Opción para usar `VolatilityRangePredictor` (PyTorch)
- [ ] Benchmark comparativo

### Fase 1.4: Diseño de Metamodelo
- [ ] Definir interfaz `BasePredictor`
- [ ] Implementar `MetamodelEnsemble`
- [ ] Sistema de ponderación adaptativa
- [ ] Tests de integración

### Fase 1.5: APIs y Frontend
- [ ] Endpoint `/api/ml/predictions/{symbol}`
- [ ] Endpoint `/api/ml/models`
- [ ] Página MLRealtime
- [ ] Página MLHistorical

---

## 8. SIGUIENTE VUELTA

### Vuelta 2 - Objetivos:
1. Análisis profundo de hyperparámetros
2. Evaluación de arquitecturas (XGBoost vs GRU vs Transformer)
3. Definición de features óptimos por modelo
4. Backtesting extensivo

### Vuelta 3 - Objetivos:
1. Validación final de soluciones
2. Documentación técnica completa
3. Plan de deployment
4. Métricas de monitoreo

---

## 9. HALLAZGOS DE EXPLORACIÓN COMPLEMENTARIA

### 9.1 Estado del Backtesting

**Scripts de Backtesting Identificados:**

| Script | Ubicación | Propósito |
|--------|-----------|-----------|
| `run_range_backtest.py` | ml-engine/scripts/ | Backtesting con RangePredictorV2 |
| `run_80wr_backtest.py` | ml-engine/scripts/ | Optimización 80% win rate |
| `run_movement_backtest.py` | ml-engine/scripts/ | MovementMagnitudePredictor |
| `llm_strategy_backtester.py` | ml-engine/scripts/ | Backtester con filtros direccionales |
| `engine.py` | llm-agent/src/backtesting/ | Motor genérico de backtesting |

**Resultados Clave:**

| Backtest | Período | Retorno | Win Rate | Max DD | Trades |
|----------|---------|---------|----------|--------|--------|
| LLM Strategy Extended | Ene-Mar 2025 | **+5.85%** | 33.3% | 15.12% | 60 |
| Range Backtest Scalping | Ene 2025 | +0.67% | **80%** | 8.61% | 100 |
| LLM Strategy Optimizado | Ene 2025 | +1.18% | 44.4% | 10.1% | 19 |

**Hallazgo Crítico**: 100% de trades ganadores fueron SHORT en XAUUSD 5m. Los filtros direccionales (RSI > 55, SAR bajista, CMF < 0) son efectivos.

### 9.2 APIs Existentes (Detalle)

**Backend Express - `/api/v1/ml`** (14+ endpoints):
- `GET /health` - Estado ML Engine
- `GET /signals/:symbol` - Señal actual
- `POST /signals/batch` - Múltiples símbolos
- `GET /predictions/:symbol` - Predicción de precio
- `GET /amd/:symbol` - Fase AMD
- `POST /backtest` - Ejecutar backtest (requiere auth)
- `GET/POST /models/*` - Gestión de modelos
- `GET /overlays/:symbol` - Overlay completo para gráficos
- `DELETE /overlays/cache/:symbol?` - Limpiar caché

**ML Engine FastAPI - Puerto 8001** (15+ endpoints):
- `POST /predict/range` - ΔHigh/ΔLow
- `POST /predict/tpsl` - Probabilidad TP vs SL
- `POST /generate/signal` - Señal completa
- `GET /api/signals/active` - Señales activas batch
- `POST /api/amd/{symbol}` - Fase AMD
- `POST /api/ict/{symbol}` - Análisis ICT/SMC
- `POST /api/ensemble/{symbol}` - Señal ensemble
- `POST /api/backtest` - Backtest con métricas
- `POST /api/train/full` - Entrenamiento
- `WS /ws/signals` - WebSocket real-time

### 9.3 Frontend Existente (Detalle)

**Páginas Implementadas:**

| Página | Ruta | Estado | Descripción |
|--------|------|--------|-------------|
| MLDashboard | `/ml-dashboard` | ✅ Completo | Dashboard central ML con tabs |
| Trading | `/trading` | ✅ Completo | Trading real-time con overlays ML |
| BacktestingDashboard | `/backtesting` | ✅ Completo | Validación histórica |
| PredictionsPage | `/admin/predictions` | ✅ Completo | Histórico predicciones |
| MLModelsPage | `/admin/models` | ✅ Completo | Gestión de modelos |

**Componentes ML Clave:**
- `PredictionCard.tsx` - Card de señal con niveles TP/SL
- `AMDPhaseIndicator.tsx` - Indicador de fase AMD
- `ICTAnalysisCard.tsx` - Análisis Smart Money Concepts
- `EnsembleSignalCard.tsx` - Señal combinada multi-modelo
- `SignalsTimeline.tsx` - Histórico de señales
- `CandlestickChartWithML.tsx` - Gráfico con overlays ML
- `MLSignalsPanel.tsx` - Panel lateral de señales

### 9.4 Brechas Identificadas vs Requerimientos

| Requerimiento | Estado Actual | Brecha |
|---------------|---------------|--------|
| Factores dinámicos ATR-based | `DynamicFactorWeighter` existe pero NO integrado | **ALTA** |
| Separación por activo/timeframe | Modelos mezclan datos | **ALTA** |
| Metamodelo | `StrategyEnsemble` parcial (pesos fijos) | **MEDIA** |
| 80%+ accuracy | 33-44% win rate actual | **CRÍTICA** |
| 2:1 o 3:1 R:R | ~1.2:1 promedio actual | **ALTA** |
| 100+ activos | Solo 3-6 soportados | **ALTA** |
| Página ML real-time | MLDashboard existe | ✅ OK |
| Página ML histórico | BacktestingDashboard existe | ✅ OK |

---

## 10. CONCLUSIONES VUELTA 1

### 10.1 Fortalezas Encontradas
1. **Infraestructura sólida**: APIs backend y ML Engine bien estructuradas
2. **Frontend completo**: Dashboard, Trading y Backtesting funcionales
3. **Modelos diversos**: 6+ modelos ML operativos
4. **Backtesting maduro**: Sistema completo con métricas detalladas
5. **Atención implementada**: `volatility_attention.py` listo para integrar

### 10.2 Debilidades Críticas
1. **Factores hardcodeados**: Bloquean escalabilidad
2. **Sin separación por activo**: Reduce precisión
3. **Win rate bajo**: 33-44% vs objetivo 80%
4. **R:R insuficiente**: 1.2:1 vs objetivo 2:1+
5. **Atención no integrada**: Código existe pero no se usa

### 10.3 Recomendaciones para Vuelta 2
1. **Prioridad 1**: Integrar `DynamicFactorWeighter` en todos los modelos
2. **Prioridad 2**: Separar modelos por símbolo y timeframe
3. **Prioridad 3**: Optimizar filtros direccionales (SHORT bias en XAUUSD)
4. **Prioridad 4**: Ajustar umbrales de confianza (0.7+ solo señales válidas)
5. **Prioridad 5**: Implementar metamodelo con pesos adaptativos

---

## 11. ANEXOS

### A. Archivos Clave

| Archivo | Ruta | Líneas | Descripción |
|---------|------|--------|-------------|
| volatility_attention.py | models/ | 722 | Sistema de atención |
| range_predictor_factor.py | models/ | 709 | Predictor con factores |
| enhanced_range_predictor.py | models/ | 711 | Predictor mejorado |
| movement_magnitude_predictor.py | models/ | 966 | Predictor de magnitud |
| dynamic_factor_weighting.py | training/ | 425 | Weighting dinámico |

### B. Configuración de Sesiones (Actual)

```python
SessionWeightConfig = {
    'overlap_weight': 2.0,      # London/NY overlap (12-16 UTC)
    'london_weight': 1.5,       # London (8-16 UTC)
    'ny_weight': 1.3,           # New York (14-21 UTC)
    'tokyo_weight': 0.7,        # Tokyo session
    'off_hours_weight': 0.3,    # Fuera de horario
    'use_atr_weighting': True,
    'atr_high_weight_boost': 1.5,
    'atr_low_weight_penalty': 0.3
}
```

### C. XGBoost Config Actual

```python
xgboost_config = {
    'n_estimators': 300,
    'max_depth': 6,
    'learning_rate': 0.03,
    'subsample': 0.8,
    'colsample_bytree': 0.8,
    'min_child_weight': 3,
    'gamma': 0.1,
    'reg_alpha': 0.1,
    'reg_lambda': 1.0,
    'tree_method': 'hist',
    'device': 'cuda'  # Si disponible
}
```

---

*Documento generado: 2026-01-06*
*Próxima revisión: Vuelta 2*