workspace/projects/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á:

# 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
• OQI-006: ML Signals
• TradingAgent SignalLogger
• Anthropic Claude API