# ML_INVENTORY.yml - Inventario de Componentes ML Engine
# OrbiQuant IA Trading Platform
# Última actualización: 2025-12-05

metadata:
  version: "1.0.0"
  last_updated: "2025-12-05"
  epic: "OQI-006"
  description: "Inventario de modelos, features y servicios del ML Engine"

# ============================================
# MODELOS DE MACHINE LEARNING
# ============================================
models:
  - id: "ML-001"
    name: "PricePredictor"
    description: "Modelo de predicción de dirección de precio"
    type: "classification"
    framework: "PyTorch"
    input_features: 45
    output: "bullish/bearish/neutral"
    confidence_range: "0.0-1.0"
    horizons:
      - "1h"
      - "4h"
      - "1d"
    symbols_supported:
      - "stocks_us"
      - "crypto_major"
    training_frequency: "weekly"
    accuracy_target: "65%"
    related_rf: "RF-ML-001"
    status: "planned"

  - id: "ML-002"
    name: "TrendDetector"
    description: "Detector de tendencias y cambios de tendencia"
    type: "classification"
    framework: "PyTorch"
    input_features: 30
    output: "uptrend/downtrend/ranging"
    horizons:
      - "4h"
      - "1d"
      - "1w"
    related_rf: "RF-ML-002"
    status: "planned"

  - id: "ML-003"
    name: "VolatilityPredictor"
    description: "Predictor de volatilidad futura"
    type: "regression"
    framework: "PyTorch"
    input_features: 25
    output: "volatility_percent"
    related_rf: "RF-ML-003"
    status: "planned"

  - id: "ML-004"
    name: "SentimentAnalyzer"
    description: "Análisis de sentimiento de noticias"
    type: "classification"
    framework: "Transformers"
    model_base: "FinBERT"
    output: "positive/negative/neutral"
    related_rf: "RF-ML-004"
    status: "planned"

# ============================================
# FEATURES ENGINEERING
# ============================================
features:
  technical:
    - id: "FT-001"
      name: "rsi_14"
      description: "Relative Strength Index 14 períodos"
      type: "float"
      range: "0-100"

    - id: "FT-002"
      name: "macd_signal"
      description: "MACD Signal Line"
      type: "float"

    - id: "FT-003"
      name: "macd_histogram"
      description: "MACD Histogram"
      type: "float"

    - id: "FT-004"
      name: "bb_position"
      description: "Posición relativa en Bollinger Bands"
      type: "float"
      range: "0-1"

    - id: "FT-005"
      name: "sma_20_50_cross"
      description: "Cruce SMA 20/50"
      type: "int"
      values: "-1/0/1"

    - id: "FT-006"
      name: "atr_14"
      description: "Average True Range 14 períodos"
      type: "float"

    - id: "FT-007"
      name: "volume_ratio"
      description: "Ratio volumen actual vs promedio"
      type: "float"

    - id: "FT-008"
      name: "price_momentum"
      description: "Momentum de precio (ROC)"
      type: "float"

  market_structure:
    - id: "FM-001"
      name: "support_distance"
      description: "Distancia al soporte más cercano"
      type: "float"

    - id: "FM-002"
      name: "resistance_distance"
      description: "Distancia a la resistencia más cercana"
      type: "float"

    - id: "FM-003"
      name: "trend_strength"
      description: "Fuerza de la tendencia (ADX)"
      type: "float"
      range: "0-100"

  sentiment:
    - id: "FS-001"
      name: "news_sentiment"
      description: "Sentimiento de noticias recientes"
      type: "float"
      range: "-1 to 1"

    - id: "FS-002"
      name: "social_sentiment"
      description: "Sentimiento de redes sociales"
      type: "float"
      range: "-1 to 1"

    - id: "FS-003"
      name: "fear_greed_index"
      description: "Índice de miedo y codicia (crypto)"
      type: "int"
      range: "0-100"

# ============================================
# SERVICIOS ML
# ============================================
services:
  - id: "SVC-ML-001"
    name: "MLPredictionService"
    description: "Servicio principal de predicciones"
    framework: "FastAPI"
    endpoints:
      - path: "/predict/{symbol}"
        method: "GET"
        description: "Obtener predicción para símbolo"
      - path: "/predict/batch"
        method: "POST"
        description: "Predicciones en batch"
    related_et: "ET-ML-001"

  - id: "SVC-ML-002"
    name: "FeatureEngineering"
    description: "Cálculo y cache de features"
    framework: "Python"
    dependencies:
      - "pandas"
      - "numpy"
      - "ta-lib"
    related_et: "ET-ML-002"

  - id: "SVC-ML-003"
    name: "ModelTrainer"
    description: "Entrenamiento y actualización de modelos"
    framework: "PyTorch"
    schedule: "weekly"
    related_et: "ET-ML-003"

  - id: "SVC-ML-004"
    name: "ModelRegistry"
    description: "Registro y versionado de modelos"
    framework: "MLflow"
    storage: "S3"
    related_et: "ET-ML-004"

# ============================================
# PIPELINES
# ============================================
pipelines:
  - id: "PIP-001"
    name: "RealTimePrediction"
    description: "Pipeline de predicción en tiempo real"
    steps:
      - "fetch_market_data"
      - "calculate_features"
      - "normalize_features"
      - "run_inference"
      - "post_process"
      - "cache_result"
    latency_target: "< 500ms"

  - id: "PIP-002"
    name: "DailyRetrain"
    description: "Pipeline de reentrenamiento diario"
    steps:
      - "fetch_training_data"
      - "feature_engineering"
      - "train_model"
      - "evaluate_model"
      - "register_if_improved"
    schedule: "daily"

  - id: "PIP-003"
    name: "BatchPrediction"
    description: "Pipeline de predicción en batch"
    steps:
      - "fetch_symbols_list"
      - "parallel_feature_calc"
      - "batch_inference"
      - "store_results"
    schedule: "every_4h"

# ============================================
# CONFIGURACIÓN
# ============================================
config:
  inference:
    cache_ttl: 60  # segundos
    batch_size: 100
    timeout: 5000  # ms

  training:
    train_test_split: 0.8
    validation_split: 0.1
    epochs: 100
    early_stopping_patience: 10

  features:
    lookback_periods:
      short: 20
      medium: 50
      long: 200
    normalization: "min_max"

# ============================================
# MÉTRICAS Y MONITOREO
# ============================================
metrics:
  model_performance:
    - name: "accuracy"
      target: "> 0.65"
    - name: "precision"
      target: "> 0.60"
    - name: "recall"
      target: "> 0.60"
    - name: "f1_score"
      target: "> 0.60"

  service_health:
    - name: "latency_p99"
      target: "< 1000ms"
    - name: "availability"
      target: "> 99.5%"
    - name: "error_rate"
      target: "< 1%"

# ============================================
# INTEGRACIÓN CON TRADINGAGENT
# ============================================
tradingagent_integration:
  description: "Migración del ML Engine existente de TradingAgent"
  source_repo: "tradingagent"
  components_to_migrate:
    - name: "PredictionEngine"
      source: "tradingagent/ml/prediction_engine.py"
      target: "apps/ml-engine/src/prediction/"
      status: "planned"

    - name: "FeatureCalculator"
      source: "tradingagent/ml/features.py"
      target: "apps/ml-engine/src/features/"
      status: "planned"

    - name: "ModelLoader"
      source: "tradingagent/ml/model_loader.py"
      target: "apps/ml-engine/src/models/"
      status: "planned"

  api_compatibility:
    description: "Mantener compatibilidad con API existente"
    endpoints_to_preserve:
      - "/api/v1/predict"
      - "/api/v1/signals"
      - "/api/v1/features"

# ============================================
# REFERENCIAS
# ============================================
references:
  requirements:
    - "docs/02-definicion-modulos/OQI-006-ml-signals/requerimientos/"
  specifications:
    - "docs/02-definicion-modulos/OQI-006-ml-signals/especificaciones/"
  traceability:
    - "docs/02-definicion-modulos/OQI-006-ml-signals/implementacion/TRACEABILITY.yml"