# OQI-007: LLM Strategy Agent

## Resumen Ejecutivo

Esta épica implementa un agente de inteligencia artificial basado en Large Language Models (LLM) que actúa como asistente de trading inteligente, interpretando señales ML, sugiriendo estrategias y explicando decisiones en lenguaje natural.

---

## Visión

> "Un copiloto de trading inteligente que combina el poder predictivo del ML con la capacidad explicativa de los LLMs para democratizar el trading profesional"

---

## Objetivos

1. **Interpretar señales ML** en lenguaje natural comprensible
2. **Sugerir estrategias** de entrada/salida basadas en contexto de mercado
3. **Explicar razonamiento** detrás de cada recomendación
4. **Gestionar conversaciones** sobre trading y educación
5. **Fine-tuning especializado** con datos de trading reales

---

## Arquitectura

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           LLM STRATEGY AGENT                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                      CONVERSATION LAYER                              │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │   │
│  │  │   Chat UI    │  │   Context    │  │      Memory Manager      │  │   │
│  │  │  Interface   │  │   Builder    │  │   (conversation history) │  │   │
│  │  └──────────────┘  └──────────────┘  └──────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│  ┌─────────────────────────────────▼───────────────────────────────────┐   │
│  │                       LLM CORE ENGINE                                │   │
│  │  ┌──────────────────────────────────────────────────────────────┐  │   │
│  │  │                    Fine-tuned Model                           │  │   │
│  │  │  ┌────────────┐  ┌────────────┐  ┌────────────────────────┐ │  │   │
│  │  │  │  Claude/   │  │  Trading   │  │    Prompt Templates    │ │  │   │
│  │  │  │   GPT-4    │  │  Adapter   │  │   (strategy, explain)  │ │  │   │
│  │  │  └────────────┘  └────────────┘  └────────────────────────┘ │  │   │
│  │  └──────────────────────────────────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│  ┌─────────────────────────────────▼───────────────────────────────────┐   │
│  │                      INTEGRATION LAYER                               │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │   │
│  │  │  ML Engine   │  │   Market     │  │     User Portfolio       │  │   │
│  │  │  Connector   │  │   Data API   │  │       Context            │  │   │
│  │  └──────────────┘  └──────────────┘  └──────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│  ┌─────────────────────────────────▼───────────────────────────────────┐   │
│  │                      TOOLS & FUNCTIONS                               │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │   │
│  │  │  Get Signal  │  │   Analyze    │  │      Execute Trade       │  │   │
│  │  │   (from ML)  │  │   Chart      │  │    (with confirmation)   │  │   │
│  │  └──────────────┘  └──────────────┘  └──────────────────────────┘  │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │   │
│  │  │  Get Price   │  │   Check      │  │      Set Alert           │  │   │
│  │  │   History    │  │  Portfolio   │  │                          │  │   │
│  │  └──────────────┘  └──────────────┘  └──────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## Capacidades del Agente

### 1. Interpretación de Señales ML

```
Usuario: "¿Qué dice el modelo sobre Bitcoin ahora?"

Agente: "Basándome en el análisis del modelo ML:

📊 **Señal actual: COMPRA (Confianza: 78%)**

**Contexto del mercado:**
- Fase AMD detectada: Acumulación
- Volatilidad: Baja (ATR en percentil 25)
- RSI: 42 (neutral, saliendo de sobreventa)

**Predicción de rango (próximos 90 min):**
- Precio actual: $43,250
- Máximo esperado: $43,520 (+0.62%)
- Mínimo esperado: $43,100 (-0.35%)

**Mi recomendación:**
Entrada en $43,200-43,300 con:
- Stop Loss: $42,950 (-0.7%)
- Take Profit: $43,500 (+0.6%)
- Risk/Reward: 1:0.85

⚠️ Nota: Esta es una señal de corto plazo (scalping).
El modelo tiene 68% de precisión en este horizonte."
```

### 2. Sugerencia de Estrategias

```
Usuario: "Tengo $5,000 para invertir, perfil moderado"

Agente: "Para tu perfil moderado con $5,000, sugiero:

**Estrategia: Orion (Trend Following)**

📈 **Distribución recomendada:**
- 60% en Orion Agent ($3,000)
  - Target: 5-10% mensual
  - Max drawdown: 10%
  - Activos: Top 10 cryptos

- 30% en Atlas Agent ($1,500)
  - Target: 3-5% mensual
  - Max drawdown: 5%
  - Activos: BTC, ETH only

- 10% en cash ($500)
  - Para oportunidades puntuales

**Proyección a 6 meses:**
- Escenario conservador: +18% ($5,900)
- Escenario esperado: +35% ($6,750)
- Escenario optimista: +55% ($7,750)

¿Quieres que proceda a abrir estas cuentas?"
```

### 3. Explicación de Decisiones

```
Usuario: "¿Por qué el bot vendió mi posición de ETH?"

Agente: "Tu posición de ETH fue cerrada por el agente Atlas:

**Detalles del trade:**
- Entrada: $2,340 (hace 3 horas)
- Salida: $2,295 (-1.9%)
- Razón: Stop Loss activado

**¿Por qué se activó el Stop Loss?**

1. **Detección de Manipulación (AMD)**
   - El modelo detectó fase de "Manipulation"
   - Volumen anormal (+180% vs promedio)
   - Wick patterns indicando barrido de stops

2. **Protección del capital**
   - Atlas tiene max drawdown de 5%
   - Esta pérdida representa 1.9% del capital asignado
   - Quedó margen para 3 trades más antes de pausar

3. **Señales técnicas**
   - RSI cayó de 55 a 38 en 30 minutos
   - Ruptura de soporte en $2,310
   - MACD cruzó a negativo

**Aprendizaje:**
El modelo priorizó preservar capital. En 7 de cada 10
casos similares, el precio continuó cayendo otro 2-3%.

¿Quieres ajustar la configuración de riesgo de Atlas?"
```

### 4. Asistente Educativo

```
Usuario: "No entiendo qué es la fase de Acumulación"

Agente: "¡Excelente pregunta! Déjame explicarte:

**🏦 Fase de Acumulación (Smart Money Concepts)**

Es cuando los grandes jugadores (instituciones, ballenas)
están comprando silenciosamente sin mover mucho el precio.

**Características:**
- Volumen bajo pero constante
- Precio en rango estrecho (consolidación)
- RSI en zona neutral o baja (30-50)
- Poca actividad de retail

**¿Por qué importa?**
Después de acumulación suele venir un movimiento alcista
fuerte. Es como la calma antes de la tormenta.

**Ejemplo en tu chart:**
[Se mostraría imagen del chart con zonas marcadas]

En el último mes, detectamos 3 fases de acumulación en BTC:
- 15 Nov: Acumulación → +8% en 48h
- 28 Nov: Acumulación → +5% en 24h
- 3 Dic: Acumulación → (en desarrollo)

¿Quieres que te avise cuando detecte la próxima?"
```

---

## Modos de Operación

### Modo Chat (Conversacional)
- Respuestas en lenguaje natural
- Contexto de conversación
- Preguntas de seguimiento

### Modo Comando (Acciones directas)
```
/signal BTCUSDT       → Obtener señal actual
/analyze ETHUSDT 4h   → Análisis técnico
/portfolio            → Ver mi portfolio
/alert BTCUSDT 45000  → Crear alerta
/trade buy BTC 100    → Ejecutar orden (requiere confirmación)
```

### Modo Proactivo (Notificaciones)
- Alertas de señales fuertes
- Cambios en posiciones
- Oportunidades detectadas
- Resumen diario

---

## Fine-Tuning Strategy

### Datos de Entrenamiento (del TradingAgent existente)

```python
# SignalLogger ya genera datos en formato LLM
{
  "messages": [
    {
      "role": "system",
      "content": "Eres un analista de trading experto..."
    },
    {
      "role": "user",
      "content": "Analiza la situación actual de XAUUSD"
    },
    {
      "role": "assistant",
      "content": "Basándome en los indicadores técnicos..."
    }
  ],
  "metadata": {
    "signal": {...},
    "outcome": "profit",
    "pnl_percent": 1.2
  }
}
```

### Fuentes de Fine-Tuning
1. **Histórico de señales** (10 años de datos)
2. **Outcomes reales** (trades ejecutados)
3. **Análisis técnico manual** (validación experta)
4. **Feedback de usuarios** (RLHF)

---

## Límites por Plan

| Plan | Mensajes/día | Funciones | Proactivo |
|------|--------------|-----------|-----------|
| Free | 10 | Básicas | ❌ |
| Basic | 50 | Análisis | ❌ |
| Pro | 200 | Todas | ✅ |
| Premium | Ilimitado | Todas + API | ✅ + Personalizado |

---

## Stack Técnico

| Componente | Tecnología |
|------------|------------|
| LLM Base | Claude 3.5 / GPT-4 Turbo |
| Fine-tuning | OpenAI API / Anthropic API |
| Orquestación | LangChain / Claude Tools |
| Vector Store | Pinecone / Weaviate |
| Cache | Redis |
| API | FastAPI (extensión ML Engine) |

---

## Métricas de Éxito

| Métrica | Target |
|---------|--------|
| Precisión de respuestas | > 90% |
| Tiempo de respuesta | < 3 segundos |
| Satisfacción usuario (NPS) | > 50 |
| Señales correctamente explicadas | > 95% |
| Trades ejecutados via agente | > 30% del total |

---

## Story Points Totales: 55 SP

---

## Referencias

- [ET-LLM-001: Arquitectura](./especificaciones/ET-LLM-001-arquitectura.md)
- [TradingAgent SignalLogger](../../../apps/ml-engine/src/utils/signal_logger.py)
- [OQI-006: ML Signals](../OQI-006-ml-signals/)
