Skip to content

Review criterion plugins

A review criterion evaluates one aspect of quality for one review record and returns a CriterionResult. The module ships agent_based, which delegates to a Drupal AI Agent. Your plugin can wrap a different AI service, a readability library, a link checker, or any rule-based test.

Minimal plugin

src/Plugin/ReviewCriterion/WordCountCriterion.php in your module:

<?php

declare(strict_types=1);

namespace Drupal\my_module\Plugin\ReviewCriterion;

use Drupal\ai_content_review\Attribute\ReviewCriterion;
use Drupal\ai_content_review\Entity\ReviewRecordInterface;
use Drupal\ai_content_review\Plugin\ReviewCriterion\CriterionResult;
use Drupal\ai_content_review\Entity\InternalReviewRecordInterface;
use Drupal\ai_content_review\Plugin\ReviewCriterion\ReviewCriterionBase;
use Drupal\Core\Entity\FieldableEntityInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\StringTranslation\TranslatableMarkup;

#[ReviewCriterion(
  id: 'word_count',
  label: new TranslatableMarkup('Word count'),
  description: new TranslatableMarkup('Scores content on whether it reaches a target length.'),
)]
final class WordCountCriterion extends ReviewCriterionBase {

  public function defaultConfiguration(): array {
    return ['target_words' => 300];
  }

  public function buildConfigurationForm(array $form, FormStateInterface $form_state): array {
    $form['target_words'] = [
      '#type' => 'number',
      '#title' => $this->t('Target word count'),
      '#default_value' => $this->configuration['target_words'],
      '#min' => 1,
    ];
    return $form;
  }

  public function execute(ReviewRecordInterface $record): CriterionResult {
    if (!$record instanceof InternalReviewRecordInterface) {
      return CriterionResult::skipped('Only reviews Drupal content.');
    }

    $entity = $record->getReviewedEntity();
    if (!$entity instanceof FieldableEntityInterface || !$entity->hasField('body')) {
      return CriterionResult::skipped('No body field to count.');
    }

    $words = str_word_count(strip_tags((string) $entity->get('body')->value));
    $target = (int) $this->configuration['target_words'];
    $score = (int) min(100, round($words / max(1, $target) * 100));

    return new CriterionResult(
      status: ReviewRecordInterface::STATUS_COMPLETE,
      score: $score,
      severity: $score < 50
        ? ReviewRecordInterface::SEVERITY_WARNING
        : ReviewRecordInterface::SEVERITY_INFO,
      explanation: sprintf('%d words against a target of %d.', $words, $target),
      rawSuggestions: [],
    );
  }

}

Clear caches and the criterion type appears in the Criterion type select on the Review Rule form.

The contract

ReviewCriterionBase implements everything except execute() and buildConfigurationForm().

Method You implement it when
execute(ReviewRecordInterface $record): CriterionResult Always. Must never throw.
buildConfigurationForm() Always, even if it returns $form unchanged.
validateConfigurationForm(), submitConfigurationForm() You need validation or custom normalisation of stored values.
startRun(), stepRun(), hasResumableRun(), poll() The work is too long for one request. See below.

The record knows what is under review, so a criterion asks it rather than being handed an entity. That is what lets the same plugin serve an internal entity and an external URL. Ask the record's bundle plugin for what it is about:

Call Gives you
$record->getType()->buildReviewContext($record) The subject as text, ready to send to an AI. Works for every record type.
$record->getType()->getTokenContexts($record) Token contexts for the subject, for token replacement in prompts.
$record->getReviewedEntity() The entity itself, on an InternalReviewRecordInterface record only.

Prefer the first two. A criterion that reaches for getReviewedEntity() works on internal records and skips on everything else, which is fine when the check is deliberate, as above.

CriterionResult

new CriterionResult(
  status: ReviewRecordInterface::STATUS_COMPLETE,
  score: 85,
  severity: ReviewRecordInterface::SEVERITY_INFO,
  explanation: 'Plain language result.',
  rawSuggestions: [
    [
      'type' => 'text_replace',
      'target' => 'body',
      'original_value' => 'Current field content.',
      'suggested_value' => 'Improved field content.',
      'rationale' => 'The current wording is passive.',
    ],
  ],
  aiProvider: 'openai',
  aiModel: 'gpt-4o',
);

CriterionResult::failed($message) and CriterionResult::skipped($explanation) cover the other two statuses. Raw suggestions are arrays. The orchestrator turns each into a saved Suggestion entity and references it from the record.

A result that completes without a score, or whose suggestions cannot be saved, is demoted to failed by the orchestrator. No status is silently swallowed.

Long-running criteria

The default startRun() calls execute() and returns done => TRUE. Override the run methods when one request is not enough:

stateDiagram-v2
    [*] --> Started: startRun()
    Started --> Stepping: done = FALSE
    Stepping --> Stepping: stepRun() per poll
    Stepping --> Finished: done = TRUE, result
    Started --> Finished: done = TRUE, result
    Stepping --> Paused: browser stopped driving
    Paused --> Stepping: hasResumableRun() is TRUE

Both startRun() and stepRun() return ['done' => bool, 'result' => CriterionResult|null].

The $input_hash argument identifies which run is being advanced. Two criteria of the same plugin on one entity are separate runs, and the poll route builds the plugin with empty configuration, so a plugin cannot derive the hash itself. Persist your run state under it.

hasResumableRun() is what lets the UI offer Resume instead of a stuck Updating or a Review that would throw away work already paid for. Return TRUE only when persisted state exists that stepRun() can continue from. poll() is reporting only: it never advances a run and never decides whether one has finished.

AgentBasedCriterion stores its in-flight runs in an expirable key-value collection and does one agent turn per stepRun() call. Read it as the worked example.

Config schema

A criterion's stored configuration array needs a schema entry, or the rule fails config validation. Add it to your module's config/schema/my_module.schema.yml:

ai_content_review.review_criterion.word_count:
  type: ai_content_review_plugin_review_criterion_base
  label: 'Word count criterion configuration'
  mapping:
    configuration:
      type: mapping
      label: 'Plugin configuration'
      mapping:
        target_words:
          type: integer
          label: 'Target word count'

Put presentational values (labels, badges) outside configuration if you add any, and anything that changes what is asked of the content inside it. InputHasher hashes configuration only.