// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.cloud.hypercomputecluster.v1alpha;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.HypercomputeCluster.V1Alpha";
option go_package = "cloud.google.com/go/hypercomputecluster/apiv1alpha/hypercomputeclusterpb;hypercomputeclusterpb";
option java_multiple_files = true;
option java_outer_classname = "MachineLearningRunsProto";
option java_package = "com.google.cloud.hypercomputecluster.v1alpha";
option php_namespace = "Google\\Cloud\\HypercomputeCluster\\V1alpha";
option ruby_package = "Google::Cloud::HypercomputeCluster::V1alpha";

// Service for managing Machine Learning Runs.
service MachineLearningRuns {
  option (google.api.default_host) = "hypercomputecluster.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Creates a Machine Learning Run.
  rpc CreateMachineLearningRun(CreateMachineLearningRunRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1alpha/{parent=projects/*/locations/*}/machineLearningRuns"
      body: "machine_learning_run"
    };
    option (google.api.method_signature) =
        "parent,machine_learning_run,machine_learning_run_id";
    option (google.longrunning.operation_info) = {
      response_type: "MachineLearningRun"
      metadata_type: "OperationMetadata"
    };
  }

  // Updates an Machine Learning Run.
  rpc UpdateMachineLearningRun(UpdateMachineLearningRunRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      patch: "/v1alpha/{machine_learning_run.name=projects/*/locations/*/machineLearningRuns/*}"
      body: "machine_learning_run"
    };
    option (google.api.method_signature) = "machine_learning_run,update_mask";
    option (google.longrunning.operation_info) = {
      response_type: "MachineLearningRun"
      metadata_type: "OperationMetadata"
    };
  }

  // Deletes a Machine Learning Run.
  rpc DeleteMachineLearningRun(DeleteMachineLearningRunRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      delete: "/v1alpha/{name=projects/*/locations/*/machineLearningRuns/*}"
    };
    option (google.api.method_signature) = "name";
    option (google.longrunning.operation_info) = {
      response_type: "google.protobuf.Empty"
      metadata_type: "OperationMetadata"
    };
  }

  // Gets a Machine Learning Run.
  rpc GetMachineLearningRun(GetMachineLearningRunRequest)
      returns (MachineLearningRun) {
    option (google.api.http) = {
      get: "/v1alpha/{name=projects/*/locations/*/machineLearningRuns/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Lists Machine Learning Runs.
  rpc ListMachineLearningRuns(ListMachineLearningRunsRequest)
      returns (ListMachineLearningRunsResponse) {
    option (google.api.http) = {
      get: "/v1alpha/{parent=projects/*/locations/*}/machineLearningRuns"
    };
    option (google.api.method_signature) = "parent";
  }

  // Creates a Profiler Target.
  rpc CreateProfilerTarget(CreateProfilerTargetRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1alpha/{parent=projects/*/locations/*/machineLearningRuns/*}/profilerTargets"
      body: "profiler_target"
    };
    option (google.api.method_signature) =
        "parent,profiler_target,profiler_target_id";
    option (google.longrunning.operation_info) = {
      response_type: "ProfilerTarget"
      metadata_type: "OperationMetadata"
    };
  }

  // Gets a Profiler Target.
  rpc GetProfilerTarget(GetProfilerTargetRequest) returns (ProfilerTarget) {
    option (google.api.http) = {
      get: "/v1alpha/{name=projects/*/locations/*/machineLearningRuns/*/profilerTargets/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // List Profiler Targets for a Machine Learning Run.
  rpc ListProfilerTargets(ListProfilerTargetsRequest)
      returns (ListProfilerTargetsResponse) {
    option (google.api.http) = {
      get: "/v1alpha/{parent=projects/*/locations/*/machineLearningRuns/*}/profilerTargets"
    };
    option (google.api.method_signature) = "parent";
  }

  // Delete a Profiler Target.
  rpc DeleteProfilerTarget(DeleteProfilerTargetRequest)
      returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1alpha/{name=projects/*/locations/*/machineLearningRuns/*/profilerTargets/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Create a Profiler Session.
  rpc CreateProfilerSession(CreateProfilerSessionRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1alpha/{parent=projects/*/locations/*/machineLearningRuns/*}/profilerSessions"
      body: "profiler_session"
    };
    option (google.api.method_signature) =
        "parent,profiler_session,profiler_session_id";
    option (google.longrunning.operation_info) = {
      response_type: "ProfilerSession"
      metadata_type: "OperationMetadata"
    };
  }

  // Get Profiler Session.
  rpc GetProfilerSession(GetProfilerSessionRequest) returns (ProfilerSession) {
    option (google.api.http) = {
      get: "/v1alpha/{name=projects/*/locations/*/machineLearningRuns/*/profilerSessions/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Lists Profiler Sessions for a Machine Learning Run.
  rpc ListProfilerSessions(ListProfilerSessionsRequest)
      returns (ListProfilerSessionsResponse) {
    option (google.api.http) = {
      get: "/v1alpha/{parent=projects/*/locations/*/machineLearningRuns/*}/profilerSessions"
    };
    option (google.api.method_signature) = "parent";
  }

  // Delete a Profiler Session.
  rpc DeleteProfilerSession(DeleteProfilerSessionRequest)
      returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1alpha/{name=projects/*/locations/*/machineLearningRuns/*/profilerSessions/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Deprecated: Use `GetProfilerSession` instead.
  // Gets a Profile Session.
  rpc GetProfileSession(GetProfileSessionRequest) returns (ProfileSession) {
    option deprecated = true;
    option (google.api.http) = {
      get: "/v1alpha/{name=projects/*/locations/*/machineLearningRuns/*/profileSessions/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Deprecated: Use `ListProfilerSessions` instead.
  // Lists Profile Sessions for a Machine Learning Run.
  rpc ListProfileSessions(ListProfileSessionsRequest)
      returns (ListProfileSessionsResponse) {
    option deprecated = true;
    option (google.api.http) = {
      get: "/v1alpha/{parent=projects/*/locations/*/machineLearningRuns/*}/profileSessions"
    };
    option (google.api.method_signature) = "parent";
  }

  // Creates a Monitored Event.
  rpc CreateMonitoredEvent(CreateMonitoredEventRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1alpha/{parent=projects/*/locations/*/machineLearningRuns/*}/monitoredEvents"
      body: "monitored_event"
    };
    option (google.api.method_signature) =
        "parent,monitored_event,monitored_event_id";
    option (google.longrunning.operation_info) = {
      response_type: "MonitoredEvent"
      metadata_type: "OperationMetadata"
    };
  }

  // Gets a specific Monitored Event.
  rpc GetMonitoredEvent(GetMonitoredEventRequest) returns (MonitoredEvent) {
    option (google.api.http) = {
      get: "/v1alpha/{name=projects/*/locations/*/machineLearningRuns/*/monitoredEvents/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Lists Monitored Events for a run.
  rpc ListMonitoredEvents(ListMonitoredEventsRequest)
      returns (ListMonitoredEventsResponse) {
    option (google.api.http) = {
      get: "/v1alpha/{parent=projects/*/locations/*/machineLearningRuns/*}/monitoredEvents"
    };
    option (google.api.method_signature) = "parent";
  }

  // Updates a Monitored Event.
  rpc UpdateMonitoredEvent(UpdateMonitoredEventRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      patch: "/v1alpha/{monitored_event.name=projects/*/locations/*/machineLearningRuns/*/monitoredEvents/*}"
      body: "monitored_event"
    };
    option (google.api.method_signature) = "monitored_event,update_mask";
    option (google.longrunning.operation_info) = {
      response_type: "MonitoredEvent"
      metadata_type: "OperationMetadata"
    };
  }

  // Deletes a Monitored Event.
  rpc DeleteMonitoredEvent(DeleteMonitoredEventRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      delete: "/v1alpha/{name=projects/*/locations/*/machineLearningRuns/*/monitoredEvents/*}"
    };
    option (google.api.method_signature) = "name";
    option (google.longrunning.operation_info) = {
      response_type: "google.protobuf.Empty"
      metadata_type: "OperationMetadata"
    };
  }
}

// State of the Machine Learning run.
enum State {
  // State is not specified.
  STATE_UNSPECIFIED = 0;

  // Run is active.
  STATE_ACTIVE = 1;

  // Run is completed.
  STATE_COMPLETED = 2;

  // Run is failed.
  STATE_FAILED = 3;
}

// A Machine Learning run.
message MachineLearningRun {
  option (google.api.resource) = {
    type: "hypercomputecluster.googleapis.com/MachineLearningRun"
    pattern: "projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}"
    plural: "machineLearningRuns"
    singular: "machineLearningRun"
  };

  // Orchestrator for the ML run like Google Compute Engine, Google
  // Kubernetes Engine, Slurm etc.
  enum Orchestrator {
    // Orchestrator type is not specified.
    ORCHESTRATOR_UNSPECIFIED = 0;

    // Google Compute Engine orchestrator.
    GCE = 1;

    // Google Kubernetes Engine orchestrator.
    GKE = 2;

    // Slurm cluster orchestrator.
    SLURM = 3;
  }

  // RunPhase defines the phase of the Machine Learning run.
  enum RunPhase {
    // State is not specified.
    RUN_PHASE_UNSPECIFIED = 0;

    // Run is active.
    ACTIVE = 1;

    // Run is completed.
    COMPLETED = 2;

    // Run is failed.
    FAILED = 3;
  }

  // Identifier. The name of the Machine Learning run.
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Optional. Display name for the run.
  string display_name = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Allows grouping of similar runs.
  //  * Helps improving UI rendering performance.
  //  * Allows comparing similar runs via fast filters.
  string run_set = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. ETag for the run.
  // It must be provided for update/delete operations and must match the
  // server's etag.
  string etag = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Tracks configuration for this run,
  // example: batch_size, jax_version, tpu_generation etc.
  Configs configs = 5 [(google.api.field_behavior) = OPTIONAL];

  // Required. List of tools enabled for this run
  // example: XProf, SMon
  repeated Tool tools = 6 [(google.api.field_behavior) = REQUIRED];

  // Optional. Deprecated: Use Cloud Logging to retrieve metrics information.
  // Metrics for the run.
  Metrics metrics = 7
      [deprecated = true, (google.api.field_behavior) = OPTIONAL];

  // Optional. Any custom labels for this run
  // Example: type:workload, type:simulation etc.
  map<string, string> labels = 8 [(google.api.field_behavior) = OPTIONAL];

  // Output only. State of the run.
  State state = 9 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Time when the run was created.
  google.protobuf.Timestamp create_time = 10
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Time when the run was last updated.
  google.protobuf.Timestamp update_time = 11
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Artifacts for the run.
  Artifacts artifacts = 12 [(google.api.field_behavior) = OPTIONAL];

  // Required. The orchestrator used for the run.
  Orchestrator orchestrator = 13 [(google.api.field_behavior) = REQUIRED];

  // Optional. The metadata for the workload associated with the run.
  WorkloadDetails workload_details = 14
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. RunPhase defines the phase of the run.
  RunPhase run_phase = 15 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Error details for the run.
  // This field is set when the run is failed.
  string error_details = 16 [(google.api.field_behavior) = OPTIONAL];

  // Output only. Time when the run was completed.
  // This field is set when the run is completed or failed.
  google.protobuf.Timestamp end_time = 17
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Allows grouping of similar runs.
  //  * Helps improving UI rendering performance.
  //  * Allows comparing similar runs via fast filters.
  string run_group = 18 [(google.api.field_behavior) = OPTIONAL];
}

// A Profiler Target.
message ProfilerTarget {
  option (google.api.resource) = {
    type: "hypercomputecluster.googleapis.com/ProfilerTarget"
    pattern: "projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/profilerTargets/{profiler_target}"
    plural: "profilerTargets"
    singular: "profilerTarget"
  };

  // Identifier. The resource name of the ProfilerTarget.
  // Format:
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/profilerTargets/{profiler_target}
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Optional. Whether this node is the master node in the cluster.
  bool is_master = 2 [(google.api.field_behavior) = OPTIONAL];

  // Required. Host name of the node / target.
  string hostname = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. Index of the node in the cluster.
  int32 node_index = 4 [(google.api.field_behavior) = REQUIRED];

  // Optional. Etag for the profiler target
  string etag = 5 [(google.api.field_behavior) = OPTIONAL];
}

// Represents a single profiler session.
message ProfilerSession {
  option (google.api.resource) = {
    type: "hypercomputecluster.googleapis.com/ProfilerSession"
    pattern: "projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/profilerSessions/{profiler_session}"
    plural: "profilerSessions"
    singular: "profilerSession"
  };

  // LINT.IfChange
  // Host tracer levels. It can have new values in future.
  enum HostTracerLevel {
    // Tracer level is unspecified.
    HOST_TRACER_LEVEL_UNSPECIFIED = 0;

    // Tracer level is disabled.
    HOST_TRACER_LEVEL_DISABLED = 1;

    // Tracer level is critical.
    HOST_TRACER_LEVEL_CRITICAL = 2;

    // Tracer level is info.
    HOST_TRACER_LEVEL_INFO = 3;

    // Tracer level is verbose.
    HOST_TRACER_LEVEL_VERBOSE = 4;
  }

  // LINT.IfChange
  // Device tracer levels. It can have new values in future.
  enum DeviceTracerLevel {
    // Tracer level is unspecified.
    DEVICE_TRACER_LEVEL_UNSPECIFIED = 0;

    // Tracer level is disabled.
    DEVICE_TRACER_LEVEL_DISABLED = 1;

    // Tracer level is enabled.
    DEVICE_TRACER_LEVEL_ENABLED = 2;
  }

  // Profiler session kind.
  enum Kind {
    // Profiler session kind is unspecified.
    KIND_UNSPECIFIED = 0;

    // Profiler session created via Command Line Interface / UI / API on demand
    // request.
    KIND_ON_DEMAND = 1;

    // Profiler session created via SDK start() and stop() calls within workload
    // code.
    KIND_PROGRAMMATIC = 2;

    // Profiler session is scanned from Google Cloud Storage bucket.
    KIND_SCANNED = 3;
  }

  // LINT.IfChange
  // Python tracer levels. It can have new values in future.
  enum PythonTracerLevel {
    // Tracer level is unspecified.
    PYTHON_TRACER_LEVEL_UNSPECIFIED = 0;

    // Tracer level is disabled.
    PYTHON_TRACER_LEVEL_DISABLED = 1;

    // Tracer level is enabled.
    PYTHON_TRACER_LEVEL_ENABLED = 2;
  }

  // Identifier. The name of the profiler session.
  // Format:
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/profilerSessions/{profiler_session}
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. The cloud storage path of the session. Example:
  // `gs://my-bucket/my-run-directory/session-1`.
  string storage_folder_uri = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The creation time of the session.
  google.protobuf.Timestamp create_time = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The URI to dashboard to see session specific data. Not
  // specified if URI is not ready yet. Form
  // https://<backend>?<params(gsc_bucket|etc)> Could contain user information
  // like bucket name etc.
  string dashboard_uri = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Customer setting to enable trace level details for the session.
  bool is_trace_enabled = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Duration for the profiler session.
  google.protobuf.Duration duration = 6
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Etag for optimistic concurrency control.
  string etag = 7 [(google.api.field_behavior) = OPTIONAL];

  // Required. List of profiler targets.
  // Targets on which profiler session to be started.
  repeated string profiler_targets = 8 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "hypercomputecluster.googleapis.com/ProfilerTarget"
    }
  ];

  // Optional. Host tracer level for the session. If the field is not set or
  // unspecified, the default is `HOST_TRACER_LEVEL_INFO`.
  HostTracerLevel host_tracer_level = 9
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Device tracer level for the session. If the field is not set or
  // unspecified, the default is `DEVICE_TRACER_LEVEL_ENABLED`.
  DeviceTracerLevel device_tracer_level = 11
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Profiler session kind.
  Kind kind = 12 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Python tracer level for the session. If the field is not set or
  // unspecified, the default is `PYTHON_TRACER_LEVEL_DISABLED`.
  PythonTracerLevel python_tracer_level = 13
      [(google.api.field_behavior) = OPTIONAL];
}

// Represents a single Monitored Event (Incident) detected by the system.
message MonitoredEvent {
  option (google.api.resource) = {
    type: "hypercomputecluster.googleapis.com/MonitoredEvent"
    pattern: "projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/monitoredEvents/{monitored_event}"
    plural: "monitoredEvents"
    singular: "monitoredEvent"
  };

  // Enum for sorting/filtering events by category.
  enum EventType {
    // Event type not specified.
    EVENT_TYPE_UNSPECIFIED = 0;

    // Performance degradation event.
    PERFORMANCE_DEGRADATION = 1;
  }

  // Identifier. Resource name of the monitored event.
  // Format:
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/monitoredEvents/{monitored_event}
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Optional. High-level type of the event.
  EventType type = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Display name of the event.
  // If not provided, this will default to the Monitored Event ID from the
  // resource name.
  string display_name = 9 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Inclusive timestamp when the event started.
  google.protobuf.Timestamp start_time = 3
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Exclusive timestamp when the event ended. If unset, the event is
  // ongoing.
  google.protobuf.Timestamp end_time = 4
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Detailed reports from one or more analyzers regarding this event.
  repeated AnalyzerReport analyzer_reports = 6
      [(google.api.field_behavior) = OPTIONAL];

  // Output only. Identifies if any of the analyzer found an insight for this
  // event.
  bool analyzer_insight_found = 10 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Represents a single profiling session.
message ProfileSession {
  option (google.api.resource) = {
    type: "hypercomputecluster.googleapis.com/ProfileSession"
    pattern: "projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/profileSessions/{profile_session}"
    plural: "profileSessions"
    singular: "profileSession"
  };

  // Identifier. The name of the profile session.
  // Format:
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/profileSessions/{profile_session}
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. The cloud storage path of the session. Example:
  // `gs://my-bucket/my-run-directory/session-1`.
  string gcs_path = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The creation time of the session.
  google.protobuf.Timestamp create_time = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The URL to dashboard to see session specific data. Not
  // specified if URL is not ready yet. Currently represents only Xprof.
  //
  // Form https://<backend>?<params(gsc_bucket|etc)>
  // Could contains user information like bucket name etc.
  string dashboard_url = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Request message for MachineLearningRuns.CreateMachineLearningRun.
message CreateMachineLearningRunRequest {
  // Required. Parent format: projects/{project}/locations/{location}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "hypercomputecluster.googleapis.com/MachineLearningRun"
    }
  ];

  // Required. The Machine Learning Run to create.
  MachineLearningRun machine_learning_run = 2
      [(google.api.field_behavior) = REQUIRED];

  // Optional. The ID of the Machine Learning Run to create.
  string machine_learning_run_id = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for MachineLearningRuns.GetMachineLearningRun.
message GetMachineLearningRunRequest {
  // Required.
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "hypercomputecluster.googleapis.com/MachineLearningRun"
    }
  ];
}

// Request message for MachineLearningRuns.ListMachineLearningRuns.
message ListMachineLearningRunsRequest {
  // Required. projects/{project}/locations/{location}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "hypercomputecluster.googleapis.com/MachineLearningRun"
    }
  ];

  // Optional. The maximum number of Machine Learning Runs to return. The
  // service may return fewer than this value. If unspecified, at most 10
  // Machine Learning Runs will be returned. The maximum value is 1000; values
  // above 1000 will be coerced to 1000. Please refer to
  // https://google.aip.dev/158 for more details.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous `ListMachineLearningRuns`
  // call. Provide this to retrieve the subsequent page. Please refer to
  // https://google.aip.dev/158 for more details.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. An expression for filtering the results of the request.
  //
  // Supported filter fields are:
  // - run_id (string): The ID of the run (e.g., "run-1").
  // - run_set (string): The run set (e.g., "run-set-1").
  // - display_name (string): The display name of the run (e.g.,
  // "display-name-1").
  // - state (enum): The state of the run (e.g., "STATE_COMPLETED").
  // - region (string): The region of the run (e.g., "us-central1").
  // - orchestrator (enum): The orchestrator used for the run (e.g.,
  // "ORCHESTRATOR_GKE").
  // - create_time (timestamp): The creation timestamp of the run.
  // - update_time (timestamp): The last update timestamp of the run.
  // - etag (string): The ETag of the run.
  //
  // Filter expressions can be combined using "AND" and "OR" operators.
  //
  // Examples:
  //
  // To filter by a single field:
  //
  //   `run_set = "run-set-1"`
  //   `state = "STATE_ACTIVE"`
  //
  // To filter by multiple fields:
  //
  //   `run_set = "run-set-1" AND state = "STATE_ACTIVE"`
  //   `region = "us-central1" AND orchestrator = "ORCHESTRATOR_GKE"`
  //
  // To filter by timestamp:
  //
  //   `create_time > "2025-05-26T10:00:00Z"`
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A comma-separated list of fields to order by, sorted in ascending
  // order. Use "desc" after a field name for descending.
  //
  // Supported fields:
  //
  //   * `run_id`
  //   * `run_set`
  //   * `display_name`
  //   * `region`
  //   * `orchestrator`
  //   * `state`
  //   * `create_time`
  //   * `update_time`
  //
  // Example: `update_time desc, create_time`.
  string order_by = 5 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for MachineLearningRuns.ListMachineLearningRuns.
message ListMachineLearningRunsResponse {
  // The Machine Learning Runs.
  repeated MachineLearningRun machine_learning_runs = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

// Request message for MachineLearningRuns.UpdateMachineLearningRun.
message UpdateMachineLearningRunRequest {
  // Required. The Machine Learning Run to update.
  MachineLearningRun machine_learning_run = 1
      [(google.api.field_behavior) = REQUIRED];

  // Optional. Used to identify fields to be updated. Allowed fields is *, we
  // don't support partial updates.
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// Request message for MachineLearningRuns.DeleteMachineLearningRun.
message DeleteMachineLearningRunRequest {
  // Required.
  // projects/{project}/locations/{location}/machineLearningRuns/{machineLearningRun}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "hypercomputecluster.googleapis.com/MachineLearningRun"
    }
  ];

  // Optional. If force=false and if a user tries to delete an ml run resource
  // that still has child resources (e.g., ProfilerTarget), the request should
  // fail with a FAILED_PRECONDITION error. If force=true, the delete request
  // should delete both parent and child resources that exist.
  bool force = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Create profiler target request
message CreateProfilerTargetRequest {
  // Required.
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "hypercomputecluster.googleapis.com/ProfilerTarget"
    }
  ];

  // Required. The Profiler Target to create.
  ProfilerTarget profiler_target = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. If not provided, the server will generate an ID based on hostname
  // and node_index. Example: "myhost-0"
  string profiler_target_id = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Get profiler target request
message GetProfilerTargetRequest {
  // Required.
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/profilerTargets/{profiler_target}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "hypercomputecluster.googleapis.com/ProfilerTarget"
    }
  ];
}

// Request message for listing profiler targets.
message ListProfilerTargetsRequest {
  // Required.
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "hypercomputecluster.googleapis.com/ProfilerTarget"
    }
  ];

  // Optional. The maximum number of profiler targets to return. The service may
  // return fewer than this value. If unspecified, at most 10 profiler targets
  // will be returned. The maximum value is 1000; values above 1000 will be
  // coerced to 1000. Please refer to https://google.aip.dev/158 for more
  // details.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous `ListProfilerTargets`
  // call. Provide this to retrieve the subsequent page. Please refer to
  // https://google.aip.dev/158 for more details.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for list profiler targets.
message ListProfilerTargetsResponse {
  // A list of profiler targets.
  repeated ProfilerTarget profiler_targets = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

// Request message for Deleting a ProfilerTarget.
message DeleteProfilerTargetRequest {
  // Required. The name of the profiler target to delete.
  // Format:
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/profilerTargets/{profiler_target}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "hypercomputecluster.googleapis.com/ProfilerTarget"
    }
  ];
}

// Request message for creating a profiler session.
message CreateProfilerSessionRequest {
  // Required.
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "hypercomputecluster.googleapis.com/ProfilerSession"
    }
  ];

  // Optional. ID for the profiler session.
  string profiler_session_id = 2 [(google.api.field_behavior) = OPTIONAL];

  // Required. The Profiler Session to create.
  ProfilerSession profiler_session = 3 [(google.api.field_behavior) = REQUIRED];
}

// Request message for MachineLearningRuns.GetProfilerSession.
message GetProfilerSessionRequest {
  // Required.
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/profilerSessions/{profiler_session}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "hypercomputecluster.googleapis.com/ProfilerSession"
    }
  ];
}

// Request message for listing profiler sessions.
message ListProfilerSessionsRequest {
  // Required.
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "hypercomputecluster.googleapis.com/ProfilerSession"
    }
  ];

  // Optional. The maximum number of profiler sessions to return. The service
  // may return fewer than this value. If unspecified, at most 10 profiler
  // sessions will be returned. The maximum value is 1000; values above 1000
  // will be coerced to 1000. Please refer to https://google.aip.dev/158 for
  // more details.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous `ListProfilerSessions`
  // call. Provide this to retrieve the subsequent page. Please refer to
  // https://google.aip.dev/158 for more details.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for list profiler sessions.
message ListProfilerSessionsResponse {
  // A list of profiler sessions.
  repeated ProfilerSession profiler_sessions = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

// Request message for Deleting a ProfilerSession.
message DeleteProfilerSessionRequest {
  // Required. The name of the profiler session to delete.
  // Format:
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/profilerSessions/{profiler_session}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "hypercomputecluster.googleapis.com/ProfilerSession"
    }
  ];
}

// Request message for MachineLearningRuns.GetProfileSession.
message GetProfileSessionRequest {
  // Required.
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/profileSessions/{profileSession}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "hypercomputecluster.googleapis.com/ProfileSession"
    }
  ];
}

// Request message for MachineLearningRuns.ListProfileSessions.
message ListProfileSessionsRequest {
  // Required. Parent format:
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "hypercomputecluster.googleapis.com/ProfileSession"
    }
  ];

  // Optional. The maximum number of Profile Sessions to return. The service may
  // return fewer than this value.
  // If unspecified, at most 50 Profile Sessions will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous `ListProfileSessions`
  // call. Provide this to retrieve the subsequent page.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for MachineLearningRuns.ListProfileSessions.
message ListProfileSessionsResponse {
  // A list of profile sessions.
  repeated ProfileSession profile_sessions = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

// Request message for CreateMonitoredEvent.
message CreateMonitoredEventRequest {
  // Required. Parent resource where the event will be created.
  // Format:
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "hypercomputecluster.googleapis.com/MachineLearningRun"
    }
  ];

  // Required. The event resource to create.
  MonitoredEvent monitored_event = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. Optional ID for the event.
  string monitored_event_id = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for GetMonitoredEvent.
message GetMonitoredEventRequest {
  // Required. The name of the monitored event to retrieve.
  // Format:
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/monitoredEvents/{monitored_event}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "hypercomputecluster.googleapis.com/MonitoredEvent"
    }
  ];
}

// Request message for ListMonitoredEvents.
message ListMonitoredEventsRequest {
  // Required. Parent resource to list events from.
  // Format:
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "hypercomputecluster.googleapis.com/MachineLearningRun"
    }
  ];

  // Optional. The maximum number of events to return. The service may return
  // fewer than this value. If unspecified, at most 50 events will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous `ListMonitoredEvents`
  // call. Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListMonitoredEvents`
  // must match the call that provided the page token.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A filter expression for filtering results.
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Order by field for sorting results.
  string order_by = 5 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for ListMonitoredEvents.
message ListMonitoredEventsResponse {
  // The list of monitored events.
  repeated MonitoredEvent monitored_events = 1;

  // Token to retrieve the next page of results.
  string next_page_token = 2;
}

// Request message for UpdateMonitoredEvent.
message UpdateMonitoredEventRequest {
  // Required. The monitored event to update.
  //
  // The event's `name` field is used to identify the event to be updated.
  MonitoredEvent monitored_event = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The list of fields to be updated.
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// Request message for DeleteMonitoredEvent.
message DeleteMonitoredEventRequest {
  // Required. The name of the monitored event to delete.
  // Format:
  // projects/{project}/locations/{location}/machineLearningRuns/{machine_learning_run}/monitoredEvents/{monitored_event}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "hypercomputecluster.googleapis.com/MonitoredEvent"
    }
  ];
}

// Configuration for a Machine Learning run.
message Configs {
  // Optional. Deprecated: userConfigs will be stored in Cloud Logging.
  // User defined configs.
  map<string, string> user_configs = 1
      [deprecated = true, (google.api.field_behavior) = OPTIONAL];

  // Optional. Software configs.
  map<string, string> software_configs = 2
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Hardware configs.
  map<string, string> hardware_configs = 3
      [(google.api.field_behavior) = OPTIONAL];
}

// Deprecated: Use Cloud Logging to retrieve metrics information.
// Metrics for a Machine Learning run.
message Metrics {
  // Output only. Average step time.
  google.protobuf.Duration avg_step = 1
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Average Model Flops Utilization (MFU).
  float avg_mfu = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Average throughput. Value depends on the kind of workload ran
  // on TPU.
  float avg_throughput = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Average latency.
  google.protobuf.Duration avg_latency = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Average TPU TensorCore utilization.
  float avg_tpu_tensorcore_utilization = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Average HBM (High Bandwidth Memory) utilization.
  float avg_hbm_utilization = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Represents information about the artifacts of the Machine Learning Run.
message Artifacts {
  // Optional. The Cloud Storage path where the artifacts of the run are stored.
  // Example: `gs://my-bucket/my-run-directory`.
  string gcs_path = 1 [(google.api.field_behavior) = OPTIONAL];
}

// A tool for a Machine Learning run.
message Tool {
  // tool - one of the diagnostic tool.
  oneof tool {
    // Optional. XProf related metadata
    Xprof xprof = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Smon (System Monitored) tool
    // Signifies that the workload is under active monitoring.
    Smon smon = 2 [(google.api.field_behavior) = OPTIONAL];
  }
}

// Workload details associated for the Machine Learning Run.
// Workload have different metadata based on the orchestrator like
// GKE cluster, Slurm cluster, Google Compute Engine instance etc.
message WorkloadDetails {
  // The metadata for the workload for different orchestrators.
  oneof metadata {
    // GKE Workload metadata.
    GKEWorkloadDetails gke = 1;
  }
}

// Workload details for the GKE orchestrator.
message GKEWorkloadDetails {
  // Required. The identifier of the workload. Example - jobset-abcd
  string id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The kind of the workload. Possible values are JobSet,
  // LeaderWorkerSet, RayCluster, RayJob, and Deployment.
  string kind = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The cluster of the workload.
  // Example - projects/<project id>/locations/<location>/clusters/<cluster
  // name>
  string cluster = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. The namespace of the workload. Example - default
  string namespace = 4 [(google.api.field_behavior) = REQUIRED];

  // Optional. The parent workload. Example - JobSet for a Job, RayJob,
  // LeaderWorkerSet etc. If a workload is a part of a RunSet, this field is
  // populate as `RunSet` and if it was ray job, it will be set to `RayJob` etc.
  // This will be an additional field to representing a workload.
  string parent_workload = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. labels for the workload.
  // Example: {"type": "workload", "app": "simulation"}.
  map<string, string> labels = 6 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Time when the workload was created.
  google.protobuf.Timestamp create_time = 7
      [(google.api.field_behavior) = OPTIONAL];
}

// XProf related metadata
message Xprof {
  // Required. XProf session id
  string session_id = 1 [(google.api.field_behavior) = REQUIRED];
}

// Smon Tool Metadata
message Smon {
  // Output only. A summary of the monitoring findings.
  string monitoring_summary = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// A detailed report from a specific analyzer.
message AnalyzerReport {
  // Represents the detection state of the analyzer.
  enum DetectionState {
    // Status is not specified.
    DETECTION_STATE_UNSPECIFIED = 0;

    // Analyzer detected an issue.
    DETECTED = 1;

    // Analyzer did not detect an issue.
    NOT_DETECTED = 2;
  }

  // Optional. Recommended actions to take.
  repeated RecommendedAction recommended_actions = 4
      [(google.api.field_behavior) = OPTIONAL];

  // Required. Name of the system executed analyzer.
  // Example - "Thermal Throttling Analyzer"
  string analyzer = 6 [(google.api.field_behavior) = REQUIRED];

  // Output only. Detection state produced by the analyzer.
  DetectionState detection_state = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. A summary details of the analyzer findings.
  string details = 8 [(google.api.field_behavior) = OPTIONAL];
}

// Represents a recommended action.
message RecommendedAction {
  // Optional. Description of the recommended action.
  // The description can be up to 1024 characters long.
  string description = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Optional link to documentation or more details about the action.
  string documentation_url = 2 [(google.api.field_behavior) = OPTIONAL];
}