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

id	title	type	project	epic	fecha	agente	status
ANALISIS-INTEGRACION-ML	Análisis de Integración ML-Engine con Subproyectos	Análisis	trading-platform	OQI-006	2026-01-07	ML-Specialist + Architecture-Analyst	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)

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)

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

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
• ML_INVENTORY.yml
• 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