# 06-DOCUMENTACIÓN: Mejora Integral de Modelos ML para Trading

**Task ID:** TASK-2026-01-25-ML-TRAINING-ENHANCEMENT
**Fase:** D - Documentación
**Estado:** En Progreso (parcial)
**Fecha:** 2026-01-25

---

## 1. DOCUMENTACIÓN CREADA

### 1.1 Orchestration (Esta tarea)

| Archivo | Propósito | Estado |
|---------|-----------|--------|
| METADATA.yml | Metadata de la tarea | ✅ Creado |
| 01-CONTEXTO.md | Fase C de CAPVED | ✅ Creado |
| 02-ANALISIS.md | Fase A de CAPVED | ✅ Creado |
| 03-PLANEACION.md | Fase P de CAPVED | ✅ Creado |
| 04-VALIDACION.md | Fase V de CAPVED | ✅ Creado |
| 05-EJECUCION.md | Fase E de CAPVED | ✅ Creado |
| 06-DOCUMENTACION.md | Fase D de CAPVED | ✅ Creado |

### 1.2 Especificaciones Técnicas (Pendientes)

| Archivo | Propósito | Estado |
|---------|-----------|--------|
| DATA-PIPELINE.md | Schema y pipeline de datos | ⏳ Pendiente |
| PVA-SPEC.md | Especificación estrategia 1 | ⏳ Pendiente |
| MRD-SPEC.md | Especificación estrategia 2 | ⏳ Pendiente |
| VBP-SPEC.md | Especificación estrategia 3 | ⏳ Pendiente |
| MSA-SPEC.md | Especificación estrategia 4 | ⏳ Pendiente |
| MTS-SPEC.md | Especificación estrategia 5 | ⏳ Pendiente |
| METAMODEL-SPEC.md | Especificación del ensemble | ⏳ Pendiente |
| LLM-INTEGRATION.md | Integración con LLM | ⏳ Pendiente |
| BACKTEST-RESULTS.md | Resultados de backtesting | ⏳ Pendiente |

---

## 2. DOCUMENTACIÓN ACTUALIZADA

### 2.1 Actualizaciones Requeridas

| Archivo | Cambio | Estado |
|---------|--------|--------|
| `OQI-006/_MAP.md` | Agregar nuevas estrategias | ⏳ Pendiente |
| `OQI-006/README.md` | Actualizar arquitectura | ⏳ Pendiente |
| `MASTER_INVENTORY.yml` | Agregar nuevos modelos | ⏳ Pendiente |
| `PROJECT-STATUS.md` | Reflejar nueva tarea | ⏳ Pendiente |
| `PROXIMA-ACCION.md` | Actualizar checkpoint | ⏳ Pendiente |
| `_INDEX.yml` de tareas | Registrar esta tarea | ⏳ Pendiente |

---

## 3. DOCUMENTACIÓN A PURGAR

### 3.1 Archivos Obsoletos

| Archivo | Razón | Acción |
|---------|-------|--------|
| `NOTA-DISCREPANCIA-PUERTOS-2025-12-08.md` | Nota temporal obsoleta | Eliminar |

### 3.2 Archivos para Consolidar

| Archivos | Archivo Destino | Acción |
|----------|-----------------|--------|
| Múltiples ARQUITECTURA-*.md | ARQUITECTURA-ML-UNIFICADA.md | Consolidar |

---

## 4. INVENTARIOS

### 4.1 ML_INVENTORY.yml (NUEVO)

```yaml
# orchestration/inventarios/ML_INVENTORY.yml
version: "1.0.0"
updated: "2026-01-25"

modelos:
  level_0_attention:
    - name: "AttentionScoreModel"
      status: "trained"
      symbols: ["XAUUSD", "EURUSD", "BTCUSD", "GBPUSD", "USDJPY", "AUDUSD"]
      timeframes: ["5m", "15m"]
      count: 12

  level_1_strategies:
    - name: "PVA - Price Variation Attention"
      status: "planned"
      architecture: "Transformer + XGBoost"

    - name: "MRD - Momentum Regime Detection"
      status: "planned"
      architecture: "HMM + LSTM + XGBoost"

    - name: "VBP - Volatility Breakout Predictor"
      status: "planned"
      architecture: "CNN 1D + Attention + XGBoost"

    - name: "MSA - Market Structure Analysis"
      status: "planned"
      architecture: "XGBoost (GNN opcional)"

    - name: "MTS - Multi-Timeframe Synthesis"
      status: "planned"
      architecture: "Hierarchical Attention Network"

  level_2_metamodel:
    - name: "Neural Gating Metamodel"
      status: "planned"
      architecture: "MLP Gating + Weighted Ensemble"

datos:
  historical:
    source: "WorkspaceOld/trading MySQL dumps"
    size: "5.6 GB"
    status: "pending_migration"

  current:
    source: "Polygon API"
    bars: 469217
    symbols: 6
    period: "365 days"
    status: "loaded"

metricas_objetivo:
  efectividad: ">=80%"
  sharpe_ratio: ">=1.5"
  max_drawdown: "<=15%"
```

---

## 5. DIAGRAMAS

### 5.1 Arquitectura General (ASCII)

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                     ML TRAINING ENHANCEMENT ARCHITECTURE                         │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  ┌─────────────┐                                                                │
│  │ Market Data │ ─────────────────────────────────────────┐                    │
│  │ (PostgreSQL)│                                          │                    │
│  └─────────────┘                                          ▼                    │
│                                                  ┌─────────────────┐           │
│                                                  │ Feature Engine  │           │
│                                                  │ (Per Strategy)  │           │
│                                                  └────────┬────────┘           │
│                                                           │                    │
│        ┌──────────────────────────────────────────────────┼──────────────┐     │
│        │                   │                   │          │              │     │
│        ▼                   ▼                   ▼          ▼              ▼     │
│  ┌──────────┐       ┌──────────┐       ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │   PVA    │       │   MRD    │       │   VBP    │ │   MSA    │ │   MTS    │ │
│  │Transformer│       │HMM+LSTM │       │  CNN 1D  │ │ XGBoost  │ │Hier.Attn │ │
│  │+XGBoost  │       │+XGBoost │       │+Attention│ │   /GNN   │ │ Network  │ │
│  └────┬─────┘       └────┬─────┘       └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│       │                  │                  │            │            │       │
│       └──────────────────┴──────────────────┴────────────┴────────────┘       │
│                                      │                                         │
│                                      ▼                                         │
│                          ┌─────────────────────┐                               │
│                          │  Neural Gating      │                               │
│                          │  Metamodel          │                               │
│                          │  (Weighted Ensemble)│                               │
│                          └──────────┬──────────┘                               │
│                                     │                                          │
│                                     ▼                                          │
│                          ┌─────────────────────┐                               │
│                          │  Signal Formatter   │                               │
│                          │  (For LLM)          │                               │
│                          └──────────┬──────────┘                               │
│                                     │                                          │
│                                     ▼                                          │
│                          ┌─────────────────────┐                               │
│                          │  LLM Agent          │                               │
│                          │  (Ollama/Claude)    │                               │
│                          └──────────┬──────────┘                               │
│                                     │                                          │
│                                     ▼                                          │
│                          ┌─────────────────────┐                               │
│                          │  Trading Decision   │                               │
│                          │  (TRADE/NO_TRADE)   │                               │
│                          └─────────────────────┘                               │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘
```

---

## 6. ADRs (Decisiones Arquitectónicas)

### ADR-ML-001: Elección de 5 Estrategias Diversificadas

**Contexto:** Se necesitan múltiples estrategias de predicción para lograr 80% de efectividad.

**Decisión:** Implementar 5 estrategias complementarias:
1. PVA - Enfoque en variación de precio pura
2. MRD - Detección de régimen de mercado
3. VBP - Predicción de breakouts de volatilidad
4. MSA - Análisis de estructura de mercado
5. MTS - Síntesis multi-timeframe

**Consecuencias:**
- (+) Diversificación reduce riesgo de fallo sistémico
- (+) Cada estrategia captura diferentes aspectos del mercado
- (-) Mayor complejidad de implementación
- (-) Mayor costo computacional de entrenamiento

### ADR-ML-002: Neural Gating vs Simple Average

**Contexto:** Se necesita combinar predicciones de 5 estrategias.

**Decisión:** Usar Neural Gating Network en lugar de promedio simple.

**Consecuencias:**
- (+) Ponderación dinámica según contexto de mercado
- (+) Aprende qué estrategia funciona mejor en qué régimen
- (-) Requiere datos de entrenamiento adicionales
- (-) Riesgo de colapso a una estrategia (mitigado con regularización)

### ADR-ML-003: Atención Agnóstica al Tiempo

**Contexto:** Se requiere que los modelos funcionen sin depender del horario.

**Decisión:** No usar features de sesión/hora en Estrategia PVA. Usar solo retornos y derivados.

**Consecuencias:**
- (+) Modelo generaliza mejor a diferentes mercados
- (+) Evita overfitting a patrones de sesión específicos
- (-) Pierde información de sesión que puede ser valiosa
- (-) Otras estrategias (MTS) sí usarán sesión para complementar

---

## 7. LECCIONES APRENDIDAS

*(Se actualizará al completar la tarea)*

```yaml
que_funciono_bien: []
que_se_puede_mejorar: []
para_futuras_tareas_similares: []
```

---

## 8. REFERENCIAS

### 8.1 Documentos Internos

- `@CAPVED` - Ciclo de vida de tareas
- `orchestration/directivas/simco/SIMCO-TAREA.md`
- `docs/02-definicion-modulos/OQI-006-ml-signals/_MAP.md`
- `projects/trading-platform/apps/ml-engine/`

### 8.2 Proyecto Antiguo

- `C:\Empresas\WorkspaceOld\Projects\trading\`
- Arquitectura XGBoost + GRU + Metamodelos
- 22 indicadores técnicos

### 8.3 Referencias Externas

- Attention Is All You Need (Transformers)
- XGBoost Documentation
- Hidden Markov Models for Time Series
- ICT/SMC Concepts (Market Structure)

---

## 9. CHECKLIST DE DOCUMENTACIÓN

- [x] Archivos CAPVED creados
- [ ] Especificaciones técnicas creadas
- [ ] Inventarios actualizados
- [ ] _INDEX.yml actualizado
- [ ] PROJECT-STATUS.md actualizado
- [ ] PROXIMA-ACCION.md actualizado
- [ ] Diagramas en formato exportable
- [ ] ADRs registrados en docs/97-adr/

---

**Estado:** Documentación parcial completada. Pendiente actualización post-ejecución.