trading-platform/docs/02-definicion-modulos/OQI-006-ml-signals/historias-usuario/US-ML-008-ver-ensemble-signal.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-ML-008	Ver Señal Ensemble	User Story	Pending	Alta	OQI-006	trading-platform	5	2026-01-25	2026-01-25

US-ML-008: Ver Señal Ensemble

Metadata

Campo	Valor
ID	US-ML-008
Épica	OQI-006 - Señales ML y Predicciones
Módulo	ml-signals
Prioridad	P0 (Alta)
Story Points	5
Sprint	Sprint 8
Estado	Pendiente
Asignado a	Por asignar

---

Historia de Usuario

Como trader/inversor, quiero ver la señal combinada (ensemble) de múltiples modelos ML con sus contribuciones individuales, para tomar decisiones más informadas y confiar en predicciones robustas de múltiples fuentes.

Descripción Detallada

El usuario debe poder ver una vista integrada que combina las predicciones de múltiples modelos ML (LSTM, RandomForest, SVM, etc.) en una señal consolidada (ensemble). La vista debe mostrar:

1. Señal Ensemble Principal: La decisión combinada (BUY/SELL/HOLD) con confianza agregada
2. Confianza Combinada: Porcentaje agregado considerando pesos de cada modelo
3. Contribuciones Individuales: Lista de modelos participantes con sus predicciones y pesos
4. Scoring Detallado: Score de cada modelo, peso asignado, contribución a la decisión final
5. Votación de Modelos: Cuántos modelos votaron por cada acción
6. Consenso: Nivel de acuerdo entre modelos

---

Mockups/Wireframes

┌──────────────────────────────────────────────────────────────────┐
│  ENSEMBLE SIGNAL                                        BTCUSDT  │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                  ENSEMBLE DECISION                         │ │
│  ├────────────────────────────────────────────────────────────┤ │
│  │                                                             │ │
│  │  Signal: 🟢 BUY                                             │ │
│  │  Confidence: ████████░ 82%                                  │ │
│  │  Score: 8.2/10                                              │ │
│  │  Consensus: STRONG (4/5 models agree)                      │ │
│  │                                                             │ │
│  │  Entry Price Avg:  $89,450.00                              │ │
│  │  TP1: $89,650 (+0.22%)  | TP2: $89,850 (+0.45%)            │ │
│  │  TP3: $90,050 (+0.67%)  | SL: $89,150 (-0.33%)             │ │
│  │                                                             │ │
│  │  Generated: 2026-01-25 10:30:15 UTC                         │ │
│  │  Expires: 2026-01-25 14:30:15 UTC (4h horizon)             │ │
│  │                                                             │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  MODEL CONTRIBUTIONS                                       │ │
│  ├────────────────────────────────────────────────────────────┤ │
│  │                                                             │ │
│  │  [Model Distribution]                                       │ │
│  │                                                             │ │
│  │  🟢 BUY:  4 models (80%)  ████████░░                        │ │
│  │  🔴 SELL: 1 model  (20%)  ██░░░░░░░░                        │ │
│  │  🔵 HOLD: 0 models (0%)   ░░░░░░░░░░                        │ │
│  │                                                             │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  DETAILED MODEL VOTING                                     │ │
│  ├────────────────────────────────────────────────────────────┤ │
│  │                                                             │ │
│  │  Model Name        Prediction  Score  Weight  Contribution│ │
│  │  ─────────────────────────────────────────────────────────│ │
│  │  ✓ LSTM            🟢 BUY      87%    25%     21.75%       │ │
│  │  ✓ RandomForest    🟢 BUY      85%    30%     25.50%       │ │
│  │  ✓ SVM             🟢 BUY      78%    20%     15.60%       │ │
│  │  ✓ Transformer     🟢 BUY      81%    15%     12.15%       │ │
│  │  ✗ GradientBoosting 🔴 SELL    72%    10%     -7.20%*      │ │
│  │                                                             │ │
│  │  *Negative contribution indicates minority prediction      │ │
│  │                                                             │ │
│  │  CONSENSUS ANALYSIS:                                       │ │
│  │  • 4 out of 5 models predict BUY (strong agreement)        │ │
│  │  • Confidence scores range from 72% to 87% (tight)         │ │
│  │  • 1 outlier (GradientBoosting) predicts SELL              │ │
│  │  • Overall consensus strength: 80% (STRONG)                │ │
│  │                                                             │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  HISTORICAL MODEL PERFORMANCE                              │ │
│  ├────────────────────────────────────────────────────────────┤ │
│  │                                                             │ │
│  │  Model Name        Accuracy  Win Rate  Last 7d  Trend      │ │
│  │  ─────────────────────────────────────────────────────────│ │
│  │  LSTM              84.2%     71.5%     72%      ↑ Good     │ │
│  │  RandomForest      82.1%     68.9%     69%      ↑ Good     │ │
│  │  SVM               79.8%     65.3%     66%      → Stable   │ │
│  │  Transformer       81.5%     70.2%     71%      ↑ Good     │ │
│  │  GradientBoosting  76.2%     61.4%     62%      ↓ Declining│ │
│  │                                                             │ │
│  │  Ensemble (Combined) 85.6%   75.1%     76%      ↑ Excellent│ │
│  │                                                             │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  [View Technical Context] [Compare Models] [View Signal History] │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  MODEL COMPARISON CHART                                          │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  Prediction Heatmap:                                             │
│                                                                   │
│         LSTM   RF   SVM  TRF  GB   ENS                            │
│  BTCUSDT [87%] [85%][78%][81%][72%][82%]  🟢 BUY               │
│  ETHUSDT [84%] [86%][75%][80%][70%][81%]  🟢 BUY               │
│  XRPUSDT [81%] [79%][72%][76%][68%][77%]  🟢 BUY               │
│  SOLUSDT [76%] [74%][69%][71%][65%][72%]  🟡 HOLD (Weak)       │
│                                                                   │
│  Legend: ENS = Ensemble Vote                                      │
│                                                                   │
│  Consensus Strength Graph:                                       │
│                                                                   │
│  100% │                                                          │
│       │      ╱─╲                                                  │
│   80% │    ╱─   ╲╱╲                                               │
│       │  ╱─        ╲─╲                                             │
│   60% │╱─              ╲───                                        │
│       │────────────────────► time                                 │
│   40% │                                                          │
│       └────────────────────────────────────────────────────────┘ │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

---

Criterios de Aceptación

Escenario 1: Ver señal ensemble

DADO que el usuario está autenticado en Trading Platform
CUANDO navega a "ML Signals > Ensemble" para un símbolo (ej: BTCUSDT)
ENTONCES ve la señal ensemble con:
  - Decisión principal (BUY/SELL/HOLD)
  - Confianza combinada (%)
  - Score de 0 a 10
  - Nivel de consenso (STRONG/MODERATE/WEAK)
  - Número de modelos votando por cada acción
Y se muestra el timestamp de generación y expiración

Escenario 2: Ver contribuciones de modelos

DADO que el usuario está viendo una señal ensemble
CUANDO expande la sección "Model Contributions"
ENTONCES ve una tabla con:
  - Nombre de cada modelo
  - Predicción individual (BUY/SELL/HOLD)
  - Score/confianza de cada modelo (%)
  - Peso asignado a cada modelo (%)
  - Contribución calculada al resultado final
Y las filas están ordenadas por peso (mayor a menor)

Escenario 3: Ver votación de modelos

DADO que existen 5 modelos en el ensemble
CUANDO veo la distribución de votos
ENTONCES se muestra:
  - Gráfico de barras: cuántos modelos votaron por cada acción
  - Porcentaje: 80% BUY, 20% SELL, 0% HOLD
  - Indicador visual de consenso (fuerte/moderado/débil)
  - Descripción: "4 out of 5 models agree on BUY"

Escenario 4: Ver performance histórico de modelos

DADO que el usuario quiere evaluar fiabilidad de cada modelo
CUANDO expande "Historical Model Performance"
ENTONCES ve para cada modelo:
  - Accuracy (%)
  - Win Rate en los últimos 7 días (%)
  - Tendencia (↑/→/↓)
  - Comparación con ensemble

Escenario 5: Detectar outliers

DADO que 1 modelo predice diferente al ensemble (ej: SELL vs BUY)
CUANDO veo la tabla de contribuciones
ENTONCES:
  - Se destaca visualmente con icono ✗ (en lugar de ✓)
  - Se muestra con color diferente (rojo vs verde)
  - Se incluye nota: "Minority prediction"
  - Contribución se resta del total (negativa)

Escenario 6: Comparar modelos lado a lado

DADO que quiero evaluar predicciones de todos los modelos
CUANDO hago click en "Compare Models"
ENTONCES se abre una vista con:
  - Heatmap de predicciones por símbolo
  - Scores de cada modelo lado a lado
  - Tendencia de consenso en tiempo (gráfico)
  - Botón para exportar comparación

Criterios Adicionales

• Debe cargar en menos de 1.5 segundos
• Soportar 5-10 modelos simultáneamente
• Actualizar automáticamente cada 30 segundos (si hay nuevas señales)
• Ser responsive en mobile
• Mostrar claramente cuál es el modelo más confiable
• Detectar y resaltar predicciones outliers
• Permitir ponderar dinámicamente los modelos (admin)

---

Tareas Técnicas

Backend:

• BE-ML-016: Crear endpoint GET /api/ml/ensemble/:symbol
• BE-ML-017: Implementar cálculo de confianza combinada (weighted average)
• BE-ML-018: Implementar votación y consenso de modelos
• BE-ML-019: Obtener scores individuales de cada modelo
• BE-ML-020: Calcular performance histórico de modelos
• BE-ML-021: Endpoint GET /api/ml/ensemble/:symbol/models (detalle)
• BE-ML-022: Endpoint GET /api/ml/ensemble/comparison (heatmap)

Frontend:

• FE-ML-035: Crear componente EnsembleSignal.tsx
• FE-ML-036: Crear componente ModelVoting.tsx
• FE-ML-037: Crear componente ModelContributions.tsx (tabla)
• FE-ML-038: Crear componente ConsensusIndicator.tsx
• FE-ML-039: Crear componente ModelPerformance.tsx
• FE-ML-040: Crear componente ModelComparison.tsx (heatmap)
• FE-ML-041: Implementar auto-refresh cada 30 segundos
• FE-ML-042: Agregar indicadores visuales para outliers

Tests:

• TEST-ML-016: Test de cálculo de confianza combinada
• TEST-ML-017: Test de votación de modelos
• TEST-ML-018: Test E2E de vista ensemble
• TEST-ML-019: Test de detección de outliers

---

Dependencias

Depende de:

• RF-ML-003: Múltiples modelos ML entrenados (LSTM, RF, SVM, Transformer, GB)
• RF-ML-004: Sistema de pesos y scoring de modelos
• US-ML-001: Ver señal básica - Estado: Completado

Bloquea:

• US-ML-009: Configurar ensemble (admin puede cambiar pesos)
• US-ML-010: Histórico de ensemble signals

---

Notas Técnicas

Endpoints involucrados:

Método	Endpoint	Descripción
GET	/api/ml/ensemble/:symbol	Obtener señal ensemble actual
GET	/api/ml/ensemble/:symbol/models	Detalle de cada modelo
GET	/api/ml/ensemble/comparison	Heatmap de predicciones
GET	/api/ml/ensemble/:symbol/performance	Performance histórico

Query Parameters - Ensemble Signal:

GET /api/ml/ensemble/BTCUSDT?
  include_performance=true&
  include_comparison=false

Response esperado:

interface EnsembleSignalResponse {
  ensemble: {
    symbol: string;
    action: 'BUY' | 'SELL' | 'HOLD';
    confidence: number; // weighted average, 0-100
    score: number; // 0-10
    consensus_strength: 'STRONG' | 'MODERATE' | 'WEAK';
    timestamp: string;
    expires_at: string;

    entry_price: number;
    tp1: number;
    tp2: number;
    tp3: number;
    sl: number;
  };

  model_votes: {
    buy_count: number;
    sell_count: number;
    hold_count: number;
    total_models: number;
    buy_percentage: number;
    sell_percentage: number;
    hold_percentage: number;
  };

  models: ModelContribution[];

  consensus_analysis: {
    all_agree: boolean;
    minority_models: string[];
    agreement_percentage: number;
    description: string;
  };
}

interface ModelContribution {
  model_id: string;
  model_name: string;
  prediction: 'BUY' | 'SELL' | 'HOLD';
  score: number; // 0-100
  confidence: number; // 0-100
  weight: number; // 0-100, suma con otros = 100
  contribution: number; // score * weight
  is_outlier: boolean;

  performance?: ModelPerformance;
}

interface ModelPerformance {
  accuracy: number; // last 100 predictions
  win_rate: number; // last 7 days
  total_signals: number;
  correct_signals: number;
  trend: 'UP' | 'STABLE' | 'DOWN';
  last_updated: string;
}

Cálculos:

// Confianza combinada (weighted average)
ensemble_confidence = sum(model.score * model.weight) / 100

// Votación
buy_percentage = (buy_count / total_models) * 100

// Contribución de cada modelo
contribution = model.score * model.weight / 100

// Consenso
consensus_strength = all_models_agree ? 'STRONG' :
                     buy_percentage > 60 ? 'MODERATE' : 'WEAK'

Componentes UI:

• EnsembleSignal: Container principal
• EnsembleHeader: Decisión + confianza + consenso
• ModelVoting: Distribución de votos (barras)
• ModelContributions: Tabla detallada
• ConsensusIndicator: Visual de acuerdo
• ModelPerformance: Stats históricos
• ModelComparison: Heatmap
• OutlierBadge: Indicador de predicción minoritaria

Estado (Zustand):

interface EnsembleStore {
  ensemble: EnsembleSignalResponse | null;
  selectedSymbol: string;
  isLoading: boolean;
  lastUpdated: string;
  autoRefreshInterval: number; // 30000 ms

  fetchEnsemble: (symbol: string) => Promise<void>;
  setAutoRefresh: (enabled: boolean) => void;
  compareModels: () => void;
}

---

Definition of Ready (DoR)

• Historia claramente escrita (quién, qué, por qué)
• Criterios de aceptación definidos
• Story points estimados
• Dependencias identificadas
• Modelos ML disponibles (LSTM, RF, SVM, Transformer, GB)
• Diseño/mockup disponible

Definition of Done (DoD)

• Código implementado según criterios
• Tests unitarios escritos y pasando (>80% coverage)
• Tests E2E pasando
• Code review aprobado
• Documentación actualizada
• QA aprobado en staging
• Auto-refresh funciona sin memory leaks
• Performance: carga < 1.5s
• Mobile responsive
• Outliers detectados y resaltados correctamente
• Desplegado en producción

---

Historial de Cambios

Fecha	Cambio	Autor
2026-01-25	Creación	Requirements-Analyst

---

Creada por: Requirements-Analyst Fecha: 2026-01-25 Última actualización: 2026-01-25