Skip to content

Suggestion plugins

A suggestion plugin knows how to apply one Suggestion entity to whatever was reviewed. The module ships three: text_replace, which replaces the quoted passage of a field with the suggested value, text_remove, which removes the quoted passage, and general_recommendation, which applies nothing and exists to carry advice.

The plugin ID is what an agent puts in a suggestion's type, so adding a plugin adds a kind of change the AI is allowed to propose.

Minimal plugin

src/Plugin/Suggestion/AddAltTextSuggestion.php in your module:

<?php

declare(strict_types=1);

namespace Drupal\my_module\Plugin\Suggestion;

use Drupal\ai_content_review\Attribute\ReviewSuggestion;
use Drupal\ai_content_review\Entity\SuggestionInterface;
use Drupal\ai_content_review\Plugin\Suggestion\SuggestionPluginBase;
use Drupal\Core\Entity\EntityInterface;
use Drupal\Core\Entity\FieldableEntityInterface;
use Drupal\Core\StringTranslation\TranslatableMarkup;

#[ReviewSuggestion(
  id: 'add_alt_text',
  label: new TranslatableMarkup('Image alt text'),
  description: new TranslatableMarkup('Writes the suggested alt text onto an image field.'),
)]
final class AddAltTextSuggestion extends SuggestionPluginBase {

  public function apply(EntityInterface $entity, SuggestionInterface $suggestion): void {
    $target = $suggestion->getTarget();
    if (!$entity instanceof FieldableEntityInterface || $target === NULL) {
      throw new \InvalidArgumentException('An image field is required.');
    }
    if (!$entity->hasField($target)) {
      throw new \InvalidArgumentException(sprintf('No field "%s" on this entity.', $target));
    }

    $item = $entity->get($target)->first();
    if ($item !== NULL) {
      $item->set('alt', $suggestion->getSuggestedValue());
    }
  }

}

The contract

public function apply(EntityInterface $entity, SuggestionInterface $suggestion): void;
  • Never save. Change the entity in memory and return. The caller saves, so several suggestions can be batched into one save.
  • Throw when the suggestion cannot be applied. The apply runs in a transaction, so nothing is written when it throws.
  • Drupal\ai_content_review\Exception\SuggestionNotApplicableException for advice an editor has to act on by hand: the target is not a text field, the quote is missing, would break markup, or would drop a link or media. The controller answers 409 with not_applicable and the message, which the editor sees.
  • Drupal\ai_content_review\Exception\StaleSuggestionException (a subclass of the one above) when the content no longer matches the suggestion: the quote is gone, or occurs more than once. The controller answers 409 with stale.
  • \InvalidArgumentException for a suggestion that is malformed: no target field, a field that does not exist, a target with a delta that is not an integer, an entity of the wrong shape. This is a fault rather than advice, so the controller logs it and answers 500 with the message.
  • Applying nothing is legitimate. general_recommendation implements apply() as a no-op, which is how a finding that has no mechanical fix still gets a card, a rationale and a place on the improvement plan.
  • Say whether Apply is offered. canApply(SuggestionInterface $suggestion): bool decides whether the editor gets an Apply button. SuggestionPluginBase offers it when the suggestion has a suggested value; text_remove offers it when the suggestion quotes a passage, since an empty suggested value is stored as NULL; general_recommendation never does. A text_replace with no suggested value is advice about the passage it quotes.
  • Find the passage with the quote matcher. The text plugins quote what they change. The quote matcher service finds the quote in the stored value (exactly, escaped, or with different whitespace between tags) and reports what replacing it would lose: links, images and embedded media must survive a replacement, and a removal never takes media with it. These markup checks apply to formatted text only: in a plain-text field such as a title, <draft> is text. In formatted text a quote only matches text, never part of a tag or a character reference, so example.com does not match inside an href.
  • Respect the item delta. Read a target with Target\TargetAddress::parse(), which gives the field name and the item's delta. Use the delta through TargetAddress::deltaIn(), which returns it only while the target field is as it was reviewed: once the field has changed, an item may have moved, so search every item instead. The text plugins do this in itemDelta() and pass the result to replaceQuoted(); a plugin for another positional field type, such as a link or a number, can use TargetAddress the same way. See Targets.

What a Suggestion entity carries

Getter Holds
getType() Your plugin ID.
getTarget() The field machine name, optionally with : and an item delta (field_notes:1), or NULL for entity-level findings.
getOriginalValue() The value captured at review time.
getSuggestedValue() The proposed replacement.
getRationale() Why the AI proposes it.
isAccepted(), isIgnored() The editor's triage decision.

Suggestions are append-only. The editor-state fields (applied_at, applied_by, decision, decided_at, decided_by, checked_off_at, checked_off_by) are written through the entity's own setters from a controller.

Telling the agent about it

An agent only proposes types it knows about. The suggestions argument of the AI Content Review Result tool enumerates the allowed plugin IDs and describes each one, so a newly added plugin becomes available to agents as soon as its class is discovered. The description is built from your plugin's attribute, as id (Label: description), and sent to the model. Write the label and description for the agent as well as for the admin UI: say what the type changes and when to use it. Mention the new type in the criterion's guidelines too, so the AI knows when to reach for it.

Config schema

Add an entry if your plugin stores configuration:

ai_content_review.review_suggestion.add_alt_text:
  type: mapping
  label: 'Image alt text suggestion configuration'
  mapping: {}