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 in the Review UI 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 })

PreviouslyLive demo

Next upAI engineering