# _MAP: OQI-006 - Señales ML

**Última actualización:** 2025-12-05
**Estado:** Parcialmente Implementado
**Versión:** 1.0.0

---

## Propósito

Esta épica implementa el sistema de predicciones y señales de trading basado en Machine Learning, utilizando modelos XGBoost para predecir rangos de precio y generar señales de entrada/salida.

---

## Contenido del Directorio

```
OQI-006-ml-signals/
├── README.md                    # Documentación técnica existente
├── _MAP.md                      # Este archivo - índice
├── requerimientos/              # Documentos de requerimientos funcionales
│   ├── RF-ML-001-predicciones.md    # Predicción de precios
│   ├── RF-ML-002-senales.md         # Generación de señales
│   ├── RF-ML-003-indicadores.md     # Indicadores técnicos
│   ├── RF-ML-004-entrenamiento.md   # Pipeline de entrenamiento
│   └── RF-ML-005-notificaciones.md  # Alertas de señales
├── especificaciones/            # Especificaciones técnicas
│   ├── ET-ML-001-arquitectura.md    # Arquitectura ML
│   ├── ET-ML-002-modelos.md         # Modelos XGBoost
│   ├── ET-ML-003-features.md        # Feature engineering
│   ├── ET-ML-004-api.md             # FastAPI endpoints
│   └── ET-ML-005-integracion.md     # Integración con backend
├── historias-usuario/           # User Stories (5 prioritarias documentadas)
│   ├── US-ML-001-ver-prediccion.md      # ✅ P0 - 5 SP
│   ├── US-ML-002-ver-senal.md           # ✅ P0 - 5 SP
│   ├── US-ML-004-ver-accuracy.md        # ✅ P1 - 3 SP
│   ├── US-ML-006-senal-en-chart.md      # ✅ P0 - 5 SP
│   └── US-ML-007-historial-senales.md   # ✅ P1 - 3 SP
└── implementacion/              # Trazabilidad de implementación
    └── TRACEABILITY.yml
```

---

## Requerimientos Funcionales

| ID | Nombre | Prioridad | SP | Estado |
|----|--------|-----------|-----|--------|
| RF-ML-001 | Predicción de Precios | P0 | 10 | ✅ Implementado + Documentado |
| RF-ML-002 | Generación de Señales | P0 | 10 | ✅ Implementado + Documentado |
| RF-ML-003 | Indicadores Técnicos | P1 | 5 | ✅ Implementado + Documentado |
| RF-ML-004 | Pipeline de Entrenamiento | P1 | 8 | ✅ Implementado + Documentado |
| RF-ML-005 | Alertas de Señales | P2 | 7 | ✅ Documentado |

**Total:** 40 SP (100% documentados)

---

## Especificaciones Técnicas

| ID | Nombre | Componente | Estado |
|----|--------|------------|--------|
| ET-ML-001 | Arquitectura | ML Engine | ✅ Documentado |
| ET-ML-002 | Modelos XGBoost | ML Engine | ✅ Documentado |
| ET-ML-003 | Feature Engineering | ML Engine | ✅ Documentado |
| ET-ML-004 | FastAPI Endpoints | FastAPI | ✅ Documentado |
| ET-ML-005 | Integración Backend | Backend | ✅ Documentado |

**Total:** 5 ET (100% documentados)

---

## Historias de Usuario

### Historias Prioritarias (Documentadas)

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-ML-001 | Ver predicción de precio | P0 | 5 | ✅ Documentado |
| US-ML-002 | Ver señal de trading | P0 | 5 | ✅ Documentado |
| US-ML-004 | Ver accuracy del modelo | P1 | 3 | ✅ Documentado |
| US-ML-006 | Ver señal en el chart | P0 | 5 | ✅ Documentado |
| US-ML-007 | Ver historial de señales | P1 | 3 | ✅ Documentado |

**Subtotal:** 21 SP documentados

### Historias Adicionales (Pendientes)

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-ML-003 | Configurar alertas de señales | P1 | 3 | Pendiente |
| US-ML-005 | Ver indicadores técnicos | P1 | 3 | Pendiente |
| US-ML-008 | Filtrar por confianza | P2 | 2 | Pendiente |
| US-ML-009 | Exportar señales a CSV | P2 | 2 | Pendiente |
| US-ML-010 | Recibir notificación push | P2 | 5 | Pendiente |

**Total:** 40 SP (21 documentados + 19 restantes)

---

## Modelos Implementados

### RangePredictor
- **Algoritmo:** XGBoost Regressor
- **Predice:** ΔHigh/ΔLow (rango de precio)
- **Features:** 21
- **Accuracy:** MAE 0.1% - 2%

### TPSLClassifier
- **Algoritmo:** XGBoost Classifier
- **Predice:** Take Profit vs Stop Loss primero
- **Features:** 15
- **Accuracy:** 68%

### SignalGenerator
- **Algoritmo:** Ensemble
- **Predice:** Señales de entrada (buy/sell/hold)
- **Features:** 21
- **Accuracy:** 65%

---

## Features Implementadas

### Volatilidad
- `volatility_5`, `volatility_10`, `volatility_20`, `volatility_50`
- `atr_5`, `atr_10`, `atr_20`, `atr_50`

### Momentum
- `momentum_5`, `momentum_10`, `momentum_20`
- `roc_5`, `roc_10`, `roc_20`

### Medias Móviles
- `sma_5`, `sma_10`, `sma_20`, `sma_50`
- `ema_5`, `ema_10`, `ema_20`, `ema_50`
- `sma_ratio_*`

### Indicadores
- `rsi_14` - Relative Strength Index
- `macd`, `macd_signal`, `macd_histogram`
- `bb_position` - Bollinger Bands

---

## Horizontes de Predicción

| Horizonte | Candles (5min) | Tiempo | Uso |
|-----------|----------------|--------|-----|
| Scalping | 6 | 30 min | Trading rápido |
| Intraday | 18 | 90 min | Day trading |
| Swing | 36 | 3 horas | Swing trading |
| Position | 72 | 6 horas | Posiciones largas |

---

## Dependencias

### Depende de:

- **OQI-001:** Autenticación - ✅ Completado
- **OQI-003:** Trading/Charts - Para mostrar señales

### Bloquea:

- **OQI-004:** Investment (agentes usan señales)

---

## Stack Técnico

| Capa | Tecnología | Uso |
|------|------------|-----|
| ML Engine | Python 3.11 + FastAPI | API de predicciones |
| Models | XGBoost 2.x | Algoritmos ML |
| Data | Pandas + NumPy | Procesamiento |
| Market Data | Binance API | Datos en tiempo real |

---

## Límites por Plan

| Plan | Señales/día | Horizontes | Símbolos |
|------|-------------|------------|----------|
| Free | 3 | Scalping | BTCUSDT |
| Basic | 10 | Scalping, Intraday | BTC, ETH |
| Pro | Ilimitado | Todos | Todos |
| Premium | Ilimitado + API | Todos + Custom | Todos |

---

## Criterios de Aceptación

### Funcionales

- [ ] Predicciones disponibles para BTCUSDT y ETHUSDT
- [ ] 4 horizontes temporales funcionando
- [ ] Señales con nivel de confianza
- [ ] Indicadores técnicos en tiempo real
- [ ] Alertas configurables por usuario
- [ ] Señales mostradas en charts

### No Funcionales

- [ ] Predicción en < 500ms
- [ ] Entrenamiento automático diario
- [ ] 99.5% uptime del ML Engine

### Técnicos

- [ ] Cobertura de tests > 70%
- [ ] Métricas de accuracy en dashboard admin
- [ ] Logs de predicciones para auditoría

---

## Hitos

| Hito | Entregables | Target |
|------|-------------|--------|
| M1 | ML Engine funcionando | Sprint 7 ✅ |
| M2 | Integración con backend | Sprint 7 |
| M3 | Señales en charts | Sprint 8 |
| M4 | Alertas + notificaciones | Sprint 8 |

---

## Referencias

- [README Técnico](./README.md)
- [Vision del Producto](../../00-vision-general/VISION-PRODUCTO.md)
- [_MAP Fase MVP](../_MAP.md)
- [ML Engine Config](../../../../apps/ml-engine/config/)