foxhunt/API_DOCUMENTATION.md

# Foxhunt API Documentation

**Version**: 1.0
**Last Updated**: 2025-10-16
**API Gateway**: `localhost:50051`
**Protocol**: gRPC with TLS/mTLS (RSA 4096-bit)

---

## Table of Contents

1. [Overview](#overview)
2. [Authentication & Authorization](#authentication--authorization)
3. [Rate Limiting](#rate-limiting)
4. [Error Handling](#error-handling)
5. [Service APIs](#service-apis)
   - [Trading Service (7 methods)](#trading-service)
   - [Trading Agent Service (18 methods)](#trading-agent-service)
   - [ML Training Service (12 methods)](#ml-training-service)
   - [Backtesting Service (6 methods)](#backtesting-service)
   - [Risk Management Service (6 methods)](#risk-management-service)
   - [Monitoring Service (10 methods)](#monitoring-service)
   - [Configuration Service (4 methods)](#configuration-service)
6. [TLI Command Reference](#tli-command-reference)
7. [Common Data Types](#common-data-types)

---

## Overview

The Foxhunt HFT Trading System exposes **37 gRPC methods** across **7 microservices**, all accessible through a single API Gateway at port **50051**. The API Gateway provides:

- **Authentication**: JWT + MFA (multi-factor authentication)
- **Rate Limiting**: Token bucket algorithm (100 req/sec default)
- **Audit Logging**: All requests logged to PostgreSQL
- **Request Routing**: Automatic service discovery and load balancing
- **TLS Encryption**: RSA 4096-bit certificates for all connections

### Service Architecture

```
┌──────────────────────────────────────────────────────────────┐
│                   API Gateway (Port 50051)                    │
│         Auth, Rate Limiting, Audit Logging, Routing           │
└──┬──────────────┬──────────────┬──────────────┬──────────────┘
   │              │              │              │
   ▼              ▼              ▼              ▼
Trading      Trading Agent  ML Training   Backtesting
Service      Service        Service        Service
(50052)      (50055)        (50054)        (50053)
```

---

## Authentication & Authorization

### JWT Authentication

All API requests require a valid JWT token in the `authorization` metadata header:

```
authorization: Bearer <jwt_token>
```

### Obtaining a JWT Token (via TLI)

```bash
# Login with username and password
tli auth login --username <username> --password <password>

# MFA verification (if enabled)
tli auth verify-mfa --code <6-digit-code>

# Token is automatically stored in ~/.config/foxhunt-tli/tokens/
```

### Token Lifetime

- **Access Token**: 1 hour (3600 seconds)
- **Refresh Token**: 7 days (604800 seconds)
- **MFA Grace Period**: 10 minutes after login

### Required Permissions

| Operation | Required Role |
|-----------|--------------|
| Submit Order | `TRADER`, `ADMIN` |
| Cancel Order | `TRADER`, `ADMIN` |
| Get Positions | `TRADER`, `VIEWER`, `ADMIN` |
| Emergency Stop | `ADMIN` only |
| Update Config | `ADMIN` only |
| View Metrics | `TRADER`, `VIEWER`, `ADMIN` |

---

## Rate Limiting

The API Gateway enforces rate limits using a token bucket algorithm:

### Default Limits

| Endpoint Type | Requests/Second | Burst Capacity |
|---------------|----------------|----------------|
| Trading Operations | 100 | 200 |
| Market Data Streams | 10 streams | 20 streams |
| Backtesting | 5 | 10 |
| ML Training | 2 | 5 |
| Configuration | 10 | 20 |

### Rate Limit Headers

Response headers indicate rate limit status:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1729123456
```

### Rate Limit Exceeded Error

```json
{
  "code": "RESOURCE_EXHAUSTED",
  "message": "Rate limit exceeded: 100 requests/second",
  "details": {
    "retry_after_seconds": 1
  }
}
```

---

## Error Handling

### gRPC Status Codes

| gRPC Code | HTTP Equivalent | Description |
|-----------|----------------|-------------|
| `OK` (0) | 200 | Success |
| `INVALID_ARGUMENT` (3) | 400 | Invalid request parameters |
| `UNAUTHENTICATED` (16) | 401 | Missing or invalid JWT token |
| `PERMISSION_DENIED` (7) | 403 | Insufficient permissions |
| `NOT_FOUND` (5) | 404 | Resource not found |
| `ALREADY_EXISTS` (6) | 409 | Resource already exists |
| `RESOURCE_EXHAUSTED` (8) | 429 | Rate limit exceeded |
| `INTERNAL` (13) | 500 | Internal server error |
| `UNAVAILABLE` (14) | 503 | Service temporarily unavailable |

### Error Response Format

```protobuf
message ErrorResponse {
  string code = 1;           // gRPC status code name
  string message = 2;        // Human-readable error message
  map<string, string> details = 3; // Additional error context
  int64 timestamp = 4;       // Error timestamp (nanoseconds)
}
```

---

## Service APIs

### Trading Service

**Base Package**: `trading`
**Backend Port**: 50052
**Total Methods**: 15 (12 core + 3 ML)

#### Core Trading Operations

##### 1. SubmitOrder

Submit a new trading order with validation and risk checks.

**Method**: `TradingService.SubmitOrder`

**Request**:
```protobuf
message SubmitOrderRequest {
  string symbol = 1;                    // Trading symbol (e.g., "AAPL", "BTC-USD", "ES.FUT")
  OrderSide side = 2;                   // BUY or SELL
  double quantity = 3;                  // Number of shares/units to trade
  OrderType order_type = 4;             // MARKET, LIMIT, STOP, STOP_LIMIT
  optional double price = 5;            // Limit price (required for LIMIT orders)
  optional double stop_price = 6;       // Stop price (required for STOP orders)
  string account_id = 7;                // Trading account identifier
  map<string, string> metadata = 8;     // Additional order metadata (strategy, tags, etc.)
}
```

**Response**:
```protobuf
message SubmitOrderResponse {
  string order_id = 1;                  // Unique order identifier
  OrderStatus status = 2;               // PENDING, SUBMITTED, etc.
  string message = 3;                   // Status message or error description
  int64 timestamp = 4;                  // Order submission timestamp (nanoseconds)
}
```

**TLI Command**: `tli trade submit --symbol <symbol> --side <BUY|SELL> --quantity <qty> --type <MARKET|LIMIT>`

**Example**:
```bash
tli trade submit --symbol ES.FUT --side BUY --quantity 10 --type MARKET
```

**Performance**: P99 latency ~15.96ms (target: <100ms)

---

##### 2. CancelOrder

Cancel an existing order by order ID.

**Method**: `TradingService.CancelOrder`

**Request**:
```protobuf
message CancelOrderRequest {
  string order_id = 1;                  // Order ID to cancel
  string account_id = 2;                // Account ID for verification
}
```

**Response**:
```protobuf
message CancelOrderResponse {
  bool success = 1;                     // True if cancellation was successful
  string message = 2;                   // Success confirmation or error message
  int64 timestamp = 3;                  // Cancellation timestamp (nanoseconds)
}
```

**TLI Command**: `tli trade cancel --order-id <order_id>`

**Example**:
```bash
tli trade cancel --order-id "550e8400-e29b-41d4-a716-446655440000"
```

---

##### 3. GetOrderStatus

Get current status of a specific order.

**Method**: `TradingService.GetOrderStatus`

**Request**:
```protobuf
message GetOrderStatusRequest {
  string order_id = 1;                  // Order ID to query
}
```

**Response**:
```protobuf
message GetOrderStatusResponse {
  Order order = 1;                      // Complete order details with current status
}
```

**TLI Command**: `tli trade status --order-id <order_id>`

**Example**:
```bash
tli trade status --order-id "550e8400-e29b-41d4-a716-446655440000"
```

---

##### 4. StreamOrders

Stream real-time order events for monitoring order lifecycle.

**Method**: `TradingService.StreamOrders` (Server Streaming)

**Request**:
```protobuf
message StreamOrdersRequest {
  optional string account_id = 1;       // Filter by account (all accounts if not specified)
  optional string symbol = 2;           // Filter by symbol (all symbols if not specified)
}
```

**Response Stream**:
```protobuf
message OrderEvent {
  string order_id = 1;                  // Order identifier
  Order order = 2;                      // Complete order details
  OrderEventType event_type = 3;        // CREATED, UPDATED, FILLED, CANCELLED, etc.
  int64 timestamp = 4;                  // Event timestamp (nanoseconds)
  string message = 5;                   // Event message or additional details
}
```

**TLI Command**: `tli trade stream --type orders [--symbol <symbol>]`

---

##### 5. GetPositions

Get current positions for account and/or symbol.

**Method**: `TradingService.GetPositions`

**Request**:
```protobuf
message GetPositionsRequest {
  optional string account_id = 1;       // Filter by account (all accounts if not specified)
  optional string symbol = 2;           // Filter by symbol (all symbols if not specified)
}
```

**Response**:
```protobuf
message GetPositionsResponse {
  repeated Position positions = 1;      // List of current positions
}
```

**TLI Command**: `tli trade positions [--symbol <symbol>]`

**Example**:
```bash
tli trade positions --symbol ES.FUT
```

---

##### 6. StreamPositions

Stream real-time position updates as trades execute.

**Method**: `TradingService.StreamPositions` (Server Streaming)

**Request**:
```protobuf
message StreamPositionsRequest {
  optional string account_id = 1;       // Filter by account (all accounts if not specified)
}
```

**Response Stream**:
```protobuf
message PositionEvent {
  string symbol = 1;                    // Trading symbol
  Position position = 2;                // Updated position details
  PositionEventType event_type = 3;     // OPENED, UPDATED, CLOSED
  int64 timestamp = 4;                  // Event timestamp (nanoseconds)
  double quantity = 5;                  // Position quantity (quick access)
  double average_price = 6;             // Average entry price (quick access)
  double unrealized_pnl = 7;            // Unrealized P&L (quick access)
}
```

**TLI Command**: `tli trade stream --type positions`

---

##### 7. GetPortfolioSummary

Get comprehensive portfolio summary with P&L and risk metrics.

**Method**: `TradingService.GetPortfolioSummary`

**Request**:
```protobuf
message GetPortfolioSummaryRequest {
  string account_id = 1;                // Account ID for portfolio summary
}
```

**Response**:
```protobuf
message GetPortfolioSummaryResponse {
  double total_value = 1;               // Total portfolio value in USD
  double unrealized_pnl = 2;            // Unrealized profit/loss
  double realized_pnl = 3;              // Realized profit/loss for the day
  double day_pnl = 4;                   // Total P&L for the current trading day
  double buying_power = 5;              // Available buying power
  double margin_used = 6;               // Amount of margin currently used
  repeated Position positions = 7;      // Detailed position information
}
```

**TLI Command**: `tli trade portfolio`

---

#### Market Data Operations

##### 8. StreamMarketData

Stream real-time market data (trades, quotes, order book).

**Method**: `TradingService.StreamMarketData` (Server Streaming)

**Request**:
```protobuf
message StreamMarketDataRequest {
  repeated string symbols = 1;          // List of symbols to subscribe to
  repeated MarketDataType data_types = 2; // TRADE, QUOTE, ORDER_BOOK
}
```

**Response Stream**:
```protobuf
message MarketDataEvent {
  string symbol = 1;                    // Trading symbol
  MarketDataType data_type = 2;         // Type of market data
  oneof data {
    Trade trade = 3;                    // Trade data (when data_type = TRADE)
    Quote quote = 4;                    // Quote data (when data_type = QUOTE)
    OrderBook order_book = 5;           // Order book data (when data_type = ORDER_BOOK)
  }
  int64 timestamp = 6;                  // Market data timestamp (nanoseconds)
}
```

**TLI Command**: `tli market stream --symbols <symbols> --types <TRADE|QUOTE|BOOK>`

---

##### 9. GetOrderBook

Get current order book snapshot for a symbol.

**Method**: `TradingService.GetOrderBook`

**Request**:
```protobuf
message GetOrderBookRequest {
  string symbol = 1;                    // Symbol to get order book for
  optional int32 depth = 2;             // Number of price levels (default: full book)
}
```

**Response**:
```protobuf
message GetOrderBookResponse {
  OrderBook order_book = 1;             // Current order book snapshot
}
```

**TLI Command**: `tli market book --symbol <symbol> [--depth <depth>]`

---

#### Execution Operations

##### 10. StreamExecutions

Stream real-time trade executions as they occur.

**Method**: `TradingService.StreamExecutions` (Server Streaming)

**Request**:
```protobuf
message StreamExecutionsRequest {
  optional string account_id = 1;       // Filter by account (all accounts if not specified)
  optional string symbol = 2;           // Filter by symbol (all symbols if not specified)
}
```

**Response Stream**:
```protobuf
message ExecutionEvent {
  string execution_id = 1;              // Execution identifier
  Execution execution = 2;              // Execution details
  int64 timestamp = 3;                  // Event timestamp (nanoseconds)
  string order_id = 4;                  // Associated order ID (quick access)
  string symbol = 5;                    // Trading symbol (quick access)
  double quantity = 6;                  // Executed quantity (quick access)
  double price = 7;                     // Execution price (quick access)
}
```

**TLI Command**: `tli trade stream --type executions`

---

##### 11. GetExecutionHistory

Get historical execution data with filtering options.

**Method**: `TradingService.GetExecutionHistory`

**Request**:
```protobuf
message GetExecutionHistoryRequest {
  optional string account_id = 1;       // Filter by account (all accounts if not specified)
  optional string symbol = 2;           // Filter by symbol (all symbols if not specified)
  optional int64 start_time = 3;        // Start time for query (nanoseconds)
  optional int64 end_time = 4;          // End time for query (nanoseconds)
  optional int32 limit = 5;             // Maximum number of executions to return
}
```

**Response**:
```protobuf
message GetExecutionHistoryResponse {
  repeated Execution executions = 1;    // List of historical executions
}
```

**TLI Command**: `tli trade history [--symbol <symbol>] [--limit <n>]`

---

#### ML Trading Operations

##### 12. SubmitMLOrder

Submit ML-generated trading order with ensemble predictions.

**Method**: `TradingService.SubmitMLOrder`

**Request**:
```protobuf
message MLOrderRequest {
  string symbol = 1;                    // Trading symbol (e.g., "ES.FUT")
  string account_id = 2;                // Trading account identifier
  bool use_ensemble = 3;                // Use ensemble voting or specific model
  optional string model_name = 4;       // Specific model name if not using ensemble
  repeated double features = 5;         // Feature vector for ML prediction (26 features: OHLCV + technicals)
}
```

**Response**:
```protobuf
message MLOrderResponse {
  string order_id = 1;                  // Order ID if executed
  string prediction_id = 2;             // Prediction ID from ensemble_predictions table
  string action = 3;                    // Action taken: BUY, SELL, HOLD
  double confidence = 4;                // Prediction confidence (0.0-1.0)
  string message = 5;                   // Status message
  bool executed = 6;                    // True if order was executed
}
```

**TLI Command**: `tli trade ml submit --symbol <symbol> [--model <DQN|PPO|MAMBA2|TFT>]`

**Example**:
```bash
# Submit ensemble ML order
tli trade ml submit --symbol ES.FUT

# Submit order using specific model
tli trade ml submit --symbol ES.FUT --model DQN
```

**Performance**: Inference latency ~200μs (DQN), ~500μs (MAMBA-2)

---

##### 13. GetMLPredictions

Get ML prediction history with outcomes.

**Method**: `TradingService.GetMLPredictions`

**Request**:
```protobuf
message MLPredictionsRequest {
  string symbol = 1;                    // Trading symbol to filter by
  optional string model_name = 2;       // Filter by specific model
  int32 limit = 3;                      // Maximum predictions to return (default: 100)
  optional int64 start_time = 4;        // Start time filter (nanoseconds)
  optional int64 end_time = 5;          // End time filter (nanoseconds)
}
```

**Response**:
```protobuf
message MLPredictionsResponse {
  repeated MLPrediction predictions = 1; // List of predictions with outcomes
}
```

**TLI Command**: `tli trade ml predictions --symbol <symbol> [--model <model>] [--limit <n>]`

**Example**:
```bash
tli trade ml predictions --symbol ES.FUT --limit 50
```

---

##### 14. GetMLPerformance

Get ML model performance metrics.

**Method**: `TradingService.GetMLPerformance`

**Request**:
```protobuf
message MLPerformanceRequest {
  optional string model_name = 1;       // Filter by specific model (or all if not specified)
  optional int64 start_time = 2;        // Start time for metrics (nanoseconds)
  optional int64 end_time = 3;          // End time for metrics (nanoseconds)
}
```

**Response**:
```protobuf
message MLPerformanceResponse {
  repeated ModelPerformance models = 1; // Performance metrics per model
}
```

**TLI Command**: `tli trade ml performance [--model <model>]`

**Example**:
```bash
# Get all model performance
tli trade ml performance

# Get specific model performance
tli trade ml performance --model MAMBA2
```

---

### Trading Agent Service

**Base Package**: `trading_agent`
**Backend Port**: 50055
**Total Methods**: 18

The Trading Agent Service orchestrates portfolio management decisions through universe selection, asset ranking, capital allocation, and order generation.

#### Universe Management

##### 1. SelectUniverse

Select tradable universe based on liquidity, volatility, and ML signals.

**Method**: `TradingAgentService.SelectUniverse`

**Request**:
```protobuf
message SelectUniverseRequest {
  UniverseCriteria criteria = 1;       // Selection criteria
  optional uint32 max_instruments = 2; // Maximum instruments in universe
  bool force_refresh = 3;              // Force recalculation
}
```

**Response**:
```protobuf
message SelectUniverseResponse {
  repeated Instrument instruments = 1; // Selected instruments
  UniverseMetrics metrics = 2;         // Universe quality metrics
  int64 timestamp = 3;                 // Selection timestamp (nanoseconds)
  string universe_id = 4;              // Unique universe identifier
}
```

**TLI Command**: `tli agent universe select [--max-instruments <n>]`

**Performance**: <1s (target met)

---

##### 2. GetUniverse

Get current trading universe configuration.

**Method**: `TradingAgentService.GetUniverse`

**Request**:
```protobuf
message GetUniverseRequest {
  optional string universe_id = 1;     // Get specific universe, or current if not specified
}
```

**Response**:
```protobuf
message GetUniverseResponse {
  string universe_id = 1;
  repeated Instrument instruments = 2;
  UniverseCriteria criteria = 3;
  UniverseMetrics metrics = 4;
  int64 created_at = 5;
  int64 updated_at = 6;
}
```

**TLI Command**: `tli agent universe show`

---

##### 3. UpdateUniverseCriteria

Update universe selection criteria.

**Method**: `TradingAgentService.UpdateUniverseCriteria`

**Request**:
```protobuf
message UpdateUniverseCriteriaRequest {
  UniverseCriteria criteria = 1;
}
```

**Response**:
```protobuf
message UpdateUniverseCriteriaResponse {
  bool success = 1;
  string message = 2;
  string universe_id = 3;              // New universe ID after update
}
```

**TLI Command**: `tli agent universe update --min-liquidity <val> --min-volatility <val>`

---

#### Asset Selection

##### 4. SelectAssets

Select specific assets to trade within universe using ML-driven ranking.

**Method**: `TradingAgentService.SelectAssets`

**Request**:
```protobuf
message SelectAssetsRequest {
  string universe_id = 1;              // Universe to select from
  AssetSelectionCriteria criteria = 2; // Selection criteria
  uint32 max_assets = 3;               // Maximum assets to select
}
```

**Response**:
```protobuf
message SelectAssetsResponse {
  repeated AssetScore assets = 1;      // Selected assets with scores
  SelectionMetrics metrics = 2;        // Selection quality metrics
  int64 timestamp = 3;
}
```

**TLI Command**: `tli agent assets select --max-assets <n>`

**Performance**: <2s (target met)

**Multi-Factor Scoring**:
- ML Score: 40% weight
- Momentum Score: 30% weight
- Value Score: 20% weight
- Liquidity Score: 10% weight

---

##### 5. GetSelectedAssets

Get current asset selection with scores.

**Method**: `TradingAgentService.GetSelectedAssets`

**Request**:
```protobuf
message GetSelectedAssetsRequest {
  optional string universe_id = 1;
}
```

**Response**:
```protobuf
message GetSelectedAssetsResponse {
  repeated AssetScore assets = 1;
  SelectionMetrics metrics = 2;
  int64 timestamp = 3;
}
```

**TLI Command**: `tli agent assets show`

---

#### Portfolio Allocation

##### 6. AllocatePortfolio

Allocate capital across selected assets using one of 5 strategies.

**Method**: `TradingAgentService.AllocatePortfolio`

**Request**:
```protobuf
message AllocatePortfolioRequest {
  repeated AssetScore assets = 1;      // Assets to allocate across
  AllocationStrategy strategy = 2;     // EQUAL_WEIGHT, RISK_PARITY, MEAN_VARIANCE, ML_OPTIMIZED, KELLY
  RiskConstraints risk_constraints = 3; // Risk limits
  double total_capital = 4;            // Total capital to allocate
}
```

**Response**:
```protobuf
message AllocatePortfolioResponse {
  repeated AssetAllocation allocations = 1; // Allocation per asset
  AllocationMetrics metrics = 2;       // Allocation quality metrics
  int64 timestamp = 3;
  string allocation_id = 4;
}
```

**TLI Command**: `tli agent allocate --strategy <EQUAL|RISK_PARITY|ML|KELLY> --capital <amount>`

**Performance**: <500ms (target met)

**Supported Allocation Strategies**:
1. **Equal Weight**: 1/N allocation
2. **Risk Parity**: Equal risk contribution per asset
3. **Mean-Variance**: Markowitz optimization
4. **ML-Optimized**: ML model-driven allocation
5. **Kelly Criterion**: Optimal bet sizing

---

##### 7. GetAllocation

Get current portfolio allocation.

**Method**: `TradingAgentService.GetAllocation`

**Request**:
```protobuf
message GetAllocationRequest {
  optional string allocation_id = 1;   // Get specific allocation, or current if not specified
}
```

**Response**:
```protobuf
message GetAllocationResponse {
  string allocation_id = 1;
  repeated AssetAllocation allocations = 2;
  AllocationMetrics metrics = 3;
  int64 created_at = 4;
  double total_capital = 5;
}
```

**TLI Command**: `tli agent allocate show`

---

##### 8. RebalancePortfolio

Rebalance portfolio based on target allocation.

**Method**: `TradingAgentService.RebalancePortfolio`

**Request**:
```protobuf
message RebalancePortfolioRequest {
  string allocation_id = 1;            // Target allocation
  double rebalance_threshold = 2;      // Min deviation to trigger rebalance (%)
  bool force_rebalance = 3;            // Force rebalance regardless of threshold
}
```

**Response**:
```protobuf
message RebalancePortfolioResponse {
  repeated RebalanceAction actions = 1; // Required rebalancing actions
  RebalanceMetrics metrics = 2;
  bool rebalance_required = 3;
  int64 timestamp = 4;
}
```

**TLI Command**: `tli agent rebalance [--threshold <pct>] [--force]`

---

#### Order Generation

##### 9. GenerateOrders

Generate orders based on allocation and ML signals.

**Method**: `TradingAgentService.GenerateOrders`

**Request**:
```protobuf
message GenerateOrdersRequest {
  string allocation_id = 1;            // Target allocation
  repeated MLSignal ml_signals = 2;    // ML predictions for timing
  OrderGenerationStrategy strategy = 3; // Order generation algorithm
}
```

**Response**:
```protobuf
message GenerateOrdersResponse {
  repeated GeneratedOrder orders = 1;  // Generated order instructions
  OrderGenerationMetrics metrics = 2;
  int64 timestamp = 3;
  string order_batch_id = 4;
}
```

**TLI Command**: `tli agent orders generate`

---

##### 10. SubmitAgentOrders

Submit generated orders to Trading Service.

**Method**: `TradingAgentService.SubmitAgentOrders`

**Request**:
```protobuf
message SubmitAgentOrdersRequest {
  string order_batch_id = 1;           // Batch ID from GenerateOrders
  repeated GeneratedOrder orders = 2;  // Orders to submit
  bool dry_run = 3;                    // Test without actual submission
}
```

**Response**:
```protobuf
message SubmitAgentOrdersResponse {
  repeated OrderSubmissionResult results = 1; // Submission results per order
  OrderSubmissionMetrics metrics = 2;
  int64 timestamp = 3;
}
```

**TLI Command**: `tli agent orders submit --batch-id <id> [--dry-run]`

---

#### Strategy Coordination

##### 11. RegisterStrategy

Register a trading strategy with the agent.

**Method**: `TradingAgentService.RegisterStrategy`

**Request**:
```protobuf
message RegisterStrategyRequest {
  string strategy_name = 1;            // Unique strategy name
  StrategyType strategy_type = 2;      // ML_ENSEMBLE, MEAN_REVERSION, MOMENTUM, ARBITRAGE, MARKET_MAKING
  StrategyConfig config = 3;           // Strategy configuration
  bool auto_enable = 4;                // Enable immediately after registration
}
```

**Response**:
```protobuf
message RegisterStrategyResponse {
  bool success = 1;
  string strategy_id = 2;
  string message = 3;
}
```

**TLI Command**: `tli agent strategy register --name <name> --type <type>`

---

##### 12. ListStrategies

Get list of active strategies.

**Method**: `TradingAgentService.ListStrategies`

**Request**:
```protobuf
message ListStrategiesRequest {
  optional StrategyStatus status_filter = 1; // ENABLED, DISABLED, PAUSED, ERROR
}
```

**Response**:
```protobuf
message ListStrategiesResponse {
  repeated Strategy strategies = 1;
}
```

**TLI Command**: `tli agent strategy list [--status <ENABLED|DISABLED>]`

---

##### 13. UpdateStrategyStatus

Enable/disable a strategy.

**Method**: `TradingAgentService.UpdateStrategyStatus`

**Request**:
```protobuf
message UpdateStrategyStatusRequest {
  string strategy_id = 1;
  StrategyStatus new_status = 2;       // ENABLED, DISABLED, PAUSED
  optional string reason = 3;
}
```

**Response**:
```protobuf
message UpdateStrategyStatusResponse {
  bool success = 1;
  string message = 2;
  Strategy updated_strategy = 3;
}
```

**TLI Command**: `tli agent strategy update --id <id> --status <ENABLED|DISABLED>`

---

#### Agent Monitoring

##### 14. GetAgentStatus

Get comprehensive agent status and performance.

**Method**: `TradingAgentService.GetAgentStatus`

**Request**:
```protobuf
message GetAgentStatusRequest {
  bool include_performance = 1;        // Include performance metrics
  bool include_positions = 2;          // Include current positions
}
```

**Response**:
```protobuf
message GetAgentStatusResponse {
  AgentStatus status = 1;
  optional AgentPerformanceMetrics performance = 2;
  optional PositionSummary positions = 3;
  int64 timestamp = 4;
}
```

**TLI Command**: `tli agent status [--with-performance] [--with-positions]`

---

##### 15. StreamAgentActivity

Stream real-time agent decisions and actions.

**Method**: `TradingAgentService.StreamAgentActivity` (Server Streaming)

**Request**:
```protobuf
message StreamAgentActivityRequest {
  repeated ActivityType activity_types = 1; // UNIVERSE_SELECTION, ASSET_SELECTION, ALLOCATION, ORDER_GENERATION, STRATEGY
}
```

**Response Stream**:
```protobuf
message AgentActivityEvent {
  ActivityType activity_type = 1;
  oneof event {
    UniverseSelectionEvent universe_event = 2;
    AssetSelectionEvent asset_event = 3;
    AllocationEvent allocation_event = 4;
    OrderGenerationEvent order_event = 5;
    StrategyEvent strategy_event = 6;
  }
  int64 timestamp = 7;
}
```

**TLI Command**: `tli agent stream [--types <types>]`

---

##### 16. GetAgentPerformance

Get agent performance metrics.

**Method**: `TradingAgentService.GetAgentPerformance`

**Request**:
```protobuf
message GetAgentPerformanceRequest {
  optional int64 start_time = 1;       // Performance window start (nanoseconds)
  optional int64 end_time = 2;         // Performance window end (nanoseconds)
  bool include_strategy_breakdown = 3; // Include per-strategy performance
}
```

**Response**:
```protobuf
message GetAgentPerformanceResponse {
  AgentPerformanceMetrics metrics = 1;
  repeated StrategyPerformance strategy_performance = 2;
  int64 timestamp = 3;
}
```

**TLI Command**: `tli agent performance [--start <time>] [--end <time>]`

---

##### 17. HealthCheck

Check Trading Agent Service health.

**Method**: `TradingAgentService.HealthCheck`

**Request**:
```protobuf
message HealthCheckRequest {}
```

**Response**:
```protobuf
message HealthCheckResponse {
  bool healthy = 1;
  string message = 2;
  map<string, string> details = 3;
}
```

**TLI Command**: `tli agent health`

---

### ML Training Service

**Base Package**: `ml_training`
**Backend Port**: 50054
**Total Methods**: 12

The ML Training Service manages model training jobs (MAMBA-2, DQN, PPO, TFT, TLOB), hyperparameter tuning with Optuna, and batch training workflows.

#### Training Job Management

##### 1. StartTraining

Initiates a new training job and returns job ID immediately.

**Method**: `MLTrainingService.StartTraining`

**Request**:
```protobuf
message StartTrainingRequest {
  string model_type = 1;                // TLOB, MAMBA_2, DQN, PPO, LIQUID, TFT
  DataSource data_source = 2;           // Training data source configuration
  Hyperparameters hyperparameters = 3;  // Model-specific training parameters
  bool use_gpu = 4;                     // Whether to use GPU acceleration
  string description = 5;               // Optional job description
  map<string, string> tags = 6;         // Optional categorization tags
}
```

**Response**:
```protobuf
message StartTrainingResponse {
  string job_id = 1;
  TrainingStatus status = 2;            // PENDING, RUNNING, COMPLETED, FAILED, STOPPED
  string message = 3;
}
```

**TLI Command**: `tli ml train --model <DQN|PPO|MAMBA2|TFT> [--gpu]`

**Example**:
```bash
tli ml train --model DQN --epochs 50 --batch-size 256 --gpu
```

**Performance**:
- DQN: ~15s for 50 epochs
- PPO: ~7s for 10 epochs
- MAMBA-2: ~1.86min for 200 epochs
- TFT: ~5-7 days for production training

---

##### 2. SubscribeToTrainingStatus

Subscribe to real-time training progress and status updates.

**Method**: `MLTrainingService.SubscribeToTrainingStatus` (Server Streaming)

**Request**:
```protobuf
message SubscribeToTrainingStatusRequest {
  string job_id = 1;
}
```

**Response Stream**:
```protobuf
message TrainingStatusUpdate {
  string job_id = 1;
  TrainingStatus status = 2;
  float progress_percentage = 3;        // Training progress (0.0 to 100.0)
  uint32 current_epoch = 4;
  uint32 total_epochs = 5;
  map<string, float> metrics = 6;       // loss, accuracy, sharpe_ratio, etc.
  string message = 7;
  int64 timestamp = 8;
  FinancialMetrics financial_metrics = 9;
  ResourceUsage resource_usage = 10;
}
```

**TLI Command**: `tli ml train --model <model> --watch`

---

##### 3. StopTraining

Stop a running training job (idempotent operation).

**Method**: `MLTrainingService.StopTraining`

**Request**:
```protobuf
message StopTrainingRequest {
  string job_id = 1;
  string reason = 2;                    // Optional reason for stopping
}
```

**Response**:
```protobuf
message StopTrainingResponse {
  bool success = 1;
  string message = 2;
}
```

**TLI Command**: `tli ml stop --job-id <job_id>`

---

##### 4. ListAvailableModels

List available ML models with their training parameters.

**Method**: `MLTrainingService.ListAvailableModels`

**Request**:
```protobuf
message ListAvailableModelsRequest {}
```

**Response**:
```protobuf
message ListAvailableModelsResponse {
  repeated ModelDefinition models = 1;
}
```

**TLI Command**: `tli ml list-models`

---

##### 5. ListTrainingJobs

Get paginated list of training job history.

**Method**: `MLTrainingService.ListTrainingJobs`

**Request**:
```protobuf
message ListTrainingJobsRequest {
  uint32 page = 1;
  uint32 page_size = 2;
  TrainingStatus status_filter = 3;
  string model_type_filter = 4;
  int64 start_time = 5;                 // Unix timestamp in seconds
  int64 end_time = 6;
}
```

**Response**:
```protobuf
message ListTrainingJobsResponse {
  repeated TrainingJobSummary jobs = 1;
  uint32 total_count = 2;
  uint32 page = 3;
  uint32 page_size = 4;
}
```

**TLI Command**: `tli ml jobs [--status <RUNNING|COMPLETED|FAILED>] [--model <model>]`

---

##### 6. GetTrainingJobDetails

Get comprehensive details for a specific training job.

**Method**: `MLTrainingService.GetTrainingJobDetails`

**Request**:
```protobuf
message GetTrainingJobDetailsRequest {
  string job_id = 1;
}
```

**Response**:
```protobuf
message GetTrainingJobDetailsResponse {
  TrainingJobDetails job_details = 1;
}
```

**TLI Command**: `tli ml job-details --job-id <job_id>`

---

#### Hyperparameter Tuning

##### 7. StartTuningJob

Start a new hyperparameter tuning job using Optuna.

**Method**: `MLTrainingService.StartTuningJob`

**Request**:
```protobuf
message StartTuningJobRequest {
  string model_type = 1;                // Model type to tune
  uint32 num_trials = 2;                // Number of tuning trials to run
  string config_path = 3;               // Path to tuning configuration file
  DataSource data_source = 4;           // Training data source
  bool use_gpu = 5;                     // Whether to use GPU acceleration
  string description = 6;
  map<string, string> tags = 7;
}
```

**Response**:
```protobuf
message StartTuningJobResponse {
  string job_id = 1;
  TuningJobStatus status = 2;           // TUNING_PENDING, TUNING_RUNNING, TUNING_COMPLETED, TUNING_FAILED, TUNING_STOPPED
  string message = 3;
}
```

**TLI Command**: `tli tune start --model <DQN|PPO|MAMBA2|TFT> --trials <n> [--watch]`

**Example**:
```bash
tli tune start --model DQN --trials 50 --watch
```

**Performance**: 5-10 minutes per trial, 4-8 hours for 50 trials

---

##### 8. GetTuningJobStatus

Get current status and best parameters from a tuning job.

**Method**: `MLTrainingService.GetTuningJobStatus`

**Request**:
```protobuf
message GetTuningJobStatusRequest {
  string job_id = 1;
}
```

**Response**:
```protobuf
message GetTuningJobStatusResponse {
  string job_id = 1;
  TuningJobStatus status = 2;
  uint32 current_trial = 3;
  uint32 total_trials = 4;
  map<string, float> best_params = 5;   // Best hyperparameters found so far
  map<string, float> best_metrics = 6;  // sharpe_ratio, training_loss, etc.
  repeated TrialResult trial_history = 7;
  string message = 8;
  int64 started_at = 9;
  int64 updated_at = 10;
}
```

**TLI Command**: `tli tune status --job-id <job_id>`

---

##### 9. StopTuningJob

Stop a running hyperparameter tuning job.

**Method**: `MLTrainingService.StopTuningJob`

**Request**:
```protobuf
message StopTuningJobRequest {
  string job_id = 1;
  string reason = 2;
}
```

**Response**:
```protobuf
message StopTuningJobResponse {
  bool success = 1;
  string message = 2;
  TuningJobStatus final_status = 3;
}
```

**TLI Command**: `tli tune stop --job-id <job_id>`

---

##### 10. StreamTuningProgress

Stream real-time tuning progress updates (trial completion events).

**Method**: `MLTrainingService.StreamTuningProgress` (Server Streaming)

**Request**:
```protobuf
message StreamProgressRequest {
  string job_id = 1;
}
```

**Response Stream**:
```protobuf
message ProgressUpdate {
  string job_id = 1;
  uint32 current_trial = 2;
  uint32 total_trials = 3;
  map<string, string> trial_params = 4;
  float trial_sharpe = 5;               // Current trial's Sharpe ratio
  float best_sharpe_so_far = 6;
  uint32 estimated_time_remaining = 7;  // Seconds until completion
  TuningJobStatus status = 8;
  string message = 9;
  int64 timestamp = 10;
  UpdateType update_type = 11;          // TRIAL_COMPLETE, HEARTBEAT, JOB_COMPLETE
}
```

**TLI Command**: `tli tune start --model <model> --trials <n> --watch`

---

##### 11. BatchStartTuningJobs

Start batch tuning job for multiple models with automatic dependency resolution.

**Method**: `MLTrainingService.BatchStartTuningJobs`

**Request**:
```protobuf
message BatchStartTuningJobsRequest {
  repeated string model_types = 1;      // List of models to tune
  uint32 trials_per_model = 2;          // Number of trials for each model
  string config_path = 3;
  DataSource data_source = 4;
  bool use_gpu = 5;
  bool auto_export_yaml = 6;            // Automatically export best params to YAML
  string yaml_export_path = 7;          // Custom YAML export path
  string description = 8;
  map<string, string> tags = 9;
}
```

**Response**:
```protobuf
message BatchStartTuningJobsResponse {
  string batch_id = 1;
  repeated string execution_order = 2;  // Model execution order (after dependency resolution)
  string message = 3;
  BatchTuningStatus status = 4;         // BATCH_PENDING, BATCH_RUNNING, BATCH_COMPLETED, etc.
}
```

**TLI Command**: `tli tune batch --models <DQN,PPO,MAMBA2,TFT> --trials <n>`

---

##### 12. GetBatchTuningStatus

Get batch tuning job status with per-model results.

**Method**: `MLTrainingService.GetBatchTuningStatus`

**Request**:
```protobuf
message GetBatchTuningStatusRequest {
  string batch_id = 1;
}
```

**Response**:
```protobuf
message GetBatchTuningStatusResponse {
  string batch_id = 1;
  BatchTuningStatus status = 2;
  uint32 current_model_index = 3;
  uint32 total_models = 4;
  repeated ModelTuningResult results = 5;
  string current_model = 6;
  int64 started_at = 7;
  int64 updated_at = 8;
  int64 estimated_completion_time = 9;
  string yaml_export_path = 10;
}
```

**TLI Command**: `tli tune batch-status --batch-id <batch_id>`

---

### Backtesting Service

**Base Package**: `foxhunt.tli.BacktestingService` (defined in TLI proto)
**Backend Port**: 50053
**Total Methods**: 6

#### Backtest Execution Management

##### 1. StartBacktest

Start a new strategy backtest with historical data.

**Method**: `BacktestingService.StartBacktest`

**Request**:
```protobuf
message StartBacktestRequest {
  string strategy_name = 1;
  repeated string symbols = 2;
  int64 start_date_unix_nanos = 3;
  int64 end_date_unix_nanos = 4;
  double initial_capital = 5;
  map<string, string> parameters = 6;
  bool save_results = 7;
  string description = 8;
}
```

**Response**:
```protobuf
message StartBacktestResponse {
  bool success = 1;
  string backtest_id = 2;
  string message = 3;
  int64 estimated_duration_seconds = 4;
}
```

**TLI Command**: `tli backtest start --strategy <name> --symbols <symbols> --start <date> --end <date> --capital <amount>`

**Example**:
```bash
tli backtest start --strategy moving_average_crossover --symbols ES.FUT,NQ.FUT --start 2024-01-01 --end 2024-03-31 --capital 100000
```

**Performance**: DBN data loading in 0.70ms for 1,674 bars (14x faster than target)

---

##### 2. GetBacktestStatus

Get current status of a running backtest.

**Method**: `BacktestingService.GetBacktestStatus`

**Request**:
```protobuf
message GetBacktestStatusRequest {
  string backtest_id = 1;
}
```

**Response**:
```protobuf
message GetBacktestStatusResponse {
  string backtest_id = 1;
  BacktestStatus status = 2;            // QUEUED, RUNNING, COMPLETED, FAILED, CANCELLED, PAUSED
  double progress_percentage = 3;
  string current_date = 4;
  uint64 trades_executed = 5;
  double current_pnl = 6;
  int64 started_at_unix_nanos = 7;
  optional int64 completed_at_unix_nanos = 8;
  optional string error_message = 9;
}
```

**TLI Command**: `tli backtest status --id <backtest_id>`

---

##### 3. GetBacktestResults

Get comprehensive backtest results and analytics.

**Method**: `BacktestingService.GetBacktestResults`

**Request**:
```protobuf
message GetBacktestResultsRequest {
  string backtest_id = 1;
  bool include_trades = 2;
  bool include_metrics = 3;
}
```

**Response**:
```protobuf
message GetBacktestResultsResponse {
  string backtest_id = 1;
  BacktestMetrics metrics = 2;
  repeated Trade trades = 3;
  repeated EquityCurvePoint equity_curve = 4;
  repeated DrawdownPeriod drawdown_periods = 5;
}
```

**TLI Command**: `tli backtest results --id <backtest_id> [--with-trades]`

---

##### 4. ListBacktests

List historical backtest runs with filtering.

**Method**: `BacktestingService.ListBacktests`

**Request**:
```protobuf
message ListBacktestsRequest {
  uint32 limit = 1;
  uint32 offset = 2;
  optional string strategy_name = 3;
  optional BacktestStatus status_filter = 4;
}
```

**Response**:
```protobuf
message ListBacktestsResponse {
  repeated BacktestSummary backtests = 1;
  uint32 total_count = 2;
}
```

**TLI Command**: `tli backtest list [--strategy <name>] [--status <COMPLETED|RUNNING>]`

---

##### 5. SubscribeBacktestProgress

Subscribe to real-time backtest progress updates.

**Method**: `BacktestingService.SubscribeBacktestProgress` (Server Streaming)

**Request**:
```protobuf
message SubscribeBacktestProgressRequest {
  string backtest_id = 1;
}
```

**Response Stream**:
```protobuf
message BacktestProgressEvent {
  string backtest_id = 1;
  double progress_percentage = 2;
  string current_date = 3;
  uint64 trades_executed = 4;
  double current_pnl = 5;
  double current_equity = 6;
  BacktestStatus status = 7;
  int64 timestamp_unix_nanos = 8;
}
```

**TLI Command**: `tli backtest start --strategy <name> --watch`

---

##### 6. StopBacktest

Stop a running backtest and optionally save partial results.

**Method**: `BacktestingService.StopBacktest`

**Request**:
```protobuf
message StopBacktestRequest {
  string backtest_id = 1;
  bool save_partial_results = 2;
}
```

**Response**:
```protobuf
message StopBacktestResponse {
  bool success = 1;
  string message = 2;
  bool results_saved = 3;
}
```

**TLI Command**: `tli backtest stop --id <backtest_id> [--save-partial]`

---

### Risk Management Service

**Base Package**: `risk`
**Backend Port**: 50052 (co-located with Trading Service)
**Total Methods**: 6

#### Value at Risk (VaR) Calculations

##### 1. GetVaR

Calculate current portfolio VaR using specified method and parameters.

**Method**: `RiskService.GetVaR`

**Request**:
```protobuf
message GetVaRRequest {
  repeated string symbols = 1;          // Symbols to include (empty = all positions)
  double confidence_level = 2;          // e.g., 0.95 for 95% VaR
  int32 lookback_days = 3;              // Historical data period
  VaRMethod method = 4;                 // HISTORICAL, PARAMETRIC, MONTE_CARLO
}
```

**Response**:
```protobuf
message GetVaRResponse {
  double portfolio_var = 1;             // Total portfolio VaR value
  repeated SymbolVaR symbol_vars = 2;   // Individual symbol VaR contributions
  double confidence_level = 3;
  int32 lookback_days = 4;
  VaRMethod method = 5;
  int64 calculated_at = 6;
}
```

**TLI Command**: `tli risk var [--symbols <symbols>] [--confidence 0.95] [--lookback 30]`

---

##### 2. StreamVaRUpdates

Stream real-time VaR updates as market conditions change.

**Method**: `RiskService.StreamVaRUpdates` (Server Streaming)

**Request**:
```protobuf
message StreamVaRRequest {
  double confidence_level = 1;
  int32 update_frequency_seconds = 2;
}
```

**Response Stream**:
```protobuf
message VaREvent {
  double portfolio_var = 1;
  repeated SymbolVaR symbol_vars = 2;
  VaRChangeType change_type = 3;        // INCREASED, DECREASED, BREACH
  int64 timestamp = 4;
}
```

**TLI Command**: `tli risk stream --type var`

---

##### 3. GetPositionRisk

Get comprehensive risk analysis for current positions.

**Method**: `RiskService.GetPositionRisk`

**Request**:
```protobuf
message GetPositionRiskRequest {
  optional string symbol = 1;           // Filter by symbol
  optional string account_id = 2;       // Filter by account
}
```

**Response**:
```protobuf
message GetPositionRiskResponse {
  repeated PositionRisk position_risks = 1;
  double portfolio_risk_score = 2;      // Overall score (0-100)
}
```

**TLI Command**: `tli risk positions [--symbol <symbol>]`

---

##### 4. ValidateOrder

Validate order against risk limits before execution.

**Method**: `RiskService.ValidateOrder`

**Request**:
```protobuf
message ValidateOrderRequest {
  string symbol = 1;
  double quantity = 2;
  double price = 3;
  string side = 4;                      // BUY or SELL
  string account_id = 5;
}
```

**Response**:
```protobuf
message ValidateOrderResponse {
  bool is_valid = 1;                    // True if order passes all risk checks
  repeated RiskViolation violations = 2;
  RiskScore risk_score = 3;
  string message = 4;
}
```

**TLI Command**: `tli risk validate --symbol <symbol> --side <BUY|SELL> --quantity <qty> --price <price>`

---

##### 5. GetRiskMetrics

Get comprehensive portfolio risk metrics and statistics.

**Method**: `RiskService.GetRiskMetrics`

**Request**:
```protobuf
message GetRiskMetricsRequest {
  optional string portfolio_id = 1;
}
```

**Response**:
```protobuf
message GetRiskMetricsResponse {
  RiskMetrics metrics = 1;
  int64 calculated_at = 2;
}
```

**TLI Command**: `tli risk metrics`

---

##### 6. EmergencyStop

Trigger emergency stop to halt trading activities.

**Method**: `RiskService.EmergencyStop`

**Request**:
```protobuf
message EmergencyStopRequest {
  EmergencyStopType stop_type = 1;      // ALL_TRADING, SYMBOL, ACCOUNT, STRATEGY
  string reason = 2;
  optional string symbol = 3;
  optional string account_id = 4;
}
```

**Response**:
```protobuf
message EmergencyStopResponse {
  bool success = 1;
  string message = 2;
  int64 timestamp = 3;
  repeated string affected_orders = 4;
}
```

**TLI Command**: `tli risk emergency-stop [--type <ALL|SYMBOL|ACCOUNT>] --reason <reason>`

**Required Permission**: `ADMIN` only

---

### Monitoring Service

**Base Package**: `monitoring`
**Backend Port**: 50052 (co-located with Trading Service)
**Total Methods**: 10

#### Health and Status Monitoring

##### 1. GetSystemStatus

Get overall system status and individual service health.

**Method**: `MonitoringService.GetSystemStatus`

**Request**:
```protobuf
message GetSystemStatusRequest {
  repeated string service_names = 1;    // Empty for all services
}
```

**Response**:
```protobuf
message GetSystemStatusResponse {
  SystemStatus overall_status = 1;
  repeated ServiceStatus service_statuses = 2;
  int64 timestamp = 3;
}
```

**TLI Command**: `tli monitor status [--services <services>]`

---

##### 2. StreamSystemStatus

Stream real-time system status changes.

**Method**: `MonitoringService.StreamSystemStatus` (Server Streaming)

**Request**:
```protobuf
message StreamSystemStatusRequest {
  repeated string service_names = 1;
  optional int32 update_frequency_seconds = 2;
}
```

**Response Stream**:
```protobuf
message SystemStatusEvent {
  SystemStatus system_status = 1;
  SystemStatusChangeType change_type = 2; // HEALTH_IMPROVED, HEALTH_DEGRADED, SERVICE_STARTED, etc.
  int64 timestamp = 3;
}
```

**TLI Command**: `tli monitor stream --type status`

---

##### 3. GetHealthCheck

Perform detailed health checks on services.

**Method**: `MonitoringService.GetHealthCheck`

**Request**:
```protobuf
message GetHealthCheckRequest {
  optional string service_name = 1;
}
```

**Response**:
```protobuf
message GetHealthCheckResponse {
  HealthStatus health_status = 1;       // HEALTHY, DEGRADED, UNHEALTHY, CRITICAL
  repeated HealthCheck health_checks = 2;
  int64 timestamp = 3;
}
```

**TLI Command**: `tli monitor health [--service <service>]`

---

##### 4. GetMetrics

Get system and application metrics.

**Method**: `MonitoringService.GetMetrics`

**Request**:
```protobuf
message GetMetricsRequest {
  repeated string metric_names = 1;
  optional int64 start_time = 2;
  optional int64 end_time = 3;
  optional MetricAggregation aggregation = 4; // SUM, AVG, MIN, MAX, COUNT
}
```

**Response**:
```protobuf
message GetMetricsResponse {
  repeated Metric metrics = 1;
  int64 timestamp = 2;
}
```

**TLI Command**: `tli monitor metrics [--names <names>] [--start <time>] [--end <time>]`

---

##### 5. StreamMetrics

Stream real-time performance metrics.

**Method**: `MonitoringService.StreamMetrics` (Server Streaming)

**Request**:
```protobuf
message StreamMetricsRequest {
  repeated string metric_names = 1;
  optional int32 update_frequency_seconds = 2;
}
```

**Response Stream**:
```protobuf
message MetricsEvent {
  repeated Metric metrics = 1;
  int64 timestamp = 2;
}
```

**TLI Command**: `tli monitor stream --type metrics --names <names>`

---

##### 6. GetLatencyMetrics

Get detailed latency performance metrics.

**Method**: `MonitoringService.GetLatencyMetrics`

**Request**:
```protobuf
message GetLatencyMetricsRequest {
  optional string service_name = 1;
  optional string operation_name = 2;
  optional int64 start_time = 3;
  optional int64 end_time = 4;
}
```

**Response**:
```protobuf
message GetLatencyMetricsResponse {
  repeated LatencyMetric latency_metrics = 1;
}
```

**TLI Command**: `tli monitor latency [--service <service>] [--operation <op>]`

**Performance Benchmarks**:
- Authentication: 4.4μs P99 (target: <10μs)
- Order Matching: 1-6μs P99 (target: <50μs)
- Order Submission: 15.96ms P99 (target: <100ms)
- API Gateway Proxy: 21-488μs (target: <1ms)

---

##### 7. GetThroughputMetrics

Get throughput and capacity metrics.

**Method**: `MonitoringService.GetThroughputMetrics`

**Request**:
```protobuf
message GetThroughputMetricsRequest {
  optional string service_name = 1;
  optional string operation_name = 2;
  optional int64 start_time = 3;
  optional int64 end_time = 4;
}
```

**Response**:
```protobuf
message GetThroughputMetricsResponse {
  repeated ThroughputMetric throughput_metrics = 1;
}
```

**TLI Command**: `tli monitor throughput [--service <service>]`

---

##### 8. StreamAlerts

Stream real-time system alerts and notifications.

**Method**: `MonitoringService.StreamAlerts` (Server Streaming)

**Request**:
```protobuf
message StreamAlertsRequest {
  optional AlertSeverity min_severity = 1; // INFO, WARNING, CRITICAL, EMERGENCY
  repeated string service_names = 2;
  repeated AlertType alert_types = 3;
}
```

**Response Stream**:
```protobuf
message AlertEvent {
  Alert alert = 1;
  AlertEventType event_type = 2;        // TRIGGERED, ACKNOWLEDGED, RESOLVED, ESCALATED
  int64 timestamp = 3;
}
```

**TLI Command**: `tli monitor stream --type alerts [--severity <level>]`

---

##### 9. AcknowledgeAlert

Acknowledge an active alert.

**Method**: `MonitoringService.AcknowledgeAlert`

**Request**:
```protobuf
message AcknowledgeAlertRequest {
  string alert_id = 1;
  string acknowledged_by = 2;
  optional string note = 3;
}
```

**Response**:
```protobuf
message AcknowledgeAlertResponse {
  bool success = 1;
  string message = 2;
  int64 timestamp = 3;
}
```

**TLI Command**: `tli monitor alert-ack --id <alert_id> --note <note>`

---

##### 10. GetActiveAlerts

Get all currently active alerts.

**Method**: `MonitoringService.GetActiveAlerts`

**Request**:
```protobuf
message GetActiveAlertsRequest {
  optional AlertSeverity min_severity = 1;
  repeated string service_names = 2;
}
```

**Response**:
```protobuf
message GetActiveAlertsResponse {
  repeated Alert active_alerts = 1;
  int32 total_count = 2;
}
```

**TLI Command**: `tli monitor alerts [--severity <level>]`

---

### Configuration Service

**Base Package**: `foxhunt.config`
**Backend Port**: 50052 (co-located with Trading Service)
**Total Methods**: 4

##### 1. GetConfig

Get a single configuration value.

**Method**: `ConfigurationService.GetConfig`

**Request**:
```protobuf
message GetConfigRequest {
  string service_scope = 1;
  string config_key = 2;
}
```

**Response**:
```protobuf
message GetConfigResponse {
  string config_value = 1;              // JSON-serialized value
  string data_type = 2;
  string description = 3;
  int64 updated_at = 4;                 // Unix timestamp
  string updated_by = 5;
}
```

**TLI Command**: `tli config get --scope <service> --key <key>`

---

##### 2. UpdateConfig

Update a configuration value.

**Method**: `ConfigurationService.UpdateConfig`

**Request**:
```protobuf
message UpdateConfigRequest {
  string service_scope = 1;
  string config_key = 2;
  string new_value = 3;                 // JSON-serialized value
  string updated_by = 4;
}
```

**Response**:
```protobuf
message UpdateConfigResponse {
  bool success = 1;
  string message = 2;
}
```

**TLI Command**: `tli config update --scope <service> --key <key> --value <value>`

**Required Permission**: `ADMIN` only

---

##### 3. ListConfigs

List all configurations for a service scope.

**Method**: `ConfigurationService.ListConfigs`

**Request**:
```protobuf
message ListConfigsRequest {
  optional string service_scope = 1;    // If not provided, lists all scopes
}
```

**Response**:
```protobuf
message ListConfigsResponse {
  repeated ConfigItem configs = 1;
}
```

**TLI Command**: `tli config list [--scope <service>]`

---

##### 4. ReloadConfig

Trigger configuration reload.

**Method**: `ConfigurationService.ReloadConfig`

**Request**:
```protobuf
message ReloadConfigRequest {
  optional string service_scope = 1;
  optional string config_key = 2;
}
```

**Response**:
```protobuf
message ReloadConfigResponse {
  bool success = 1;
  string message = 2;
}
```

**TLI Command**: `tli config reload [--scope <service>] [--key <key>]`

---

## TLI Command Reference

Complete mapping of TLI commands to gRPC methods.

### Authentication Commands

| TLI Command | gRPC Method | Description |
|-------------|-------------|-------------|
| `tli auth login` | N/A (HTTP/REST) | Login with username/password |
| `tli auth verify-mfa` | N/A (HTTP/REST) | Verify MFA code |
| `tli auth logout` | N/A | Clear stored JWT token |
| `tli auth status` | N/A | Check authentication status |

### Trading Commands

| TLI Command | gRPC Method | Service |
|-------------|-------------|---------|
| `tli trade submit` | `TradingService.SubmitOrder` | Trading |
| `tli trade cancel` | `TradingService.CancelOrder` | Trading |
| `tli trade status` | `TradingService.GetOrderStatus` | Trading |
| `tli trade positions` | `TradingService.GetPositions` | Trading |
| `tli trade portfolio` | `TradingService.GetPortfolioSummary` | Trading |
| `tli trade history` | `TradingService.GetExecutionHistory` | Trading |
| `tli trade stream` | `TradingService.StreamOrders/StreamPositions/StreamExecutions` | Trading |

### ML Trading Commands

| TLI Command | gRPC Method | Service |
|-------------|-------------|---------|
| `tli trade ml submit` | `TradingService.SubmitMLOrder` | Trading |
| `tli trade ml predictions` | `TradingService.GetMLPredictions` | Trading |
| `tli trade ml performance` | `TradingService.GetMLPerformance` | Trading |

### Trading Agent Commands

| TLI Command | gRPC Method | Service |
|-------------|-------------|---------|
| `tli agent universe select` | `TradingAgentService.SelectUniverse` | Trading Agent |
| `tli agent universe show` | `TradingAgentService.GetUniverse` | Trading Agent |
| `tli agent universe update` | `TradingAgentService.UpdateUniverseCriteria` | Trading Agent |
| `tli agent assets select` | `TradingAgentService.SelectAssets` | Trading Agent |
| `tli agent assets show` | `TradingAgentService.GetSelectedAssets` | Trading Agent |
| `tli agent allocate` | `TradingAgentService.AllocatePortfolio` | Trading Agent |
| `tli agent allocate show` | `TradingAgentService.GetAllocation` | Trading Agent |
| `tli agent rebalance` | `TradingAgentService.RebalancePortfolio` | Trading Agent |
| `tli agent orders generate` | `TradingAgentService.GenerateOrders` | Trading Agent |
| `tli agent orders submit` | `TradingAgentService.SubmitAgentOrders` | Trading Agent |
| `tli agent strategy register` | `TradingAgentService.RegisterStrategy` | Trading Agent |
| `tli agent strategy list` | `TradingAgentService.ListStrategies` | Trading Agent |
| `tli agent strategy update` | `TradingAgentService.UpdateStrategyStatus` | Trading Agent |
| `tli agent status` | `TradingAgentService.GetAgentStatus` | Trading Agent |
| `tli agent performance` | `TradingAgentService.GetAgentPerformance` | Trading Agent |
| `tli agent stream` | `TradingAgentService.StreamAgentActivity` | Trading Agent |
| `tli agent health` | `TradingAgentService.HealthCheck` | Trading Agent |

### ML Training Commands

| TLI Command | gRPC Method | Service |
|-------------|-------------|---------|
| `tli ml train` | `MLTrainingService.StartTraining` | ML Training |
| `tli ml stop` | `MLTrainingService.StopTraining` | ML Training |
| `tli ml jobs` | `MLTrainingService.ListTrainingJobs` | ML Training |
| `tli ml job-details` | `MLTrainingService.GetTrainingJobDetails` | ML Training |
| `tli ml list-models` | `MLTrainingService.ListAvailableModels` | ML Training |

### Hyperparameter Tuning Commands

| TLI Command | gRPC Method | Service |
|-------------|-------------|---------|
| `tli tune start` | `MLTrainingService.StartTuningJob` | ML Training |
| `tli tune status` | `MLTrainingService.GetTuningJobStatus` | ML Training |
| `tli tune stop` | `MLTrainingService.StopTuningJob` | ML Training |
| `tli tune batch` | `MLTrainingService.BatchStartTuningJobs` | ML Training |
| `tli tune batch-status` | `MLTrainingService.GetBatchTuningStatus` | ML Training |

### Backtesting Commands

| TLI Command | gRPC Method | Service |
|-------------|-------------|---------|
| `tli backtest start` | `BacktestingService.StartBacktest` | Backtesting |
| `tli backtest status` | `BacktestingService.GetBacktestStatus` | Backtesting |
| `tli backtest results` | `BacktestingService.GetBacktestResults` | Backtesting |
| `tli backtest list` | `BacktestingService.ListBacktests` | Backtesting |
| `tli backtest stop` | `BacktestingService.StopBacktest` | Backtesting |

### Risk Management Commands

| TLI Command | gRPC Method | Service |
|-------------|-------------|---------|
| `tli risk var` | `RiskService.GetVaR` | Risk |
| `tli risk positions` | `RiskService.GetPositionRisk` | Risk |
| `tli risk validate` | `RiskService.ValidateOrder` | Risk |
| `tli risk metrics` | `RiskService.GetRiskMetrics` | Risk |
| `tli risk emergency-stop` | `RiskService.EmergencyStop` | Risk |
| `tli risk stream` | `RiskService.StreamVaRUpdates` | Risk |

### Monitoring Commands

| TLI Command | gRPC Method | Service |
|-------------|-------------|---------|
| `tli monitor status` | `MonitoringService.GetSystemStatus` | Monitoring |
| `tli monitor health` | `MonitoringService.GetHealthCheck` | Monitoring |
| `tli monitor metrics` | `MonitoringService.GetMetrics` | Monitoring |
| `tli monitor latency` | `MonitoringService.GetLatencyMetrics` | Monitoring |
| `tli monitor throughput` | `MonitoringService.GetThroughputMetrics` | Monitoring |
| `tli monitor alerts` | `MonitoringService.GetActiveAlerts` | Monitoring |
| `tli monitor alert-ack` | `MonitoringService.AcknowledgeAlert` | Monitoring |
| `tli monitor stream` | `MonitoringService.StreamMetrics/StreamAlerts/StreamSystemStatus` | Monitoring |

### Configuration Commands

| TLI Command | gRPC Method | Service |
|-------------|-------------|---------|
| `tli config get` | `ConfigurationService.GetConfig` | Configuration |
| `tli config update` | `ConfigurationService.UpdateConfig` | Configuration |
| `tli config list` | `ConfigurationService.ListConfigs` | Configuration |
| `tli config reload` | `ConfigurationService.ReloadConfig` | Configuration |

### Market Data Commands

| TLI Command | gRPC Method | Service |
|-------------|-------------|---------|
| `tli market stream` | `TradingService.StreamMarketData` | Trading |
| `tli market book` | `TradingService.GetOrderBook` | Trading |

---

## Common Data Types

### Order Enums

```protobuf
enum OrderSide {
  ORDER_SIDE_UNSPECIFIED = 0;
  ORDER_SIDE_BUY = 1;
  ORDER_SIDE_SELL = 2;
}

enum OrderType {
  ORDER_TYPE_UNSPECIFIED = 0;
  ORDER_TYPE_MARKET = 1;
  ORDER_TYPE_LIMIT = 2;
  ORDER_TYPE_STOP = 3;
  ORDER_TYPE_STOP_LIMIT = 4;
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_SUBMITTED = 2;
  ORDER_STATUS_PARTIALLY_FILLED = 3;
  ORDER_STATUS_FILLED = 4;
  ORDER_STATUS_CANCELLED = 5;
  ORDER_STATUS_REJECTED = 6;
}
```

### Position Data

```protobuf
message Position {
  string symbol = 1;
  double quantity = 2;                  // Positive = long, negative = short
  double average_price = 3;
  double market_value = 4;
  double unrealized_pnl = 5;
  double realized_pnl = 6;
  string account_id = 7;
  int64 updated_at = 8;
}
```

### Order Data

```protobuf
message Order {
  string order_id = 1;
  string symbol = 2;
  OrderSide side = 3;
  double quantity = 4;
  double filled_quantity = 5;
  OrderType order_type = 6;
  optional double price = 7;
  optional double stop_price = 8;
  OrderStatus status = 9;
  int64 created_at = 10;
  optional int64 updated_at = 11;
  string account_id = 12;
  map<string, string> metadata = 13;
}
```

### Risk Data

```protobuf
enum RiskLevel {
  RISK_LEVEL_UNSPECIFIED = 0;
  RISK_LEVEL_LOW = 1;
  RISK_LEVEL_MEDIUM = 2;
  RISK_LEVEL_HIGH = 3;
  RISK_LEVEL_CRITICAL = 4;
}

enum VaRMethod {
  VAR_METHOD_UNSPECIFIED = 0;
  VAR_METHOD_HISTORICAL = 1;
  VAR_METHOD_PARAMETRIC = 2;
  VAR_METHOD_MONTE_CARLO = 3;
}
```

### Training Job Status

```protobuf
enum TrainingStatus {
  UNKNOWN = 0;
  PENDING = 1;
  RUNNING = 2;
  COMPLETED = 3;
  FAILED = 4;
  STOPPED = 5;
  PAUSED = 6;
}

enum TuningJobStatus {
  TUNING_UNKNOWN = 0;
  TUNING_PENDING = 1;
  TUNING_RUNNING = 2;
  TUNING_COMPLETED = 3;
  TUNING_FAILED = 4;
  TUNING_STOPPED = 5;
}
```

---

## Method Count Summary

| Service | Methods | Port |
|---------|---------|------|
| Trading Service | 15 (12 core + 3 ML) | 50052 |
| Trading Agent Service | 18 | 50055 |
| ML Training Service | 12 | 50054 |
| Backtesting Service | 6 | 50053 |
| Risk Management Service | 6 | 50052 |
| Monitoring Service | 10 | 50052 |
| Configuration Service | 4 | 50052 |
| **Total** | **71** | - |

**Note**: The CLAUDE.md document mentions 37 methods, which refers to the **user-facing methods accessible via API Gateway**. The actual proto definitions include **71 total gRPC methods** across all services (including internal/admin methods).

**API Gateway Exposed Methods**: 37 (subset of 71 total, excluding internal/admin methods)

---

## Appendix: Performance Benchmarks

### Latency Targets

| Operation | P99 Latency | Target | Status |
|-----------|-------------|--------|--------|
| Authentication | 4.4μs | <10μs | ✅ Met |
| Order Matching | 1-6μs | <50μs | ✅ Met |
| Order Submission | 15.96ms | <100ms | ✅ Met |
| API Gateway Proxy | 21-488μs | <1ms | ✅ Met |
| DBN Data Loading | 0.70ms | <10ms | ✅ Met (14x faster) |
| ML Inference (DQN) | ~200μs | <1ms | ✅ Met |
| ML Inference (MAMBA-2) | ~500μs | <1ms | ✅ Met |
| Universe Selection | <1s | <1s | ✅ Met |
| Asset Selection | <2s | <2s | ✅ Met |
| Portfolio Allocation | <500ms | <500ms | ✅ Met |

### Throughput

| Operation | Throughput | Target | Status |
|-----------|-----------|--------|--------|
| PostgreSQL Inserts | 2,979/sec | 660/sec | ✅ Met (4.5x) |
| API Gateway Requests | 100/sec | 100/sec | ✅ Met |
| Market Data Streams | 10 streams | 10 streams | ✅ Met |

---

## References

- **Proto Files**: `/services/{service}/proto/*.proto`
- **TLI Commands**: `/tli/src/commands/*.rs`
- **API Gateway**: `/services/api_gateway/src/main.rs`
- **CLAUDE.md**: System architecture and current status

**Last Updated**: 2025-10-16
**Maintained By**: Foxhunt Development Team