def merge_validation_gold_and_candidate(examples,
                                        candidates,
                                        n_candidates):
  """Merge gold and candidate examples for the validation fold.

  Note: This mutates the members of examples, specifically adds the
    tfidf_candidate field.

  Args:
    examples: A dictionary of examples to merge with, typically containing only
      gold examples
    candidates: Candidates to possibly include
    n_candidates: The max number of candidates to return

  Returns:
    A list of examples.
  """
  for candidate in candidates:
    key = (candidate['wikipedia_url'], candidate['sentence_id'])
    # Prevent duplicates, just mark them as retrieved and attach doc score
    if key in examples:
      examples[key]['retrieved'] = True
      examples[key]['doc_score'] = candidate['doc_score']
    else:
      examples[key] = candidate

  sorted_candidates = sorted(
      examples.values(), key=lambda x: x['sentence_score'], reverse=True)
  final_candidates = sorted_candidates[:n_candidates]
  final_examples = {}
  for candidate in final_candidates:
    key = (candidate['wikipedia_url'], candidate['sentence_id'])
    candidate['tfidf_candidate'] = True
    final_examples[key] = candidate

  bottom_candidates = sorted_candidates[n_candidates:]
  for candidate in bottom_candidates:
    key = (candidate['wikipedia_url'], candidate['sentence_id'])
    # Force include gold examples, but mark them with tfidf_candidate=False
    # to indicate they should be excluded in validation evaluations.
    if candidate['gold']:
      candidate['tfidf_candidate'] = False
      final_examples[key] = candidate

  return list(final_examples.values())