foxhunt/AGENT_6_QUICK_REFERENCE.md

Agent 6 Quick Reference - Terminal Formatting API

For Agents 2-4: How to use the rich terminal formatting functions

---

📦 Import Statement

use crate::commands::trade_ml::{
    format_ml_order_submission,
    format_ml_predictions,
    format_ml_performance,
    SubmitMLOrderResponse,
    GetMLPredictionsResponse,
    GetMLPerformanceResponse,
    MLPrediction,
    ModelPerformance,
};

---

🎨 Function 1: Order Submission Formatting

Agent 2 - Use in submit command handler

// After successful order submission:
let response = SubmitMLOrderResponse {
    order_id: "order_12345".to_string(),
    symbol: "ES.FUT".to_string(),
    model_used: "Ensemble".to_string(),  // or "MAMBA2", "DQN", etc.
    predicted_action: "BUY".to_string(),  // or "SELL", "HOLD"
    confidence: 0.85,  // 0.0-1.0 (will be displayed as %)
    quantity: 1.0,
    account_id: "main_account".to_string(),
};

format_ml_order_submission(&response);

Output Example:

✅ ML order submitted successfully!

Order ID: order_12345
Symbol: ES.FUT
Model: Ensemble
Predicted Action: BUY
Confidence: 85.0%
Quantity: 1
Account: main_account

---

📊 Function 2: Predictions History Formatting

Agent 3 - Use in predictions command handler

// After fetching predictions from API:
let response = GetMLPredictionsResponse {
    predictions: vec![
        MLPrediction {
            timestamp: "2025-10-16T12:00:00Z".to_string(),
            model_id: "MAMBA2".to_string(),
            symbol: "ES.FUT".to_string(),
            predicted_action: "BUY".to_string(),
            confidence: 0.85,
            actual_return: Some(0.025),  // 2.5% profit
        },
        MLPrediction {
            timestamp: "2025-10-16T11:00:00Z".to_string(),
            model_id: "DQN".to_string(),
            symbol: "ES.FUT".to_string(),
            predicted_action: "SELL".to_string(),
            confidence: 0.72,
            actual_return: Some(-0.012),  // -1.2% loss
        },
        // ... more predictions
    ],
};

format_ml_predictions(&response, "ES.FUT");

Output Example:

ML Predictions for ES.FUT (Last 10)

┌────────────┬────────┬────────┬─────────┬────────────┬─────────┐
│ Timestamp  │ Model  │ Symbol │ Action  │ Confidence │ Outcome │
├────────────┼────────┼────────┼─────────┼────────────┼─────────┤
│ 2025-10-16 │ MAMBA2 │ ES.FUT │ BUY     │ 85.0%      │ +2.50%  │
│ 2025-10-16 │ DQN    │ ES.FUT │ SELL    │ 72.5%      │ -1.20%  │
└────────────┴────────┴────────┴─────────┴────────────┴─────────┘

---

📈 Function 3: Performance Metrics Formatting

Agent 4 - Use in performance command handler

// After fetching performance metrics from API:
let response = GetMLPerformanceResponse {
    models: vec![
        ModelPerformance {
            model_id: "MAMBA2".to_string(),
            accuracy: 72.5,  // 72.5%
            total_predictions: 150,
            sharpe_ratio: 1.82,
            avg_return: 0.023,  // 2.3%
            max_drawdown: 0.031,  // 3.1%
        },
        ModelPerformance {
            model_id: "DQN".to_string(),
            accuracy: 68.2,
            total_predictions: 200,
            sharpe_ratio: 1.45,
            avg_return: 0.018,
            max_drawdown: 0.045,
        },
        // ... more models
    ],
    ensemble_threshold: 0.70,
    active_models: 2,
    total_models: 4,
};

format_ml_performance(&response);

Output Example:

ML Model Performance (Last 30 days)

┌────────┬──────────┬──────────────┬──────────────┬────────────┬──────────────┐
│ Model  │ Accuracy │ Predictions  │ Sharpe Ratio │ Avg Return │ Max Drawdown │
├────────┼──────────┼──────────────┼──────────────┼────────────┼──────────────┤
│ MAMBA2 │ 72.5%    │ 150          │ 1.82         │ +2.3%      │ 3.1%         │
│ DQN    │ 68.2%    │ 200          │ 1.45         │ +1.8%      │ 4.5%         │
└────────┴──────────┴──────────────┴──────────────┴────────────┴──────────────┘

Ensemble Confidence Threshold: 0.70
Active Models: 2/4

---

🎨 Color Coding Rules

Confidence Colors

• ≥80%: Green (high confidence)
• 60-79%: Yellow (moderate confidence)
• <60%: Red (low confidence)

Action Colors

• BUY: Green
• SELL: Red
• HOLD: Yellow

Performance Colors

• Accuracy: Green (≥70%), Yellow (≥60%), Red (<60%)
• Sharpe Ratio: Green (≥1.5), Yellow (≥1.0), Red (<1.0)

---

🔄 Converting gRPC Proto to Formatting Structs

Example: SubmitMLOrderResponse

// From gRPC proto response:
let proto_response = submit_order_response;  // From API call

// Convert to formatting struct:
let display_response = SubmitMLOrderResponse {
    order_id: proto_response.order_id,
    symbol: proto_response.symbol,
    model_used: proto_response.model_used.unwrap_or_else(|| "Ensemble".to_string()),
    predicted_action: match proto_response.action {
        1 => "BUY".to_string(),
        2 => "SELL".to_string(),
        3 => "HOLD".to_string(),
        _ => "UNKNOWN".to_string(),
    },
    confidence: proto_response.confidence,
    quantity: proto_response.quantity,
    account_id: proto_response.account_id,
};

format_ml_order_submission(&display_response);

---

🚨 Important Notes

1. Values are already percentages in structs:

   • accuracy: 72.5 means 72.5%, not 0.725
   • confidence: 0.85 means 0.85 (will be displayed as 85.0%)
   • avg_return: 0.023 means 0.023 (will be displayed as +2.3%)

2. Actual return is optional:

   • Use Some(value) for completed predictions with P&L
   • Use None for pending predictions (displays "N/A")

3. Timestamp format:

   • Use ISO 8601 format: "2025-10-16T12:00:00Z"
   • Will be displayed as-is in table

4. Model names:

   • Use: "MAMBA2", "DQN", "PPO", "TFT", "Ensemble"
   • Ensemble gets special yellow color
   • Single models get blue color

---

✅ Testing Checklist for Agents 2-4

• Import formatting functions successfully
• Create sample response struct
• Call formatting function
• Verify no compilation errors
• Verify no runtime panics
• Verify color output looks correct in terminal
• Test with edge cases (empty predictions, zero values)
• Test with real gRPC proto responses

---

📞 Agent 6 Contact

File: tli/src/commands/trade_ml.rs Lines: 601-879 (formatting module) Tests: Lines 927-1001

All functions are public and ready for integration!