Tools for a model

A model inserts, reads and changes charts and diagrams through tool calls. The tools are built from what this editor supports and write through the same Commands as a person does.

Pro ExtensionAlphaPilot 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 chart tools beside the diagram tools, and answer each 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 saying how to fix the call
`pos`	`number`	The chart or diagram an insert or an update wrote. It is also named at the end of `output`

Charts

The chart tools are insertChart, insertLinkedChart, updateChart, readChart, listCharts and describeChartCapabilities. The formats and Renderers of this editor appear in their definitions as enums.

Only what this editor can draw

The type enum lists the chart types a registered Renderer draws.
describeChartCapabilities names the types of each Renderer.
A call that would insert a chart nobody sees is refused, with the types or Renderers to use instead. Nothing is written.
A renderer that is not registered, or that does not draw the chart's type, is refused the same way.
An updateChart that changes the type to one nobody draws is refused the same way.

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

A chart that reads a Data Source

insertLinkedChart inserts a chart and links it to a Data Source with linkChartSource.

Parameter	Type	Description
`provider`	`string`	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 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.

Diagrams

The diagram tools are insertDiagram, updateDiagram, readDiagram and listDiagrams.

A model writes Mermaid, which it already knows.
A call with a pie, an xychart, a sankey, a radar or a treemap is refused with a message pointing at insertChart.
listDiagrams names each diagram's format.
A draw.io or BPMN diagram is read and changed as its whole XML.

Formats and Renderers

insertDiagram creates Mermaid, or BPMN with format: 'bpmn'.
The tools write the source whatever is registered, as the Commands do. The source belongs to the document; a Renderer only draws it.
A format or a kind no Renderer here draws is written all the same. The output tells the model that it shows as unavailable here.

PreviouslyVersions

Next upSize and view