// 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/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 = "ExplanationMetadataProto";
option java_package = "com.google.cloud.aiplatform.v1beta1";

// Metadata describing the Model's input and output for explanation.
message ExplanationMetadata {
  // Metadata of the input of a feature.
  message InputMetadata {
    // Baseline inputs for this feature.
    //
    // If no baseline is specified, AI Platform chooses the baseline for this
    // feature. If multiple baselines are specified, AI Platform returns the
    // average attributions across them in
    // [Attributions.baseline_attribution][].
    //
    // The element of the baselines must be in the same format as the feature's
    // input in the [instance][google.cloud.aiplatform.v1beta1.ExplainRequest.instances][]. The schema of any
    // single instance may be specified via Endpoint's DeployedModels'
    // [Model's][google.cloud.aiplatform.v1beta1.DeployedModel.model]
    // [PredictSchemata's][google.cloud.aiplatform.v1beta1.Model.predict_schemata]
    // [instance_schema_uri][google.cloud.aiplatform.v1beta1.PredictSchemata.instance_schema_uri].
    repeated google.protobuf.Value input_baselines = 1;
  }

  // Metadata of the prediction output to be explained.
  message OutputMetadata {
    // Defines how to map [Attribution.output_index][google.cloud.aiplatform.v1beta1.Attribution.output_index] to
    // [Attribution.output_display_name][google.cloud.aiplatform.v1beta1.Attribution.output_display_name].
    //
    // If neither of the fields are specified,
    // [Attribution.output_display_name][google.cloud.aiplatform.v1beta1.Attribution.output_display_name] will not be populated.
    oneof display_name_mapping {
      // Static mapping between the index and display name.
      //
      // Use this if the outputs are a deterministic n-dimensional array, e.g. a
      // list of scores of all the classes in a pre-defined order for a
      // multi-classification Model. It's not feasible if the outputs are
      // non-deterministic, e.g. the Model produces top-k classes or sort the
      // outputs by their values.
      //
      // The shape of the value must be an n-dimensional array of strings. The
      // number of dimentions must match that of the outputs to be explained.
      // The [Attribution.output_display_name][google.cloud.aiplatform.v1beta1.Attribution.output_display_name] is populated by locating in the
      // mapping with [Attribution.output_index][google.cloud.aiplatform.v1beta1.Attribution.output_index].
      //
      google.protobuf.Value index_display_name_mapping = 1;

      // Specify a field name in the prediction to look for the display name.
      //
      // Use this if the prediction contains the display names for the outputs.
      //
      // The display names in the prediction must have the same shape of the
      // outputs, so that it can be located by [Attribution.output_index][google.cloud.aiplatform.v1beta1.Attribution.output_index] for
      // a specific output.
      string display_name_mapping_key = 2;
    }
  }

  // Required. Map from feature names to feature input metadata. Keys are the name of the
  // features. Values are the specification of the feature.
  //
  // An empty InputMetadata is valid. It describes a text feature which has the
  // name specified as the key in [ExplanationMetadata.inputs][google.cloud.aiplatform.v1beta1.ExplanationMetadata.inputs]. The baseline
  // of the empty feature is chosen by AI Platform.
  //
  map<string, InputMetadata> inputs = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. Map from output names to output metadata.
  //
  // Keys are the name of the output field in the prediction to be explained.
  // Currently only one key is allowed.
  //
  map<string, OutputMetadata> outputs = 2 [(google.api.field_behavior) = REQUIRED];

  // Points to a YAML file stored on Google Cloud Storage describing the format
  // of the [feature attributions][google.cloud.aiplatform.v1beta1.Attribution.feature_attributions].
  // The schema is defined as an OpenAPI 3.0.2
  // [Schema Object](https://tinyurl.com/y538mdwt#schema-object).
  // AutoML tabular Models always have this field populated by AI Platform.
  // Note: The URI given on output may be different, including the URI scheme,
  // than the one given on input. The output URI will point to a location where
  // the user only has a read access.
  string feature_attributions_schema_uri = 3;
}
