// Copyright 2016 Google Inc.
//
// 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.ml.v1beta1;

import "google/api/annotations.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";

option java_multiple_files = true;
option java_outer_classname = "JobServiceProto";
option java_package = "com.google.cloud.ml.api.v1beta1";

// Copyright 2016 Google Inc. All Rights Reserved.
//
// Proto file for the Machine Learning Service
// Describes the 'job service' to manage training and prediction jobs.



// Allows creating and managing training and prediction jobs.
service JobService {
  // Create a training or a prediction job.
  rpc CreateJob(CreateJobRequest) returns (Job) {
    option (google.api.http) = { post: "/v1beta1/{parent=projects/*}/jobs" body: "job" };
  }

  // List jobs in the project.
  rpc ListJobs(ListJobsRequest) returns (ListJobsResponse) {
    option (google.api.http) = { get: "/v1beta1/{parent=projects/*}/jobs" };
  }

  // Describe a job.
  rpc GetJob(GetJobRequest) returns (Job) {
    option (google.api.http) = { get: "/v1beta1/{name=projects/*/jobs/*}" };
  }

  // Cancel a running job.
  rpc CancelJob(CancelJobRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = { post: "/v1beta1/{name=projects/*/jobs/*}:cancel" body: "*" };
  }
}

// Represents input parameters for a training job.
message TrainingInput {
  // Scale tiers.
  enum ScaleTier {
    // A single worker instance and no parameter servers.
    BASIC = 0;

    // A few workers and one parameter server.
    STANDARD_1 = 1;

    // A medium amount of workers and a few parameter servers.
    STANDARD_2 = 2;

    // A large amount of worker with more parameter servers.
    PREMIUM_1 = 3;

    // A very large amount of workers with even more parameter servers.
    PREMIUM_2 = 4;

    // Specify your own amounts of replicas in the `worker_count` and
    // `parameter_server_count` fields, as well as machine types for the master,
    // the workers and the parameter servers.
    CUSTOM = 5;
  }

  // Required. Specifies the machine types, the amounts of replicas for workers
  // and parameter servers.
  ScaleTier scale_tier = 1;

  // Optional. Specifies the master machine type.
  // The following types are supported:
  //
  // - `standard`
  // - `large_model`
  // - `complex_model_s`
  // - `complex_model_m`
  // - `complex_model_l`
  //
  // Cannot be used in combination with a standard scale tier.
  string master_type = 2;

  // Optional. Specifies the worker machine type.
  // The following types are supported:
  //
  // - `standard`
  // - `large_model`
  // - `complex_model_s`
  // - `complex_model_m`
  // - `complex_model_l`
  //
  // Cannot be used in combination with a standard scale tier.
  string worker_type = 3;

  // Optional. Specifies the parameter server machine type.
  // The following types are supported:
  //
  // - `standard`
  // - `large_model`
  // - `complex_model_s`
  // - `complex_model_m`
  // - `complex_model_l`
  //
  // Cannot be used in combination with a standard scale tier.
  string parameter_server_type = 4;

  // Optional. Specifies the required amount of worker replicas.
  // Cannot be used in combination with a standard scale tier.
  int64 worker_count = 5;

  // Optional. Specifies the required amount of parameter server replicas.
  // Cannot be used in combination with a standard scale tier.
  int64 parameter_server_count = 6;

  // Required. The Google Cloud Storage location of the packages with
  // the training program and any additional dependencies.
  repeated string package_uris = 7;

  // Required. The Python module name to run after installing the packages.
  string python_module = 8;

  // Optional. Command line arguments to pass to the program.
  repeated string args = 10;

  // Optional. The set of Hyperparameters to tune.
  HyperparameterSpec hyperparameters = 12;

  // Required. The Google Compute Engine region to run the training job in.
  string region = 14;
}

// Represents a set of hyperparameters to optimize.
message HyperparameterSpec {
  // The optimization goal of the objective value.
  enum GoalType {
    // Goal Type will default to maximize.
    GOAL_TYPE_UNSPECIFIED = 0;

    // Maximize the goal metric.
    MAXIMIZE = 1;

    // Minimize the goal metric.
    MINIMIZE = 2;
  }

  // Required. Should the evaluation metric be maximized or minimized?
  GoalType goal = 1;

  // Required. The set of parameters to tune.
  repeated ParameterSpec params = 2;

  // Optional. How many training trials should be attempted to optimize.
  // Defaults to one.
  int32 max_trials = 3;

  // Optional. How many training trials should be run in parallel.
  // More parallelization will be faster, but parallel trials only benefit
  // from the information gained by previous trials.
  // Each trial will use the same scale tier and machine types.
  // Defaults to one.
  int32 max_parallel_trials = 4;
}

// Represents a single hyperparameter to optimize.
message ParameterSpec {
  // The type of the parameter.
  enum ParameterType {
    // Parameter type must be specified.  Unspecified values will be treated
    // as an error.
    PARAMETER_TYPE_UNSPECIFIED = 0;

    // Type for real-valued parameters.
    DOUBLE = 1;

    // Type for integral parameters.
    INTEGER = 2;

    // The parameter is categorical, with a value chosen from the categories
    // field.
    CATEGORICAL = 3;

    // The parameter is real valued, with a fixed set of feasible points. If
    // `type==DISCRETE`, feasible_points must be provided, and
    // {`min_value`, `max_value`} will be ignored.
    DISCRETE = 4;
  }

  // The type of scaling that should be applied to this parameter.
  enum ScaleType {
    // By default, no scaling is applied.
    NONE = 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;
  }

  // Required. The parameter name must be unique amongst all ParameterConfigs in
  // a HyperparameterSpec message. E.g., "learning_rate".
  string parameter_name = 1;

  // Required. The type of the parameter.
  ParameterType type = 4;

  // Required if type is `DOUBLE` or `INTEGER`. This field
  // should be unset if type is `CATEGORICAL`. This value should be integers if
  // type is INTEGER.
  double min_value = 2;

  // Required if typeis `DOUBLE` or `INTEGER`. This field
  // should be unset if type is `CATEGORICAL`. This value should be integers if
  // type is `INTEGER`.
  double max_value = 3;

  // Required if type is `CATEGORICAL`. The list of possible categories.
  repeated string categorical_values = 5;

  // Required if type is `DISCRETE`.
  // A list of feasible points.
  // The list should be in strictly increasing order. For instance, this
  // parameter might have possible settings of 1.5, 2.5, and 4.0. This list
  // shouldn't be too large - probably not more than 1,000 points.
  repeated double discrete_values = 6;

  // Optional. How the parameter should be scaled to the hypercube.
  // Leave unset for categorical parameters.
  // Some kind of scaling is strongly recommended for real or integral
  // parameters (e.g., `UNIT_LINEAR_SCALE`).
  ScaleType scale_type = 7;
}

// Represents the result of a hyperparameter tuning trial from a training job.
message HyperparameterOutput {
  // An observed value of a metric.
  message HyperparameterMetric {
    // The global training step for this metric.
    int64 training_step = 1;

    // The objective value at this training step.
    double objective_value = 2;
  }

  // The trial id for these results.
  string trial_id = 1;

  // The hyperparameters given to this trial.
  map<string, string> hyperparameters = 2;

  // The final objective metric seen for this trial.
  HyperparameterMetric final_metric = 3;

  // All recorded object metrics for this trial.
  repeated HyperparameterMetric all_metrics = 4;
}

// Represents results of a training job.
message TrainingOutput {
  // The number of tuning trials completed successfully.
  int64 completed_trial_count = 1;

  // Results for individual Hyperparameter trials.
  repeated HyperparameterOutput trials = 2;
}

// Represents input parameters for a prediction job.
message PredictionInput {
  // The format used to separate data instances in the source files.
  enum DataFormat {
    // Unspecified format.
    DATA_FORMAT_UNSPECIFIED = 0;

    // The source file is a text file with instances separated by the
    // new-line character.
    TEXT = 1;

    // The source file is a TFRecord file.
    TF_RECORD = 2;
  }

  // Required. The model or the version to use for prediction.
  oneof model_version {
    // The name of the model. The default version will be used.
    // E.g "project/your_project/models/your_model"
    string model_name = 1;

    // The version to be used.
    // E.g "project/your_project/models/your_model/versions/your_version"
    string version_name = 2;
  }

  // Required. The format of the input data files.
  DataFormat data_format = 3;

  // Required. The Google Cloud Storage location of the input data files.
  // May contain wildcards.
  repeated string input_paths = 4;

  // Required. The output Google Cloud Storage location.
  string output_path = 5;

  // Optional. The maximum amount of workers to be used for parallel processing.
  // Defaults to 10.
  int64 max_worker_count = 6;

  // Required. The Google Compute Engine region to run the prediction job in.
  string region = 7;
}

// Represents results of a prediction job.
message PredictionOutput {
  // The output Google Cloud Storage location provided at the job creation time.
  string output_path = 1;

  // The number of generated predictions.
  int64 prediction_count = 2;

  // The number of data instances which resulted in errors.
  int64 error_count = 3;
}

// Represents a training or prediction job.
message Job {
  // Describes the job state.
  enum State {
    // The job state is unspecified.
    STATE_UNSPECIFIED = 0;

    // The job has been just created and is awaiting to be processed.
    QUEUED = 1;

    // The job is being prepared to run.
    PREPARING = 2;

    // Training or prediction is in progress.
    RUNNING = 3;

    // The job completed successfully.
    SUCCEEDED = 4;

    // The job failed.
    // `error_message` should contain the details of the failure.
    FAILED = 5;

    // The job is being cancelled.
    // `error_message` should describe the reason for the cancellation.
    CANCELLING = 6;

    // The job has been cancelled.
    // `error_message` should describe the reason for the cancellation.
    CANCELLED = 7;
  }

  // Required. The user-specified id of the job.
  string job_id = 1;

  // Required. Parameters to create a job.
  oneof input {
    // Input parameters to create a training job.
    TrainingInput training_input = 2;

    // Input parameters to create a prediction job.
    PredictionInput prediction_input = 3;
  }

  // Output only. When the job was created.
  google.protobuf.Timestamp create_time = 4;

  // Output only. When the job processing was started.
  google.protobuf.Timestamp start_time = 5;

  // Output only. When the job processing was completed.
  google.protobuf.Timestamp end_time = 6;

  // Output only. The detailed state of a job.
  State state = 7;

  // Output only. The details of a failure or a cancellation.
  string error_message = 8;

  // Output only. The current result of the job.
  oneof output {
    // The current training job result.
    TrainingOutput training_output = 9;

    // The current prediction job result.
    PredictionOutput prediction_output = 10;
  }
}

// Request message for the CreateJob method.
message CreateJobRequest {
  // Required. The project name.
  // Authorization: requires `Editor` role on the specified project.
  string parent = 1;

  // Required. The job to create.
  Job job = 2;
}

// Request message for the ListJobs method.
message ListJobsRequest {
  // Required. The name of the project whose jobs are to be listed.
  // Authorization: requires `Viewer` role on the specified project.
  string parent = 1;

  // Optional. Specifies the subset of jobs to retrieve.
  string filter = 2;

  // Optional. Specifies the ordering of the jobs.
  string order_by = 3;

  // Optional. A token for continuing the enumeration.
  string page_token = 4;

  // Optional. The page size.
  int32 page_size = 5;
}

// Response message for the ListJobs method.
message ListJobsResponse {
  // The list of jobs.
  repeated Job jobs = 1;

  // Optional pagination token to use for retrieving the next page of results.
  string next_page_token = 2;
}

// Request message for the GetJob method.
message GetJobRequest {
  // Required. The name of the job.
  // Authorization: requires `Viewer` role on the parent project.
  string name = 1;
}

// Request message for the CancelJob method.
message CancelJobRequest {
  // Required. The name of the job.
  // Authorization: requires `Editor` role on the parent project.
  string name = 1;
}