Tools for a model

An AI model, such as a large language model (LLM), can insert, read and change charts and diagrams through tool calls. On this page, "model" always means an AI model. The extension builds the tool definitions from what your editor supports. Each tool writes through the same commands that a user's edits use.

AlphaPilot program

Run the tool calls a model would make, and see each answer and its effect on the document:

New tab

Quick start

Offer the model the chart tools and the diagram tools. Answer each tool call with the matching run function:

import {
  getChartToolDefinitions,
  getDiagramToolDefinitions,
  runChartTool,
  runDiagramTool,
} from '@tiptap-pro/extension-diagrams'

const tools = [...getChartToolDefinitions(editor), ...getDiagramToolDefinitions(editor)]

// A call to a chart tool
const result = runChartTool(editor, name, input)
// A call to a diagram tool
const other = runDiagramTool(editor, name, input)

Functions

Function	Returns
`getChartToolDefinitions(editor)`	Tool definitions (`name`, `description`, `inputSchema`) for the chart tools
`runChartTool(editor, name, input)`	`{ ok, output, pos? }` after running one chart tool
`getDiagramToolDefinitions(editor)`	Tool definitions for the diagram tools
`runDiagramTool(editor, name, input)`	`{ ok, output, pos? }` after running one diagram tool

What a call returns

Field	Type	Description
`ok`	`boolean`	Whether the call succeeded
`output`	`string`	JSON, or on failure a message that tells the model how to fix the call
`pos`	`number`	The position of the chart or diagram that an insert or an update wrote. The end of `output` names it too

Charts

The chart tools are insertChart, insertLinkedChart, updateChart, readChart, listCharts and describeChartCapabilities. Their definitions list the formats and Renderers of your editor as enums.

Only what this editor can draw

The tools never insert a chart that no registered Renderer can draw. The type enum lists the chart types that a registered Renderer draws, and describeChartCapabilities names the types of each Renderer.

These calls are refused, and nothing is written:

an insert of a chart that no Renderer draws
a renderer that is not registered, or that does not draw the chart's type
an updateChart call that changes the type to one no Renderer draws

The answer names the types or Renderers to use instead:

{
  "ok": false,
  "output": "No Renderer here draws \"sankey\" charts. Use one of these types: line, bar, pie."
}

A chart that reads a Data Source

The tool insertLinkedChart inserts a chart and links it to a Data Source, such as a CSV file at a URL, with linkChartSource. The command of the same name, insertLinkedChart, is different: it makes a chart that follows a table in the document. The tool cannot do that, because it does not offer the document-table source.

Parameter	Type	Description
`provider`	`string`	The Data Source. An enum of the registered Data Sources other than `document-table`
`address`	`object`	Where the source reads from, such as `{ url }` for a CSV or JSON file at a URL
`type`	`string`	The chart type. Optional
`title`	`string`	The chart's title. Optional
`readOnly`	`boolean`	The chart is read-only unless this is `false`

The data arrives after the call returns. A failed read goes to onSourceError. The tool links url-csv and url-json only when your app sets allowSourceUrl, and only to the URLs it allows. allowSourceUrl decides where a request may go, not what the URL holds. A model can still put document text into an allowed URL, for example in its query. So allow only hosts you trust with the document's content.

Diagrams

The diagram tools are insertDiagram, updateDiagram, readDiagram and listDiagrams. A model writes Mermaid, which it already knows. listDiagrams names each diagram's format. A draw.io or BPMN diagram is read and changed as its whole XML.

A Mermaid chart kind, such as a pie, is a chart. A diagram tool call with one is refused, with a message that points the model to insertChart.

Formats and Renderers

insertDiagram creates Mermaid or BPMN. For BPMN, the call passes format: 'bpmn'. Without a format, it creates Mermaid, unless your editor draws BPMN but not Mermaid.
insertDiagram does not offer draw.io. Its format enum is mermaid and bpmn. The model can read and change an existing draw.io diagram with readDiagram and updateDiagram.
The tools write the source whatever Renderers are registered, as the commands do. A format or a kind that no Renderer here draws is written all the same. The output tells the model that it shows as unavailable in this editor.

PreviouslyVersions

Next upSize and view