foxhunt/proto/ml.proto

syntax = "proto3";

package ml;

// ML Service provides machine learning model management, predictions, and insights for trading decisions.
// This service integrates multiple ML models including MAMBA-2, TLOB transformers, DQN, and PPO models
// to provide real-time predictions, ensemble voting, and model performance monitoring.
service MLService {
  // Model Predictions and Inference
  // Get single prediction from a specific model
  rpc GetPrediction(GetPredictionRequest) returns (GetPredictionResponse);
  
  // Stream real-time predictions from multiple models
  rpc StreamPredictions(StreamPredictionsRequest) returns (stream PredictionEvent);
  
  // Get ensemble voting results from multiple models
  rpc GetEnsembleVote(GetEnsembleVoteRequest) returns (GetEnsembleVoteResponse);

  // Model Lifecycle Management
  // Get current status of ML models (health, performance, etc.)
  rpc GetModelStatus(GetModelStatusRequest) returns (GetModelStatusResponse);
  
  // List all available models and their capabilities
  rpc GetAvailableModels(GetAvailableModelsRequest) returns (GetAvailableModelsResponse);
  
  // Trigger model retraining with new data
  rpc RetrainModel(RetrainModelRequest) returns (RetrainModelResponse);

  // Model Performance and Analytics
  // Get comprehensive performance metrics for a model
  rpc GetModelPerformance(GetModelPerformanceRequest) returns (GetModelPerformanceResponse);
  
  // Stream real-time model performance metrics
  rpc StreamModelMetrics(StreamModelMetricsRequest) returns (stream ModelMetricsEvent);

  // Feature Analysis and Signal Intelligence
  // Get feature importance analysis for model interpretation
  rpc GetFeatureImportance(GetFeatureImportanceRequest) returns (GetFeatureImportanceResponse);
  
  // Stream real-time signal strength indicators across models
  rpc StreamSignalStrength(StreamSignalStrengthRequest) returns (stream SignalStrengthEvent);

  // Server-streaming: polls GetModelStatus at gateway level
  rpc StreamModelStatus(StreamModelStatusRequest) returns (stream GetModelStatusResponse);
}

// Streaming request messages

message StreamModelStatusRequest {
  string model_name = 1;       // empty = all models
  uint32 interval_seconds = 2; // 0 = server default (5s)
}

// Prediction Messages

// Request for model prediction
message GetPredictionRequest {
  string model_name = 1;                // Model to use (e.g., "mamba2", "tlob-transformer")
  string symbol = 2;                    // Trading symbol to predict
  optional int32 horizon_minutes = 3;   // Prediction horizon in minutes
  map<string, double> features = 4;     // Input features for prediction
}

// Response containing model prediction
message GetPredictionResponse {
  Prediction prediction = 1;            // Model prediction with details
  double confidence = 2;                // Prediction confidence (0.0 to 1.0)
  int64 timestamp = 3;                  // Prediction timestamp (nanoseconds)
}

message StreamPredictionsRequest {
  repeated string model_names = 1;
  repeated string symbols = 2;
  optional int32 update_frequency_seconds = 3;
}

message GetEnsembleVoteRequest {
  string symbol = 1;
  optional int32 horizon_minutes = 2;
  repeated string model_names = 3;
}

message GetEnsembleVoteResponse {
  EnsembleVote ensemble_vote = 1;
  repeated ModelVote individual_votes = 2;
  double overall_confidence = 3;
  int64 timestamp = 4;
}

// Model Management Messages
message GetModelStatusRequest {
  optional string model_name = 1;
}

message GetModelStatusResponse {
  repeated ModelStatus model_statuses = 1;
}

message GetAvailableModelsRequest {}

message GetAvailableModelsResponse {
  repeated ModelInfo available_models = 1;
}

message RetrainModelRequest {
  string model_name = 1;
  optional int64 start_time = 2;
  optional int64 end_time = 3;
  map<string, string> parameters = 4;
}

message RetrainModelResponse {
  bool success = 1;
  string message = 2;
  optional string job_id = 3;
  int64 started_at = 4;
}

// Performance Messages
message GetModelPerformanceRequest {
  string model_name = 1;
  optional int64 start_time = 2;
  optional int64 end_time = 3;
}

message GetModelPerformanceResponse {
  ModelPerformance performance = 1;
}

message StreamModelMetricsRequest {
  repeated string model_names = 1;
  optional int32 update_frequency_seconds = 2;
}

// Feature Analysis Messages
message GetFeatureImportanceRequest {
  string model_name = 1;
  optional string symbol = 2;
}

message GetFeatureImportanceResponse {
  repeated FeatureImportance feature_importances = 1;
  string model_name = 2;
  int64 calculated_at = 3;
}

message StreamSignalStrengthRequest {
  repeated string symbols = 1;
  optional int32 update_frequency_seconds = 2;
}

// Core ML Data Types

// Complete prediction information from a model
message Prediction {
  string model_name = 1;                // Model that generated prediction
  string symbol = 2;                    // Trading symbol
  PredictionType prediction_type = 3;   // Type of prediction (buy/sell/hold/price direction)
  double value = 4;                     // Predicted value (price change, probability, etc.)
  double confidence = 5;                // Model confidence in prediction (0.0 to 1.0)
  int32 horizon_minutes = 6;            // Prediction time horizon
  repeated Feature features = 7;        // Input features used for prediction
  int64 timestamp = 8;                  // Prediction generation timestamp (nanoseconds)
}

message EnsembleVote {
  string symbol = 1;
  PredictionType consensus_prediction = 2;
  double consensus_confidence = 3;
  int32 votes_buy = 4;
  int32 votes_sell = 5;
  int32 votes_hold = 6;
  int32 total_models = 7;
  SignalStrength signal_strength = 8;
}

message ModelVote {
  string model_name = 1;
  PredictionType prediction = 2;
  double confidence = 3;
  double weight = 4;
}

message ModelStatus {
  string model_name = 1;
  ModelState state = 2;
  optional string error_message = 3;
  int64 last_updated = 4;
  int64 last_prediction = 5;
  ModelHealth health = 6;
  map<string, string> metadata = 7;
}

message ModelInfo {
  string model_name = 1;
  string model_type = 2;
  string description = 3;
  repeated string supported_symbols = 4;
  repeated int32 supported_horizons = 5;
  ModelCapabilities capabilities = 6;
  map<string, string> parameters = 7;
}

message ModelPerformance {
  string model_name = 1;
  double accuracy = 2;
  double precision = 3;
  double recall = 4;
  double f1_score = 5;
  double sharpe_ratio = 6;
  double win_rate = 7;
  double avg_return = 8;
  double max_drawdown = 9;
  int32 total_predictions = 10;
  int64 performance_period_start = 11;
  int64 performance_period_end = 12;
  repeated DailyPerformance daily_performance = 13;
}

message DailyPerformance {
  string date = 1;
  double accuracy = 2;
  double return_pct = 3;
  int32 predictions_count = 4;
  double sharpe_ratio = 5;
}

message FeatureImportance {
  string feature_name = 1;
  double importance_score = 2;
  FeatureType feature_type = 3;
  double contribution_pct = 4;
}

message Feature {
  string name = 1;
  double value = 2;
  FeatureType feature_type = 3;
  double normalized_value = 4;
}

message ModelCapabilities {
  bool supports_streaming = 1;
  bool supports_retraining = 2;
  bool supports_feature_importance = 3;
  bool supports_confidence_intervals = 4;
  repeated string supported_asset_classes = 5;
}

// Event Messages
message PredictionEvent {
  string model_name = 1;
  string symbol = 2;
  Prediction prediction = 3;
  PredictionEventType event_type = 4;
  int64 timestamp = 5;
}

message ModelMetricsEvent {
  string model_name = 1;
  ModelMetrics metrics = 2;
  int64 timestamp = 3;
}

message SignalStrengthEvent {
  string symbol = 1;
  SignalStrength signal_strength = 2;
  repeated ModelSignal model_signals = 3;
  int64 timestamp = 4;
}

message ModelMetrics {
  string model_name = 1;
  double cpu_usage = 2;
  double memory_usage_mb = 3;
  double gpu_usage = 4;
  double predictions_per_second = 5;
  double avg_inference_time_ms = 6;
  int32 queue_size = 7;
  ModelHealth health = 8;
}

message ModelSignal {
  string model_name = 1;
  double signal_strength = 2;
  PredictionType direction = 3;
  double confidence = 4;
}

// Enums

// Types of predictions that ML models can generate
enum PredictionType {
  PREDICTION_TYPE_UNSPECIFIED = 0;      // Default/unknown prediction type
  PREDICTION_TYPE_BUY = 1;              // Recommendation to buy (go long)
  PREDICTION_TYPE_SELL = 2;             // Recommendation to sell (go short)
  PREDICTION_TYPE_HOLD = 3;             // Recommendation to hold position
  PREDICTION_TYPE_PRICE_UP = 4;         // Price expected to increase
  PREDICTION_TYPE_PRICE_DOWN = 5;       // Price expected to decrease
  PREDICTION_TYPE_VOLATILITY_HIGH = 6;  // High volatility expected
  PREDICTION_TYPE_VOLATILITY_LOW = 7;   // Low volatility expected
}

// Current operational state of ML models
enum ModelState {
  MODEL_STATE_UNSPECIFIED = 0;          // Default/unknown state
  MODEL_STATE_LOADING = 1;              // Model is loading from storage
  MODEL_STATE_READY = 2;                // Model loaded and ready for predictions
  MODEL_STATE_PREDICTING = 3;           // Model actively making predictions
  MODEL_STATE_TRAINING = 4;             // Model is being retrained
  MODEL_STATE_ERROR = 5;                // Model encountered an error
  MODEL_STATE_OFFLINE = 6;              // Model is offline/disabled
}

// Health status of ML models
enum ModelHealth {
  MODEL_HEALTH_UNSPECIFIED = 0;         // Default/unknown health
  MODEL_HEALTH_HEALTHY = 1;             // Model operating normally
  MODEL_HEALTH_DEGRADED = 2;            // Model performance degraded
  MODEL_HEALTH_UNHEALTHY = 3;           // Model not performing well
  MODEL_HEALTH_CRITICAL = 4;            // Model in critical state
}

// Types of features used in ML models
enum FeatureType {
  FEATURE_TYPE_UNSPECIFIED = 0;         // Default/unknown feature type
  FEATURE_TYPE_PRICE = 1;               // Price-based features (OHLC, etc.)
  FEATURE_TYPE_VOLUME = 2;              // Volume-based features
  FEATURE_TYPE_TECHNICAL = 3;           // Technical indicators (RSI, MACD, etc.)
  FEATURE_TYPE_FUNDAMENTAL = 4;         // Fundamental analysis features
  FEATURE_TYPE_SENTIMENT = 5;           // Market sentiment features
  FEATURE_TYPE_MACRO = 6;               // Macroeconomic features
  FEATURE_TYPE_TIME = 7;                // Time-based features
  FEATURE_TYPE_ORDERBOOK = 8;           // Order book depth and microstructure features
  FEATURE_TYPE_MICROSTRUCTURE = 9;      // Market microstructure and flow features
}

// Signal strength levels for predictions
enum SignalStrength {
  SIGNAL_STRENGTH_UNSPECIFIED = 0;      // Default/unknown strength
  SIGNAL_STRENGTH_VERY_WEAK = 1;        // Very weak signal confidence
  SIGNAL_STRENGTH_WEAK = 2;             // Weak signal confidence
  SIGNAL_STRENGTH_MODERATE = 3;         // Moderate signal confidence
  SIGNAL_STRENGTH_STRONG = 4;           // Strong signal confidence
  SIGNAL_STRENGTH_VERY_STRONG = 5;      // Very strong signal confidence
}

enum PredictionEventType {
  PREDICTION_EVENT_TYPE_UNSPECIFIED = 0;
  PREDICTION_EVENT_TYPE_NEW = 1;
  PREDICTION_EVENT_TYPE_UPDATED = 2;
  PREDICTION_EVENT_TYPE_EXPIRED = 3;
  PREDICTION_EVENT_TYPE_CONFIRMED = 4;
}