// 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";

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

// Copyright 2016 Google Inc. All Rights Reserved.
//
// Proto file for the Prediction service, both online and batch prediction.



// The Prediction API, which serves predictions for models managed by
// ModelService.
service OnlinePredictionService {
  // Performs prediction on the data in the request.
  //
  // Responses are very similar to requests. There are two top-level fields,
  // each of which are JSON lists:
  //
  //  * `predictions`: The list of predictions for each of the inputs
  // in the request.
  //  * `error`: An error message if any instance produced an error.
  //
  // There is a one-to-one correspondence between the predictions and the
  // instances in the request. Each individual prediction takes the same form
  // as an instance in the request, namely JSON strings, numbers, booleans,
  // or lists thereof. If your model has more than one output tensor, each
  // prediction will be a JSON object with the keys being the output aliases
  // in the graph.
  //
  // If there is an error processing any single instance, no predictions
  // are returned and the `error` field is populated with the error message.
  //
  // Examples:
  //
  // <pre>
  // # Predictions for three input instances, predictions are an integer label,
  //
  // # e.g., a digit in digit recognition
  //
  // {"predictions": [5, 4, 3]}
  //
  // # Predictions for two input instances in a two-class classification
  //
  // # problem. The labels are strings and scores are the probability of
  //
  // # "car" and "beach".
  //
  // {"predictions": [{"label": "beach", "scores": [0.1, 0.9]},
  //                  {"label": "car", "scores": [0.75, 0.25]}]}
  //
  // # An error:
  //
  //  {"error": "Divide by zero"}
  // </pre>
  rpc Predict(PredictRequest) returns (google.api.HttpBody) {
    option (google.api.http) = { post: "/v1beta1/{name=projects/**}:predict" body: "*" };
  }
}

// Request for predictions to be issued against a trained model.
//
// The body of the request consists of a single JSON object with a single
// top-level field:
//
//  * `instances`: a list of JSON values representing the instances to use for
//  prediction.
//
// The structure of each element of the instances list is the type of data
// your model expects to work on. There are two types of instances: those
// that include named inputs and those that do not.
//
// Most data does not include named inputs. In this case, each instance will
// be a JSON boolean, number, string, or (possibly deeply nested) list of
// any of the above. For instance, if your model accepts rows of CSV data,
// then each element is a string; if each data instance is a vector of ints
// or floats, use a JSON list of numbers, etc. More examples are as follows:
//
// <pre>
// # CSV data
//
// {"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}
//
// # Text
//
// {"instances": ["the quick brown fox", "la bruja le dio"]}
//
// # Sentences, each a list of words (vectors of strings).
//
// {"instances": [["the","quick","brown"], ["la","bruja","le"]]}
//
// # Three instances, each a floating point scalar, e.g., to compute f(x).
//
// {"instances": [0.0, 1.1, 2.2]}  # 3 instances (integer scalars)
//
// # Two instances, each a 3 element vecor of ints.
//
// {"instances": [[0,1,2], [3,4,5],...]}
//
// # A single instance, which is 2x3 matrix of ints.
//
// {"instances": [[[0,1,2], [3,4,5]], ...]}
//
// # A single image represented as a 3-dimensional list with dimesions:
//
// # height, width, and channels (3).
//
// {"instances": [[[[0,1,2], [3,4,5], …]]]]}
// </pre>
//
//  Importantly, if your data is not UTF-8 (the only currently supported
//  character set), you will need to base64 encode the data and mark it as
//  binary. The latter is accomplished by using a JSON object of the form:
// <pre>{"b": "..."} </pre>
// in place of any JSON string that is base64 encoded. For example:
//
// <pre>
// # Two Serialized tf.Examples (fake data, for illustrative purposes only)
//
// {"instances": [{"b": "X5ad6u"}, {"b": "IA9j4nx"}]}
//
// # Two JPEG image byte strings (fake data, for illustrative purposes only)
//
// {"instances": [{"b": "ASa8asdf"}, {"b": "JLK7ljk3"}]}
// </pre>
//
// In the case that your data includes named references, you will send a
// JSON object with the named references as the keys. For instance, if
// you used Cloud ML's preprocessing library and used the JSON key-value
// pair data format, you would send instances as follows:
//
// <pre>
// # JSON input data to be preprocessed.
//
// {"instances": [{"a": 1.0,  "b": true,  "c": "x"},
//                {"a": -2.0, "b": false, "c": "y"}]}
// </pre>
//
// Another use case is if your underlying TensorFlow graph contains multiple
// input tensors, then the keys would be the aliases to the input tensors, e.g.,
//
// <pre>
// # Graph with input tensor aliases "tag" (string) and "image" (base64
//
// # encoded string).
//
// {"instances": [{"tag": "beach", "image": {"b": "ASa8asdf"}},
//                {"tag": "car", "image": {"b": "JLK7ljk3"}}]}
//
// # Graph with input tensor aliases "tag" (string) and "image"
//
// # (3-dimensional array of 8-bit ints).
//
// {"instances": [{"tag": "beach", "image": [[[263,1,10], [262,2,11], ...]]},
//                {"tag": "car", "image": [[[10,11,24], [23,10,15], ...]]}]}
// </pre>
//
// There is a one-to-one correspondence between the predictions and the
// instances in the request. Each individual prediction takes the same form
// as an instance in the request, namely JSON strings, numbers, booleans, or
// lists thereof. If your model has more than one output tensor, each
// prediction will be a JSON object with the keys being the output aliases
// in the graph.
//
// Examples:
//
// <pre>
// # Predictions for three input instances, predictions are an integer label,
//
// # e.g., a digit in digit recognition
//
// {"predictions": [5, 4, 3]}
//
// # Predictions for two input instances in a two-class classification
//
// # problem. The labels are strings and scores are the probability of "car"
//
// # and "beach".
//
// {"predictions": [{"label": "beach", "scores": [0.1, 0.9]},
// {"label": "car", "scores": [0.75, 0.25]}]}
// </pre>
message PredictRequest {
  // Required. The resource name of a model or a version.
  // Authorization: requires `Viewer` role on the parent project.
  string name = 1;

  //
  // Required. The prediction request body.
  google.api.HttpBody http_body = 2;
}