# OrbiQuant LLM Agent - Deployment Guide

## Overview

El servicio LLM Agent proporciona un copiloto de trading inteligente que se ejecuta localmente en GPU usando Ollama, con soporte para modelos como Llama 3 y Mistral.

## Tabla de Contenidos

1. [Requisitos del Sistema](#requisitos-del-sistema)
2. [Instalación de Ollama](#instalación-de-ollama)
3. [Configuración del Servicio](#configuración-del-servicio)
4. [Instalación de Dependencias](#instalación-de-dependencias)
5. [Iniciar el Servicio](#iniciar-el-servicio)
6. [Verificación](#verificación)
7. [Troubleshooting](#troubleshooting)

---

## Requisitos del Sistema

### Hardware Recomendado
- **GPU:** NVIDIA RTX 5060 Ti (16GB VRAM) o superior
- **RAM:** Mínimo 16GB, recomendado 32GB
- **Storage:** 20GB libres para modelos

### Software
- **OS:** Linux (Ubuntu 20.04+) o WSL2
- **GPU Drivers:** NVIDIA drivers 525.60.13+
- **Docker:** 20.10+ con NVIDIA Container Toolkit
- **Python:** 3.11+
- **Conda:** Miniconda o Anaconda

---

## Instalación de Ollama

### Opción 1: Docker (Recomendado)

```bash
# Navegar al directorio del servicio
cd /home/isem/workspace/projects/trading-platform/apps/llm-agent

# Iniciar Ollama con GPU
docker-compose -f docker-compose.ollama.yml up -d

# Verificar que Ollama está corriendo
curl http://localhost:11434/api/tags

# Pull del modelo Llama 3 8B (recomendado para 16GB VRAM)
docker exec orbiquant-ollama ollama pull llama3:8b

# Alternativas según tu VRAM:
# docker exec orbiquant-ollama ollama pull mistral:7b        # Más rápido
# docker exec orbiquant-ollama ollama pull llama3:70b       # Requiere 40GB+ VRAM
# docker exec orbiquant-ollama ollama pull mixtral:8x7b     # Requiere 32GB+ VRAM
```

**Nota:** La primera descarga del modelo puede tomar 10-30 minutos dependiendo de tu conexión.

### Opción 2: Instalación Nativa

```bash
# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Iniciar Ollama
ollama serve &

# Pull del modelo
ollama pull llama3:8b
```

### Verificar GPU

```bash
# Verificar que Ollama detecta tu GPU
docker exec orbiquant-ollama nvidia-smi

# O en instalación nativa:
nvidia-smi

# Deberías ver tu RTX 5060 Ti listada
```

---

## Configuración del Servicio

### 1. Configurar Variables de Entorno

```bash
cd /home/isem/workspace/projects/trading-platform/apps/llm-agent

# Copiar archivo de ejemplo
cp .env.example .env

# Editar configuración
nano .env
```

Configuración mínima para Ollama:

```bash
# LLM Provider
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
LLM_MODEL=llama3:8b

# Service URLs (ajustar según tu deployment)
BACKEND_URL=http://localhost:8000
DATA_SERVICE_URL=http://localhost:8001
ML_ENGINE_URL=http://localhost:8002

# Database (usar la misma que el backend)
DATABASE_URL=postgresql://orbiquant:orbiquant123@localhost:5432/orbiquant

# Redis
REDIS_URL=redis://localhost:6379/0
```

### 2. Modelos Disponibles

| Modelo | VRAM Requerida | Velocidad | Calidad | Uso Recomendado |
|--------|---------------|-----------|---------|-----------------|
| `llama3:8b` | 8GB | Rápido | Excelente | **Recomendado para RTX 5060 Ti** |
| `mistral:7b` | 6GB | Muy rápido | Buena | Desarrollo/pruebas rápidas |
| `llama3:70b` | 40GB+ | Lento | Excepcional | Servidores de alta gama |
| `mixtral:8x7b` | 32GB+ | Medio | Excelente | GPUs grandes |
| `codellama:7b` | 6GB | Rápido | Buena | Code generation |

---

## Instalación de Dependencias

### Crear Entorno Conda

```bash
cd /home/isem/workspace/projects/trading-platform/apps/llm-agent

# Crear entorno
conda env create -f environment.yml

# Activar entorno
conda activate orbiquant-llm-agent

# O instalar con pip en el entorno
pip install -r requirements.txt
```

### Dependencias Principales

```
fastapi>=0.104.0          # API framework
uvicorn[standard]>=0.24.0 # ASGI server
sse-starlette>=1.6.5      # Streaming support
aiohttp>=3.9.0            # Async HTTP client
loguru>=0.7.0             # Logging
pydantic>=2.0.0           # Data validation
```

---

## Iniciar el Servicio

### Opción 1: Desarrollo (con hot-reload)

```bash
cd /home/isem/workspace/projects/trading-platform/apps/llm-agent

# Activar entorno
conda activate orbiquant-llm-agent

# Iniciar servicio
uvicorn src.main:app --reload --host 0.0.0.0 --port 8003

# El servicio estará disponible en:
# - API: http://localhost:8003
# - Docs: http://localhost:8003/docs
# - Health: http://localhost:8003/api/v1/health
```

### Opción 2: Producción

```bash
# Con más workers (1 por CPU core)
uvicorn src.main:app --host 0.0.0.0 --port 8003 --workers 4

# O usando gunicorn
gunicorn src.main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8003
```

### Opción 3: Docker (futuro)

```bash
# TODO: Crear Dockerfile para el servicio
docker-compose up llm-agent
```

---

## Verificación

### 1. Health Check

```bash
# Check básico
curl http://localhost:8003/

# Health detallado
curl http://localhost:8003/api/v1/health

# Expected response:
{
  "status": "healthy",
  "llm_provider": "ollama",
  "llm_available": true,
  "active_contexts": 0,
  "available_tools": 12
}
```

### 2. Listar Modelos

```bash
curl http://localhost:8003/api/v1/models

# Expected response:
{
  "models": ["llama3:8b"],
  "current": "llama3:8b"
}
```

### 3. Listar Tools

```bash
curl "http://localhost:8003/api/v1/tools?user_plan=pro"

# Expected response:
{
  "plan": "pro",
  "tools": [
    "get_signal",
    "get_analysis",
    "get_news",
    "check_portfolio",
    "get_positions",
    "execute_trade",
    ...
  ],
  "count": 12
}
```

### 4. Test Chat (básico)

```bash
curl -X POST http://localhost:8003/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test-user",
    "conversation_id": "test-conv",
    "message": "¿Qué es el RSI?",
    "user_plan": "free",
    "stream": false
  }'
```

### 5. Test Análisis

```bash
curl -X POST http://localhost:8003/api/v1/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test-user",
    "symbol": "AAPL",
    "user_plan": "pro"
  }'
```

### 6. Interactive API Docs

Abre en tu navegador: http://localhost:8003/docs

Aquí puedes probar todos los endpoints interactivamente.

---

## Troubleshooting

### Ollama no arranca

**Síntoma:** `Connection refused` al hacer curl a Ollama

**Solución:**
```bash
# Verificar que el container está corriendo
docker ps | grep ollama

# Ver logs
docker logs orbiquant-ollama

# Reiniciar container
docker restart orbiquant-ollama
```

### GPU no detectada

**Síntoma:** Modelo corre muy lento, CPU usage al 100%

**Solución:**
```bash
# Verificar NVIDIA Container Toolkit
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

# Reinstalar nvidia-container-toolkit
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker
```

### Out of Memory (OOM)

**Síntoma:** `CUDA out of memory` o el modelo no carga

**Solución:**
1. Usar un modelo más pequeño:
   ```bash
   docker exec orbiquant-ollama ollama pull mistral:7b
   ```
2. Cerrar otras aplicaciones que usen GPU
3. Configurar `.env`:
   ```
   LLM_MODEL=mistral:7b
   ```

### Modelo muy lento

**Optimizaciones:**

1. **Reducir max_tokens:**
   ```
   MAX_TOKENS=1024  # En lugar de 2048
   ```

2. **Usar modelo más pequeño:**
   ```
   LLM_MODEL=mistral:7b
   ```

3. **Verificar que usa GPU:**
   ```bash
   # Durante inferencia, debería mostrar GPU usage
   watch -n 0.5 nvidia-smi
   ```

### Herramientas no funcionan

**Síntoma:** Tools retornan errores de conexión

**Solución:**
```bash
# Verificar que otros servicios están corriendo
curl http://localhost:8000/health  # Backend
curl http://localhost:8001/health  # Data Service
curl http://localhost:8002/health  # ML Engine

# Ajustar URLs en .env si es necesario
```

### Import Errors

**Síntoma:** `ModuleNotFoundError` al iniciar

**Solución:**
```bash
# Asegurarse de estar en el entorno correcto
conda activate orbiquant-llm-agent

# Reinstalar dependencias
pip install -r requirements.txt

# Verificar instalación
python -c "import fastapi; import aiohttp; print('OK')"
```

---

## Monitoreo

### Logs del Servicio

```bash
# Los logs se muestran en la consola
# Usar loguru levels: DEBUG, INFO, WARNING, ERROR

# Cambiar nivel en .env:
LOG_LEVEL=DEBUG
```

### Monitoreo de GPU

```bash
# Uso en tiempo real
watch -n 1 nvidia-smi

# Solo memoria
nvidia-smi --query-gpu=memory.used,memory.total --format=csv

# Temperatura
nvidia-smi --query-gpu=temperature.gpu --format=csv
```

### Ollama Web UI (Opcional)

Si levantaste Ollama con docker-compose, tendrás una UI web en:

http://localhost:3000

Desde ahí puedes:
- Chatear directamente con los modelos
- Gestionar modelos instalados
- Ver logs y métricas

---

## Performance Tips

### 1. Optimizar Temperatura

```python
# En .env, ajustar según el caso de uso:
TEMPERATURE=0.3  # Para análisis técnico (más determinista)
TEMPERATURE=0.7  # Para conversación general (más creativo)
TEMPERATURE=0.9  # Para brainstorming (muy creativo)
```

### 2. Context Window

Los modelos tienen límites de contexto:
- Llama 3 8B: 8K tokens (~6K palabras)
- Mistral 7B: 32K tokens (~24K palabras)

El sistema automáticamente limita el historial a `max_history=20` mensajes.

### 3. Batch Requests

Para múltiples análisis, usa requests paralelos:

```python
import asyncio
import aiohttp

async def analyze_multiple(symbols):
    async with aiohttp.ClientSession() as session:
        tasks = [
            session.post('http://localhost:8003/api/v1/analyze', json={
                'user_id': 'user-1',
                'symbol': symbol,
                'user_plan': 'pro'
            })
            for symbol in symbols
        ]
        results = await asyncio.gather(*tasks)
        return results

# Uso
symbols = ['AAPL', 'GOOGL', 'MSFT']
results = await analyze_multiple(symbols)
```

---

## Siguientes Pasos

1. Integrar con el frontend (WebSocket para streaming)
2. Implementar persistencia de conversaciones en PostgreSQL
3. Añadir RAG con ChromaDB para documentación de trading
4. Implementar rate limiting por usuario
5. Añadir métricas y telemetría

---

## Recursos

- **Ollama Docs:** https://github.com/ollama/ollama
- **Llama 3 Info:** https://ai.meta.com/llama/
- **FastAPI Docs:** https://fastapi.tiangolo.com/
- **Trading Tools API:** Ver `/docs/02-definicion-modulos/OQI-007-llm-agent/`

---

**Estado:** ✅ COMPLETADO
**Versión:** 1.0.0
**Última actualización:** 2025-12-07