A chart proposal can look reasonable and still leave out the field that makes it work. Ask for stacked bars without saying what forms the stacks, and the problem begins before a single bar is drawn. Semiotic's prepareChart checks the proposal and returns reasons to revise it before an application shows the result.
Why this matters
A person reading a chart rarely sees its configuration. They cannot tell whether an absent series was intentional, a field was misspelled, or the data never reached the renderer. Checking those conditions during generation makes the failure visible to the author, who still has a chance to fix it.
Try an incomplete proposal
Start with Valid proposal: four bars compare synthetic revenue by region. East is highest and West is lowest. Then choose Stacked bar, no stackBy. The same rows have no field identifying stack segments, so validation blocks the proposal and explains the missing requirement. Return to Valid proposal to restore the chart.
Configuration checks passed · render evidence not requested
East has the highest revenue and West the lowest.
The broken proposal never paints a misleading plain bar — it returns the precise reason a stacked bar needs stackBy, for the agent to fix and retry.
What a passing result means
Structural validation checks the component and props. Diagnostics look for known problems, with error-level findings blocking by default. Supplying data enables the fit check and repair suggestions. Supplying a renderer adds evidence about the rendered scene, including whether it is empty or semantically degenerate.
This browser demo does not supply an evidence renderer. Its passing result means the enabled configuration checks passed; it does not certify the pixels, the source data, or the explanation. Even with render evidence, an author must review the comparison, units, accessibility, and the claim the chart is being used to support.
Wiring it up
import { prepareChart } from "semiotic/ai" import { renderChartWithEvidence } from "semiotic/server" const result = prepareChart(proposal, { data, render: renderChartWithEvidence, // Node or a server render path }) if (result.ok) { // Review result.svg and result.evidence before publishing. } else { // Show result.reasons and use result.repair to revise the proposal. }chartGenerationTool() supplies a JSON Schema tool definition drawn from the chart registry. The adapter functions toAnthropicTool and toOpenAITool shape that definition for a caller's integration. Your host application chooses and calls the model; these helpers do not call one.
When to reach for it
Use the check between a proposed configuration and a render in a dashboard builder, reporting assistant, or chart editor. Keep a human review when a chart makes a consequential claim or uses unfamiliar data. For a hand-authored chart that needs no generation loop, use the chart component directly and run the relevant validation and accessibility checks.
Other places this helps
The same sequence is useful for generated forms, queries, and configuration files: inspect the structure, check it against the intended task, execute it in the right environment, and examine the result. Each step answers a different question.