# TRACEABILITY.yml - OQI-006 Señales ML
# Mapeo de requerimientos a implementación

version: "1.0.0"
epic: OQI-006
name: "Señales ML y Predicciones"
updated: "2025-12-05"
status: pending

# Resumen de trazabilidad
summary:
  total_requirements: 5
  total_specs: 5
  total_user_stories: 7
  total_files_to_implement: 40
  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
    user_stories:
      - US-ML-001
    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:
      - US-ML-004
    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"