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

module blink.mojom;

import "mojo/public/mojom/base/values.mojom";
import "third_party/blink/public/mojom/ai/ai_common.mojom";

// The status of the ModelStreamingResponder response.
// TODO(leimy): return more information about the erroneous case.
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
//
// LINT.IfChange(ModelStreamingResponseStatus)
enum ModelStreamingResponseStatus {
  // There response is not fully streamed back yet, and the interface will
  // remain open.
  kOngoing = 0,
  // The ModelStreamingResponder completes and closes.
  kComplete = 1,
  // The following enums are for the case when the ModelStreamingResponder closes with some errors.
  kErrorUnknown = 2,
  // The request was invalid.
  kErrorInvalidRequest = 3,
  // The request was throttled.
  kErrorRequestThrottled = 4,
  // User permission errors such as not signed-in or not allowed to execute
  // model.
  kErrorPermissionDenied = 5,
  // Other generic failures.
  kErrorGenericFailure = 6,
  // Retryable error occurred in server.
  kErrorRetryableError = 7,
  // Non-retryable error occurred in server.
  kErrorNonRetryableError = 8,
  // Unsupported language.
  kErrorUnsupportedLanguage = 9,
  // Request was filtered.
  kErrorFiltered = 10,
  // Response was disabled.
  kErrorDisabled = 11,
  // The request was cancelled.
  kErrorCancelled = 12,
  // The session has been destroyed.
  kErrorSessionDestroyed = 13,
  // The input exceeds the quota limit.
  kErrorInputTooLarge = 14,
  // Response was retracted due to low quality.
  kErrorResponseLowQuality = 15,
  // The response exceeded output limits and was truncated.
  kErrorResponseExceedsMaxTokens = 16,
  // The response exceeded the remaining available context.
  kErrorResponseExceedsRemainingContext = 17,
  // Failed to parse the response.
  kErrorResponseParsingFailed = 18,
  // Failed to run safety checks.
  kErrorFailedToRunSafety = 19,
  // Failed to count tokens.
  kErrorFailedToCountTokens = 20,
  // Append new items here.
};
// LINT.ThenChange(//tools/metrics/histograms/metadata/ai/enums.xml:AIModelStreamingResponseStatus)

// The struct stores the information about the context for the session.
struct ModelExecutionContextInfo {
  // The latest number of existing tokens.
  uint64 current_tokens;
};

// Represents a tool call requested by the language model during execution.
struct ToolCall {
  // Unique identifier for this tool call within the session.
  string call_id;
  // The tool name to be invoked.
  string name;
  // Arguments as structured data fitting the tool's input schema.
  mojo_base.mojom.DictionaryValue arguments;
};

// Provides methods for the model session to pass the information back to the
// built-in AI interfaces (e.g. AILanguageModel, AISummarizer etc.) when they
// request to feed inputs to the session.
// There are two cases that use this from the interfaces:
// - When executing the model to perform some tasks and expecting the response
// to be streamed back.
// - When appending some inputs to the context without actually executing them.
// The operation is only considered finished when `OnCompletion()` or
// `OnError()` is called. After that, there won't be any request sent through
// this interface and the remote should close the connection.
// TODO(crbug.com/409355678): rename this to something that describes the
// use cases more accurately (e.g. `AIInputFeedingClient`).
interface ModelStreamingResponder {
  // Called when the model execution completes. The optional `context_info`
  // contain information about the session like the current number of tokens
  // and if the context overflows.
  // It will only be set when necessary, for example, in the `AILanguageModel`
  // interface as it maintains the context of the past model execution.
  // TODO(crbug.com/409355678): Merge OnCompletion and OnError.
  OnCompletion(ModelExecutionContextInfo? context_info);

  // Called when the model execution encounters errors.
  // `quota_error_info` may provide additional info for kErrorInputTooLarge.
  OnError(ModelStreamingResponseStatus status, QuotaErrorInfo? quota_error_info);

  // The following methods might be called zero or one or multiple times, but
  // they won't happen after `OnCompletion()` or `OnError()`.

  // Called when there is a new chunk of data available for streaming.
  OnStreaming(string text);

  // Called when the model requests tool execution.
  // Clients should validate and then execute or surface calls to JS API client.
  // Model sessions typically expect a tool result or error input thereafter.
  OnToolCalls(array<ToolCall> tool_calls);

  // Called when the context overflows when reserving the space for the newly
  // added items. It does not indicate a failure or guarantee the success.
  // Used by Prompt API only.
  OnContextOverflow();
};