// Copyright 2020 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto2";

package permissions;

option optimize_for = LITE_RUNTIME;

// Features that depend on the site that triggered the permission request.
// Currently empty but added proactively for future versions.
message SiteFeatures {
  // This field must be an origin-only URL with a `http` or `https` scheme
  // Example of valid value: `https://example.org`.
  optional string origin = 1;
}

// Statistical features about client's interactions with permission prompts.
// These features are computed on all permission actions that happened before
// the current permission request.
message StatsFeatures {
  // Average deny rate for the client.
  optional float avg_deny_rate = 1;
  // Average grant rate for the client.
  optional float avg_grant_rate = 2;
  // Average dismiss rate for the client.
  optional float avg_dismiss_rate = 3;
  // Average ignore rate for the client.
  optional float avg_ignore_rate = 4;
  // Number of permission prompts seen by the client.
  optional int32 prompts_count = 5;
}

// Features representing the overall (not permission-specific) client state at
// the time the permission was requested.
message ClientFeatures {
  // Statistical features about client's previous interactions with permission
  // prompts, aggregated across all permission types.
  optional StatsFeatures client_stats = 1;

  // Enum defining the client platforms.
  enum Platform {
    PLATFORM_UNSPECIFIED = 0;
    PLATFORM_MOBILE = 1;
    PLATFORM_DESKTOP = 2;
  }

  // The platform run by the client that originated the suggestion request.
  optional Platform platform = 2;

  // Enum defining gesture types.
  enum Gesture {
    GESTURE_UNSPECIFIED = 0;
    NO_GESTURE = 1;
    GESTURE = 2;
  }

  // The type of gesture performed by the user on the page before the permission
  // prompt was shown.
  optional Gesture gesture = 3;

  // Similar to the above declared `Gesture` enum but is used only for on-device
  // model.
  enum GestureEnum {
    GESTURE_V2 = 0;
    GESTURE_UNSPECIFIED_V2 = 1;
  }

  optional GestureEnum gesture_enum = 4;

  // Similar to the above declared `Platform` enum but is used only for
  // on-device model.
  enum PlatformEnum {
    PLATFORM_MOBILE_V2 = 0;
    PLATFORM_DESKTOP_V2 = 1;
    PLATFORM_UNSPECIFIED_V2 = 3;
  }

  optional PlatformEnum platform_enum = 5;

  // Message containing the experiment config for the client request.
  message ExperimentConfig {
    // Optional. If set, the experiment id used to generate the predictions.
    optional int32 experiment_id = 1;
  }

  // Optional. The client experiment config.
  optional ExperimentConfig experiment_config = 6;
}

// Features related to a specific permission type.
message PermissionFeatures {
  // Statistical features about client's previous interactions with permission
  // prompts of the specific permission type.
  optional StatsFeatures permission_stats = 1;

  // Features related to the notification permission.
  message NotificationPermission {}

  // Features related to the geolocation permission.
  message GeolocationPermission {}

  // This field has two purposes:
  //   * it specifies the permission type
  //   * it contains the possible additional features for the specified type.
  oneof permission_type {
    NotificationPermission notification_permission = 2;
    GeolocationPermission geolocation_permission = 3;
  }

  // Enum defining the permission relevance generated by an AI and/or TFLite
  // on-device model.
  enum Relevance {
    RELEVANCE_UNSPECIFIED = 0;
    RELEVANCE_VERY_LOW = 1;
    RELEVANCE_LOW = 2;
    RELEVANCE_MEDIUM = 3;
    RELEVANCE_HIGH = 4;
    RELEVANCE_VERY_HIGH = 5;
  }

  // Optional. The permission relevance generated by an on-device model.
  optional Relevance permission_relevance = 4;
}
// Permission suggestion with the predicted likelihood that the user will grant
// the permission prompt (more details at go/hedgehog-backend).
message PermissionPrediction {
  // Additional information regarding the notification suggestion.
  message NotificationPrediction {}

  // Additional information regarding the geolocation prediction.
  message GeolocationPrediction {}

  // This field has two purposes:
  //   * it specifies the permission type for which we generated the suggestion
  //   * it contains the possible additional information for the specified type.
  oneof prediction_type {
    NotificationPrediction notification_prediction = 1;
    GeolocationPrediction geolocation_prediction = 3;
  }

  // Information about how likely a user is to perform a specific action.
  message Likelihood {
    // Discretized likelihood values (see go/hedgehog-provider-browser). The ML
    // models generate predictions as floats in the range [0, 1]; the service
    // maps these floats to the discretized likelihood values in this enum using
    // thresholds that are defined in the implementation.
    enum DiscretizedLikelihood {
      DISCRETIZED_LIKELIHOOD_UNSPECIFIED = 0;
      VERY_UNLIKELY = 1;
      UNLIKELY = 2;
      NEUTRAL = 3;
      LIKELY = 4;
      VERY_LIKELY = 5;
    }
    // Discretized likelihood of the user performing the action.
    optional DiscretizedLikelihood discretized_likelihood = 1;
  }

  // The ML predicts the likelihood of the user NOT granting the permission. We
  // then convert it to how likely the user is to GRANT the permission request.
  optional Likelihood grant_likelihood = 2;
}

// Message sent from the client to get suggestions for one or more permissions.
message GeneratePredictionsRequest {
  // Features representing the overall (not permission-specific) client state.
  optional ClientFeatures client_features = 1;
  // Features that depend on the site that the client was visiting when the
  // permission request was triggered.
  optional SiteFeatures site_features = 2;
  // Each PermissionFeatures message details a specific permission for which the
  // client wants to receive a suggestion.
  repeated PermissionFeatures permission_features = 3;
}
// The response message returned by the ChromePermissionsSuggestionsService to
// the Chrome client.
message GeneratePredictionsResponse {
  // One PermissionSuggestion is generated for each PermissionFeatures in the
  // request. The order is kept between the input and output lists.
  repeated PermissionPrediction prediction = 1;
}