# Documentaci\u00f3n de Estrategias y Modelos ML - OrbiQuant IA

**Fecha de Creaci\u00f3n:** 2025-12-05
**Versi\u00f3n:** 1.0.0
**Estado:** Completo

---

## Descripci\u00f3n General

Esta carpeta contiene la documentaci\u00f3n exhaustiva de las estrategias de trading institucional y la arquitectura de modelos Machine Learning para el m\u00f3dulo **OQI-006-ml-signals** de OrbiQuant IA.

**Total:** 6,189 l\u00edneas de documentaci\u00f3n t\u00e9cnica
**Tama\u00f1o:** ~204 KB

---

## Documentos Disponibles

### 1. ESTRATEGIA-AMD-COMPLETA.md
**L\u00edneas:** 1,417
**Tama\u00f1o:** 42 KB

Documentaci\u00f3n exhaustiva de la estrategia AMD (Accumulation-Manipulation-Distribution) basada en los conceptos de Richard Wyckoff y Smart Money.

**Contenido:**
- ✅ Conceptos fundamentales de AMD
- ✅ Fase 1: Accumulation (características, indicadores, subfases)
- ✅ Fase 2: Manipulation (tipos, detección, stop hunting)
- ✅ Fase 3: Distribution (señales, patrones, estrategias)
- ✅ Detección de transiciones entre fases
- ✅ Indicadores técnicos especializados (Volume Profile, Order Blocks, FVG, Liquidity Pools)
- ✅ Integración con modelos ML (AMDDetector)
- ✅ Implementación práctica con código Python

**Casos de Uso:**
- Diseño del modelo AMDDetector
- Feature engineering para detección de fases
- Target labeling para entrenamiento
- Estrategias de trading específicas por fase

---

### 2. ESTRATEGIA-ICT-SMC.md
**L\u00edneas:** 1,268
**Tama\u00f8o:** 41 KB

Estrategias complementarias de ICT (Inner Circle Trader) y Smart Money Concepts (SMC).

**Contenido:**
- ✅ ICT Concepts:
  - Optimal Trade Entry (OTE) - Zonas Fibonacci 62-79%
  - Killzones (London, NY, Asian sessions)
  - Weekly & Daily Ranges
  - Premium/Discount Pricing
  - Market Maker Models (MMSM/MMBM)
  - Power of 3
- ✅ Smart Money Concepts:
  - Change of Character (CHOCH)
  - Break of Structure (BOS)
  - Inducement
  - Displacement
  - Liquidity Voids
- ✅ Sistema de Confluence (scoring multi-factor)
- ✅ Integración AMD + ICT + SMC
- ✅ Features derivados para ML

**Casos de Uso:**
- Timing óptimo de entradas
- Identificación de zonas de alta probabilidad
- Confluence scoring para filtrado de señales
- Feature engineering avanzado

---

### 3. MODELOS-ML-DEFINICION.md
**L\u00edneas:** 1,712
**Tama\u00f1o:** 58 KB

Arquitectura completa de todos los modelos Machine Learning del sistema.

**Contenido:**
- ✅ **Modelo 1: AMDDetector**
  - Clasificador multiclass (XGBoost)
  - 50 input features
  - Output: 4 fases (neutral, accumulation, manipulation, distribution)
  - Métricas esperadas: >70% accuracy overall

- ✅ **Modelo 2: RangePredictor**
  - Regressor + Classifier (XGBoost)
  - 70+ input features (base + AMD)
  - Output: delta_high, delta_low para múltiples horizontes
  - Métricas esperadas: MAE <0.003, Directional Acc >95%

- ✅ **Modelo 3: TPSLClassifier**
  - Binary classifier con calibración (XGBoost)
  - 80+ input features (stacking con Range)
  - Output: P(TP antes de SL)
  - Métricas actuales: 85.9% accuracy, 0.94 ROC-AUC

- ✅ **Modelo 4: LiquidityHunter**
  - Detector de liquidity sweeps
  - 30 features especializados
  - Output: P(sweep), timing, risk score

- ✅ **Modelo 5: OrderFlowAnalyzer** (opcional)
  - LSTM para análisis de flujo institucional
  - Requiere datos granulares

- ✅ **Meta-Modelo: StrategyOrchestrator**
  - Ensemble weighted + rule-based
  - Combina todos los modelos
  - Genera señal final BUY/SELL/HOLD

- ✅ Pipeline de entrenamiento completo
- ✅ Métricas de evaluación
- ✅ FastAPI service para producción
- ✅ Monitoring y retraining automático

**Casos de Uso:**
- Diseño e implementación de modelos
- Pipeline de entrenamiento
- Deployment a producción
- Evaluación y monitoring

---

### 4. FEATURES-TARGETS-ML.md
**L\u00edneas:** 869
**Tama\u00f1o:** 29 KB

Catálogo completo de features (variables de entrada) y targets (variables objetivo) para todos los modelos.

**Contenido:**
- ✅ **Features Base (21)**
  - Volatilidad (8): volatility_*, atr_*
  - Momentum (6): momentum_*, roc_*, rsi_14
  - Medias Móviles (7): sma_*, ratios, slopes

- ✅ **Features AMD (25)**
  - Price Action (10): range_ratio, body_size, wicks, etc.
  - Volumen (8): volume_ratio, OBV, VWAP
  - Market Structure (7): higher_highs, swings, structure_score

- ✅ **Features ICT (15)**
  - OTE & Fibonacci (5): posición en rango, zonas
  - Killzones & Timing (5): sesiones, strength
  - Ranges (5): weekly/daily position

- ✅ **Features SMC (12)**
  - Structure Breaks (6): CHOCH, BOS counts
  - Displacement & Flow (6): strength, direction

- ✅ **Features Liquidez (10)**
  - BSL/SSL distance, density, strength
  - Sweep detection y proximity

- ✅ **Features Microestructura (8)**
  - CVD, tick imbalance, large orders

- ✅ **Targets para cada modelo**
  - AMD Phase (multiclass)
  - Delta High/Low (regression + bins)
  - TP vs SL (binary)
  - Liquidity Sweeps (binary + timing)

- ✅ **Feature Engineering Pipeline completo**
- ✅ Consideraciones técnicas (scaling, missing values, validation)

**Dimensión Total:** ~91 features base

**Casos de Uso:**
- Referencia para feature engineering
- Target labeling para entrenamiento
- Validación de features
- Debugging de modelos

---

### 5. PIPELINE-ORQUESTACION.md
**L\u00edneas:** 923
**Tama\u00f1o:** 34 KB

Pipeline completo de orquestación que conecta todos los modelos.

**Contenido:**
- ✅ Arquitectura del pipeline end-to-end
- ✅ Flujo de datos detallado (10 pasos)
- ✅ Grafo de dependencias entre modelos
- ✅ Implementación completa de StrategyOrchestrator
- ✅ Escenarios de uso:
  - Setup perfecto (alta confluence)
  - Manipulation phase (hold)
  - Baja confluence (hold)
- ✅ Optimización y performance:
  - Caching strategy
  - Parallel execution
  - Batch processing
- ✅ Monitoring y alertas:
  - Métricas Prometheus
  - Logging estructurado
  - Sistema de alertas

**Latencias esperadas:**
- End-to-end: <1,200ms
- Por modelo: 50-200ms

**Casos de Uso:**
- Implementación del pipeline completo
- Optimización de performance
- Setup de monitoring
- Debugging de flujo

---

## Flujo de Lectura Recomendado

### Para Trading Strategists
1. **ESTRATEGIA-AMD-COMPLETA.md** - Fundamentos de AMD
2. **ESTRATEGIA-ICT-SMC.md** - Conceptos complementarios
3. **PIPELINE-ORQUESTACION.md** - Cómo se integra todo

### Para ML Engineers
1. **FEATURES-TARGETS-ML.md** - Qué features usar
2. **MODELOS-ML-DEFINICION.md** - Arquitectura de modelos
3. **PIPELINE-ORQUESTACION.md** - Cómo conectar modelos

### Para Full Stack Developers
1. **PIPELINE-ORQUESTACION.md** - API y flujo
2. **MODELOS-ML-DEFINICION.md** - Endpoints y schemas
3. **FEATURES-TARGETS-ML.md** - Input/output data

---

## Integración con TradingAgent Existente

Los modelos documentados aquí se integran con el código existente en:

```
[LEGACY: apps/ml-engine - migrado desde TradingAgent]/
├── src/models/
│   ├── range_predictor.py      → Ver MODELOS-ML-DEFINICION.md
│   ├── tp_sl_classifier.py     → Ver MODELOS-ML-DEFINICION.md
│   └── signal_generator.py     → Ver PIPELINE-ORQUESTACION.md
├── src/strategies/
│   └── amd_detector.py         → Ver ESTRATEGIA-AMD-COMPLETA.md
└── models/phase2/              → Modelos entrenados
```

**Performance Actual (TradingAgent Phase 2):**
- RangePredictor: 69.3% bin accuracy
- TPSLClassifier: 85.9% accuracy, 0.94 ROC-AUC
- Símbolos: BTCUSDT, ETHUSDT
- Próximos: XAUUSD, EURUSD

---

## Mejoras vs TradingAgent

| Aspecto | TradingAgent Actual | Documentación Nueva |
|---------|-------------------|-------------------|
| **AMD Detector** | Implementación básica | Modelo ML completo con 50 features |
| **Features** | 21 básicos | 91 features (base + AMD + ICT + SMC) |
| **Estrategias** | Solo AMD | AMD + ICT + SMC + Confluence |
| **Modelos** | 2 (Range, TPSL) | 5 (AMD, Range, TPSL, Liquidity, OrderFlow) |
| **Orquestación** | SignalGenerator simple | StrategyOrchestrator avanzado |
| **Confluence** | No implementado | Sistema de scoring multi-factor |
| **Monitoring** | Básico | Prometheus + alertas |

---

## Próximos Pasos

### Fase 1: Implementación Core (2 semanas)
- [ ] Implementar AMDDetector según MODELOS-ML-DEFINICION.md
- [ ] Extender features según FEATURES-TARGETS-ML.md
- [ ] Agregar features ICT/SMC
- [ ] Entrenar AMDDetector con datos históricos

### Fase 2: Integración (2 semanas)
- [ ] Mejorar RangePredictor con features AMD
- [ ] Mejorar TPSLClassifier con stacking
- [ ] Implementar LiquidityHunter
- [ ] Crear StrategyOrchestrator

### Fase 3: Optimización (1 semana)
- [ ] Implementar caching según PIPELINE-ORQUESTACION.md
- [ ] Setup monitoring y alertas
- [ ] Optimizar latencias
- [ ] Backtesting completo

### Fase 4: Producción (1 semana)
- [ ] Deployment FastAPI
- [ ] CI/CD pipeline
- [ ] Auto-retraining
- [ ] Documentación API

---

## Contacto y Soporte

**Equipo ML Engineering:**
- Email: ml-engineering@orbiquant.ai
- Slack: #ml-signals

**Revisión de Código:**
- Pull Requests en GitHub
- Code review obligatorio antes de merge

**Documentación Adicional:**
- Arquitectura General: `/docs/01-arquitectura/`
- API Specs: `/docs/02-definicion-modulos/OQI-006-ml-signals/especificaciones/`
- Tests: `/docs/02-definicion-modulos/OQI-006-ml-signals/pruebas/`

---

## Changelog

### v1.0.0 - 2025-12-05
- ✅ Documentación inicial completa
- ✅ 5 documentos técnicos generados
- ✅ 6,189 líneas de documentación
- ✅ Integración con TradingAgent definida

---

**Última actualización:** 2025-12-05
**Próxima revisión:** 2025-Q1
**Mantenido por:** Trading Strategist Team