foxhunt/tli/docs/ML_TRADING_COMMANDS.md

# TLI ML Trading Commands

Complete guide to using TLI's ML-powered trading commands for automated order submission, prediction history, and model performance monitoring.

## Prerequisites

- TLI installed and authenticated (`tli auth login`)
- API Gateway running (port 50051)
- Trading Service running (port 50052)
- Valid JWT with `trading.submit` and `trading.view` scopes

## Commands Overview

```bash
tli trade ml submit       # Submit ML-generated orders
tli trade ml predictions  # View prediction history
tli trade ml performance  # View model performance metrics
```

---

## 1. Submit ML Orders

### Basic Usage (Ensemble Mode)

```bash
tli trade ml submit --symbol ES.FUT --account my_account
```

**Output**:
```
✅ ML order submitted successfully!

Order ID: 550e8400-e29b-41d4-a716-446655440000
Symbol: ES.FUT
Model: Ensemble (4 models)
Predicted Action: BUY
Confidence: 87.2%
Quantity: 1
Account: my_account
```

### Single Model Mode

```bash
tli trade ml submit --symbol ES.FUT --account my_account --model DQN
```

**Available Models**:
- `DQN` - Deep Q-Network (RL agent)
- `MAMBA2` - Mamba-2 State Space Model
- `PPO` - Proximal Policy Optimization
- `TFT` - Temporal Fusion Transformer
- `TLOB` - Temporal Limit Order Book (requires L2 data, pending training)
- `Liquid` - Liquid Neural Network (CUDA validation complete, pending training)

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `--symbol` | ✅ | Trading symbol (ES.FUT, NQ.FUT, etc.) |
| `--account` | ✅ | Account ID for order submission |
| `--model` | ❌ | Specific model (default: ensemble) |

### Examples

```bash
# Ensemble prediction for ES.FUT
tli trade ml submit --symbol ES.FUT --account prod_account

# MAMBA-2 prediction for NQ.FUT
tli trade ml submit --symbol NQ.FUT --account test_account --model MAMBA2

# PPO prediction for ZN.FUT
tli trade ml submit --symbol ZN.FUT --account rl_account --model PPO
```

---

## 2. View ML Predictions

### Basic Usage

```bash
tli trade ml predictions --symbol ES.FUT
```

**Output**:
```
ML Predictions for ES.FUT (Last 10)

┌─────────────────────┬────────┬─────────┬────────┬────────────┬─────────┐
│ Timestamp           │ Model  │ Symbol  │ Action │ Confidence │ Outcome │
├─────────────────────┼────────┼─────────┼────────┼────────────┼─────────┤
│ 2025-10-16 07:30:00 │ DQN    │ ES.FUT  │ BUY    │ 87.2%      │ +0.5%   │
│ 2025-10-16 07:25:00 │ MAMBA2 │ ES.FUT  │ HOLD   │ 72.1%      │ N/A     │
│ 2025-10-16 07:20:00 │ PPO    │ ES.FUT  │ SELL   │ 81.3%      │ +0.3%   │
└─────────────────────┴────────┴─────────┴────────┴────────────┴─────────┘
```

### With Filters

```bash
# Filter by model
tli trade ml predictions --symbol ES.FUT --model MAMBA2

# Limit results
tli trade ml predictions --symbol ES.FUT --limit 50

# Combined filters
tli trade ml predictions --symbol ES.FUT --model DQN --limit 20
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `--symbol` | ✅ | Trading symbol to query |
| `--model` | ❌ | Filter by specific model |
| `--limit` | ❌ | Max results (default: 10, max: 100) |

---

## 3. View Model Performance

### All Models

```bash
tli trade ml performance
```

**Output**:
```
ML Model Performance (Last 30 days)

┌────────┬──────────┬──────────────┬──────────────┬───────────┬────────────┐
│ Model  │ Accuracy │ Predictions  │ Sharpe Ratio │ Avg Return│ Max Drawdown│
├────────┼──────────┼──────────────┼──────────────┼───────────┼────────────┤
│ DQN    │ 68.2%    │ 1,243        │ 1.42         │ +2.1%     │ -3.2%      │
│ MAMBA2 │ 72.5%    │ 1,189        │ 1.67         │ +2.8%     │ -2.1%      │
│ PPO    │ 65.3%    │ 1,156        │ 1.18         │ +1.5%     │ -4.5%      │
│ TFT    │ 70.1%    │ 1,221        │ 1.53         │ +2.4%     │ -2.8%      │
└────────┴──────────┴──────────────┴──────────────┴───────────┴────────────┘

Ensemble Confidence Threshold: 0.60
Active Models: 4/6 (TLOB and Liquid NN training pending)
```

### Single Model

```bash
tli trade ml performance --model MAMBA2
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `--model` | ❌ | Filter by specific model (shows all if omitted) |

---

## Performance Metrics Explained

- **Accuracy**: Percentage of correct predictions (BUY when price goes up, SELL when down)
- **Sharpe Ratio**: Risk-adjusted returns (>1.0 is good, >2.0 is excellent)
- **Avg Return**: Average profit/loss per trade
- **Max Drawdown**: Largest peak-to-trough decline

---

## Ensemble Mode

When no `--model` is specified, TLI uses **ensemble mode**:

1. Queries all active models
2. Weights predictions by confidence scores
3. Calculates ensemble vote
4. Uses weighted average for final decision

**Benefits**:
- More robust predictions
- Reduced single-model bias
- Higher confidence threshold (0.60 vs 0.50)

---

## Troubleshooting

### "Not authenticated"

```bash
tli auth login
```

### "Permission denied"

Verify JWT has `trading.submit` and `trading.view` scopes:
```bash
tli auth token --decode
```

### "Trading Service unavailable"

Check service status:
```bash
docker-compose ps trading_service
curl http://localhost:8081/health
```

### "Model not found"

Ensure model is trained and deployed. Check model status:
```bash
tli trade ml performance
```

---

## Best Practices

1. **Start with Ensemble Mode**: More reliable than single models
2. **Monitor Performance**: Check `tli trade ml performance` weekly
3. **Use Paper Trading First**: Test in simulation before live capital
4. **Set Confidence Thresholds**: Only trade when confidence >70%
5. **Diversify Across Models**: Don't rely on single model predictions

---

## See Also

- [TLI Authentication](AUTH.md)
- [Trading Agent Service](../services/trading_agent_service/README.md)
- [ML Training Guide](../ml/TRAINING_GUIDE.md)