foxhunt/docs/AGENT_11.10_QUICK_REFERENCE.md

Agent 11.10 - Trading Agent Service Design - Quick Reference

Date: 2025-10-16 Mission: Design the Trading Agent Service architecture Status: ✅ DESIGN COMPLETE

---

What Was Created

1. TRADING_AGENT_SERVICE_DESIGN.md (15,000+ words)

Comprehensive design document covering:

• Executive Summary: Service overview and key principles
• Architecture Overview: Current vs. target state diagrams
• Service Responsibilities: Clear separation between Agent (decision) and Trading Service (execution)
• gRPC API Design: Complete proto definition with 15 service methods
• Data Flow Diagrams: 4 detailed flow diagrams
• Integration Points: Trading Service, ML Training Service, TLI, Backtesting Service
• Service Configuration: Port allocation, environment variables, Docker setup
• Database Schema: 7 new tables for agent data persistence
• Implementation Plan: 8-week phased rollout
• Success Criteria: Functional, non-functional, integration, and testing requirements
• Risk Analysis: Technical and operational risks with mitigations
• Future Enhancements: Post-MVP roadmap

2. TRADING_AGENT_ARCHITECTURE_DIAGRAMS.md (7,000+ words)

Visual reference with 10 ASCII diagrams:

• System architecture overview
• Internal service architecture
• Trading decision flow (5 steps)
• Strategy coordination flow
• Integration sequence diagrams
• Database schema diagram
• Deployment architecture
• Monitoring dashboard layout

3. AGENT_11.10_QUICK_REFERENCE.md (this file)

Quick reference for implementation.

---

Key Design Decisions

1. Service Port: 50055

• gRPC: 50055
• Health: 8083
• Metrics: 9095

2. Service Responsibilities

Trading Agent Service (Decision-Making):

• ✅ Universe selection (which markets to trade)
• ✅ Asset selection (which instruments)
• ✅ Portfolio allocation (capital distribution)
• ✅ Order generation (create order instructions)
• ✅ Strategy coordination (manage multiple strategies)
• ✅ Risk management coordination (portfolio-level)
• ✅ Performance monitoring (track agent performance)

Trading Service (Execution):

• ✅ Order execution and lifecycle management
• ✅ Position tracking and PnL calculation
• ✅ Market data streaming
• ✅ Execution quality monitoring
• ✅ Paper trading simulation

Clear Separation: Agent decides, Trading Service executes.

3. gRPC API Structure (15 Methods)

Universe Management (3 methods):

• SelectUniverse(criteria) → Universe
• GetUniverse(universe_id) → Universe
• UpdateUniverseCriteria(criteria) → Universe

Asset Selection (2 methods):

• SelectAssets(universe_id, criteria) → Assets
• GetSelectedAssets(universe_id) → Assets

Portfolio Allocation (3 methods):

• AllocatePortfolio(assets, strategy, risk) → Allocation
• GetAllocation(allocation_id) → Allocation
• RebalancePortfolio(allocation_id, threshold) → RebalanceActions

Order Generation (2 methods):

• GenerateOrders(allocation_id, ml_signals) → Orders
• SubmitAgentOrders(order_batch_id, orders) → SubmissionResults

Strategy Coordination (3 methods):

• RegisterStrategy(name, type, config) → StrategyID
• ListStrategies(status_filter) → Strategies
• UpdateStrategyStatus(strategy_id, status) → Strategy

Monitoring (2 methods):

• GetAgentStatus(include_perf, include_pos) → Status
• StreamAgentActivity(activity_types) → stream Events
• GetAgentPerformance(window) → Metrics

4. Integration Patterns

Trading Agent → Trading Service:

// Get current positions
let positions = trading_client.get_positions(account_id).await?;

// Submit orders
let result = trading_client.submit_ml_order(MLOrderRequest {
    symbol: "ES.FUT",
    use_ensemble: true,
    features: feature_vector,
    ...
}).await?;

Trading Agent → ML Training Service:

// Get ML predictions
let predictions = ml_client.get_ml_predictions(GetMLPredictionsRequest {
    symbols: vec!["ES.FUT", "NQ.FUT"],
    models: vec!["DQN", "MAMBA2", "PPO", "TFT"],
    ...
}).await?;

TLI Commands (via API Gateway):

tli agent universe select --min-liquidity 0.7
tli agent universe show
tli agent assets select --top-n 5
tli agent allocate --strategy risk-parity --capital 1000000
tli agent orders generate --allocation-id abc123
tli agent orders submit --batch-id xyz789
tli agent strategy register --name "ml_v1" --type ML_ENSEMBLE
tli agent status
tli agent performance --window 24h
tli agent activity stream

5. Database Schema (7 Tables)

• trading_universes: Universe history
• asset_selections: Asset selection history
• portfolio_allocations: Portfolio allocation snapshots
• order_batches: Generated order batches
• agent_strategies: Registered strategies
• agent_activity_log: Activity audit trail
• agent_performance_metrics: Time-series performance data

6. Implementation Plan (8 Weeks)

Phase 1 (Week 1): Core service setup Phase 2 (Week 2): Universe & asset selection Phase 3 (Week 3): Portfolio allocation Phase 4 (Week 4): Order generation & execution Phase 5 (Week 5): Strategy coordination Phase 6 (Week 6): Monitoring & API Gateway integration Phase 7 (Week 7): Backtesting integration Phase 8 (Week 8): Production hardening

---

Performance Targets

• ✅ Universe selection: <1 second
• ✅ Asset selection: <2 seconds (including ML query)
• ✅ Portfolio allocation: <500ms
• ✅ Order generation: <200ms
• ✅ End-to-end (universe → orders): <5 seconds
• ✅ API response time: <100ms (non-blocking operations)

---

Example Workflow

Daily Rebalancing at Market Open:

08:30 AM → SelectUniverse(min_liquidity: 0.7)
           Returns: [ES.FUT, NQ.FUT, ZN.FUT, 6E.FUT]

08:31 AM → SelectAssets(universe_id, max_assets: 3)
           Queries ML Training Service
           Returns: [ES.FUT (0.85), NQ.FUT (0.78), ZN.FUT (0.72)]

08:32 AM → AllocatePortfolio(assets, RISK_PARITY, $1M)
           Returns: {ES: 35%, NQ: 40%, ZN: 25%}

08:33 AM → GenerateOrders(allocation_id, ml_signals)
           Returns: [BUY ES 15, BUY NQ 20, SELL ZN 5]

08:33 AM → SubmitAgentOrders(order_batch_id, orders)
           Calls Trading Service.SubmitMLOrder()
           Returns: {accepted: 3, rejected: 0, rate: 100%}

08:34 AM → StreamAgentActivity()
           Streams order fill events

08:35 AM → GetAgentPerformance(window: 24h)
           Returns: {pnl: $12.5K, sharpe: 1.8, win_rate: 65%}

---

Key Metrics (Prometheus)

# Universe
trading_agent_universe_size{universe_id} gauge
trading_agent_universe_liquidity_score{universe_id} gauge

# Asset Selection
trading_agent_selected_assets{universe_id} gauge
trading_agent_asset_composite_score{symbol} gauge

# Portfolio
trading_agent_portfolio_utilization gauge
trading_agent_portfolio_sharpe gauge

# Orders
trading_agent_orders_generated counter
trading_agent_orders_accepted counter
trading_agent_order_acceptance_rate gauge

# Strategies
trading_agent_strategy_pnl{strategy_id} gauge
trading_agent_strategy_sharpe{strategy_id} gauge

# Health
trading_agent_errors_total{error_type} counter
trading_agent_api_request_duration_seconds{method} histogram

---

Next Steps

1. ✅ Design Complete: Review and approve design documents
2. ⏳ Create GitHub Issues: Break down implementation into 8 phases
3. ⏳ Start Phase 1: Core service setup (Week 1)
4. ⏳ Iterative Development: Weekly demos and reviews

---

Files Created

Documentation

• /home/jgrusewski/Work/foxhunt/docs/TRADING_AGENT_SERVICE_DESIGN.md (15,000 words)
• /home/jgrusewski/Work/foxhunt/docs/TRADING_AGENT_ARCHITECTURE_DIAGRAMS.md (7,000 words)
• /home/jgrusewski/Work/foxhunt/docs/AGENT_11.10_QUICK_REFERENCE.md (this file)

Proto Definition (Not Yet Created)

• services/trading_agent_service/proto/trading_agent.proto (ready in design doc)

Implementation Structure (To Be Created)

services/trading_agent_service/
├── proto/
│   └── trading_agent.proto
├── src/
│   ├── main.rs
│   ├── lib.rs
│   ├── universe_manager.rs
│   ├── asset_selector.rs
│   ├── portfolio_allocator.rs
│   ├── order_generator.rs
│   ├── strategy_coordinator.rs
│   ├── risk_engine.rs
│   ├── repositories/
│   └── grpc_service.rs
├── Cargo.toml
├── Dockerfile
└── tests/

---

Success Criteria

Functional Requirements

• ✅ Universe selection completes in <1 second
• ✅ Asset selection completes in <2 seconds (including ML query)
• ✅ Portfolio allocation completes in <500ms
• ✅ Order generation completes in <200ms
• ✅ End-to-end (universe → orders) completes in <5 seconds
• ✅ Strategies execute on schedule with <100ms jitter
• ✅ All APIs return in <100ms (excluding long-running operations)

Non-Functional Requirements

• ✅ Service uptime >99.9%
• ✅ No data loss (all decisions logged to database)
• ✅ Prometheus metrics exported
• ✅ Health checks respond in <10ms
• ✅ Graceful shutdown (drain in-flight requests)
• ✅ Docker container restart recovery

Integration Requirements

• ✅ Trading Service integration (order submission)
• ✅ ML Training Service integration (prediction queries)
• ✅ API Gateway proxy configured
• ✅ TLI commands functional
• ✅ Backtesting simulation working

Testing Requirements

• ✅ Unit test coverage >80%
• ✅ Integration tests for all gRPC methods
• ✅ End-to-end tests across services
• ✅ Load tests (100 req/s sustained)
• ✅ Chaos tests (service failure recovery)

---

Design Principles

1. Separation of Concerns: Decision-making (Agent) vs. execution (Trading Service)
2. Reusability: Backtesting can reuse agent logic
3. Testability: Agent logic can be tested independently
4. Scalability: Agent can be scaled independently of Trading Service
5. Maintainability: Clear boundaries between components
6. Observability: Comprehensive metrics and logging
7. Resilience: Graceful degradation and error handling

---

Risk Mitigation

Technical Risks

• ML service latency → Cache predictions, use stale data if needed
• Trading service downtime → Queue orders, retry with exponential backoff
• Database bottleneck → Index optimization, read replicas, caching
• Strategy logic errors → Extensive testing, paper trading validation
• Order submission failures → Idempotent retry, comprehensive error handling

Operational Risks

• Configuration errors → Schema validation, default values, dry-run mode
• Resource exhaustion → Resource limits, monitoring alerts
• Data corruption → Database transactions, audit logging
• Version incompatibility → API versioning, backward compatibility

---

Alternatives Considered

Alternative	Decision	Rationale
Embed agent logic in Trading Service	❌ Rejected	Violates SRP, harder to test, couples decision-making with execution
Use message queue instead of gRPC	❌ Rejected	Added complexity for MVP, can add later if needed
Agent as library, not service	❌ Rejected	Limits reusability (backtesting needs it)

---

Future Enhancements (Post-MVP)

1. Advanced Allocation Strategies:

   • Black-Litterman allocation
   • Hierarchical risk parity
   • Reinforcement learning-based allocation

2. Multi-Account Support:

   • Manage multiple trading accounts
   • Cross-account risk aggregation

3. Regime Detection:

   • Automatic strategy switching based on market regime
   • Volatility regime detection

4. Advanced Rebalancing:

   • Tax-aware rebalancing
   • Transaction cost optimization

5. Strategy Marketplace:

   • User-defined strategies
   • Strategy backtesting UI
   • Strategy performance leaderboard

---

Summary

Trading Agent Service is a critical new component that orchestrates trading decisions by managing universe selection, asset selection, portfolio allocation, and strategy coordination. It drives the Trading Service by generating and submitting orders based on ML predictions, market conditions, and risk constraints.

Key Achievement: Clear separation of concerns between decision-making (Agent) and execution (Trading Service), enabling independent testing, scaling, and reusability across backtesting and live trading.

Estimated Implementation Time: 8 weeks (1 developer) Risk Level: Medium (new service, but clear interfaces) Status: ✅ DESIGN COMPLETE - READY FOR IMPLEMENTATION

---

Document Status: ✅ COMPLETE Last Updated: 2025-10-16 Agent: 11.10