# OrbiQuant IA - Personal Trading Platform

## Quick Start Guide

Esta guía te ayudará a configurar OrbiQuant como tu plataforma personal de trading con IA.

## Arquitectura

```
┌─────────────────────────────────────────────────────────────────┐
│                        Frontend (React)                          │
│                    http://localhost:5173                         │
└───────────────────────────┬─────────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────────┐
│                      Backend API (Express)                       │
│                    http://localhost:3000                         │
└───────┬───────────────────┼───────────────────┬─────────────────┘
        │                   │                   │
┌───────▼───────┐  ┌───────▼───────┐  ┌───────▼───────┐
│   ML Engine   │  │  LLM Agent    │  │ Data Service  │
│   (FastAPI)   │  │  (FastAPI)    │  │  (FastAPI)    │
│   :8001       │  │   :8003       │  │   :8002       │
└───────┬───────┘  └───────┬───────┘  └───────┬───────┘
        │                  │                   │
        │          ┌───────▼───────┐          │
        │          │   Ollama      │          │
        │          │  (Local LLM)  │          │
        │          │   :11434      │          │
        │          └───────────────┘          │
        │                                     │
┌───────▼─────────────────────────────────────▼───────┐
│                   PostgreSQL + Redis                 │
└───────────────────────────┬─────────────────────────┘
                            │
             ┌──────────────┼──────────────┐
             │              │              │
      ┌──────▼──────┐ ┌─────▼─────┐ ┌─────▼─────┐
      │  MT4/MT5    │ │ Polygon   │ │  Binance  │
      │  (MetaAPI)  │ │   API     │ │   API     │
      └─────────────┘ └───────────┘ └───────────┘
```

## Requisitos

### Software
- Docker & Docker Compose
- Git
- (Opcional) Ollama para LLM local
- (Opcional) NVIDIA GPU + CUDA para aceleración

### Cuentas y APIs
1. **MetaAPI.cloud** - Para conectar MT4/MT5
   - Regístrate en https://metaapi.cloud
   - Crea una cuenta MT4/MT5
   - Obtén tu token y account ID

2. **LLM Provider** (elige uno):
   - **Ollama** (Recomendado, gratis, local): https://ollama.ai
   - **OpenAI**: https://platform.openai.com
   - **Anthropic Claude**: https://console.anthropic.com

3. **Market Data** (opcional):
   - Polygon.io para datos forex/crypto

## Instalación

### 1. Clonar y configurar

```bash
cd /home/isem/workspace/projects/trading-platform

# Copiar configuración
cp apps/personal/.env.example apps/personal/.env

# Editar configuración
nano apps/personal/.env
```

### 2. Configurar credenciales en `.env`

```bash
# LLM - Usa Ollama local (recomendado)
LLM_PROVIDER=ollama
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=llama3:8b

# O usa OpenAI
# LLM_PROVIDER=openai
# OPENAI_API_KEY=sk-your-key

# MT4/MT5 via MetaAPI
METAAPI_TOKEN=your-token-from-metaapi-cloud
METAAPI_ACCOUNT_ID=your-account-id

# Modo de trading (IMPORTANTE: empieza con paper!)
TRADE_MODE=paper
```

### 3. Instalar Ollama (si usas LLM local)

```bash
# Instalar Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Descargar modelo
ollama pull llama3:8b

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

### 4. Iniciar la plataforma

```bash
# Método 1: Script automático
./scripts/start-personal.sh

# Método 2: Docker Compose manual
docker compose -f docker-compose.personal.yml up -d
```

### 5. Acceder a la plataforma

- **Dashboard**: http://localhost:5173
- **API Docs**: http://localhost:8001/docs
- **LLM Agent**: http://localhost:8003/docs

## Uso

### Conectar MT4

1. Abre el dashboard
2. Ve a Settings > MT4 Connection
3. Ingresa tus credenciales de MetaAPI
4. Click "Connect"

### Chat con el Asistente IA

El LLM Agent puede:
- Analizar mercados con ICT/SMC
- Detectar fases AMD
- Ejecutar trades en MT4
- Calcular position sizing
- Escanear múltiples símbolos

Ejemplos de comandos:
```
"Analiza EURUSD con ICT"
"¿Cuál es la mejor oportunidad ahora?"
"Dame señales para XAUUSD"
"Abre un trade de 0.1 lotes en EURUSD con SL en 1.0850"
"Muestra mis posiciones abiertas"
```

### Trading Automático

Para habilitar auto-trading (úsalo con cuidado):

```bash
# En .env
AUTO_TRADE_ENABLED=true
AUTO_TRADE_REQUIRE_CONFIRMATION=true  # Mantén esto en true
AUTO_TRADE_MIN_CONFIDENCE=0.7
AUTO_TRADE_MIN_SCORE=60
```

## ML Models

### ICT/SMC Detector
Detecta conceptos de Smart Money:
- Order Blocks (zonas institucionales)
- Fair Value Gaps (imbalances)
- Liquidity Sweeps (stop hunts)
- Break of Structure / Change of Character
- Premium/Discount zones

### AMD Detector
Identifica fases de mercado:
- **Accumulation**: Smart money acumulando
- **Manipulation**: Stop hunts, fake breakouts
- **Distribution**: Smart money distribuyendo

### Strategy Ensemble
Combina múltiples modelos para señales de alta confianza.

## Endpoints Principales

### ML Engine (8001)

```bash
# ICT Analysis
POST /api/ict/EURUSD

# Ensemble Signal
POST /api/ensemble/EURUSD

# Multi-symbol Scan
POST /api/scan
{
  "symbols": ["EURUSD", "GBPUSD", "XAUUSD"],
  "timeframe": "1h",
  "min_score": 50
}
```

### LLM Agent (8003)

```bash
# Chat
POST /api/v1/chat
{
  "message": "Analiza EURUSD",
  "stream": true
}

# Auto-trade status
GET /api/v1/auto-trade/status
```

### Data Service (8002)

```bash
# Connect MT4
POST /api/mt4/connect
{
  "token": "your-metaapi-token",
  "account_id": "your-account-id"
}

# Get account info
GET /api/mt4/account

# Execute trade
POST /api/mt4/trade
{
  "symbol": "EURUSD",
  "action": "BUY",
  "volume": 0.01,
  "stop_loss": 1.0850,
  "take_profit": 1.0950
}
```

## Comandos Útiles

```bash
# Ver logs
docker compose -f docker-compose.personal.yml logs -f

# Ver logs de un servicio específico
docker compose -f docker-compose.personal.yml logs -f ml-engine

# Reiniciar
docker compose -f docker-compose.personal.yml restart

# Detener
docker compose -f docker-compose.personal.yml down

# Reconstruir después de cambios
docker compose -f docker-compose.personal.yml up -d --build
```

## Troubleshooting

### Ollama no conecta
```bash
# Verificar que Ollama está corriendo
curl http://localhost:11434/api/tags

# Si no responde, iniciar Ollama
ollama serve
```

### MT4 no conecta
1. Verifica que METAAPI_TOKEN y METAAPI_ACCOUNT_ID son correctos
2. Revisa que la cuenta MT4 está desplegada en MetaAPI dashboard
3. Puede tomar 30-60 segundos la primera conexión

### GPU no detectada
```bash
# Verificar NVIDIA drivers
nvidia-smi

# Verificar NVIDIA Container Toolkit
docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi
```

## Seguridad

- **NUNCA** uses `TRADE_MODE=live` sin entender completamente el sistema
- Siempre empieza con `paper` trading
- Mantén `AUTO_TRADE_REQUIRE_CONFIRMATION=true`
- No expongas los puertos fuera de localhost en producción
- Guarda tus API keys de forma segura

## Soporte

- Issues: https://github.com/your-repo/issues
- Docs: Swagger en cada servicio (/docs)