Review changes

The AI Toolkit lets you show AI-generated changes in a review UI, so your users can accept or reject them.

There are two approaches:

• Use the Tracked Changes extension to render the review UI. Changes persist as part of the document and are visible to other users.
• AI Toolkit suggestions: a decoration-based UI that's ephemeral and only visible to the current user of the document.

Tracked Changes

The AI Toolkit integrates with the Tracked Changes extension to show the review UI. Follow these guides to get started:

AI Toolkit suggestions

AI Toolkit suggestions are a decoration-based review UI that is ephemeral and only visible to the current user of the document.

They are an alternative to the Tracked Changes review UI that you can use when you'd like the review UI to only be visible to the current user of the document, and not to other users of the collaborative document.

What are suggestions?

A suggestion is a proposed change to the document. Every Suggestion object has these properties:

• id (string): A unique identifier for the suggestion.
• range (Range): This is the position of the suggestion. It has a from property (the place where the suggestion starts) and a to property (the place where the suggestion ends). Learn more about ranges in the Concepts guide.
• The content that the AI suggests inserting into that range. This content is stored in the replacementOptions property.

See all the properties of the Suggestion object in the API reference.

Two types of suggestions

There are two types of suggestions:

• Preview mode: The change is previewed before applying it. The document is not modified until the user accepts the suggestion.
• Review mode: The change is reviewed after applying it. The document has already been modified and the suggestion allows the user to undo the change.

How to generate suggestions?

Suggestions are generated when you call a method of the AI Toolkit that edits the document.

These methods can be configured in three different ways:

Option 1: Do not show suggestions

The default behaviour of AI Toolkit methods is to edit the document directly and not generate any suggestions.

toolkit.executeTool({
  toolName: 'tiptapEdit',
  input: {},
  // No reviewOptions property
  // or:
  // reviewOptions: { mode: 'disabled' }
})

Option 2: Generate suggestions before editing the document

This approach does not modify the document and generates suggestions in preview mode.

The document is edited only if the user accepts the suggestions.

toolkit.executeTool({
  toolName: 'tiptapEdit',
  input: {},
  reviewOptions: { mode: 'preview' },
})

Option 3: Generate suggestions after editing the document

This approach modifies the document directly and generates suggestions in review mode. These suggestions allow the user to undo the change by applying the suggestion.

toolkit.executeTool({
  toolName: 'tiptapEdit',
  input: {},
  reviewOptions: { mode: 'review' },
})

The diff utility has other options, learn about them in the API reference.

Accepting and rejecting suggestions

You can accept and reject suggestions by calling the acceptSuggestion and rejectSuggestion methods.

toolkit.acceptSuggestion('suggestion-1')
toolkit.rejectSuggestion('suggestion-1')

These methods return AI feedback that you can collect and send to the AI to improve future suggestions.

const result = toolkit.acceptSuggestion('suggestion-1')
// result.aiFeedback.events

You can also accept and reject all suggestions at once by calling the acceptAllSuggestions and rejectAllSuggestions methods.

Suggestions can be read and updated programmatically. See the API reference for all available methods.

Guides

Follow these guides to get started: