// Copyright 2020 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.aiplatform.v1beta1;

import "google/api/field_behavior.proto";
import "google/cloud/aiplatform/v1beta1/explanation_metadata.proto";
import "google/protobuf/struct.proto";
import "google/api/annotations.proto";

option go_package = "google.golang.org/genproto/googleapis/cloud/aiplatform/v1beta1;aiplatform";
option java_multiple_files = true;
option java_outer_classname = "ExplanationProto";
option java_package = "com.google.cloud.aiplatform.v1beta1";

// Explanation of a [prediction][ExplainResponse.predictions] produced by the
// Model on a given [instance][google.cloud.aiplatform.v1beta1.ExplainRequest.instances].
//
// Currently, only AutoML tabular Models support explanation.
message Explanation {
  // Output only. Feature attributions grouped by predicted outputs.
  //
  // For Models that predict only one output, such as regression Models that
  // predict only one score, there is only one attibution that explains the
  // predicted output. For Models that predict multiple outputs, such as
  // multiclass Models that predict multiple classes, each element explains one
  // specific item. [Attribution.output_index][google.cloud.aiplatform.v1beta1.Attribution.output_index] can be used to identify which
  // output this attribution is explaining.
  //
  repeated Attribution attributions = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Aggregated explanation metrics for a Model over a set of instances.
//
// Currently, only AutoML tabular Models support aggregated explanation.
message ModelExplanation {
  // Output only. Aggregated attributions explaning the Model's prediction outputs over the
  // set of instances. The attributions are grouped by outputs.
  //
  // For Models that predict only one output, such as regression Models that
  // predict only one score, there is only one attibution that explains the
  // predicted output. For Models that predict multiple outputs, such as
  // multiclass Models that predict multiple classes, each element explains one
  // specific item. [Attribution.output_index][google.cloud.aiplatform.v1beta1.Attribution.output_index] can be used to identify which
  // output this attribution is explaining.
  //
  // The [baselineOutputValue][google.cloud.aiplatform.v1beta1.Attribution.baseline_output_value],
  // [instanceOutputValue][google.cloud.aiplatform.v1beta1.Attribution.instance_output_value] and
  // [featureAttributions][google.cloud.aiplatform.v1beta1.Attribution.feature_attributions] fields are
  // averaged over the test data.
  //
  // NOTE: Currently AutoML tabular classification Models produce only one
  // attribution, which averages attributions over all the classes it predicts.
  // [Attribution.approximation_error][google.cloud.aiplatform.v1beta1.Attribution.approximation_error] is not populated.
  repeated Attribution mean_attributions = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Attribution that explains a particular prediction output.
message Attribution {
  // Output only. Model predicted output if the input instance is constructed from the
  // baselines of all the features defined in [ExplanationMetadata.inputs][google.cloud.aiplatform.v1beta1.ExplanationMetadata.inputs].
  // The field name of the output is determined by the key in
  // [ExplanationMetadata.outputs][google.cloud.aiplatform.v1beta1.ExplanationMetadata.outputs].
  //
  // If the Model predicted output is a tensor value (for example, an ndarray),
  // this is the value in the output located by [output_index][google.cloud.aiplatform.v1beta1.Attribution.output_index].
  //
  // If there are multiple baselines, their output values are averaged.
  double baseline_output_value = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Model predicted output on the corresponding [explanation
  // instance][ExplainRequest.instances]. The field name of the output is
  // determined by the key in [ExplanationMetadata.outputs][google.cloud.aiplatform.v1beta1.ExplanationMetadata.outputs].
  //
  // If the Model predicted output is a tensor value (for example, an ndarray),
  // this is the value in the output located by [output_index][google.cloud.aiplatform.v1beta1.Attribution.output_index].
  double instance_output_value = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Attributions of each explained feature. Features are extracted from
  // the [prediction instances][google.cloud.aiplatform.v1beta1.ExplainRequest.instances] according to
  // [explanation input metadata][google.cloud.aiplatform.v1beta1.ExplanationMetadata.inputs].
  //
  // The value is a struct, whose keys are the name of the feature. The values
  // are how much the feature in the [instance][google.cloud.aiplatform.v1beta1.ExplainRequest.instances]
  // contributed to the predicted result.
  //
  // The format of the value is determined by the feature's input format:
  //
  //   * If the feature is a scalar value, the attribution value is a
  //     [floating number][google.protobuf.Value.number_value].
  //
  //   * If the feature is an array of scalar values, the attribution value is
  //     an [array][google.protobuf.Value.list_value].
  //
  //   * If the feature is a struct, the attribution value is a
  //     [struct][google.protobuf.Value.struct_value]. The keys in the
  //     attribution value struct are the same as the keys in the feature
  //     struct. The formats of the values in the attribution struct are
  //     determined by the formats of the values in the feature struct.
  //
  // The [ExplanationMetadata.feature_attributions_schema_uri][google.cloud.aiplatform.v1beta1.ExplanationMetadata.feature_attributions_schema_uri] field,
  // pointed to by the [ExplanationSpec][google.cloud.aiplatform.v1beta1.ExplanationSpec] field of the
  // [Endpoint.deployed_models][google.cloud.aiplatform.v1beta1.Endpoint.deployed_models] object, points to the schema file that
  // describes the features and their attribution values (if it is populated).
  google.protobuf.Value feature_attributions = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The index that locates the explained prediction output.
  //
  // If the prediction output is a scalar value, output_index is not populated.
  // If the prediction output is a tensor value (for example, an ndarray),
  // the length of output_index is the same as the number of dimensions of the
  // output. The i-th element in output_index is the element index of the i-th
  // dimension of the output vector. Indexes start from 0.
  repeated int32 output_index = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The display name of the output identified by [output_index][google.cloud.aiplatform.v1beta1.Attribution.output_index], e.g. the
  // predicted class name by a multi-classification Model.
  //
  // This field is only populated iff the Model predicts display names as a
  // separate field along with the explained output. The predicted display name
  // must has the same shape of the explained output, and can be located using
  // output_index.
  string output_display_name = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Error of [feature_attributions][google.cloud.aiplatform.v1beta1.Attribution.feature_attributions] caused by approximation used in the
  // explanation method. Lower value means more precise attributions.
  //
  // For Sampled Shapley
  // [attribution][google.cloud.aiplatform.v1beta1.ExplanationParameters.sampled_shapley_attribution],
  // increasing [path_count][google.cloud.aiplatform.v1beta1.SampledShapleyAttribution.path_count] might reduce
  // the error.
  //
  double approximation_error = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Specification of Model explanation.
//
// Currently, only AutoML tabular Models support explanation.
message ExplanationSpec {
  // Required. Parameters that configure explaining of the Model's predictions.
  ExplanationParameters parameters = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. Metadata describing the Model's input and output for explanation.
  ExplanationMetadata metadata = 2 [(google.api.field_behavior) = REQUIRED];
}

// Parameters to configure explaining for Model's predictions.
message ExplanationParameters {
  // An attribution method that approximates Shapley values for features that
  // contribute to the label being predicted. A sampling strategy is used to
  // approximate the value rather than considering all subsets of features.
  SampledShapleyAttribution sampled_shapley_attribution = 1;
}

// An attribution method that approximates Shapley values for features that
// contribute to the label being predicted. A sampling strategy is used to
// approximate the value rather than considering all subsets of features.
message SampledShapleyAttribution {
  // Required. The number of feature permutations to consider when approximating the
  // Shapley values.
  //
  // Valid range of its value is [1, 50], inclusively.
  int32 path_count = 1 [(google.api.field_behavior) = REQUIRED];
}
