// Copyright 2021 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.

// Next MinVersion: 2

// Datatypes and interfaces of text suggester API.

// NOTE: This mojom exists in two places and must be kept in sync:
//       Chromium:  //chromeos/services/machine_learning/public/mojom/
//       Chrome OS: src/platform2/ml/mojom/
//       Note: Other repos downstream of Chromium might also use this mojom.

// Example: A backwards-compatible mojom change (and corresponding
// implementation change) can be made in Chrome OS first, then replicated to the
// clients (Chromium, other downstream repos) later.
// Use //chromeos/services/machine_learning/public/mojom/roll_mojoms.sh to help
// replicate Chrome OS-side changes over to Chromium.

module chromeos.machine_learning.mojom;

// Represents a single completion candidate
// Next ordinal: 2
[Stable]
struct NextWordCompletionCandidate {
  // The completing text suggested
  string text@0;

  // The normalized confidence score for the generated candidate
  float normalized_score@1;
};

// The mode with which a suggestion should be used by a consumer
[Stable, Extensible]
enum TextSuggestionMode {
   // A prediction suggestion is the text predicted after a word. For example
   // the preceding text could be "how are", and the suggested text would be
   // "you".
   [Default] kPrediction = 1,

   // A completion suggestion is similar to a prediction, however the suggestion
   // also completes any unfinished words in the preceding text. For example,
   // the preceding text could be "how ar", and the suggested text would be
   // "e you".
   kCompletion = 2,
};

// Defines a query for text suggestions
// Next ordinal: 3
[Stable]
struct TextSuggesterQuery {
  // The text used to generate suggestions
  string text@0;

  // Optional: completion candidates for the final word in the text
  array<NextWordCompletionCandidate> next_word_candidates@1;

  // The types of suggestions requested
  [MinVersion=1] TextSuggestionMode suggestion_mode@2;
};

// Represents a single generated multi word suggestion candidate.
// Next ordinal: 2
[Stable]
struct MultiWordSuggestionCandidate {
  // The text suggested
  string text@0;

  // The normalized confidence score for this candidate
  float normalized_score@1;
};

// Represents all types of suggestion candidates generated by the service.
//
// TODO(crbug/1201949): Note that the Extensible keyword is not supported for
// union types. We may need to revisit this type in the future.
//
// Next ordinal: 1
[Stable, Extensible]
union TextSuggestionCandidate {
  MultiWordSuggestionCandidate multi_word@0;
};

// The result to text suggestion queries, contains any candidates generated.
// Next ordinal: 2
[Stable]
struct TextSuggesterResult {
  // Status of the response
  [Stable, Extensible, Default=ERROR]
  enum Status {
    // Text suggestions generated successfully
    OK = 0,
    // There was an error while generating candidates, no candidates will be
    // returned with this result.
    ERROR = 1,
  };

  Status status@0;

  // The list of candidates generated by the text suggester service
  array<TextSuggestionCandidate> candidates@1;
};

// Experiment groups for multi word suggestions
// Next value: 5
[Stable, Extensible]
enum MultiWordExperimentGroup {
  [Default] kDefault = 0,
  kGboard = 1,
  // Experiment groups used for the relaxed gboard settings finch experiment
  kGboardRelaxedA = 2,
  kGboardRelaxedB = 3,
  kGboardRelaxedC = 4
};

// Encapsulates any settings details for a TextSuggester
// Next ordinal: 1
[Stable]
struct TextSuggesterSpec {
  // The experimental group for multi word suggestions
  MultiWordExperimentGroup multi_word_experiment@0;
};

// The top level interface for requesting text based suggestions in the Chromium
// browser process from the sandboxed ML service process.
// Next ordinal: 1
[Stable]
interface TextSuggester {
  // Generates text suggestions from the given context
  Suggest@0(TextSuggesterQuery query) => (TextSuggesterResult result);
};