trading-platform/docs/02-definicion-modulos/OQI-007-llm-agent/_MAP.md

# _MAP: OQI-007 - LLM Strategy Agent

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

---

## Propósito

Esta épica implementa un agente de IA conversacional basado en LLMs que interpreta señales ML, sugiere estrategias de trading, explica decisiones y actúa como copiloto inteligente para los usuarios.

---

## Contenido del Directorio

```
OQI-007-llm-agent/
├── README.md                    # Documentación técnica
├── _MAP.md                      # Este archivo - índice
├── requerimientos/              # Documentos de requerimientos funcionales ✅
│   ├── RF-LLM-001-chat-interface.md        # ✅ Interfaz de chat WebSocket
│   ├── RF-LLM-002-market-analysis.md       # ✅ Análisis de mercado vía LLM
│   ├── RF-LLM-003-strategy-suggestions.md  # ✅ Sugerencias de estrategias
│   ├── RF-LLM-004-educational-assistance.md # ✅ Asistencia educativa
│   ├── RF-LLM-005-tool-integration.md      # ✅ Integración de tools (16 tools)
│   └── RF-LLM-006-context-management.md    # ✅ Gestión de contexto y memoria
├── especificaciones/            # Especificaciones técnicas ✅
│   ├── ET-LLM-001-arquitectura-chat.md     # ✅ Arquitectura WebSocket/Chat
│   ├── ET-LLM-002-agente-analisis.md       # ✅ Agente de análisis
│   ├── ET-LLM-003-motor-estrategias.md     # ✅ Motor de estrategias
│   ├── ET-LLM-004-integracion-educacion.md # ✅ Integración educativa
│   ├── ET-LLM-005-arquitectura-tools.md    # ✅ Arquitectura de tools
│   └── ET-LLM-006-gestion-memoria.md       # ✅ Gestión de memoria
├── historias-usuario/           # User Stories ✅
│   ├── US-LLM-001-enviar-mensaje.md        # ✅ Enviar mensaje al agente
│   ├── US-LLM-002-gestionar-conversaciones.md # ✅ Gestionar conversaciones
│   ├── US-LLM-003-analisis-simbolo.md      # ✅ Solicitar análisis de símbolo
│   ├── US-LLM-004-ver-senales-ml.md        # ✅ Ver señales ML via chat
│   ├── US-LLM-005-estrategia-personalizada.md # ✅ Estrategia personalizada
│   ├── US-LLM-006-historial-estrategias.md # ✅ Ver historial de estrategias
│   ├── US-LLM-007-asistencia-educativa.md  # ✅ Asistencia educativa
│   ├── US-LLM-008-recomendaciones-aprendizaje.md # ✅ Recomendaciones
│   ├── US-LLM-009-consultar-datos-chat.md  # ✅ Consultar datos vía chat
│   └── US-LLM-010-paper-trading-chat.md    # ✅ Paper trading vía chat
└── implementacion/              # Trazabilidad
    └── TRACEABILITY.yml
```

---

## Requerimientos Funcionales

| ID | Nombre | Prioridad | SP | Estado |
|----|--------|-----------|-----|--------|
| RF-LLM-001 | Interfaz de Chat WebSocket | P0 | 8 | ✅ Documentado |
| RF-LLM-002 | Análisis de Mercado vía LLM | P0 | 10 | ✅ Documentado |
| RF-LLM-003 | Sugerencias de Estrategias | P0 | 10 | ✅ Documentado |
| RF-LLM-004 | Asistencia Educativa | P1 | 8 | ✅ Documentado |
| RF-LLM-005 | Integración de Tools | P1 | 8 | ✅ Documentado |
| RF-LLM-006 | Gestión de Contexto y Memoria | P2 | 11 | ✅ Documentado |

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

---

## Especificaciones Técnicas

| ID | Nombre | Componente | Estado |
|----|--------|------------|--------|
| ET-LLM-001 | Arquitectura Chat | WebSocket Gateway | ✅ Documentado |
| ET-LLM-002 | Agente de Análisis | LLM Engine | ✅ Documentado |
| ET-LLM-003 | Motor de Estrategias | Strategy Engine | ✅ Documentado |
| ET-LLM-004 | Integración Educativa | Education Module | ✅ Documentado |
| ET-LLM-005 | Arquitectura Tools | Tool Registry | ✅ Documentado |
| ET-LLM-006 | Gestión de Memoria | Context Manager | ✅ Documentado |

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

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-LLM-001 | Enviar mensaje al agente | P0 | 5 | ✅ Documentado |
| US-LLM-002 | Gestionar conversaciones | P0 | 5 | ✅ Documentado |
| US-LLM-003 | Solicitar análisis de símbolo | P0 | 8 | ✅ Documentado |
| US-LLM-004 | Ver señales ML vía chat | P1 | 8 | ✅ Documentado |
| US-LLM-005 | Estrategia personalizada | P1 | 5 | ✅ Documentado |
| US-LLM-006 | Ver historial de estrategias | P1 | 5 | ✅ Documentado |
| US-LLM-007 | Asistencia educativa | P1 | 5 | ✅ Documentado |
| US-LLM-008 | Recomendaciones de aprendizaje | P2 | 3 | ✅ Documentado |
| US-LLM-009 | Consultar datos vía chat | P2 | 3 | ✅ Documentado |
| US-LLM-010 | Paper trading vía chat | P2 | 8 | ✅ Documentado |

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

---

## Capacidades del Agente

### Interpretación de Señales ML
- Traducir predicciones numéricas a lenguaje natural
- Contextualizar con indicadores técnicos
- Nivel de confianza y riesgo explicado

### Sugerencia de Estrategias
- Basado en perfil de riesgo del usuario
- Considerando capital disponible
- Adaptado a horizonte temporal

### Explicación de Decisiones
- Por qué se abrió/cerró un trade
- Análisis post-mortem de operaciones
- Lecciones aprendidas

### Modo Proactivo
- Alertas de oportunidades
- Notificaciones de riesgo
- Resumen diario/semanal

---

## Integración con ML Engine

### Datos del TradingAgent existente

El agente LLM consumirá:

```python
# Señales del SignalGenerator
{
  "symbol": "BTCUSDT",
  "signal": "buy",
  "confidence": 0.78,
  "phase_amd": "accumulation",
  "range_prediction": {
    "delta_high": 0.62,
    "delta_low": -0.35
  },
  "tpsl": {
    "prob_tp_first": 0.68,
    "suggested_sl": 0.7,
    "suggested_tp": 0.6
  }
}

# Datos para fine-tuning (SignalLogger)
{
  "messages": [...],
  "outcome": "profit",
  "pnl_percent": 1.2
}
```

---

## Tools Disponibles

| Tool | Descripción | Parámetros |
|------|-------------|------------|
| `get_signal` | Obtener señal ML actual | symbol, horizon |
| `analyze_chart` | Análisis técnico | symbol, timeframe |
| `get_portfolio` | Estado del portfolio | user_id |
| `execute_trade` | Ejecutar orden | symbol, side, amount |
| `set_alert` | Crear alerta | symbol, condition |
| `get_history` | Historial de precios | symbol, period |
| `explain_indicator` | Explicar indicador | indicator_name |

---

## Límites por Plan

| Plan | Mensajes/día | Tools | Proactivo | Fine-tune |
|------|--------------|-------|-----------|-----------|
| Free | 10 | 3 básicos | ❌ | ❌ |
| Basic | 50 | 5 | ❌ | ❌ |
| Pro | 200 | Todos | ✅ | ❌ |
| Premium | Ilimitado | Todos + API | ✅ Personalizado | ✅ |

---

## Dependencias

### Depende de:

- **OQI-001:** Autenticación (usuarios, sesiones)
- **OQI-006:** ML Signals (predicciones, señales)
- **TradingAgent:** SignalLogger, modelos existentes

### Bloquea:

- Ninguna (épica independiente)

---

## Stack Técnico

| Capa | Tecnología | Uso |
|------|------------|-----|
| LLM Provider | Claude API / OpenAI | Modelo base |
| Orquestación | LangChain / Claude SDK | Flujo de agente |
| Vector DB | Pinecone | RAG para contexto |
| Memory | Redis | Historial de conversación |
| API | FastAPI | Endpoints del agente |
| Frontend | React | Chat UI |
| Fine-tuning | OpenAI/Anthropic API | Mejora continua |

---

## Criterios de Aceptación

### Funcionales

- [ ] Agente responde preguntas sobre señales ML
- [ ] Explica decisiones de trading en lenguaje claro
- [ ] Sugiere estrategias personalizadas
- [ ] Puede ejecutar órdenes con confirmación
- [ ] Envía alertas proactivas configurables
- [ ] Mantiene contexto de conversación

### No Funcionales

- [ ] Respuesta en < 3 segundos
- [ ] Disponibilidad 99.5%
- [ ] Precisión de respuestas > 90%

### Técnicos

- [ ] Integración con ML Engine existente
- [ ] Pipeline de fine-tuning automatizado
- [ ] Logs para análisis de calidad

---

## Hitos

| Hito | Entregables | Target |
|------|-------------|--------|
| M1 | Chat básico + interpretación señales | Sprint 9 |
| M2 | Tools completos + explicaciones | Sprint 10 |
| M3 | Modo proactivo + alertas | Sprint 10 |
| M4 | Fine-tuning + mejora continua | Sprint 11 |

---

## Referencias

- [README Principal](./README.md)
- [OQI-006: ML Signals](../OQI-006-ml-signals/)
- [TradingAgent SignalLogger]([LEGACY: apps/ml-engine - migrado desde TradingAgent]/src/utils/signal_logger.py)
- [Anthropic Claude API](https://docs.anthropic.com/)