foxhunt/tli/proto/ml.proto

syntax = "proto3";

package foxhunt.ml;

// ML Service - Model Insights & Predictions
service MLService {
  // Real-time ML streams
  rpc StreamModelPredictions(ModelRequest) returns (stream PredictionResponse);
  rpc StreamSignalStrength(SignalRequest) returns (stream SignalResponse);
  rpc StreamModelMetrics(MetricsRequest) returns (stream ModelMetricsResponse);

  // Model management
  rpc GetModelPerformance(ModelPerformanceRequest) returns (ModelPerformanceResponse);
  rpc GetEnsembleVote(EnsembleRequest) returns (EnsembleResponse);
  rpc GetFeatureImportance(FeatureRequest) returns (FeatureResponse);
  rpc RetrainModel(RetrainRequest) returns (RetrainResponse);

  // Model status
  rpc GetModelStatus(ModelStatusRequest) returns (ModelStatusResponse);
  rpc GetAvailableModels(Empty) returns (AvailableModelsResponse);
}

// ML Training Service - Dedicated Training Management
service MLTrainingService {
  // Training job management
  rpc StartTraining(StartTrainingRequest) returns (TrainingJob);
  rpc StopTraining(StopTrainingRequest) returns (TrainingJob);
  rpc ListTrainingJobs(ListTrainingJobsRequest) returns (ListTrainingJobsResponse);

  // Real-time training monitoring (streaming)
  rpc WatchTrainingProgress(WatchTrainingRequest) returns (stream TrainingProgressUpdate);

  // Training configuration and validation
  rpc ValidateTrainingConfig(TrainingConfigRequest) returns (TrainingConfigResponse);
  rpc GetTrainingTemplates(TrainingTemplatesRequest) returns (TrainingTemplatesResponse);

  // Resource management
  rpc GetResourceUtilization(ResourceRequest) returns (ResourceResponse);
  rpc StreamResourceMetrics(ResourceRequest) returns (stream ResourceMetricsUpdate);
}

// Real-time streaming requests
message ModelRequest {
  repeated string model_names = 1; // Empty for all models
  repeated string symbols = 2; // Empty for all symbols
  uint32 update_interval_seconds = 3; // Default: 1 second
}

message PredictionResponse {
  string model_name = 1;
  string symbol = 2;
  PredictionType prediction = 3;
  double confidence = 4;
  int64 timestamp_unix_nanos = 5;
  repeated double features = 6;
  double signal_strength = 7;
  ModelState model_state = 8;
}

message SignalRequest {
  repeated string symbols = 1;
  uint32 lookback_minutes = 2; // Signal strength lookback
  SignalAggregationType aggregation = 3;
}

message SignalResponse {
  string symbol = 1;
  double signal_strength = 2; // -1.0 to 1.0 (bearish to bullish)
  SignalDirection direction = 3;
  double confidence = 4;
  repeated ModelSignal model_signals = 5;
  int64 timestamp_unix_nanos = 6;
}

message ModelSignal {
  string model_name = 1;
  double signal = 2;
  double weight = 3;
  ModelState state = 4;
}

message MetricsRequest {
  repeated string model_names = 1;
  MetricType metric_type = 2;
  uint32 update_interval_seconds = 3;
}

message ModelMetricsResponse {
  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;
  uint64 predictions_made = 8;
  int64 last_training_unix_nanos = 9;
  ModelState state = 10;
  int64 timestamp_unix_nanos = 11;
}

// Model management requests
message ModelPerformanceRequest {
  string model_name = 1;
  optional int64 start_time_unix_nanos = 2;
  optional int64 end_time_unix_nanos = 3;
  repeated string symbols = 4; // Empty for all
}

message ModelPerformanceResponse {
  string model_name = 1;
  PerformanceMetrics overall = 2;
  repeated SymbolPerformance by_symbol = 3;
  repeated TimeseriesMetric timeseries = 4;
  ModelConfig config = 5;
}

message PerformanceMetrics {
  double accuracy = 1;
  double precision = 2;
  double recall = 3;
  double f1_score = 4;
  double auc_roc = 5;
  double sharpe_ratio = 6;
  double calmar_ratio = 7;
  double max_drawdown = 8;
  double win_rate = 9;
  double avg_return_per_trade = 10;
  uint64 total_predictions = 11;
  uint64 correct_predictions = 12;
}

message SymbolPerformance {
  string symbol = 1;
  PerformanceMetrics metrics = 2;
  uint64 trade_count = 3;
  double total_return = 4;
}

message TimeseriesMetric {
  int64 timestamp_unix_nanos = 1;
  double accuracy = 2;
  double signal_strength = 3;
  double volatility = 4;
}

message EnsembleRequest {
  repeated string symbols = 1;
  repeated string model_names = 2; // Empty for all models
  EnsembleMethod method = 3;
}

message EnsembleResponse {
  repeated EnsembleVote votes = 1;
  EnsembleMethod method_used = 2;
  double overall_confidence = 3;
  int64 timestamp_unix_nanos = 4;
}

message EnsembleVote {
  string symbol = 1;
  PredictionType consensus = 2;
  double confidence = 3;
  repeated ModelVote model_votes = 4;
  double signal_strength = 5;
}

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

message FeatureRequest {
  string model_name = 1;
  optional string symbol = 2;
  FeatureImportanceType type = 3;
}

message FeatureResponse {
  string model_name = 1;
  repeated FeatureImportance features = 2;
  FeatureImportanceType type = 3;
  int64 computed_at_unix_nanos = 4;
}

message FeatureImportance {
  string feature_name = 1;
  double importance_score = 2;
  double rank = 3;
  FeatureCategory category = 4;
  string description = 5;
}

message RetrainRequest {
  string model_name = 1;
  repeated string symbols = 2;
  int64 start_data_unix_nanos = 3;
  int64 end_data_unix_nanos = 4;
  map<string, string> hyperparameters = 5;
  bool force_retrain = 6;
}

message RetrainResponse {
  bool success = 1;
  string message = 2;
  string job_id = 3;
  int64 estimated_completion_unix_nanos = 4;
  TrainingStatus status = 5;
}

message ModelStatusRequest {
  repeated string model_names = 1; // Empty for all models
}

message ModelStatusResponse {
  repeated ModelStatus models = 1;
  int64 timestamp_unix_nanos = 2;
}

message ModelStatus {
  string model_name = 1;
  ModelState state = 2;
  ModelType type = 3;
  string version = 4;
  int64 last_trained_unix_nanos = 5;
  int64 last_prediction_unix_nanos = 6;
  PerformanceMetrics current_performance = 7;
  repeated string supported_symbols = 8;
  ModelConfig config = 9;
  string description = 10;
}

message ModelConfig {
  string model_type = 1;
  map<string, string> hyperparameters = 2;
  repeated string features = 3;
  uint32 lookback_window = 4;
  uint32 prediction_horizon = 5;
  double confidence_threshold = 6;
}

message AvailableModelsResponse {
  repeated AvailableModel models = 1;
  uint32 total_count = 2;
  int64 timestamp_unix_nanos = 3;
}

message AvailableModel {
  string model_name = 1;
  string display_name = 2;
  ModelType type = 3;
  string description = 4;
  repeated string supported_symbols = 5;
  ModelState state = 6;
  string version = 7;
  PerformanceMetrics performance_summary = 8;
}

// Empty message for parameterless requests
message Empty {}

// Enums
enum PredictionType {
  PREDICTION_TYPE_UNSPECIFIED = 0;
  PREDICTION_TYPE_BUY = 1;
  PREDICTION_TYPE_SELL = 2;
  PREDICTION_TYPE_HOLD = 3;
  PREDICTION_TYPE_STRONG_BUY = 4;
  PREDICTION_TYPE_STRONG_SELL = 5;
}

enum ModelState {
  MODEL_STATE_UNSPECIFIED = 0;
  MODEL_STATE_ACTIVE = 1;
  MODEL_STATE_TRAINING = 2;
  MODEL_STATE_LOADING = 3;
  MODEL_STATE_ERROR = 4;
  MODEL_STATE_DISABLED = 5;
  MODEL_STATE_WARM_UP = 6;
}

enum ModelType {
  MODEL_TYPE_UNSPECIFIED = 0;
  MODEL_TYPE_DQN = 1;
  MODEL_TYPE_PPO = 2;
  MODEL_TYPE_MAMBA = 3;
  MODEL_TYPE_TRANSFORMER = 4;
  MODEL_TYPE_LSTM = 5;
  MODEL_TYPE_TFT = 6;
  MODEL_TYPE_LIQUID = 7;
  MODEL_TYPE_ENSEMBLE = 8;
}

enum SignalDirection {
  SIGNAL_DIRECTION_UNSPECIFIED = 0;
  SIGNAL_DIRECTION_BULLISH = 1;
  SIGNAL_DIRECTION_BEARISH = 2;
  SIGNAL_DIRECTION_NEUTRAL = 3;
}

enum SignalAggregationType {
  SIGNAL_AGGREGATION_TYPE_UNSPECIFIED = 0;
  SIGNAL_AGGREGATION_TYPE_WEIGHTED_AVERAGE = 1;
  SIGNAL_AGGREGATION_TYPE_MAJORITY_VOTE = 2;
  SIGNAL_AGGREGATION_TYPE_CONFIDENCE_WEIGHTED = 3;
}

enum EnsembleMethod {
  ENSEMBLE_METHOD_UNSPECIFIED = 0;
  ENSEMBLE_METHOD_WEIGHTED_AVERAGE = 1;
  ENSEMBLE_METHOD_MAJORITY_VOTE = 2;
  ENSEMBLE_METHOD_STACKING = 3;
  ENSEMBLE_METHOD_BAYESIAN = 4;
}

enum FeatureImportanceType {
  FEATURE_IMPORTANCE_TYPE_UNSPECIFIED = 0;
  FEATURE_IMPORTANCE_TYPE_PERMUTATION = 1;
  FEATURE_IMPORTANCE_TYPE_SHAP = 2;
  FEATURE_IMPORTANCE_TYPE_GAIN = 3;
  FEATURE_IMPORTANCE_TYPE_SPLIT = 4;
}

enum FeatureCategory {
  FEATURE_CATEGORY_UNSPECIFIED = 0;
  FEATURE_CATEGORY_PRICE = 1;
  FEATURE_CATEGORY_VOLUME = 2;
  FEATURE_CATEGORY_TECHNICAL = 3;
  FEATURE_CATEGORY_SENTIMENT = 4;
  FEATURE_CATEGORY_MACRO = 5;
  FEATURE_CATEGORY_TEMPORAL = 6;
}

enum TrainingStatus {
  TRAINING_STATUS_UNSPECIFIED = 0;
  TRAINING_STATUS_QUEUED = 1;
  TRAINING_STATUS_PREPARING = 2; // Resource allocation, data loading
  TRAINING_STATUS_RUNNING = 3;
  TRAINING_STATUS_COMPLETED = 4;
  TRAINING_STATUS_FAILED = 5;
  TRAINING_STATUS_STOPPING = 6;
  TRAINING_STATUS_CANCELLED = 7;
}

// New messages for MLTrainingService
message StartTrainingRequest {
  string model_name = 1;
  string dataset_id = 2;
  TrainingHyperparameters hyperparameters = 3;
  ResourceRequirements resource_requirements = 4;
  repeated string tags = 5;
  string description = 6;
  bool auto_deploy = 7; // Auto-deploy on successful completion
}

message StopTrainingRequest {
  string job_id = 1;
  bool force = 2; // Force stop without cleanup
}

message ListTrainingJobsRequest {
  optional string model_name = 1;
  optional TrainingStatus status = 2;
  optional int64 start_time_after = 3;
  optional int64 start_time_before = 4;
  repeated string tags = 5;
  int32 limit = 6;
  string cursor = 7; // For pagination
}

message ListTrainingJobsResponse {
  repeated TrainingJob jobs = 1;
  string next_cursor = 2;
  int32 total_count = 3;
}

message TrainingJob {
  string job_id = 1;
  string model_name = 2;
  TrainingStatus status = 3;
  int64 start_time = 4;
  optional int64 end_time = 5;
  optional string resulting_model_id = 6;
  TrainingHyperparameters hyperparameters = 7;
  ResourceRequirements resource_requirements = 8;
  repeated string tags = 9;
  string description = 10;
  TrainingMetrics current_metrics = 11;
  optional string error_message = 12;
  double progress_percentage = 13;
}

message WatchTrainingRequest {
  string job_id = 1;
  bool include_logs = 2;
  bool include_metrics = 3;
}

message TrainingProgressUpdate {
  string job_id = 1;
  TrainingStatus status = 2;
  int32 current_epoch = 3;
  int32 total_epochs = 4;
  double progress_percentage = 5;
  TrainingMetrics metrics = 6;
  optional string log_message = 7;
  int64 timestamp = 8;
  optional ResourceUtilization resource_usage = 9;
}

message TrainingHyperparameters {
  double learning_rate = 1;
  int32 batch_size = 2;
  int32 epochs = 3;
  optional double dropout_rate = 4;
  optional int32 hidden_layers = 5;
  optional int32 hidden_units = 6;
  map<string, string> custom_params = 7;
}

message ResourceRequirements {
  int32 gpu_count = 1;
  int32 cpu_cores = 2;
  int64 memory_gb = 3;
  optional string gpu_type = 4; // e.g., "V100", "A100"
  int64 disk_gb = 5;
}

message TrainingMetrics {
  double loss = 1;
  double accuracy = 2;
  double validation_loss = 3;
  double validation_accuracy = 4;
  double learning_rate = 5;
  map<string, double> custom_metrics = 6;
}

message ResourceUtilization {
  double gpu_utilization = 1; // 0.0 to 1.0
  double gpu_memory_used = 2; // 0.0 to 1.0
  double cpu_utilization = 3;
  double memory_used = 4;
  double disk_used = 5;
  int64 timestamp = 6;
}

message TrainingConfigRequest {
  string model_name = 1;
  TrainingHyperparameters hyperparameters = 2;
  ResourceRequirements resource_requirements = 3;
}

message TrainingConfigResponse {
  bool valid = 1;
  repeated string validation_errors = 2;
  repeated string validation_warnings = 3;
  optional TrainingHyperparameters suggested_params = 4;
  optional ResourceRequirements suggested_resources = 5;
  double estimated_duration_hours = 6;
}

message TrainingTemplatesRequest {
  optional string model_type = 1;
}

message TrainingTemplatesResponse {
  repeated TrainingTemplate templates = 1;
}

message TrainingTemplate {
  string template_id = 1;
  string name = 2;
  string description = 3;
  string model_type = 4;
  TrainingHyperparameters default_hyperparameters = 5;
  ResourceRequirements recommended_resources = 6;
  repeated string supported_datasets = 7;
}

message ResourceRequest {
  // Empty for now, might add filtering later
}

message ResourceResponse {
  ResourceUtilization current_utilization = 1;
  repeated ResourceUtilization gpu_utilization = 2;
  int32 available_gpus = 3;
  int32 total_gpus = 4;
  repeated string active_training_jobs = 5;
}

message ResourceMetricsUpdate {
  ResourceUtilization utilization = 1;
  repeated TrainingJob active_jobs = 2;
  int64 timestamp = 3;
}

enum MetricType {
  METRIC_TYPE_UNSPECIFIED = 0;
  METRIC_TYPE_ACCURACY = 1;
  METRIC_TYPE_PERFORMANCE = 2;
  METRIC_TYPE_LATENCY = 3;
  METRIC_TYPE_ALL = 4;
}

enum LogLevel {
  LOG_LEVEL_UNSPECIFIED = 0;
  LOG_LEVEL_DEBUG = 1;
  LOG_LEVEL_INFO = 2;
  LOG_LEVEL_WARNING = 3;
  LOG_LEVEL_ERROR = 4;
  LOG_LEVEL_CRITICAL = 5;
}