rckrdmrd
a7cca885f0
Changes include: - Updated architecture documentation - Enhanced module definitions (OQI-001 to OQI-008) - ML integration documentation updates - Trading strategies documentation - Orchestration and inventory updates - Docker configuration updates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
301 lines
8.4 KiB
Markdown
301 lines
8.4 KiB
Markdown
---
|
||
id: "RF-ML-001"
|
||
title: "Predicciones de Rangos de Precio"
|
||
type: "Requirement"
|
||
status: "Done"
|
||
priority: "Alta"
|
||
epic: "OQI-006"
|
||
project: "trading-platform"
|
||
version: "1.0.0"
|
||
created_date: "2025-12-05"
|
||
updated_date: "2026-01-04"
|
||
---
|
||
|
||
# RF-ML-001: Predicciones de Rangos de Precio
|
||
|
||
**Versión:** 1.0.0
|
||
**Fecha:** 2025-12-05
|
||
**Épica:** OQI-006 - Señales ML y Predicciones
|
||
**Prioridad:** P0
|
||
**Story Points:** 10
|
||
|
||
---
|
||
|
||
## Descripción
|
||
|
||
El sistema debe proporcionar predicciones de rangos de precio futuros (máximo y mínimo esperados) para diferentes horizontes temporales utilizando modelos de Machine Learning basados en XGBoost. Las predicciones deben incluir niveles de confianza y actualizarse en tiempo real.
|
||
|
||
---
|
||
|
||
## Requisitos Funcionales
|
||
|
||
### RF-ML-001.1: Modelo de Predicción XGBoost
|
||
|
||
El sistema debe:
|
||
- Utilizar XGBoost para predecir `max_ratio` y `min_ratio`
|
||
- Entrenar dos modelos independientes (uno para máximos, otro para mínimos)
|
||
- Configuración del modelo:
|
||
- `n_estimators`: 100 árboles
|
||
- `max_depth`: 6 niveles
|
||
- `learning_rate`: 0.1
|
||
- `subsample`: 0.8
|
||
- `colsample_bytree`: 0.8
|
||
|
||
### RF-ML-001.2: Horizontes de Predicción
|
||
|
||
El sistema debe soportar 4 horizontes temporales:
|
||
|
||
| Horizonte | Candles (5min) | Tiempo Total | Uso Típico |
|
||
|-----------|----------------|--------------|------------|
|
||
| **Scalping** | 6 | 30 minutos | Trading rápido intraday |
|
||
| **Intraday** | 18 | 90 minutos | Day trading activo |
|
||
| **Swing** | 36 | 3 horas | Posiciones de días |
|
||
| **Position** | 72 | 6 horas | Posiciones largas |
|
||
|
||
### RF-ML-001.3: Cálculo de Predicciones
|
||
|
||
El sistema debe calcular:
|
||
|
||
**Precio Máximo Esperado:**
|
||
```
|
||
predicted_high = current_price × (1 + max_ratio)
|
||
```
|
||
|
||
**Precio Mínimo Esperado:**
|
||
```
|
||
predicted_low = current_price × (1 - min_ratio)
|
||
```
|
||
|
||
**Nivel de Confianza:**
|
||
```
|
||
confidence = f(MAE, RMSE, horizon)
|
||
- Scalping: ~0.69 (mayor confianza)
|
||
- Intraday: ~0.59
|
||
- Swing: ~0.45
|
||
- Position: ~0.45 (menor confianza)
|
||
```
|
||
|
||
### RF-ML-001.4: Features del Modelo
|
||
|
||
El sistema debe calcular 30+ features técnicas agrupadas en:
|
||
|
||
**Volatilidad (8 features):**
|
||
- `volatility_5`, `volatility_10`, `volatility_20`, `volatility_50`
|
||
- `atr_5`, `atr_10`, `atr_20`, `atr_50`
|
||
|
||
**Momentum (6 features):**
|
||
- `momentum_5`, `momentum_10`, `momentum_20`
|
||
- `roc_5`, `roc_10`, `roc_20`
|
||
|
||
**Medias Móviles (12 features):**
|
||
- SMA: `sma_5`, `sma_10`, `sma_20`, `sma_50`
|
||
- EMA: `ema_5`, `ema_10`, `ema_20`, `ema_50`
|
||
- Ratios: `sma_ratio_5`, `sma_ratio_10`, `sma_ratio_20`, `sma_ratio_50`
|
||
|
||
**Indicadores Técnicos (4 features):**
|
||
- `rsi_14` - Relative Strength Index
|
||
- `macd`, `macd_signal`, `macd_histogram`
|
||
- `bb_position` - Posición en Bollinger Bands
|
||
|
||
**Volumen (1 feature):**
|
||
- `volume_ratio` - Ratio vs SMA 20 períodos
|
||
|
||
**High/Low (6+ features):**
|
||
- `hl_range_pct` - Rango high-low como porcentaje
|
||
- `high_distance`, `low_distance`
|
||
- `hist_max_ratio_*`, `hist_min_ratio_*`
|
||
|
||
### RF-ML-001.5: Métricas de Precisión
|
||
|
||
El sistema debe rastrear métricas de entrenamiento:
|
||
|
||
| Métrica | Descripción | Valor Aceptable |
|
||
|---------|-------------|-----------------|
|
||
| `high_mae` | Mean Absolute Error para máximos | < 2% |
|
||
| `high_rmse` | Root Mean Squared Error para máximos | < 2.5% |
|
||
| `low_mae` | Mean Absolute Error para mínimos | < 2% |
|
||
| `low_rmse` | Root Mean Squared Error para mínimos | < 2.5% |
|
||
|
||
### RF-ML-001.6: Actualización en Tiempo Real
|
||
|
||
El sistema debe:
|
||
- Recalcular predicciones cada vez que se cierra una nueva vela de 5 minutos
|
||
- Mantener WebSocket activo en `/ws/{symbol}` para streaming de predicciones
|
||
- Enviar actualizaciones automáticas a clientes conectados
|
||
- Incluir timestamp de la predicción en formato ISO 8601
|
||
|
||
---
|
||
|
||
## Datos de Entrada
|
||
|
||
| Campo | Tipo | Descripción | Requerido |
|
||
|-------|------|-------------|-----------|
|
||
| symbol | string | Par de trading (ej: BTCUSDT) | Sí |
|
||
| horizon | enum | Horizonte: scalping, intraday, swing, position, all | No (default: all) |
|
||
|
||
---
|
||
|
||
## Datos de Salida
|
||
|
||
```typescript
|
||
interface Prediction {
|
||
symbol: string;
|
||
timestamp: string; // ISO 8601
|
||
current_price: number;
|
||
predictions: {
|
||
[horizon: string]: {
|
||
high: number; // Precio máximo esperado
|
||
low: number; // Precio mínimo esperado
|
||
high_ratio: number; // Ratio de subida (1 + %)
|
||
low_ratio: number; // Ratio de bajada (1 - %)
|
||
confidence: number; // 0-1, nivel de confianza
|
||
minutes: number; // Duración del horizonte
|
||
}
|
||
};
|
||
model_version: string;
|
||
is_trained: boolean;
|
||
}
|
||
```
|
||
|
||
**Ejemplo:**
|
||
```json
|
||
{
|
||
"symbol": "BTCUSDT",
|
||
"timestamp": "2025-12-05T18:05:08.889327Z",
|
||
"current_price": 89388.99,
|
||
"predictions": {
|
||
"scalping": {
|
||
"high": 89663.86,
|
||
"low": 88930.53,
|
||
"high_ratio": 1.0031,
|
||
"low_ratio": 0.9949,
|
||
"confidence": 0.69,
|
||
"minutes": 30
|
||
},
|
||
"intraday": {
|
||
"high": 90213.60,
|
||
"low": 88013.61,
|
||
"high_ratio": 1.0093,
|
||
"low_ratio": 0.9848,
|
||
"confidence": 0.59,
|
||
"minutes": 90
|
||
}
|
||
},
|
||
"model_version": "1.0.0",
|
||
"is_trained": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Reglas de Negocio
|
||
|
||
1. **Símbolos Soportados:** Solo BTCUSDT y ETHUSDT inicialmente
|
||
2. **Modelo Pre-entrenado:** Debe existir modelo entrenado antes de hacer predicciones
|
||
3. **Datos Históricos:** Requiere mínimo 500 velas de 5min para predicción confiable
|
||
4. **Confianza Decreciente:** La confianza disminuye con horizontes más largos
|
||
5. **Caché:** Predicciones se cachean por 5 minutos (1 vela completa)
|
||
6. **Rate Limiting:** Máximo 10 requests/minuto por usuario para endpoint REST
|
||
|
||
---
|
||
|
||
## Criterios de Aceptación
|
||
|
||
```gherkin
|
||
Escenario: Obtener predicción para BTCUSDT
|
||
DADO que el modelo está entrenado para BTCUSDT
|
||
Y el usuario está autenticado
|
||
CUANDO hace GET /api/predict/BTCUSDT?horizon=all
|
||
ENTONCES recibe predicciones para los 4 horizontes
|
||
Y cada predicción incluye high, low, confidence
|
||
Y el precio actual coincide con el último cierre
|
||
Y el timestamp es reciente (< 5 min)
|
||
|
||
Escenario: Predicción de horizonte único
|
||
DADO que el modelo está entrenado
|
||
CUANDO hace GET /api/predict/BTCUSDT?horizon=scalping
|
||
ENTONCES recibe solo predicción de scalping (30 min)
|
||
Y el nivel de confianza es >= 0.65
|
||
|
||
Escenario: Modelo no entrenado
|
||
DADO que NO existe modelo entrenado para ETHUSDT
|
||
CUANDO hace GET /api/predict/ETHUSDT
|
||
ENTONCES recibe error 503 Service Unavailable
|
||
Y el mensaje indica "Model not trained for ETHUSDT"
|
||
Y is_trained = false
|
||
|
||
Escenario: Actualización en tiempo real vía WebSocket
|
||
DADO que el usuario está conectado a /ws/BTCUSDT
|
||
CUANDO se cierra una nueva vela de 5 minutos
|
||
ENTONCES recibe predicción actualizada automáticamente
|
||
Y el timestamp de la predicción es el actual
|
||
```
|
||
|
||
---
|
||
|
||
## Dependencias
|
||
|
||
### Técnicas:
|
||
- **XGBoost 2.0+:** Motor de predicción
|
||
- **Binance API:** Datos de mercado (velas de 5min)
|
||
- **Pandas/NumPy:** Procesamiento de features
|
||
- **FastAPI:** Endpoints REST y WebSocket
|
||
- **Redis:** Caché de predicciones (opcional)
|
||
|
||
### Funcionales:
|
||
- **RF-ML-003:** Indicadores técnicos para features
|
||
- **RF-ML-004:** Pipeline de entrenamiento previo
|
||
|
||
---
|
||
|
||
## Notas Técnicas
|
||
|
||
### Arquitectura del Predictor
|
||
|
||
```python
|
||
# apps/ml-services/src/models/predictor.py
|
||
|
||
class MaxMinPricePredictor:
|
||
"""
|
||
Predictor de rangos de precio máximo/mínimo
|
||
|
||
Utiliza dos modelos XGBoost independientes:
|
||
- xgb_high: Predice max_ratio
|
||
- xgb_low: Predice min_ratio
|
||
"""
|
||
|
||
def predict(self, symbol: str, horizon: str) -> dict:
|
||
# 1. Fetch últimas 500 velas de 5min
|
||
# 2. Calcular 30+ features técnicas
|
||
# 3. Predecir max_ratio y min_ratio
|
||
# 4. Convertir ratios a precios absolutos
|
||
# 5. Calcular nivel de confianza
|
||
# 6. Retornar predicción estructurada
|
||
```
|
||
|
||
### Optimizaciones:
|
||
- Feature engineering vectorizado con NumPy
|
||
- Caché de datos de mercado (TTL: 1 min)
|
||
- Modelos pre-cargados en memoria
|
||
- Batch processing para múltiples horizontes
|
||
|
||
### Limitaciones:
|
||
- Precisión disminuye en horizontes largos (>3h)
|
||
- Requiere re-entrenamiento semanal para mantener accuracy
|
||
- No funciona bien en mercados extremadamente volátiles (eventos black swan)
|
||
|
||
---
|
||
|
||
## Referencias
|
||
|
||
- [XGBoost Documentation](https://xgboost.readthedocs.io/)
|
||
- [Binance API - Klines](https://binance-docs.github.io/apidocs/spot/en/#kline-candlestick-data)
|
||
- [Technical Indicators Library - TA-Lib](https://ta-lib.org/)
|
||
- [FastAPI WebSockets](https://fastapi.tiangolo.com/advanced/websockets/)
|
||
|
||
---
|
||
|
||
**Creado por:** Requirements-Analyst
|
||
**Fecha:** 2025-12-05
|
||
**Última actualización:** 2025-12-05
|