components/ntp_snippets/contextual/proto/get_pivots_request.proto

// Copyright 2018 The Chromium Authors. All rights reserved.
// 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;

package contextual_suggestions;

import "chrome_search_api_request_context.proto";

message GetPivotsRequest {
  // Context common to the search API.
  optional SearchApiRequestContext context = 1;

  // Request fields specific to the Pivots request.
  optional GetPivotsQuery query = 2;
}

message GetPivotsQuery {
  // A historical chain of the user's past exploration to date, sorted from
  // most recent to least recent (reverse chronological order).  A context is
  // usually a document and some related data (eg. salient terms and/or query
  // that generated that doc).
  repeated ExploreContext context = 1;

  // Parameters related to pivot documents.
  optional PivotDocumentParams document_params = 2;

  // Parameters related to clustering pivot items (documents, queries,
  // questions, etc.).
  optional PivotClusteringParams clustering_params = 6;

  // Parameters related to peek text.
  optional PivotPeekTextParams peek_text_params = 7;
}

// One piece of historical context in the user's exploration session.
message ExploreContext {
  // If specified, the (possibly uncanonicalized) document the user visited.
  optional string url = 1;
}

message PivotDocumentParams {
  // If true, compute pivot documents.
  optional bool enabled = 1 [default = false];

  // How many documents should we return?
  optional int32 num = 2 [default = 5];

  // If we have fewer documents than this to return, then don't return any.
  optional int32 min_documents = 6 [default = 3];

  // If true, return images for documents.
  optional bool enable_images = 3 [default = false];

  // When images are returned, what aspect ratio should be used.
  enum ImageAspectRatio {
    // Allow the server to select.  This will typically return a thumbnail in
    // the same aspect ratio as the original image.
    ASPECT_RATIO_UNSPECIFIED = 0;
    // Crop to a square image.
    SQUARE = 1;
  }
  optional ImageAspectRatio image_aspect_ratio = 4
      [default = ASPECT_RATIO_UNSPECIFIED];
}

// Parameters for clustering pivot items (documents, queries, questions, etc).
message PivotClusteringParams {
  // Whether or not to group PivotItems on similar topics into clusters.
  optional bool enabled = 1;

  // Minimum number of clusters we should return.
  optional int32 min = 2;

  // Maximum number of clusters we should return.
  optional int32 max = 3;
}

// Parameters related to the peek text.
message PivotPeekTextParams {
  // Whether or not to return peek text.
  optional bool enabled = 1 [default = false];
}