choose method

@nonVirtual Future<DeciderAnswer> choose(DeciderInput input, { Iterable<String>? among, int topK = 5, CancelToken? cancelToken, })

The option for input, or an abstention.

among restricts the candidates to those option ids, when capabilities.supportsAmong; a decider without it fails with DeciderUnsupportedException for any non-null among. Unknown ids throw ArgumentError; an empty set abstains with AbstainReason.noCandidates. topK (≥ 1) caps DeciderAnswer.ranked; the margin and probabilities still cover every candidate.

cancelToken fails the call with DeciderCancelledException: before decide runs, at the decider's own checks while it runs, and once it returns — a decider that does not look at the token still has its answer dropped. A close while the call runs fails it the same way. An embedding decider checks before it embeds the input, before core replaces a closed embedder, and when the embedding returns: an embedding already sent is not interrupted, and its vector is dropped. A failure of the model that arrives after the token was cancelled is reported as the cancel.

Errors arrive as a FAILED FUTURE: DeciderUnsupportedException for context, among or an input modality not in capabilities (checked here, for every decider), DeciderSpaceMismatchException when the embedder core now serves is in another embedding space, DeciderCancelledException, the model's own failures unchanged (EmbedderClosedException, EmbeddingInputTooLongException — an input is never truncated — …), StateError after close.

Implementation

@nonVirtual
Future<DeciderAnswer> choose(
  DeciderInput input, {
  Iterable<String>? among,
  int topK = 5,
  CancelToken? cancelToken,
}) async {
  final request = checkedDeciderRequest(
    this,
    input,
    among: among,
    topK: topK,
    cancelToken: cancelToken,
  );
  final DeciderAnswer answer;
  try {
    answer = await decide(request);
  } on DeciderCancelledException {
    rethrow;
  } on Exception {
    // The caller gave up on this answer: what the model did after that is
    // not its failure to handle. Errors (bugs) still surface.
    throwIfDeciderCancelled(cancelToken);
    rethrow;
  }
  throwIfDeciderCancelled(cancelToken);
  if (!identical(answer.questionType, capabilities.questionType)) {
    throw StateError(
      '$runtimeType answered a ${answer.questionType.name} question; its '
      'capabilities say ${capabilities.questionType.name}.',
    );
  }
  return answer;
}