foxhunt/AGENT_10_QUICK_REFERENCE.md

Agent 10 Quick Reference: GetMLPerformance Proxy

Mission Complete ✅

File: /home/jgrusewski/Work/foxhunt/services/api_gateway/src/grpc/ml_trading_proxy.rs

---

Implementation Summary

Method Signature

pub async fn get_ml_performance(
    &self,
    request: Request<MlPerformanceRequest>,
    claims: &JwtClaims,
) -> Result<Response<MlPerformanceResponse>, Status>

Key Features

1. Rate Limiting: 20 requests/minute per user (expensive queries)
2. Permission Check: Requires "trading.view" scope
3. Input Validation:
   • model_name: Must be DQN, MAMBA_2, PPO, or TFT
   • time_range: start_time < end_time
4. Audit Logging: Comprehensive JSON logs for compliance
5. Error Mapping: User-friendly error messages

Flow

1. Check rate limit (20 req/min)
   ↓
2. Validate permission (trading.view)
   ↓
3. Validate input (model_name, time_range)
   ↓
4. Forward to Trading Service
   ↓
5. Audit log (JSON structured)
   ↓
6. Return response

---

Rate Limiting Infrastructure

Struct Fields

pub struct MlTradingProxy {
    client: TradingServiceClient<Channel>,
    rate_limiter_predictions: Arc<RateLimiter<...>>,    // 100 req/min
    rate_limiter_performance: Arc<RateLimiter<...>>,   // 20 req/min
}

Constructor

pub fn new(client: TradingServiceClient<Channel>) -> Self {
    let quota_predictions = Quota::per_minute(NonZeroU32::new(100).unwrap());
    let rate_limiter_predictions = Arc::new(RateLimiter::keyed(quota_predictions));
    
    let quota_performance = Quota::per_minute(NonZeroU32::new(20).unwrap());
    let rate_limiter_performance = Arc::new(RateLimiter::keyed(quota_performance));
    
    Self { client, rate_limiter_predictions, rate_limiter_performance }
}

---

Validation Rules

Model Name

• Required: No
• Valid Values: "DQN", "MAMBA_2", "PPO", "TFT"
• Error: Status::invalid_argument("Invalid model name: ...")

Time Range

• Required: No (both start_time and end_time)
• Rule: start_time must be < end_time
• Error: Status::invalid_argument("Invalid time range: ...")

---

Audit Log Format

{
  "action": "get_ml_performance",
  "user": "user_id_from_jwt",
  "model_filter": "DQN",
  "time_range": {
    "start": 1234567890,
    "end": 1234567999
  },
  "results": {
    "models_count": 4,
    "model_names": ["DQN", "MAMBA_2", "PPO", "TFT"]
  },
  "timestamp": "2025-10-16T12:34:56.789Z"
}

---

Error Codes

Backend Error	Status Code	Message
Unavailable	resource_exhausted	"Trading Service temporarily unavailable"
NotFound	not_found	"No performance data available"
Internal	internal	"Database error occurred"
Rate Limit	resource_exhausted	"Rate limit exceeded: 20 req/min"
Permission	permission_denied	"Insufficient permissions: 'trading.view'"
Invalid Model	invalid_argument	"Invalid model name: ..."
Invalid Time	invalid_argument	"Invalid time range: ..."

---

Integration with Agent 13

Agent 13: Implements backend performance calculation in Trading Service

Contract:

• Request: MLPerformanceRequest { model_name?, start_time?, end_time? }
• Response: MLPerformanceResponse { models: Vec<ModelPerformance> }
• ModelPerformance: { model_name, total_predictions, correct_predictions, accuracy, sharpe_ratio, avg_pnl }

Database: ensemble_predictions table

• Aggregation: COUNT, AVG, Sharpe calculation
• Filters: model_name, timestamp range
• Joins: orders, fills (for P&L)

---

Testing Commands

Unit Tests

cargo test -p api_gateway ml_trading_proxy::tests

Integration Tests

# Start Trading Service
cargo run -p trading_service &

# Run API Gateway tests
cargo test -p api_gateway service_proxy_tests::test_get_ml_performance

Manual Testing (curl)

# Get JWT token first
TOKEN=$(curl -X POST http://localhost:50051/auth/login \
  -d '{"username":"test","password":"test"}' | jq -r .token)

# Call GetMLPerformance
grpcurl -H "Authorization: Bearer $TOKEN" \
  -d '{"model_name":"DQN","start_time":1234567890,"end_time":1234567999}' \
  localhost:50051 foxhunt.tli.TradingService/GetMLPerformance

---

Performance Metrics

Metric	Target	Implementation
Routing Overhead	<10μs	Zero-copy forwarding
Rate Limiter Overhead	<50ns	Atomic operations
Permission Check	<100ns	In-memory hash lookup
Audit Logging	Non-blocking	Async tracing

---

Deployment Checklist

• Verify rate limiter works (20 req/min)
• Test permission validation
• Test model name validation
• Test time range validation
• Verify audit logs appear
• Test error mapping
• Load test (100+ concurrent users)
• Monitor Prometheus metrics
• Set up alerting rules

---

Next Steps

1. Agent 13: Implement backend calculation
2. Integration Test: API Gateway ↔ Trading Service
3. Load Test: 20 req/min rate limit
4. Production: Enable monitoring/alerting

---

Agent 10 Complete ✅