syntax = "proto3";

package vizier;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
import "vizier/key_value.proto";

// A message representing a Study.
message Study {
  option (google.api.resource) = {
    type: "aiplatform.googleapis.com/Study"
    pattern: "owners/{owner_id}/studies/{study_id}"
  };

  // The name of a study. The study's globally unique identifier.
  // Format: `owners/{owner_id}/studies/{study_id}`
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Describes the Study, default value is empty string.
  string display_name = 2;

  // Configuration of the Study.
  StudySpec study_spec = 3 [(google.api.field_behavior) = REQUIRED];

  // Describes the Study state.
  enum State {
    // The study state is unspecified.
    STATE_UNSPECIFIED = 0;
    // The study is active.
    ACTIVE = 1;
    // The study is stopped due to an internal error.
    INACTIVE = 2;
    // The study is done when the service exhausts the parameter search space
    // or max_trial_count is reached.
    COMPLETED = 3;
  }
  // The detailed state of a Study.
  State state = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Time at which the study was created.
  google.protobuf.Timestamp create_time = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // A human readable reason why the Study is inactive.
  // This should be empty if a study is ACTIVE or COMPLETED.
  string inactive_reason = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// A message representing a Trial. A Trial contains a unique set of Parameters
// that has been or will be evaluated, along with the objective metrics got by
// running the Trial.
// (-- api-linter: core::0123::resource-annotation=disabled
//     aip.dev/not-precedent: We will expose Trial resource later. --)
message Trial {
  // Resource name of the Trial assigned by the service.
  // (-- aip.dev/beta-blocker:
  //  TODO: Expose Study/Trial API, make "name" visible, remove the
  // id field. --)
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The identifier of the Trial assigned by the service.
  string id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Describes a Trial state.
  enum State {
    // The Trial state is unspecified.
    STATE_UNSPECIFIED = 0;
    // Indicates that a specific Trial has been requested, but it has not yet
    // been suggested by the service.
    REQUESTED = 1;
    // Indicates that the Trial has been suggested.
    ACTIVE = 2;
    // Indicates that the Trial should stop according to the service.
    STOPPING = 3;
    // Indicates that the Trial is completed successfully.
    SUCCEEDED = 4;
    // Indicates that the Trial should not be attempted again.
    // The service will set a Trial to INFEASIBLE when it's done but missing
    // the final_measurement.
    INFEASIBLE = 5;
  }
  // The detailed state of the Trial.
  State state = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // A message representing a parameter to be tuned.
  message Parameter {
    // The ID of the parameter. The parameter should be defined in
    // [StudySpec's Parameters][StudySpec.parameters].
    string parameter_id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // The value of the parameter.
    // `number_value` will be set if a parameter defined in StudySpec is
    // in type 'INTEGER', 'DOUBLE' or 'DISCRETE'.
    // `string_value` will be set if a parameter defined in StudySpec is
    // in type 'CATEGORICAL'.
    google.protobuf.Value value = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The parameters of the Trial.
  repeated Parameter parameters = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The final measurement containing the objective value.
  Measurement final_measurement = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // A list of measurements that are strictly lexicographically
  // ordered by their induced tuples (steps, elapsed_duration).
  // These are used for early stopping computations.
  repeated Measurement measurements = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Time when the Trial was started.
  google.protobuf.Timestamp start_time = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Time when the Trial's status changed to `SUCCEEDED` or `INFEASIBLE`.
  google.protobuf.Timestamp end_time = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // The identifier of the client that originally requested this Trial.
  // Each client is identified by a unique client_id. When a client
  // asks for a suggestion, Vizier will assign it a Trial. The client should
  // evaluate the Trial, complete it, and report back to Vizier.
  // If suggestion is asked again by same client_id before the Trial is
  // completed, the same Trial will be returned. Multiple clients with
  // different client_ids can ask for suggestions simultaneously, each of them
  // will get their own Trial.
  string client_id = 9 [(google.api.field_behavior) = OUTPUT_ONLY];

  // A human readable string describing why the Trial is
  // infeasible. This is set only if Trial state is `INFEASIBLE`.
  string infeasible_reason = 10 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Arbitrary metadata associated with the Trial.  This is not processed by
  // the Vizier server, but is readable/writeable by Pythia policies and user
  // code.
  // FYI, the "" namespace may be read and written by the user.
  // NOTE: Each KeyValue item is limited to 10 megabytes.
  // NOTE: Keys should be unique within their namespaces.
  repeated KeyValue metadata = 11;
}

// Represents specification of a Study.
message StudySpec {
  // Represents a metric to optimize.
  message MetricSpec {
    // The ID of the metric. Must not contain whitespaces and must be unique
    // amongst all MetricSpecs.
    string metric_id = 1 [(google.api.field_behavior) = REQUIRED];

    // The available types of optimization goals.
    enum GoalType {
      // Goal Type will default to maximize.
      GOAL_TYPE_UNSPECIFIED = 0;
      // Maximize the goal metric.
      MAXIMIZE = 1;
      // Minimize the goal metric.
      MINIMIZE = 2;
    }
    // The optimization goal of the metric.
    GoalType goal = 2 [(google.api.field_behavior) = REQUIRED];

    // Used in safe optimization to specify threshold levels and risk tolerance.
    message SafetyMetricConfig {
      // Safety threshold (boundary value between safe and unsafe).
      double safety_threshold = 1 [(google.api.field_behavior) = REQUIRED];

      // Desired minimum fraction of safe trials (over total number of trials)
      // that should be targeted by the algorithm at any time during the
      // study (best effort). This should be between 0.0 and 1.0 and a value of
      // 0.0 means that there is no minimum and an algorithm proceeds without
      // targeting any specific fraction (default if unset). NOTE: A value
      // of 1.0 means that the algorithm attempts to only Suggest safe Trials.
      optional double desired_min_safe_trials_fraction = 2;
    }

    // When set, the metric becomes a safety metric for safe search.
    SafetyMetricConfig safety_config = 3;
  }
  // Metric specs for the Study.
  repeated MetricSpec metrics = 1 [(google.api.field_behavior) = REQUIRED];

  // Represents a single parameter to optimize.
  message ParameterSpec {
    // The ID of the parameter. Must not contain whitespaces and must be unique
    // amongst all ParameterSpecs.
    string parameter_id = 1 [(google.api.field_behavior) = REQUIRED];

    // Value specification for a parameter in `DOUBLE` type.
    message DoubleValueSpec {
      // Inclusive minimum value of the parameter.
      double min_value = 1 [(google.api.field_behavior) = REQUIRED];
      // Inclusive maximum value of the parameter.
      double max_value = 2 [(google.api.field_behavior) = REQUIRED];

      // A default value for a `DOUBLE` parameter that is assumed to be a
      // relatively good starting point.  Unset value signals that there is no
      // offered starting point.
      //
      // Currently only supported by the Optimizer service. Not supported by
      // HyperparamterTuningJob or TrainingPipeline.
      google.protobuf.DoubleValue default_value = 3;
    }

    // Value specification for a parameter in `INTEGER` type.
    message IntegerValueSpec {
      // Inclusive minimum value of the parameter.
      int64 min_value = 1 [(google.api.field_behavior) = REQUIRED];
      // Inclusive maximum value of the parameter.
      int64 max_value = 2 [(google.api.field_behavior) = REQUIRED];

      // A default value for an `INTEGER` parameter that is assumed to be a
      // relatively good starting point.  Unset value signals that there is no
      // offered starting point.
      //
      // Currently only supported by the Optimizer service. Not supported by
      // HyperparamterTuningJob or TrainingPipeline.
      google.protobuf.Int64Value default_value = 3;
    }

    // Value specification for a parameter in `CATEGORICAL` type.
    message CategoricalValueSpec {
      // The list of possible categories.
      repeated string values = 1 [(google.api.field_behavior) = REQUIRED];

      // A default value for a `CATEGORICAL` parameter that is assumed to be a
      // relatively good starting point.  Unset value signals that there is no
      // offered starting point.
      //
      // Currently only supported by the Optimizer service. Not supported by
      // HyperparamterTuningJob or TrainingPipeline.
      google.protobuf.StringValue default_value = 2;
    }

    // Value specification for a parameter in `DISCRETE` type.
    message DiscreteValueSpec {
      // A list of possible values.
      // The list should be in increasing order and at least 1e-10 apart.
      // For instance, this parameter might have possible settings of 1.5, 2.5,
      // and 4.0. This list should not contain more than 1,000 values.
      repeated double values = 1 [(google.api.field_behavior) = REQUIRED];

      // A default value for a `DISCRETE` parameter that is assumed to be a
      // relatively good starting point.  Unset value signals that there is no
      // offered starting point.  It automatically rounds to the
      // nearest feasible discrete point.
      //
      // Currently only supported by the Optimizer service. Not supported by
      // HyperparamterTuningJob or TrainingPipeline.
      google.protobuf.DoubleValue default_value = 2;
    }

    oneof parameter_value_spec {
      // The value spec for a 'DOUBLE' parameter.
      DoubleValueSpec double_value_spec = 2;
      // The value spec for an 'INTEGER' parameter.
      IntegerValueSpec integer_value_spec = 3;
      // The value spec for a 'CATEGORICAL' parameter.
      CategoricalValueSpec categorical_value_spec = 4;
      // The value spec for a 'DISCRETE' parameter.
      DiscreteValueSpec discrete_value_spec = 5;
    }

    // The type of scaling that should be applied to this parameter.
    enum ScaleType {
      // By default, no scaling is applied.
      SCALE_TYPE_UNSPECIFIED = 0;
      // Scales the feasible space to (0, 1) linearly.
      UNIT_LINEAR_SCALE = 1;
      // Scales the feasible space logarithmically to (0, 1). The entire
      // feasible space must be strictly positive.
      UNIT_LOG_SCALE = 2;
      // Scales the feasible space "reverse" logarithmically to (0, 1). The
      // result is that values close to the top of the feasible space are spread
      // out more than points near the bottom. The entire feasible space must be
      // strictly positive.
      UNIT_REVERSE_LOG_SCALE = 3;
    }

    // How the parameter should be scaled.
    // Leave unset for `CATEGORICAL` parameters.
    ScaleType scale_type = 6;

    // Represents a parameter spec with condition from its parent parameter.
    message ConditionalParameterSpec {
      // The spec for a conditional parameter.
      ParameterSpec parameter_spec = 1 [(google.api.field_behavior) = REQUIRED];

      // Represents the spec to match discrete values from parent parameter.
      message DiscreteValueCondition {
        // Matches values of the parent parameter of 'DISCRETE' type.
        // All values must exist in `discrete_value_spec` of parent parameter.
        //
        // The Epsilon of the value matching is 1e-10.
        repeated double values = 1 [(google.api.field_behavior) = REQUIRED];
      }

      // Represents the spec to match integer values from parent parameter.
      message IntValueCondition {
        // Matches values of the parent parameter of 'INTEGER' type.
        // All values must lie in `integer_value_spec` of parent parameter.
        repeated int64 values = 1 [(google.api.field_behavior) = REQUIRED];
      }

      // Represents the spec to match categorical values from parent parameter.
      message CategoricalValueCondition {
        // Matches values of the parent parameter of 'CATEGORICAL' type.
        // All values must exist in `categorical_value_spec` of parent
        // parameter.
        repeated string values = 1 [(google.api.field_behavior) = REQUIRED];
      }

      // A set of parameter values from the parent ParameterSpec's feasible
      // space.
      oneof parent_value_condition {
        // The spec for matching values from a parent parameter of
        // `DISCRETE` type.
        DiscreteValueCondition parent_discrete_values = 2;

        // The spec for matching values from a parent parameter of `INTEGER`
        // type.
        IntValueCondition parent_int_values = 3;

        // The spec for matching values from a parent parameter of
        // `CATEGORICAL` type.
        CategoricalValueCondition parent_categorical_values = 4;
      }
    }

    // A conditional parameter node is active if the parameter's value matches
    // the conditional node's parent_value_condition.
    //
    // If two items in conditional_parameter_specs have the same name, they
    // must have disjoint parent_value_condition.
    repeated ConditionalParameterSpec conditional_parameter_specs = 10;
  }

  // The set of parameters to tune.
  repeated ParameterSpec parameters = 2
      [(google.api.field_behavior) = REQUIRED];

  // The search algorithm specified for the Study.
  // See pyvizier.Algorithm for a list of native Vizier algorithms.
  string algorithm = 3;

  // The Pythia endpoint, for custom algorithms, or a Pythia service running
  // as a separate binary.
  optional string pythia_endpoint = 8;

  // Use the deault early stopping policy.
  reserved 4, 5;
  message DefaultEarlyStoppingSpec {}

  oneof automated_stopping_spec {
    DefaultEarlyStoppingSpec default_stopping_spec = 9;
  }

  // Describes the noise level of the repeated observations.
  //
  // "Noisy" means that the repeated observations with the same Trial parameters
  // may lead to different metric evaluations.
  enum ObservationNoise {
    // The default noise level chosen by the AI Platform service.
    OBSERVATION_NOISE_UNSPECIFIED = 0;
    // AI Platform Optimizer assumes that the objective function is (nearly)
    // perfectly reproducible, and will never repeat the same Trial
    // parameters.
    LOW = 1;
    // AI Platform Optimizer will estimate the amount of noise in metric
    // evaluations, it may repeat the same Trial parameters more than once.
    HIGH = 2;
  }

  // The observation noise level of the study.
  // Currently only supported by the Optimizer service. Not supported by
  // HyperparamterTuningJob or TrainingPipeline.
  ObservationNoise observation_noise = 6;

  // Arbitrary metadata associated with the Study.  This is not processed by
  // the Vizier server, but is readable/writeable by Pythia policies and user
  // code.
  // FYI, the "" namespace may be read and written by the user.
  // NOTE: Each KeyValue item is limited to 10 megabytes.
  // NOTE: Keys should be unique within their namespaces.
  repeated KeyValue metadata = 7;
}

// A message representing a Measurement of a Trial. A Measurement contains
// the Metrics got by executing a Trial using suggested hyperparameter
// values.
message Measurement {
  // Time that the Trial has been running at the point of this Measurement.
  google.protobuf.Duration elapsed_duration = 1
      [(google.api.field_behavior) = OUTPUT_ONLY];
  // The number of steps the machine learning model has been trained for.
  // Must be non-negative.
  int64 step_count = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // A message representing a metric in the measurement.
  message Metric {
    // The ID of the Metric. The Metric should be defined in
    // [StudySpec's Metrics][StudySpec.metrics].
    string metric_id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
    // The value for this metric.
    double value = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  }
  // A list of metrics got by evaluating the objective functions using suggested
  // Parameter values.
  repeated Metric metrics = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}