trading-platform-ml-engine-v2/README.md

# Trading Platform ML Engine

Motor de Machine Learning para predicciones y senales de trading en Trading Platform.

## Stack Tecnologico

- **Lenguaje:** Python 3.10+
- **Framework API:** FastAPI + Uvicorn
- **Deep Learning:** PyTorch 2.0+
- **Gradient Boosting:** XGBoost 2.0+ (CUDA support)
- **Data Processing:** Pandas, NumPy, PyArrow
- **Async DB:** Motor (MongoDB async driver)

## Estructura del Proyecto

```
ml-engine/
├── config/               # Configuracion YAML
│   ├── database.yaml     # Conexion a bases de datos
│   ├── models.yaml       # Parametros de modelos
│   ├── trading.yaml      # Configuracion de trading
│   └── validation_oos.yaml # Validacion out-of-sample
├── models/               # Modelos entrenados y reportes
│   ├── attention/        # Modelos con mecanismo de atencion
│   ├── metamodels/       # Meta-modelos (ensemble)
│   ├── symbol_timeframe_models/ # Modelos por simbolo/timeframe
│   └── *.md              # Reportes de entrenamiento
├── src/
│   ├── api/              # Endpoints FastAPI
│   ├── backtesting/      # Motor de backtesting
│   ├── config/           # Carga de configuracion
│   ├── data/             # Data loaders y procesamiento
│   ├── models/           # Definiciones de modelos
│   ├── pipelines/        # Pipelines de ML
│   ├── services/         # Servicios de negocio
│   ├── training/         # Logica de entrenamiento
│   └── utils/            # Utilidades
├── tests/                # Tests pytest
├── charts/               # Graficos generados
├── logs/                 # Logs de ejecucion
└── reports/              # Reportes de backtesting
```

## Instalacion

### Con Conda (Recomendado)

```bash
# Crear entorno desde environment.yml
conda env create -f environment.yml
conda activate trading-ml

# O instalar dependencias manualmente
pip install -r requirements.txt
```

### Variables de Entorno

```bash
cp .env.example .env
```

```env
# API
ML_ENGINE_HOST=0.0.0.0
ML_ENGINE_PORT=8000

# Database
MONGO_URI=mongodb://localhost:27017
POSTGRES_URI=postgresql://user:pass@localhost:5432/trading

# GPU (opcional)
CUDA_VISIBLE_DEVICES=0

# Logging
LOG_LEVEL=INFO

# Trading Data
POLYGON_API_KEY=your_polygon_key
```

## Scripts Disponibles

```bash
# Iniciar API server
python -m uvicorn src.api.main:app --reload --port 8000

# Entrenamiento de modelos
python -m src.training.train_models --config config/models.yaml

# Backtesting
python -m src.backtesting.run_backtest --symbol BTCUSD --timeframe 1h

# Tests
pytest tests/ -v
```

## Modelos Implementados

### Attention Models
- **TemporalAttention:** Atencion temporal para series de tiempo
- **MultiHeadAttention:** Atencion multi-cabeza para features

### XGBoost Models
- **DirectionalClassifier:** Prediccion de direccion (LONG/SHORT/NEUTRAL)
- **ProbabilisticRegressor:** Estimacion de probabilidad de movimiento

### Meta-Models
- **EnsembleVoting:** Combinacion de modelos por votacion
- **StackedEnsemble:** Stacking de predicciones

## API Endpoints

### Predicciones

```
GET  /api/v1/predictions/{symbol}
POST /api/v1/predictions/batch
```

### Senales

```
GET  /api/v1/signals/active
GET  /api/v1/signals/{symbol}/history
```

### Health

```
GET  /api/v1/health
GET  /api/v1/models/status
```

## Configuracion de Modelos

```yaml
# config/models.yaml
models:
  attention:
    hidden_size: 256
    num_heads: 8
    dropout: 0.1

  xgboost:
    n_estimators: 500
    max_depth: 8
    learning_rate: 0.01

features:
  lookback_periods: [5, 10, 20, 50, 100]
  technical_indicators:
    - RSI
    - MACD
    - Bollinger
    - ATR
```

## Backtesting

```bash
# Backtest simple
python -m src.backtesting.run_backtest \
  --symbol BTCUSD \
  --timeframe 1h \
  --start 2024-01-01 \
  --end 2024-12-31

# Backtest con parametros custom
python -m src.backtesting.run_backtest \
  --config config/validation_oos.yaml \
  --output reports/backtest_$(date +%Y%m%d).json
```

## Entrenamiento

### Entrenamiento Completo

```bash
python -m src.training.train_models \
  --symbols BTCUSD ETHUSD \
  --timeframes 1h 4h \
  --epochs 100 \
  --output models/
```

### Entrenamiento Incremental

```bash
python -m src.training.incremental_train \
  --model-path models/attention/latest.pt \
  --new-data data/recent/
```

## Testing

```bash
# Tests unitarios
pytest tests/unit/ -v

# Tests de integracion
pytest tests/integration/ -v

# Coverage
pytest --cov=src tests/
```

## Docker

```bash
# Build imagen
docker build -t trading-ml-engine .

# Ejecutar con GPU
docker run --gpus all -p 8000:8000 trading-ml-engine

# Sin GPU
docker run -p 8000:8000 trading-ml-engine
```

## Metricas y Monitoreo

- **Precision de Direccion:** > 55% target
- **Sharpe Ratio:** > 1.5 target
- **Max Drawdown:** < 15% limite

Logs en `logs/` con formato JSON para integracion con sistemas de monitoreo.

## Documentacion Relacionada

- [Analisis ML Vuelta 1](../../docs/99-analisis/ML-MODELOS-VUELTA1-ANALISIS.md)
- [Analisis ML Vuelta 2](../../docs/99-analisis/ML-MODELOS-VUELTA2-ANALISIS.md)
- [Analisis ML Final](../../docs/99-analisis/ML-MODELOS-VUELTA3-FINAL.md)
- [Inventario ML](../../docs/90-transversal/inventarios/ML_INVENTORY.yml)
- [Especificacion Factores de Atencion](../../docs/99-analisis/ET-ML-FACTORES-ATENCION-SPEC.md)
- [Reporte BTCUSD Fase 11](../../docs/99-analisis/REPORTE-ENTREGA-FASE11-BTCUSD.md)

---

**Proyecto:** Trading Platform
**Version:** 0.1.0
**Actualizado:** 2026-01-07