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

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

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

View Performance (Currently Mock)

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)

• Paper trading executor works
• Predictions generate every 60s
• Tests pass (58/58)
• 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

• Fetch pending predictions (SQL filtering)
• Prediction-to-order conversion
• Order creation SQL
• Position tracking

Integration Tests

• Background task starts
• Predictions generate every 60s
• Error handling (doesn't crash)
• Graceful shutdown

E2E Tests

• Data → Features → ML → DB → Orders
• Latency < 2 seconds
• High confidence executes
• 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