foxhunt/PAPER_TRADING_QUICK_REFERENCE.md

# Paper Trading Quick Reference Guide

## Implementation Status

### What Works ✅
```
Prediction Generation Loop
├─ 60-second interval polling
├─ EnsembleCoordinator (DQN, PPO, MAMBA-2, TFT)
├─ Feature extraction (15 features)
└─ Database persistence (ensemble_predictions table)

Paper Trading Executor
├─ 100ms polling of predictions
├─ Confidence filtering (≥60%)
├─ Order creation (lowercase enum)
├─ Position tracking (HashMap)
└─ Risk limits enforcement

TLI Commands
├─ tli trade ml submit (order submission)
├─ tli trade ml predictions (history view)
└─ tli trade ml performance (metrics view)

Database Schema
├─ ensemble_predictions (per-model attribution)
├─ model_performance_attribution (rolling metrics)
├─ ml_predictions (alternative tracking)
└─ TimescaleDB hypertables (optimized)

Tests
└─ 58/58 tests passing (E2E, unit, integration)
```

### What's Missing 🟡
```
Real Performance Tracking
├─ P&L calculation (not populated)
├─ Sharpe ratio (not calculated)
├─ Win rate (not tracked)
└─ Drawdown (not monitored)

Backtesting Framework
├─ Historical replay
├─ Feature consistency
└─ Performance validation

Integration Points
├─ Outcome linking (prediction→order→fill)
├─ Real market prices (currently mocked)
└─ Metrics calculation (SQL exists, never runs)
```

---

## File Location Map

### Core Implementation
```
services/trading_service/src/
├─ paper_trading_executor.rs (600+ lines)
│  └─ Polls predictions, creates orders
├─ prediction_generation_loop.rs (600+ lines)
│  └─ Generates ML predictions every 60s
└─ ml_performance_metrics.rs (300+ lines)
   └─ Sharpe ratio & accuracy calculations
```

### TLI Commands
```
tli/src/commands/
└─ trade_ml.rs (1060 lines)
   ├─ submit: ML order submission
   ├─ predictions: History view
   └─ performance: Metrics display (mock data)
```

### Tests
```
services/trading_service/tests/
├─ paper_trading_executor_tests.rs (unit tests)
├─ prediction_generation_loop_tests.rs (integration)
└─ ml_paper_trading_e2e_test.rs (E2E workflow)
```

### Database
```
migrations/
├─ 022_create_ensemble_tables.sql (ensemble schema)
└─ 031_create_ml_predictions_table.sql (metrics schema)
```

---

## Critical Gaps Analysis

### Gap 1: Outcome Linking
**Problem**: Paper trading executor creates orders but never records actual outcomes
**Impact**: Cannot calculate real P&L or Sharpe ratios
**Fix**: Link predictions to order fills, calculate P&L
**Effort**: 2-3 days

### Gap 2: Performance Metrics
**Problem**: Sharpe ratio SQL exists but is never executed
**Impact**: TLI performance command returns hardcoded mock data
**Fix**: Implement daily metric calculation background task
**Effort**: 1-2 days

### Gap 3: Backtesting
**Problem**: No historical replay capability
**Impact**: Cannot validate ML performance before deployment
**Fix**: Create historical data replay module
**Effort**: 3-5 days

### Gap 4: Real Market Data
**Problem**: Current prices are mocked (hardcoded)
**Impact**: Cannot calculate actual slippage or P&L
**Fix**: Integrate real market data feeds
**Effort**: 1-2 days

---

## Performance Calculation Flow

### Current (Broken) ❌
```
Prediction → Order Created → (no outcome tracking) → TLI shows MOCK data
```

### Needed (Real Sharpe) ✅
```
Prediction
  ↓
Order Created + Linked to prediction
  ↓
Order Fills (price + size recorded)
  ↓
P&L Calculated: (exit_price - entry_price) × size
  ↓
Daily Metric Aggregation
  ├─ Accuracy: correct_predictions / total_predictions
  ├─ Sharpe: (avg_pnl / stddev_pnl) × sqrt(252)
  ├─ Win Rate: winning_trades / total_trades
  └─ Drawdown: max_peak - trough / peak
  ↓
model_performance_attribution Table Updated
  ↓
TLI Displays REAL metrics
```

---

## TLI Command Examples

### Submit ML Order
```bash
tli trade ml submit --symbol ES.FUT --account main
# Output:
# ✅ ML order submitted successfully!
# Order ID: abc123...
# Symbol: ES.FUT
# Model: Ensemble
# Predicted Action: BUY
# Confidence: 85.0%
```

### View Predictions
```bash
tli trade ml predictions --symbol ES.FUT --limit 5
# Output: ASCII table with timestamp, model, action, confidence, outcome
```

### View Performance (Currently Mock)
```bash
tli trade ml performance --model MAMBA2
# Output (MOCK DATA):
# Model    Accuracy  Predictions  Sharpe  Return  Drawdown
# MAMBA2   72.5%     150          1.82    +2.3%   3.1%
# DQN      68.2%     200          1.45    +1.8%   4.5%
```

---

## Database Schema Summary

### ensemble_predictions (Main Table)
| Column | Type | Purpose |
|--------|------|---------|
| id | UUID | Unique prediction ID |
| prediction_timestamp | TIMESTAMPTZ | When predicted |
| symbol | VARCHAR(20) | ES.FUT, NQ.FUT, etc |
| ensemble_action | VARCHAR(10) | BUY, SELL, HOLD |
| ensemble_confidence | DOUBLE | 0.0-1.0 |
| order_id | UUID FK | Links to orders table |
| pnl | BIGINT | **NEVER POPULATED** |
| dqn_signal, ppo_signal, etc | DOUBLE | Per-model votes |

### model_performance_attribution (Metrics Table)
| Column | Type | Purpose |
|--------|------|---------|
| model_id | VARCHAR(50) | DQN, PPO, MAMBA2, TFT |
| window_hours | INTEGER | 1, 24, or 168 |
| accuracy | DOUBLE | Correct % |
| sharpe_ratio | DOUBLE | **NOT CALCULATED** |
| win_rate | DOUBLE | Profitable % |
| max_drawdown | DOUBLE | Peak-to-trough |

---

## Next Steps Priority

### Week 1 (Validation)
- [x] Paper trading executor works
- [x] Predictions generate every 60s
- [x] Tests pass (58/58)
- [x] TLI commands functional

### Week 2 (Real Metrics)
- [ ] Link predictions to outcomes
- [ ] Calculate real P&L
- [ ] Implement Sharpe ratio calculation
- [ ] Update TLI to show real data

### Week 3 (Backtesting)
- [ ] Historical replay framework
- [ ] Feature consistency validation
- [ ] Performance reporting

### Week 4+ (Production)
- [ ] Live deployment
- [ ] Performance monitoring
- [ ] Circuit breakers

---

## Key Metrics Definitions

### Accuracy
```
Correct Predictions / Total Predictions × 100
Example: 72.5% = 145/200 correct
```

### Sharpe Ratio (Annualized)
```
(Mean Return / Std Dev of Returns) × √252
Example: 1.82 = (0.023 / 0.0126) × 15.87
Where 252 = trading days/year
Target: > 1.0 (ideally > 1.5)
```

### Win Rate
```
Profitable Trades / Total Trades × 100
Example: 72.5% = 145/200 trades profitable
```

### Max Drawdown
```
Max Peak - Trough / Peak × 100
Example: 3.1% = worst case loss from peak
Lower is better (risk metric)
```

### Average Return
```
Total P&L / Number of Trades
Example: +2.3% = avg profit per trade
```

---

## Testing Checklist

### Unit Tests
- [x] Fetch pending predictions (SQL filtering)
- [x] Prediction-to-order conversion
- [x] Order creation SQL
- [x] Position tracking

### Integration Tests
- [x] Background task starts
- [x] Predictions generate every 60s
- [x] Error handling (doesn't crash)
- [x] Graceful shutdown

### E2E Tests
- [x] Data → Features → ML → DB → Orders
- [x] Latency < 2 seconds
- [x] High confidence executes
- [x] Position limits respected

### Missing Tests
- [ ] Outcome linking
- [ ] Real P&L calculation
- [ ] Sharpe ratio accuracy
- [ ] Historical backtesting

---

## Deployment Readiness

### Ready for Paper Trading
- Paper trading executor: ✅ READY
- Prediction generation: ✅ READY
- TLI commands: ✅ READY
- Database schema: ✅ READY

### NOT Ready for Live Trading
- Real Sharpe ratios: ❌ NO DATA
- P&L tracking: ❌ NOT IMPLEMENTED
- Backtesting validation: ❌ NO FRAMEWORK
- Performance monitoring: ❌ INCOMPLETE

### Recommendation
Start 1-2 week paper trading validation period with infrastructure as-is. Implement real performance tracking in parallel. Don't deploy real capital until Sharpe ratios are validated.

---

**Generated**: October 17, 2025
**Codebase Status**: 95% Complete, 5% Integration Gaps