# TRACEABILITY.yml - OQI-006 Senales ML
# Mapeo de requerimientos a implementacion

version: "1.7.0"
epic: OQI-006
name: "Senales ML y Predicciones"
updated: "2026-01-07"
status: completed

# Changelog
changelog:
  - version: "1.7.0"
    date: "2026-01-07"
    changes:
      - "Corregido mapeo US-ML-004: cambiado de RF-ML-005 a RF-ML-001"
      - "Agregado mapeo ET-ML-006 (Enhanced Range Predictor) a RF-ML-001"
      - "Agregado mapeo ET-ML-007 (Hierarchical Attention) a RF-ML-001, RF-ML-002"
      - "Validacion de alineacion documentacion-codigo completada"
  - version: "1.6.0"
    date: "2026-01-07"
    changes:
      - "Cross-validation EURUSD: conservative +0.0780 expectancy, 48.2% WR"
      - "Neural Gating Network arquitectura implementada"
      - "Documentacion final de resultados multi-activo"
      - "OBJETIVO LOGRADO: Expectancy positiva validada en 2 activos"
  - version: "1.5.0"
    date: "2026-01-07"
    changes:
      - "V2 MEJORAS: Lograda expectancy POSITIVA (+0.0284)"
      - "3 estrategias rentables: conservative, dynamic_rr, aggressive_filter"
      - "Implementado R:R dinamico basado en delta_high/delta_low"
      - "Win Rate mejorado de 42% a 46.9%"
  - version: "1.4.0"
    date: "2026-01-07"
    changes:
      - "FASE 4 completada: Pipeline jerarquico, servicio predictor, backtesting"
      - "Resultados backtesting: Win Rate 42% (PASS), Expectancy -0.04 (FAIL)"
      - "Hallazgo: Medium attention tiene mejor win rate que High attention"
  - version: "1.3.0"
    date: "2026-01-07"
    changes:
      - "Nivel 2 (Metamodelo) implementado para XAUUSD y EURUSD"
  - version: "1.2.0"
    date: "2026-01-07"
    changes:
      - "Nivel 1 (Base Models) con attention features implementado"
  - version: "1.1.0"
    date: "2026-01-06"
    changes:
      - "Nivel 0 (Attention Model) implementado"

# Resumen de trazabilidad
summary:
  total_requirements: 5
  total_specs: 7
  total_user_stories: 7
  total_files_to_implement: 48
  test_coverage: "TBD"
  story_points: 40

# Mapeo de Requerimientos Funcionales
requirements:
  RF-ML-001:
    name: "Predicciones de Precio"
    status: pending
    specs:
      - ET-ML-001
      - ET-ML-002
      - ET-ML-006
      - ET-ML-007
    user_stories:
      - US-ML-001
      - US-ML-004
    implementation:
      ml_engine:
        - path: ml-engine/services/prediction_service.py
          description: "Servicio de predicciones"
          methods:
            - get_prediction
            - get_predictions_batch
            - get_prediction_history
            - invalidate_cache
        - path: ml-engine/models/lstm_predictor.py
          description: "Modelo LSTM de predicción"
          methods:
            - predict
            - train
            - evaluate
        - path: ml-engine/models/transformer_predictor.py
          description: "Modelo Transformer de predicción"
          methods:
            - predict
            - train
            - evaluate
      backend:
        - path: apps/backend/src/modules/ml/services/ml-proxy.service.ts
          description: "Proxy al ML Engine"
          methods:
            - getPrediction
            - getPredictionsBatch
        - path: apps/backend/src/modules/ml/controllers/ml.controller.ts
          methods:
            - getPrediction
        - path: apps/backend/src/modules/ml/ml.routes.ts
          routes:
            - "GET /ml/predictions/:symbol"
            - "POST /ml/predictions/batch"
      frontend:
        - path: apps/frontend/src/modules/trading/components/MLOverlay.tsx
          description: "Overlay de predicciones en chart"
        - path: apps/frontend/src/modules/trading/components/PredictionPanel.tsx
          description: "Panel de predicciones"
      database:
        - path: apps/database/schemas/06_ml_schema.sql
          tables:
            - predictions
            - prediction_accuracy
          enums:
            - prediction_type_enum
            - prediction_horizon_enum
    tests:
      - path: ml-engine/tests/test_prediction_service.py
        status: pending

  RF-ML-002:
    name: "Señales de Trading"
    status: pending
    specs:
      - ET-ML-001
      - ET-ML-004
    user_stories:
      - US-ML-002
      - US-ML-006
      - US-ML-007
    implementation:
      ml_engine:
        - path: ml-engine/services/signal_service.py
          description: "Servicio de señales"
          methods:
            - generate_signal
            - get_active_signals
            - get_signal_history
            - evaluate_signal
        - path: ml-engine/strategies/momentum_strategy.py
          description: "Estrategia de momentum ML"
        - path: ml-engine/strategies/mean_reversion_strategy.py
          description: "Estrategia de reversión a la media"
        - path: ml-engine/strategies/amd_strategy.py
          description: "Estrategia AMD (Accumulation/Manipulation/Distribution)"
      backend:
        - path: apps/backend/src/modules/ml/services/signal.service.ts
          description: "Servicio de señales"
          methods:
            - getSignals
            - getActiveSignals
            - getSignalHistory
            - subscribeToSignals
        - path: apps/backend/src/modules/ml/controllers/ml.controller.ts
          methods:
            - getSignals
            - getSignalById
        - path: apps/backend/src/modules/ml/ml.routes.ts
          routes:
            - "GET /ml/signals"
            - "GET /ml/signals/:id"
            - "GET /ml/signals/history"
      frontend:
        - path: apps/frontend/src/modules/trading/pages/Signals.tsx
          description: "Página de señales"
        - path: apps/frontend/src/modules/trading/components/SignalCard.tsx
          description: "Tarjeta de señal"
        - path: apps/frontend/src/modules/trading/components/SignalList.tsx
          description: "Lista de señales"
        - path: apps/frontend/src/modules/trading/components/SignalOverlay.tsx
          description: "Overlay de señales en chart"
      database:
        - path: apps/database/schemas/06_ml_schema.sql
          tables:
            - signals
            - signal_outcomes
          enums:
            - signal_type_enum
            - signal_strength_enum
            - signal_status_enum
    tests:
      - path: ml-engine/tests/test_signal_service.py
        status: pending

  RF-ML-003:
    name: "Indicadores ML"
    status: pending
    specs:
      - ET-ML-003
    user_stories: []
    implementation:
      ml_engine:
        - path: ml-engine/indicators/ml_trend_indicator.py
          description: "Indicador de tendencia ML"
        - path: ml-engine/indicators/ml_volatility_indicator.py
          description: "Indicador de volatilidad ML"
        - path: ml-engine/indicators/amd_zone_indicator.py
          description: "Indicador de zonas AMD"
        - path: ml-engine/indicators/smart_money_indicator.py
          description: "Indicador de Smart Money"
      backend:
        - path: apps/backend/src/modules/ml/services/ml-indicator.service.ts
          description: "Servicio de indicadores ML"
          methods:
            - getMLIndicators
            - getIndicatorData
        - path: apps/backend/src/modules/ml/ml.routes.ts
          routes:
            - "GET /ml/indicators/:symbol"
      frontend:
        - path: apps/frontend/src/modules/trading/components/AMDZoneIndicator.tsx
          description: "Indicador de zonas AMD"
        - path: apps/frontend/src/modules/trading/components/MLTrendIndicator.tsx
          description: "Indicador de tendencia ML"
      database:
        - path: apps/database/schemas/06_ml_schema.sql
          tables:
            - ml_indicators
            - amd_zones
    tests:
      - path: ml-engine/tests/test_ml_indicators.py
        status: pending

  RF-ML-004:
    name: "Entrenamiento de Modelos"
    status: pending
    specs:
      - ET-ML-002
    user_stories: []
    implementation:
      ml_engine:
        - path: ml-engine/training/train_lstm.py
          description: "Script de entrenamiento LSTM"
        - path: ml-engine/training/train_transformer.py
          description: "Script de entrenamiento Transformer"
        - path: ml-engine/training/hyperparameter_tuning.py
          description: "Optimización de hiperparámetros"
        - path: ml-engine/training/model_registry.py
          description: "Registro de modelos"
        - path: ml-engine/data/feature_engineering.py
          description: "Ingeniería de features"
        - path: ml-engine/data/data_pipeline.py
          description: "Pipeline de datos"
      database:
        - path: apps/database/schemas/06_ml_schema.sql
          tables:
            - ml_models
            - model_versions
            - training_runs
            - feature_sets
          enums:
            - model_type_enum
            - model_status_enum
    tests:
      - path: ml-engine/tests/test_training.py
        status: pending

  RF-ML-005:
    name: "Notificaciones de Señales"
    status: pending
    specs:
      - ET-ML-005
    user_stories: []
    implementation:
      backend:
        - path: apps/backend/src/modules/ml/services/notification.service.ts
          description: "Servicio de notificaciones ML"
          methods:
            - notifySignal
            - subscribeToAlerts
            - unsubscribeFromAlerts
            - getNotificationPreferences
        - path: apps/backend/src/modules/ml/controllers/ml.controller.ts
          methods:
            - setNotificationPreferences
            - getNotificationPreferences
        - path: apps/backend/src/modules/ml/ml.routes.ts
          routes:
            - "GET /ml/notifications/preferences"
            - "PUT /ml/notifications/preferences"
            - "POST /ml/notifications/subscribe"
      frontend:
        - path: apps/frontend/src/modules/settings/components/SignalNotifications.tsx
          description: "Configuración de notificaciones de señales"
      database:
        - path: apps/database/schemas/06_ml_schema.sql
          tables:
            - signal_subscriptions
            - signal_notifications
    external:
      - service: Firebase Cloud Messaging
        usage: "Push notifications"
      - service: Twilio
        usage: "SMS notifications"
    tests:
      - path: apps/backend/tests/ml/notification.service.test.ts
        status: pending

# Modelos ML
ml_models:
  - name: LSTM Price Predictor
    type: lstm
    input: OHLCV + technical indicators
    output: Price prediction (1h, 4h, 1d)
    accuracy_target: ">60%"
  - name: Transformer Trend
    type: transformer
    input: Market data + sentiment
    output: Trend direction
    accuracy_target: ">55%"
  - name: AMD Zone Detector
    type: cnn
    input: Price action patterns
    output: AMD zones
    accuracy_target: ">65%"
  - name: Signal Generator
    type: ensemble
    input: All model outputs
    output: Trading signals
    accuracy_target: ">50% win rate"

# Feature Engineering
features:
  technical:
    - RSI (14, 21)
    - MACD
    - Bollinger Bands
    - ATR
    - VWAP
    - Volume Profile
  pattern:
    - Candlestick patterns
    - Chart patterns
    - Support/Resistance levels
  market:
    - Market sentiment
    - VIX
    - Correlation matrix
  custom:
    - AMD zones
    - Smart Money indicators
    - Order flow

# Mapeo de archivos de configuración
config_files:
  ml_engine:
    - path: ml-engine/config/model_config.yaml
      description: "Configuración de modelos"
    - path: ml-engine/config/training_config.yaml
      description: "Configuración de entrenamiento"
    - path: ml-engine/config/inference_config.yaml
      description: "Configuración de inferencia"
  backend:
    - path: apps/backend/src/modules/ml/ml.module.ts
      description: "Módulo ML"
    - path: apps/backend/src/modules/ml/types/ml.types.ts
      description: "Tipos TypeScript"
    - path: apps/backend/src/config/ml.config.ts
      description: "Configuración de conexión ML"
  frontend:
    - path: apps/frontend/src/modules/trading/stores/ml.store.ts
      description: "Store de ML Zustand"
    - path: apps/frontend/src/modules/trading/hooks/useMLSignals.ts
      description: "Hook de señales ML"

# Dependencias externas
external_dependencies:
  python:
    - name: torch
      version: "^2.1.0"
      usage: "Deep learning framework"
    - name: tensorflow
      version: "^2.15.0"
      usage: "Alternative DL framework"
    - name: scikit-learn
      version: "^1.3.0"
      usage: "ML utilities"
    - name: pandas
      version: "^2.1.0"
      usage: "Data manipulation"
    - name: numpy
      version: "^1.26.0"
      usage: "Numerical computing"
    - name: fastapi
      version: "^0.104.0"
      usage: "ML API server"
    - name: ta-lib
      version: "^0.4.28"
      usage: "Technical analysis"
  npm_backend:
    - name: axios
      version: "^1.6.0"
      usage: "HTTP client for ML Engine"
  npm_frontend:
    - name: lightweight-charts
      version: "^4.1.0"
      usage: "ML overlays en charts"

# APIs
api_endpoints:
  ml_engine:
    base_url: "http://localhost:8000/api/v1"
    endpoints:
      - method: GET
        path: /predict/:symbol
        description: "Obtener predicción"
      - method: POST
        path: /predict/batch
        description: "Predicciones en batch"
      - method: GET
        path: /signals
        description: "Señales activas"
      - method: GET
        path: /indicators/:symbol
        description: "Indicadores ML"
      - method: POST
        path: /train
        description: "Iniciar entrenamiento"
        auth: admin
  backend:
    base_path: /api/v1/ml
    endpoints:
      - method: GET
        path: /predictions/:symbol
        requirement: RF-ML-001
        auth: true
      - method: GET
        path: /signals
        requirement: RF-ML-002
        auth: true
      - method: GET
        path: /signals/:id
        requirement: RF-ML-002
        auth: true
      - method: GET
        path: /indicators/:symbol
        requirement: RF-ML-003
        auth: true
      - method: GET
        path: /accuracy
        requirement: RF-ML-001
        auth: true
      - method: PUT
        path: /notifications/preferences
        requirement: RF-ML-005
        auth: true

# Integración con TradingAgent existente
tradingagent_integration:
  source: "[LEGACY: /home/isem/workspace-old/UbuntuML/TradingAgent - migrado a apps/ml-engine]"
  components_to_migrate:
    - path: backend/market_data/
      target: ml-engine/data/
      status: pending
    - path: backend/ml_models/
      target: ml-engine/models/
      status: pending
    - path: backend/strategies/
      target: ml-engine/strategies/
      status: pending
    - path: backend/backtest/
      target: ml-engine/backtest/
      status: pending
  new_components:
    - AMD zone detection
    - Smart Money indicators
    - Signal aggregation
    - Real-time inference API

# Dependencias de épicas
dependencies:
  blocks:
    - epic: OQI-004
      reason: "Agentes de inversión usan señales ML"
    - epic: OQI-007
      reason: "LLM Agent consulta señales ML"
  blocked_by:
    - epic: OQI-001
      reason: "Requiere autenticación"
    - epic: OQI-003
      reason: "Requiere datos de trading/charts"

# Notas y decisiones
notes:
  - "ML Engine como microservicio Python separado"
  - "Modelos entrenados offline, inferencia en tiempo real"
  - "Cache de predicciones con TTL de 5 minutos"
  - "Señales generadas cada 15 minutos"
  - "Accuracy tracking para mejora continua"
  - "A/B testing de estrategias"
  - "Migrar componentes de TradingAgent gradualmente"

# Implementacion 2026-01-04
recent_changes:
  - date: "2026-01-07"
    developer: "Claude Code"
    spec: "ET-ML-007"
    changes:
      - type: ml_engine
        files:
          - apps/ml-engine/src/models/attention_score_model.py
          - apps/ml-engine/src/training/attention_trainer.py
          - apps/ml-engine/src/training/symbol_timeframe_trainer.py
          - apps/ml-engine/scripts/train_attention_model.py
          - apps/ml-engine/scripts/train_symbol_timeframe_models.py
        description: "Hierarchical Attention Architecture - Niveles 0 y 1"
        features:
          - "Modelo de Atencion (Nivel 0) con 9 features"
          - "Output dual: attention_score (0-3) + attention_class (low/med/high)"
          - "Target: move_multiplier = future_range / rolling_median"
          - "Integracion de attention features en modelos base (52 features)"
          - "Script train_attention_model.py con CLI args"
          - "Flag --use-attention en train_symbol_timeframe_models.py"
        metrics:
          attention_model:
            r2_regression: "0.12-0.22"
            classification_accuracy: "54-61%"
            feature_importance_top: "ATR_ratio (34-50%)"
          base_models:
            total_features: 52
            new_features: ["attention_score", "attention_class"]
    status: implemented
    pending_work:
      - "Tests unitarios para attention model"
      - "Integracion con FastAPI endpoints"

  - date: "2026-01-07"
    developer: "Claude Code"
    spec: "ET-ML-007"
    changes:
      - type: ml_engine
        files:
          - apps/ml-engine/src/models/asset_metamodel.py
          - apps/ml-engine/src/training/metamodel_trainer.py
          - apps/ml-engine/scripts/train_metamodels.py
        description: "Hierarchical Attention Architecture - Nivel 2 (Metamodelo)"
        features:
          - "AssetMetamodel con XGBoost Stacking"
          - "3 modelos: HIGH, LOW, CONFIDENCE"
          - "10 meta-features combinando 5m y 15m"
          - "Entrenamiento con OOS predictions"
          - "Script train_metamodels.py con CLI args"
        metrics:
          XAUUSD:
            samples: 18749
            mae_high: 2.0818
            mae_low: 2.2241
            r2_high: 0.0674
            r2_low: 0.1150
            confidence_accuracy: "90.01%"
            improvement_vs_avg: "+1.9%"
          EURUSD:
            samples: 19505
            mae_high: 0.0005
            mae_low: 0.0004
            r2_high: -0.0417
            r2_low: -0.0043
            confidence_accuracy: "86.26%"
            improvement_vs_avg: "+3.0%"
    status: implemented
    pending_work:
      - "FASE 4: Pipeline unificado y evaluacion"
      - "Tests unitarios para metamodel"
      - "Entrenar BTCUSD, GBPUSD, USDJPY"

  - date: "2026-01-04"
    developer: "Claude Code"
    changes:
      - type: frontend
        files:
          - apps/frontend/src/modules/trading/components/CandlestickChartWithML.tsx
          - apps/frontend/src/modules/trading/pages/Trading.tsx
        description: "Visualizacion de predicciones ML en graficos de trading"
        features:
          - "Lineas de precio para Entry/SL/TP de senales activas"
          - "Visualizacion de rango predicho (High/Low)"
          - "Indicador de fase AMD (Accumulation/Manipulation/Distribution)"
          - "Marcadores de senal en velas"
          - "Panel de controles ML con checkboxes para activar/desactivar capas"
          - "Auto-refresh de datos ML cada 30 segundos"
          - "Preparacion para Order Blocks y Fair Value Gaps"
    status: implemented
    pending_work:
      - "Implementar visualizacion de Order Blocks en chart"
      - "Implementar visualizacion de Fair Value Gaps"
      - "Conectar con API real del ML Engine (actualmente mock)"
      - "WebSocket para actualizaciones en tiempo real"

# Especificaciones Tecnicas Adicionales
specs_added:
  ET-ML-007:
    name: "Hierarchical Attention Architecture"
    date: "2026-01-07"
    description: "Arquitectura ML de 3 niveles jerarquicos"
    levels:
      - level: 0
        name: "AttentionScoreModel"
        status: implemented
        features_input: 9
        output: ["attention_score", "attention_class"]
      - level: 1
        name: "SymbolTimeframeModel"
        status: implemented
        features_input: 52
        enhancement: "attention features added"
      - level: 2
        name: "AssetMetamodel"
        status: implemented
        features_input: 10
        output: ["delta_high_final", "delta_low_final", "confidence"]
    fase_4_pipeline:
      date: "2026-01-07"
      files:
        - src/pipelines/hierarchical_pipeline.py
        - src/services/hierarchical_predictor.py
        - scripts/evaluate_hierarchical.py
      backtest_results:
        period: "2024-09-01 to 2024-12-31"
        symbols: ["XAUUSD", "EURUSD"]
        metrics:
          XAUUSD:
            win_rate: "42.1%"
            expectancy: "-0.042"
            total_signals: 2554
            status: "Win Rate PASS, Expectancy FAIL"
          EURUSD:
            win_rate: "41.5%"
            expectancy: "-0.043"
            total_signals: 2680
            filtered: "24.4%"
            status: "Win Rate PASS, Expectancy FAIL"
      findings:
        - "Win Rate improved from 22-25% baseline to 41-42%"
        - "Expectancy still negative (-0.04 vs target +0.10)"
        - "Medium attention has higher win rate than High attention"
        - "Attention filtering not aggressive enough"
      next_steps:
        - "Adjust attention threshold (filter high attention trades)"
        - "Use metamodel confidence_proba for filtering"
        - "Implement dynamic R:R using predicted deltas"
        - "Consider Neural Gating Network"
    trained_symbols: ["XAUUSD", "EURUSD"]
    pending_symbols: ["BTCUSD", "GBPUSD", "USDJPY"]
    training_date: "2026-01-07"
    saved_models:
      - "models/attention/"
      - "models/symbol_timeframe_models/"
      - "models/metamodels/XAUUSD/"
      - "models/metamodels/EURUSD/"