components/segmentation_platform/public/proto/output_config.proto

// Copyright 2022 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";
option optimize_for = LITE_RUNTIME;
option java_package = "org.chromium.components.segmentation_platform.proto";
option java_outer_classname = "OutputConfigProto";

package segmentation_platform.proto;

// Used as time unit for rest of this proto.
enum TimeUnit {
  UNKNOWN_TIME_UNIT = 0;
  YEAR = 1;
  MONTH = 2;
  WEEK = 3;
  DAY = 4;
  HOUR = 5;
  MINUTE = 6;
  SECOND = 7;
}

// Defines what type of model is supplied. Results are based on which
// classifier/regressor the model is in.
message Predictor {
  // A classifier to interpret model results as a boolean. The final result
  // supplied to the client `ordered_lables` of length one, with either
  // `positive_label` or `negative label`.
  message BinaryClassifier {
    // Model score below threshold is classified as `negative_label` else
    // `positive_label`.
    optional float threshold = 1;
    // Labels for positive and negative outputs.
    optional string positive_label = 2;
    optional string negative_label = 3;
  }

  // A classifier to interpret model results as one of multiple classes. Each
  // output of the model corresponds to one of the classes. The number of labels
  // should be equal to the number of outputs from the model. The final result
  // supplied to the client is list of `ordered_labels` of size `top_k_outputs`.
  message MultiClassClassifier {
    // Number of top results the client is interested in. Must be less than
    // or equal to the number of labels specified.
    optional int64 top_k_outputs = 1;

    // Class labels associated with the outputs. The number of outputs from the
    // model must be equal to the length of this list. Each label maps to the
    // corresponding output index.
    repeated string class_labels = 2;

    // Threshold to get `class_labels` with score above it. Only labels with
    // score above or equal to threshold are returned. Must not be used along
    // with `class_thresholds`.
    optional float threshold = 3;

    // Per-class thresholds. Used to assign a different threshold to each class
    // so that class_labels[n] is returned when outputs[n] >=
    // class_thresholds[n]. Length of this list must be the same as the length
    // of `class_labels`. Must not be used along with `threshold`.
    repeated float class_thresholds = 4;
  }

  // A post-processor that converts a continuous model score into discrete
  // ranges. The final result supplied to the client is one of the bin labels or
  // `underflow_label`.
  message BinnedClassifier {
    // A bin represents a bucket containing entries.
    message Bin {
      // Represents minimum range for this bin. Entries are between the current
      // bin `min_range` (inclusive) to the next bin `min_range` (exclusive).
      // Range of bin : [min_range , next-bin min_range)
      optional float min_range = 1;
      // Signify what the bin corresponds to.
      optional string label = 2;
    }
    // BinnedClassifier contains multiple bins arranged in ascending order of
    // min_range of the bins. The result is `ordered_labels` of length 1 with
    // selected bin's label.
    repeated Bin bins = 1;

    // In case the model score is less than the `min_range` of the first label,
    // `underflow_label` is returned. If not supplied, then empty vector is
    // returned.
    optional string underflow_label = 2;
  }

  // Describes a regression model.
  message Regressor {}

  // Used when the model does not fit in any of the above descriptions. Contains
  // basic description about the model output. Model result is vector of floats
  // with labels.
  message GenericPredictor {
    // Label assigned to each corresponding output value returned by the model.
    // The number of outputs from the model must be equal to the length of this
    // list.
    repeated string output_labels = 1;
  }

  // Specifies how to post process the raw model results based on model type,
  // e.g. classification or regression.
  oneof PredictorType {
    BinaryClassifier binary_classifier = 1;
    MultiClassClassifier multi_class_classifier = 2;
    BinnedClassifier binned_classifier = 3;
    Regressor regressor = 4;
    GenericPredictor generic_predictor = 5;
  }
}

// TTL for the result, unit in TimeUnit.
message PredictedResultTTL {
  // TTL for the predicted result can be optionally configured based on the top
  // result. For example, for a ClassificationResult with
  // `ordered_labels` B, A, C, the TTL value of B in `top_label_to_ttl_map` will
  // be used as the result TTL. This field is only valid for Classifier
  // predictor (binary, multi class and binned).
  map<string, uint64> top_label_to_ttl_map = 1;

  // TTL when no other TTL is specified for a particular label.
  optional uint64 default_ttl = 2;

  // The time unit to be used for TTL.
  optional TimeUnit time_unit = 3;
}

// Specified by client in the metadata on how to interpret the model results.
message OutputConfig {
  // A post-processor associated with the model.
  optional Predictor predictor = 1;

  // TTL associated with the PredictionResult. Config defines when to refresh
  // results.
  optional PredictedResultTTL predicted_result_ttl = 2;

  // Flag to ignore previous model TTL. If this is set to true, ttl is ignored
  // and results are refreshed on model update. This is false by default. It
  // doesn't have any effect on TTL.
  optional bool ignore_previous_model_ttl = 3;
}