AI Toolkit concepts

Understand the basic concepts that will help you work with the AI Toolkit.

Position

The AI Toolkit methods allow you to read and edit the document at specific positions.

Positions allow you to locate elements in the document. They are represented as an integer.

The first position in the document is 0. The last position in the document is equal to the document content size.

const position = 0
const lastPosition = editor.state.doc.content.size

The position of the cursor can be obtained using the selection property of the editor state.

const position = editor.state.selection.head

Range

A range is a pair of positions. It represents a contiguous range of content in the document.

import { Range } from '@tiptap/core'

const range: Range = { from: 0, to: 100 }

The range of the entire document is:

const range = { from: 0, to: editor.doc.content.size }

You can get the range of the selection using the selection property of the editor state.

const range = { from: editor.state.selection.from, to: editor.state.selection.to }

You can insert or read content at a specific position or range.

const range: Range = { from: 0, to: 100 }

// Read the document
editor.commands.tiptapRead({ range })

editor.commands.insertHtml(
  '<p>AI-generated content</p>',
  {
    position: range,
  }
})

Ranges are used to determine the position of suggestions.

Suggestion

A suggestion represents a proposed change to the document. When the AI makes a change to the document, you can show it as a suggestion so that the user can review and accept or reject it. Learn more about suggestions in the Suggestions guide.

NodeRange

A node range is a range of top-level nodes in the document.

Top-level nodes are the direct children of the doc node.

A node range is an object with two properties:

from (number): The index of the first node in the range (inclusive)
to (number): The index after the last node in the range (exclusive upper bound)

// Range from the first to the 100th node
const nodeRange: NodeRange = { from: 0, to: 100 }

The node range of the entire document is:

const nodeRange = { from: 0, to: editor.state.doc.childCount }

Tiptap Read and Tiptap Edit

Tiptap Edit is a format developed by Tiptap that allows AI to edit the document efficiently and accurately. With it, the AI can make small, precise edits fast, without replacing the whole document. It enables a reduction in token usage of up to 95%.

Tiptap Edit is available as a tool for AI agents to use. It is also available as a workflow.

For Tiptap Edit to work, you need to read the document with Tiptap Read first. Tiptap Read is available as a tool for AI agents to use, or as a workflow.

const { content } = toolkit.tiptapRead()
toolkit.tiptapEdit({ content })

Optimizing Tiptap Edit

With Tiptap Edit, the AI can select and replace nodes efficiently. By default, the AI can select and replace any block node in the document.

If you want the AI to be able to select and replace other types of nodes, you can configure the selectableNodeTypes property of the Tiptap Edit tool.

This allows you to replace inline nodes or limit the nodes that the AI can select and replace.

const selectableNodeTypes = ['paragraph', 'heading', 'codeBlock']
const { content } = toolkit.tiptapRead({ selectableNodeTypes })
toolkit.tiptapEdit({ content, selectableNodeTypes })

Besides the nodes in selectableNodeTypes, the AI can replace the entire document or any top-level node in the document. If the selectableNodeTypes property is set to an empty array, the AI will only be able to select and replace top-level nodes in the document.

PreviouslyLive demo

Next upSuggestions