trading-platform/docs/99-analisis/ANALISIS-INTEGRACION-ML-ENGINE.md

---
id: "ANALISIS-INTEGRACION-ML"
title: "Análisis de Integración ML-Engine con Subproyectos"
type: "Análisis"
project: "trading-platform"
epic: "OQI-006"
fecha: "2026-01-07"
agente: "ML-Specialist + Architecture-Analyst"
status: "COMPLETO"
---

# Análisis de Integración: ML-Engine con Subproyectos

**Fecha:** 2026-01-07
**Agente:** ML-Specialist + Architecture-Analyst
**Estado:** ✅ COMPLETO

---

## 1. Resumen Ejecutivo

Este documento presenta un análisis completo de la integración del subproyecto `ml-engine` con los demás subproyectos de la plataforma trading-platform. Se identifican puntos de integración, problemas potenciales y recomendaciones para asegurar una correcta integración.

---

## 2. Arquitectura de Subproyectos

```
trading-platform/apps/
├── backend/          # API Gateway (NestJS/TypeScript) - Puerto 3081
├── data-service/     # Servicio de datos de mercado (FastAPI) - Puerto 3084
├── ml-engine/        # Motor de ML y predicciones (FastAPI) - Puerto 3083
├── trading-agents/   # Agentes de trading automático (FastAPI) - Puerto 3086
├── llm-agent/        # Agente LLM para análisis (FastAPI)
├── database/         # DDL y scripts PostgreSQL
├── frontend/         # UI React
└── mcp-*/            # Conectores MCP (MetaTrader, Binance)
```

---

## 3. Puntos de Integración Identificados

### 3.1 Backend → ML-Engine

**Archivo:** `apps/backend/src/shared/clients/ml-engine.client.ts`

**Endpoints consumidos:**

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/health` | GET | Health check |
| `/api/v1/models` | GET | Listar modelos |
| `/api/v1/signals/predict` | POST | Obtener señal individual |
| `/api/v1/signals/batch` | POST | Señales en lote |
| `/api/v1/signals/latest/{symbol}` | GET | Última señal cacheada |
| `/api/v1/predictions/range/{symbol}` | GET | Predicciones de rango |
| `/api/v1/amd/analyze/{symbol}` | GET | Análisis AMD |
| `/api/v1/backtest/run` | POST | Ejecutar backtest |
| `/ws/signals` | WebSocket | Señales en tiempo real |

**Configuración:** `ML_ENGINE_URL` (default: `http://localhost:8001`)

---

### 3.2 ML-Engine → Data-Service

**Archivo:** `apps/ml-engine/src/data/data_service_client.py`

**Endpoints consumidos:**

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/health` | GET | Health check |
| `/api/symbols` | GET | Lista de símbolos |
| `/api/ohlcv` | GET | Datos OHLCV históricos |
| `/api/snapshot/{symbol}` | GET | Ticker actual |

**Configuración:** `DATA_SERVICE_URL` (default: `http://localhost:8001`)

---

### 3.3 Trading-Agents → ML-Engine

**Archivo:** `apps/trading-agents/src/signals/ml_consumer.py`

**Integración:** Polling HTTP cada 5 segundos

**Métodos:**
- `get_signal(symbol)` - Señal por símbolo
- `get_signals_batch(symbols)` - Señales en lote
- `subscribe(symbol, callback)` - Suscripción a actualizaciones

---

### 3.4 Backend → Trading-Agents

**Archivo:** `apps/backend/src/shared/clients/trading-agents.client.ts`

**Endpoints consumidos:**

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/api/v1/agents/{type}/start` | POST | Iniciar agente |
| `/api/v1/agents/{type}/stop` | POST | Detener agente |
| `/api/v1/agents/{type}/status` | GET | Estado del agente |
| `/api/v1/signals/broadcast` | POST | Difundir señal |

---

## 4. Bases de Datos

### 4.1 PostgreSQL Local (trading_platform)

**Puerto:** 5433
**Schemas verificados:**

| Schema | Tablas | Estado |
|--------|--------|--------|
| ml | 9 tablas | ✅ OK |
| trading | 10 tablas | ✅ OK |
| auth | 11 tablas | ✅ OK |
| education | 14 tablas | ✅ OK |
| financial | 10 tablas | ⚠️ Errores dependencia |
| investment | 7 tablas | ⚠️ Errores dependencia |
| llm | 5 tablas | ✅ OK |
| audit | 1 tabla | ✅ OK |

**Tablas ML relevantes:**
- `ml.models` - Registro de modelos
- `ml.model_versions` - Versiones de modelos
- `ml.predictions` - Predicciones generadas
- `ml.prediction_outcomes` - Resultados de predicciones
- `ml.feature_store` - Almacén de features

---

### 4.2 MySQL Remoto (db_trading_meta)

**Host:** 72.60.226.4:3306
**Propósito:** Datos históricos OHLCV (solo lectura)

**Tablas:**
- `tickers_agg_data` - Datos OHLCV agregados

**Nota:** Los datos BTCUSD actualizados en FASE 11 residen aquí.

---

## 5. Problemas Identificados

### 5.1 Críticos

| ID | Problema | Impacto | Componentes |
|----|----------|---------|-------------|
| P-001 | Puertos inconsistentes en configuración | Alto | Todos |
| P-002 | Conflicto URL Data Service (8001 vs 3084) | Alto | ml-engine, data-service |
| P-003 | Schemas financial/investment con errores DDL | Alto | database |

### 5.2 Importantes

| ID | Problema | Impacto | Componentes |
|----|----------|---------|-------------|
| P-004 | Sin cliente Data Service en Backend | Medio | backend |
| P-005 | Formato señales diferente ML/Agents | Medio | ml-engine, trading-agents |
| P-006 | Polling 5s puede ser agresivo | Medio | trading-agents |
| P-007 | Sin circuit breaker en clientes | Medio | Todos |

### 5.3 Menores

| ID | Problema | Impacto | Componentes |
|----|----------|---------|-------------|
| P-008 | Sin health check centralizado | Bajo | backend |
| P-009 | Sin deduplicación de señales | Bajo | trading-agents |
| P-010 | Sin cache Redis configurado | Bajo | ml-engine |

---

## 6. Configuración de Puertos

### 6.1 Estado Actual (Inconsistente)

| Servicio | .env.example | Código Default | Recomendado |
|----------|-------------|----------------|-------------|
| Backend | 3081 | 3081 | 3081 |
| ML Engine | 3083 | 8001 | 3083 |
| Data Service | 3084 | 8001 | 3084 |
| Trading Agents | 3086 | 8004 | 3086 |

### 6.2 Acción Requerida

Alinear todas las configuraciones al estándar definido en `.env.example`.

---

## 7. Contratos de Datos

### 7.1 MLSignal (ML-Engine Output)

```python
class MLSignal:
    symbol: str
    timeframe: str
    direction: Literal['long', 'short', 'neutral']
    confidence: float  # 0.0 - 1.0
    entry_price: float
    stop_loss: float
    take_profit: float
    risk_reward_ratio: float
    prob_tp_first: float
    amd_phase: str
    volatility_regime: str
    timestamp: datetime
    metadata: dict
```

### 7.2 SignalInput (Trading-Agents Input)

```python
class SignalInput:
    symbol: str
    action: Literal['buy', 'sell', 'hold']
    confidence: float
    price: float
    stop_loss: Optional[float]
    take_profit: Optional[float]
    metadata: Optional[dict]
```

### 7.3 Transformación Requerida

```python
def ml_signal_to_agent_input(ml_signal: MLSignal) -> SignalInput:
    action_map = {'long': 'buy', 'short': 'sell', 'neutral': 'hold'}
    return SignalInput(
        symbol=ml_signal.symbol,
        action=action_map[ml_signal.direction],
        confidence=ml_signal.confidence,
        price=ml_signal.entry_price,
        stop_loss=ml_signal.stop_loss,
        take_profit=ml_signal.take_profit,
        metadata=ml_signal.metadata
    )
```

---

## 8. Validación de ML-Engine

### 8.1 Modelos Entrenados

| Símbolo | Attention | Base | Metamodel | Backtest | Estado |
|---------|-----------|------|-----------|----------|--------|
| XAUUSD | ✅ | ✅ | ✅ | ✅ Rentable | COMPLETO |
| EURUSD | ✅ | ✅ | ✅ | ✅ Rentable | COMPLETO |
| GBPUSD | ✅ | ✅ | ✅ | ✅ Rentable | COMPLETO |
| USDJPY | ✅ | ✅ | ✅ | ✅ Rentable | COMPLETO |
| BTCUSD | ✅ | ✅ | ✅ | ✅ Rentable | COMPLETO (FASE 11) |

### 8.2 Features Pipeline

- **Total features:** 50 (sin attention) / 52 (con attention)
- **Arquitectura:** Hierarchical Pipeline (Attention → Base → Metamodel)
- **Estrategias:** 7 estrategias de backtest implementadas

---

## 9. Recomendaciones de Integración

### 9.1 Prioridad Alta

| # | Acción | Responsable | Esfuerzo |
|---|--------|-------------|----------|
| 1 | Unificar configuración de puertos | DevOps | 2h |
| 2 | Corregir errores DDL (financial, investment) | Database | 4h |
| 3 | Crear convertidor MLSignal→SignalInput | ML-Engine | 2h |
| 4 | Implementar health check centralizado | Backend | 3h |

### 9.2 Prioridad Media

| # | Acción | Responsable | Esfuerzo |
|---|--------|-------------|----------|
| 5 | Crear cliente Data Service en Backend | Backend | 4h |
| 6 | Implementar circuit breaker en clientes | Backend/Agents | 4h |
| 7 | Cambiar polling a WebSocket | Trading-Agents | 6h |
| 8 | Configurar Redis cache | DevOps/ML | 4h |

### 9.3 Prioridad Baja

| # | Acción | Responsable | Esfuerzo |
|---|--------|-------------|----------|
| 9 | Deduplicación de señales | Trading-Agents | 2h |
| 10 | Tests de integración E2E | Testing | 8h |
| 11 | Documentar OpenAPI specs | Todos | 4h |

---

## 10. Diagrama de Flujo de Señales

```
┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
│ Data Source │───▶│ Data Service │───▶│    ML Engine    │
│ (MySQL/API) │    │  (FastAPI)   │    │    (FastAPI)    │
└─────────────┘    └──────────────┘    └────────┬────────┘
                                                │
                            ┌───────────────────┼───────────────────┐
                            │                   │                   │
                            ▼                   ▼                   ▼
                    ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
                    │    Backend    │   │Trading Agents │   │   Frontend    │
                    │   (NestJS)    │   │   (FastAPI)   │   │   (React)     │
                    └───────────────┘   └───────┬───────┘   └───────────────┘
                                                │
                                                ▼
                                        ┌───────────────┐
                                        │  PostgreSQL   │
                                        │ (Predictions) │
                                        └───────────────┘
```

---

## 11. Conclusiones

### 11.1 Estado de Integración

| Componente | Integración | Calificación |
|------------|-------------|--------------|
| ML-Engine ↔ Data-Service | Funcional | ⭐⭐⭐⭐ |
| Backend ↔ ML-Engine | Funcional | ⭐⭐⭐⭐ |
| Trading-Agents ↔ ML-Engine | Funcional (polling) | ⭐⭐⭐ |
| Database DDL | Parcialmente funcional | ⭐⭐⭐ |

### 11.2 Resumen

- **ML-Engine** está correctamente implementado con modelos entrenados para 5 símbolos
- **Integración con Backend** funciona pero requiere unificación de puertos
- **Trading-Agents** consume señales pero podría mejorar con WebSocket
- **Base de datos ML** correctamente estructurada, otros schemas requieren corrección

---

## 12. Referencias

- [PLAN-IMPLEMENTACION-FASES.md](./PLAN-IMPLEMENTACION-FASES.md)
- [ML_INVENTORY.yml](../90-transversal/inventarios/ML_INVENTORY.yml)
- [REPORTE-ENTREGA-FASE11-BTCUSD.md](./REPORTE-ENTREGA-FASE11-BTCUSD.md)
- Backend Client: `apps/backend/src/shared/clients/ml-engine.client.ts`
- ML API: `apps/ml-engine/src/api/main.py`

---

*Generado: 2026-01-07 | Sistema: SIMCO | Agentes: ML-Specialist, Architecture-Analyst*