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

// Next MinVersion: 5

// Top-level API of the Machine Learning Service: loading models for inference.

// 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;

// NOTE: The base directory for 'import' statements is expected to differ
//       between Chromium and Chrome OS versions of this file.
import "ml/mojom/document_scanner.mojom";
import "ml/mojom/grammar_checker.mojom";
import "ml/mojom/handwriting_recognizer.mojom";
import "ml/mojom/model.mojom";
import "ml/mojom/soda.mojom";
import "ml/mojom/text_classifier.mojom";
import "ml/mojom/text_suggester.mojom";
import "ml/mojom/web_platform_handwriting.mojom";

// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
[Stable, Extensible]
enum LoadModelResult {
  OK = 0,
  MODEL_SPEC_ERROR = 1,
  LOAD_MODEL_ERROR = 2,
  FEATURE_NOT_SUPPORTED_ERROR = 3,
  LANGUAGE_NOT_SUPPORTED_ERROR = 4,
};

// Top-level interface between Chromium browser process and the ML Service
// daemon.
// Next ordinal: 11
[Stable, Uuid="9e5e4750-40cc-4eda-ac09-3457d06a45ab"]
interface MachineLearningService {
  // Binds another pipe to this instance.
  Clone@5(pending_receiver<MachineLearningService> receiver);

  // The BuiltinModelId inside BuiltinModelSpec is used to specify the model to
  // be loaded.
  LoadBuiltinModel@0(BuiltinModelSpec spec, pending_receiver<Model> receiver)
      => (LoadModelResult result);
  // The FlatbufferModelSpec contains both of the flatbuffer content and the
  // metadata.
  LoadFlatBufferModel@1(FlatBufferModelSpec spec,
                        pending_receiver<Model> receiver)
      => (LoadModelResult result);
  // Create a new TextClassifier.
  LoadTextClassifier@2(pending_receiver<TextClassifier> receiver)
      => (LoadModelResult result);
  // Create and initialize a handwriting recognizer with given `spec`.
  LoadHandwritingModel@3(
      HandwritingRecognizerSpec spec,
      pending_receiver<HandwritingRecognizer> receiver)
      => (LoadHandwritingModelResult result);
  // Will be deprecated soon.
  LoadHandwritingModelWithSpec@4(
      HandwritingRecognizerSpec spec,
      pending_receiver<HandwritingRecognizer> receiver)
      => (LoadModelResult result);
  // Create and initialize a speech recognizer with given `config`.
  LoadSpeechRecognizer@6(SodaConfig config,
      pending_remote<SodaClient> soda_client,
      pending_receiver<SodaRecognizer> soda_recognizer)
      => (LoadModelResult result);
  // Create and initialize a grammar checker.
  LoadGrammarChecker@7(pending_receiver<GrammarChecker> receiver)
      => (LoadModelResult result);
  // Create and initialize a text suggester.
  [MinVersion=2] LoadTextSuggester@8(
      pending_receiver<TextSuggester> receiver,
      [MinVersion=3] TextSuggesterSpec? spec)
      => (LoadModelResult result);
  // Create a handwriting recognizer for web platform API.
  // This API shares the same HWR engine with `LoadHandwritingModel` and
  // `LoadHandwritingModelWithSpec` but with a different interface. This API is
  // as identical to the Web Platform HWR API as possible so that we do not
  // need to convert the input/output in the browser process. This is required
  // for security reasons.
  [MinVersion=1] LoadWebPlatformHandwritingModel@9(
    chromeos.machine_learning.web_platform.mojom.HandwritingModelConstraint
      constraint,
    pending_receiver<
      chromeos.machine_learning.web_platform.mojom.HandwritingRecognizer>
      receiver)
      => (LoadHandwritingModelResult result);
  // Create and initialize a document scanner.
  [MinVersion=4] LoadDocumentScanner@10(
            pending_receiver<DocumentScanner> receiver)
      => (LoadModelResult result);
};