rckrdmrd/trading-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
trading-platform/docs/02-definicion-modulos/OQI-007-llm-agent/requerimientos/RF-LLM-005-tool-integration.md
rckrdmrd c1b5081208 feat(ml): Complete FASE 11 - BTCUSD update and comprehensive documentation alignment 
ML Engine Updates:
- Updated BTCUSD with Polygon API data (2024-2025): 215,699 new records
- Re-trained all ML models: Attention (R²: 0.223), Base, Metamodel (87.3% confidence)
- Backtest results: +176.71R profit with aggressive_filter strategy

Documentation Consolidation:
- Created docs/99-analisis/_MAP.md index with 13 new analysis documents
- Consolidated inventories: removed duplicates from orchestration/inventarios/
- Updated ML_INVENTORY.yml with BTCUSD metrics and training results
- Added execution reports: FASE11-BTCUSD, correction issues, alignment validation

Architecture & Integration:
- Updated all module documentation with NEXUS v3.4 frontmatter
- Fixed _MAP.md indexes across all folders
- Updated orchestration plans and traces

Files: 229 changed, 5064 insertions(+), 1872 deletions(-)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-07 09:31:29 -06:00

286 lines
11 KiB
Markdown
Raw Permalink Blame History

---
id: "RF-LLM-005"
title: "Integración de Herramientas (Tools)"
type: "Requirement"
status: "Done"
priority: "Alta"
epic: "OQI-007"
project: "trading-platform"
version: "1.0.0"
created_date: "2025-12-05"
updated_date: "2026-01-04"
---
# RF-LLM-005: Integración de Herramientas (Tools)
**Épica:** OQI-007 - LLM Strategy Agent
**Versión:** 1.0
**Fecha:** 2025-12-05
**Estado:** Planificado
**Prioridad:** P0 - Crítico
---
## Descripción
El agente LLM debe poder ejecutar herramientas (tools) para obtener información en tiempo real, realizar cálculos y ejecutar acciones en la plataforma. Las herramientas permiten al agente interactuar con sistemas externos y proporcionar respuestas precisas basadas en datos actuales.
---
## Requisitos Funcionales
### RF-LLM-005.1: Herramienta de Market Data
- El agente debe consultar precio actual de cualquier símbolo
- El agente debe obtener OHLCV de múltiples timeframes
- El agente debe consultar indicadores técnicos calculados
- El agente debe obtener datos históricos para análisis
- El agente debe manejar símbolos de stocks y crypto
### RF-LLM-005.2: Herramienta de Portfolio
- El agente debe consultar posiciones actuales del usuario
- El agente debe obtener P&L de posiciones
- El agente debe consultar historial de trades
- El agente debe calcular métricas de portfolio
- El agente debe verificar capital disponible
### RF-LLM-005.3: Herramienta de Noticias
- El agente debe buscar noticias relevantes por símbolo
- El agente debe obtener sentiment de noticias
- El agente debe filtrar noticias por fecha
- El agente debe identificar noticias de impacto alto
### RF-LLM-005.4: Herramienta de ML Signals
- El agente debe consultar predicciones del ML Engine
- El agente debe obtener nivel de confianza de predicciones
- El agente debe acceder a features usados en predicción
- El agente debe obtener histórico de precisión del modelo
### RF-LLM-005.5: Herramienta de Paper Trading
- El agente debe poder crear órdenes de paper trading
- El agente debe consultar órdenes pendientes
- El agente debe cancelar órdenes si el usuario lo solicita
- El agente debe calcular impacto de orden propuesta
### RF-LLM-005.6: Herramienta de Alerts
- El agente debe crear alertas de precio
- El agente debe listar alertas activas
- El agente debe modificar/eliminar alertas
- El agente debe configurar alertas de indicadores
### RF-LLM-005.7: Herramienta de Cálculos
- El agente debe calcular position sizing
- El agente debe calcular risk/reward ratios
- El agente debe convertir monedas
- El agente debe calcular correlaciones entre activos
### RF-LLM-005.8: Herramienta de Watchlist
- El agente debe agregar símbolos a watchlist
- El agente debe consultar watchlist actual
- El agente debe remover símbolos de watchlist
- El agente debe obtener resumen de watchlist
---
## Criterios de Aceptación
```gherkin
Feature: Integración de Herramientas
Scenario: Consultar precio actual
Given el usuario pregunta "¿Cuál es el precio de BTC?"
When el agente usa la herramienta get_price
Then obtiene precio actualizado (max 15 seg delay)
And responde con precio formateado
And incluye cambio porcentual 24h
Scenario: Crear orden de paper trading
Given soy usuario Premium
And tengo paper trading habilitado
When digo "Compra 10 acciones de AAPL"
Then el agente usa herramienta create_paper_order
And confirma los parámetros antes de ejecutar
And muestra orden creada
Scenario: Consultar señales ML
Given soy usuario Pro
When pregunto "¿Qué dice el ML sobre TSLA?"
Then el agente usa herramienta get_ml_signals
And muestra predicción con confianza
And explica los features principales
Scenario: Crear alerta de precio
Given digo "Avísame cuando AAPL llegue a $190"
When el agente procesa la solicitud
Then usa herramienta create_alert
And confirma alerta creada
And muestra listado de alertas activas
Scenario: Herramienta no disponible por plan
Given soy usuario Free
When digo "Crea una orden de paper trading"
Then el agente detecta herramienta restringida
And informa que requiere plan Pro
And sugiere upgrade
```
---
## Reglas de Negocio
| Regla | Descripción |
|-------|-------------|
| RN-001 | Confirmar antes de ejecutar acciones (órdenes, alertas) |
| RN-002 | Paper trading solo para Pro/Premium |
| RN-003 | ML signals solo para Pro/Premium |
| RN-004 | Máximo 10 herramienta-calls por mensaje |
| RN-005 | Cache de market data: 5 segundos |
| RN-006 | No ejecutar trades reales (solo paper) |
| RN-007 | Logging de todas las herramientas ejecutadas |
---
## Catálogo de Herramientas
### Herramientas de Lectura (Todos los planes)
| Tool ID | Nombre | Descripción | Rate Limit |
|---------|--------|-------------|------------|
| T-001 | `get_price` | Obtener precio actual | 60/min |
| T-002 | `get_ohlcv` | Obtener velas OHLCV | 30/min |
| T-003 | `get_indicators` | Obtener indicadores técnicos | 30/min |
| T-004 | `get_news` | Buscar noticias por símbolo | 10/min |
| T-005 | `get_watchlist` | Obtener watchlist del usuario | 60/min |
| T-006 | `calculate` | Cálculos financieros | 100/min |
### Herramientas Pro (Pro/Premium)
| Tool ID | Nombre | Descripción | Rate Limit |
|---------|--------|-------------|------------|
| T-007 | `get_ml_signals` | Obtener señales ML | 30/min |
| T-008 | `get_portfolio` | Obtener portfolio actual | 30/min |
| T-009 | `create_paper_order` | Crear orden paper trading | 10/min |
| T-010 | `cancel_paper_order` | Cancelar orden | 20/min |
| T-011 | `create_alert` | Crear alerta de precio | 20/min |
| T-012 | `manage_alerts` | Listar/modificar alertas | 30/min |
### Herramientas Premium
| Tool ID | Nombre | Descripción | Rate Limit |
|---------|--------|-------------|------------|
| T-013 | `backtest_strategy` | Ejecutar backtest | 5/min |
| T-014 | `get_correlations` | Análisis de correlaciones | 10/min |
| T-015 | `portfolio_analysis` | Análisis avanzado portfolio | 10/min |
| T-016 | `export_data` | Exportar datos a CSV | 5/min |
---
## Esquema de Tool Calls
```yaml
# Ejemplo: get_price
tool_call:
name: "get_price"
parameters:
symbol: "AAPL"
tool_response:
success: true
data:
symbol: "AAPL"
price: 185.50
change_24h: 2.35
change_percent: 1.28
volume: 45000000
timestamp: "2025-12-05T15:30:00Z"
# Ejemplo: create_paper_order
tool_call:
name: "create_paper_order"
parameters:
symbol: "AAPL"
side: "buy"
quantity: 10
order_type: "market"
tool_response:
success: true
data:
order_id: "paper-12345"
status: "pending_confirmation"
estimated_cost: 1855.00
message: "Confirma la orden: Comprar 10 AAPL a mercado (~$1,855)"
```
---
## Flujo de Ejecución de Tools
```
┌─────────────────────────────────────────────────────────────┐
│ 1. Usuario envía mensaje │
│ "Compra 5 TSLA si el precio baja a $240" │
└──────────────────────────┬──────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 2. LLM analiza intent │
│ - Acción: crear alerta + orden condicional │
│ - Tools necesarios: get_price, create_alert │
└──────────────────────────┬──────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 3. Verificar permisos │
│ - ¿Usuario tiene plan Pro? ✓ │
│ - ¿Rate limit OK? ✓ │
└──────────────────────────┬──────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 4. Ejecutar tool: get_price("TSLA") │
│ Response: { price: 245.30, ... } │
└──────────────────────────┬──────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 5. Ejecutar tool: create_alert │
│ { symbol: "TSLA", condition: "<=", price: 240 } │
└──────────────────────────┬──────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 6. LLM genera respuesta con resultados │
│ "He creado una alerta para TSLA a $240..." │
└─────────────────────────────────────────────────────────────┘
```
---
## Dependencias
### Épicas Requeridas
- **OQI-001:** Autenticación (verificar plan del usuario)
- **OQI-003:** Market data y paper trading
- **OQI-006:** ML Signals
### Servicios Internos
- MarketDataService
- PaperTradingService
- AlertService
- MLSignalService
- PortfolioService
---
## Especificaciones Técnicas Relacionadas
- [ET-LLM-005: Arquitectura de Tools](../especificaciones/ET-LLM-005-arquitectura-tools.md)
- [ET-LLM-006: Rate Limiting y Seguridad](../especificaciones/ET-LLM-006-seguridad.md)
---
## Historias de Usuario Relacionadas
- US-LLM-009: Consultar datos de mercado vía chat
- US-LLM-010: Crear órdenes de paper trading vía chat
---
*Documento de requerimientos - Sistema NEXUS*
*Trading Platform*
Reference in New Issue View Git Blame Copy Permalink