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\SuggestionNotApplicableExceptionfor 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 withnot_applicableand 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 withstale.\InvalidArgumentExceptionfor 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_recommendationimplementsapply()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): booldecides whether the editor gets an Apply button.SuggestionPluginBaseoffers it when the suggestion has a suggested value;text_removeoffers it when the suggestion quotes a passage, since an empty suggested value is stored as NULL;general_recommendationnever does. Atext_replacewith 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, soexample.comdoes not match inside anhref. - Respect the item delta. Read a target with
Target\TargetAddress::parse(), which gives the field name and the item's delta. Use the delta throughTargetAddress::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 initemDelta()and pass the result toreplaceQuoted(); a plugin for another positional field type, such as a link or a number, can useTargetAddressthe 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: {}