Skip to content

Guide for AI agents

A short guide meant to be pasted into an agent's system prompt. The same text is published as plain Markdown at AGENTS.md and llms.txt. To have your AI follow it on its own, install the Agent Skill.

One function, one JSON object. No design decisions: the library makes them.

import { plot, safePlot } from 'plotagents';
const svg = plot({ type, data, x, y, series, title, subtitle, source });

Rules for a good chart

  1. title, subtitle and source are optional. Leave them out when the page around the chart already says it. When you set a title, make it the finding, a full sentence with the key number: "Biobío accounts for 30% of sales", not "Sales by region". subtitle says how to read it (measure, unit, period); source says where the data comes from.
  2. Choose a data shape that fits the table. Rows ([{ region: "Biobío", sales: 1240 }]) are fine for a few rows. For many rows, write the field names once: header + rows [["region", "sales"], ["Biobío", 1240], ["Ñuble", 830]], columns { region: ["Biobío", "Ñuble"], sales: [1240, 830] }, or CSV text "region,sales\nBiobío,1240". For a wide table, pass y: ["revenue", "costs"]. In a dashboard, pass data once at the top.
  3. padding is 8 px top and bottom and 0 at the sides by default; set a number, [vertical, horizontal] or { top, right, bottom, left } to change it.
  4. Call safePlot(spec) as your tool: it never throws and returns errors, warnings and suggestions, each with a fix. If ok is false, fix the spec and call again.
  5. Set locale: "en" for English number formats (default is Spanish: 1.234,5); also "pt", "fr", "de", or "auto" to recognize it from the text. Tables recognize it on their own.

Which type

To showtypeKey fields
Compare categoriesbarx, y, series?, stack? (true / "percent"), top?
Count rows per categorycountplotx
Mean per category with a CIbarplot or pointx, y, hue?
Change over timelinex date ("2024-03") or year, y, series?; ci: true with several observations per x
A project plan or schedulegantttask, start, end (or duration), group?, progress?, dependsOn?, today?, collapsed?
Volume over timearealike line; stacks with series
The shape of a series in a table cellsparkx, y, width/height any size (e.g. 108×26), fill?, series?
One row of a distribution in a table cellrailvalue, min, max, band?: [lo, hi], median?, refs?: [{ field | value, label }], clip? / domain? (past an end → chevron); 160×18 by default
Who passed whom over timebump (slope for first vs last)x period, y value (or rank), series, top?, ends?: "first-last"
Measures on different scalesline + index: true, or facetthere is no dual axis
Exponential growthline + yScale: "log"
Relationship between two measuresregplot (fit + CI) / scatter / bubblex, y, hue?, size?, label?
Relationship + marginalsjointplotx, y
Which measures move togethercorr (correlation)vars? (default: every numeric field), method? ("spearman"), alpha?: 0.05; cluster: true or type: "clustermap" groups them with a dendrogram
Every pair of measures at oncepairplot (splom)vars (3–6), hue?, corner?, kind?: "reg"
Distribution of one measurehist (kde: true), kde, ecdfx, hue?
Distribution by categorybox, violin, strip, swarmx category, y measure, hue?
Distribution where each thing stays one thingdotplotx, bin?, label?, series?, highlight?, ticks?: [[value, label]]
Multi-dimensional profileradaraxis, value, series (≤ 4 series)
Hierarchical part-to-wholetreemap or sunburstpath: [level1, level2, …], value
Part-to-whole, ≤ 6 partsdonut / pielabel, value; half: true for a semicircle
Magnitude on a gridheatmapx, y, value
A count as a number of thingswaffleseries, value? (or one square per row), columns?, unit?
How things group, and at what heightdendrogramrows id, parent, heightField? or linkage + labels; cut?, clusters?
A value per region, state or countrychoropleth (symbolmap for totals)geo: "chile" | "usa" | "world" or any GeoJSON/TopoJSON object, key, value (text → one color per category)
Dots at real places on a street mappointmaplon, lat (auto-detected), size?, hue?, value?, label?; tiles: "osm" (default) / "esri-gray" / "esri-dark", or carto-* / mapbox-* with tilesKey
Who is connected to whomnetworkedges from, to, value?; nodes? with group; layout?
Exchanges between a few groupschordfrom, to, value
Age structurepyramidage, sex, value
A process with decisionsflowchartnodes (type, lane), edges (label)
Flows between stagessankeyfrom, to, value
One or more numberskpiitems: [{ label, value, delta, period, trend, target, good }]
Exact values to look uptablecolumns?: [field | { field, type, label, format, good, target }], sortBy?, total?, group?; types bar, delta, heat, sparkline, progress, badge, check are inferred when omitted
What comes up most in textwordcloudtext (field or raw text), value?, series?; prefer bar + top to compare exactly

seaborn names work (histplot, kdeplot, boxplot, violinplot, lmplot, stripplot, swarmplot, pointplot), and hue is an alias of series. Leave type out to infer it from the data.

Most useful options

  • highlight: "Ñuble": emphasize one category or series and mute the rest. exclude: ["Maule"] drops entries and recomputes the chart; colors stay put.
  • legend: "top" | "bottom" | "left" | "right" | false: where the legend goes (top by default).
  • colorScale: "viridis": any matplotlib colormap for heatmaps, maps and treemaps by change ("RdBu" diverges around 0; _r reverses; or a list of colors). palette: "tab10" for categories.
  • palette: "nordico": a minimal palette family (arcilla, nordico, tinta: five muted colors, the 6th series on goes gray; cdia is the default): validated colors plus matching ramps, with a dark variant under theme: "noche". palettes: ["cdia", "arcilla", "nordico", "tinta"] (or true) bakes the alternatives into one SVG; data-palette="nordico" on any ancestor switches, and toHTML adds the buttons.
  • dashed for what is not a firm number (estimates, projections, provisional figures): a name, a list, or a data field (dashed: "provisional"). Shapes keep their color, with a hatched fill and a dashed outline. On a time axis, dashedFrom: 2025 dashes lines, areas and columns from that year on. Always set dashedLabel ("Projection", "Preliminary") so readers know what the hatching means.
  • facet: "region" (+ columns): one panel per value, on a shared scale.
  • time: "year": one period at a time (the latest) with % change vs the previous one. Time controls are off by default: add slider: true only when the person asks to move through periods (buttons for ≤ 8 periods, a minimal slider otherwise; "buttons" / "slider" force one, play: false hides play). Treemaps can be colored by change with colorBy: "change".
  • refLines: [{ y: 600, label: "Target" }] and annotations: [{ x: "2024-01", label: "New branch" }].
  • format: "percent" | "currency" | "compact" | "integer" or { prefix, suffix, decimals }.
  • xScale / yScale: "log".
  • table: give a title that states the finding like any chart. More than 15 rows paginate in tens (pageSize), phones get one card per row, and the browser adds sort, search and paging. Use good: "down" on costs so ▲ turns red, progress with target: "budget" for spent vs budget, and total: true for a totals row. Keep 4–7 columns.
  • theme: "noche" or a JSON object ({ extends, categorical, type, marks, font }); palette: [...] for your own colors.
  • font: "Poppins" and textScale: 1.5 (presentation mode); configure({ font, textScale }) sets them for every chart.
  • network + focus: "node id": center a node and highlight its neighbors.
  • Your own map: geo: <GeoJSON or TopoJSON>; the matching property is found for you (featureKey to force it). Add markers: [{ lon, lat, label }], layers: [{ geo, label }] for rivers or routes, and fitTo: ["Biobío"] or a [lonMin, latMin, lonMax, latMax] box to zoom.
  • Maps for a static site: geo: { paths: { id: "M…Z" } } takes outlines already projected (no projection runs); views: [{ id, label, value }, …] bakes several readings of one geometry into one SVG (switch with data-view, plotagents/views); pathPrecision: 1, simplify: 0.5 shrink the paths; fitTo: "mainland" drops far islands; microstates: true draws Singapore or Malta as dots; world countries match by ISO-2 too.
  • gantt: day end dates are inclusive; a row without end is a milestone. Always set today on a live plan. collapsed: ["Phase 2"] (or true) folds phases into one summary bar; in the browser a click on a phase toggles it.
  • network + layout: "force" | "circular" | "radial" | "concentric" | "clusters" | "tree" | "grid" picks the placement; curveness: 0 straightens edges.
  • pointmap draws on OpenStreetMap tiles by default (tiles: "esri-gray", "mapbox-light" + tilesKey, or your own { url, attribution }). Tiles load only when the SVG is inline or in toHTML, not inside <img>.
  • Your own look for every chart: registerTheme("acme", { background, text, grid: { color, dash }, categorical: "tab10", font }) then configure({ theme: "acme" }).
  • geo: "usa": states match by postal code ("TX"), English or Spanish name, or FIPS ("48"). Alaska and Hawaii are insets; Puerto Rico appears only when your data has it. In the browser, maps zoom on click, Ctrl/⌘ + scroll or pinch.

Mistakes the library already handles

  • More than 8 series → the 9th onward turn gray; lint suggests highlight or facet.
  • Colliding line labels → spread apart with leader lines.
  • Donut with more than 6 parts → folds into "Other".
  • Long category labels → switches to horizontal.
  • Hard-to-tell custom palette → lint names the offending pair.
  • Numbers as text ("1.234,5", "12%", "$ 3.000") → parsed automatically.
  • Tens of thousands of points → drawn as batched paths, still fast.
  • Empty categories (null, "") → grouped as "(no data)" / "(sin dato)", never a "null" label.

Dashboards

When someone asks for a dashboard, call safeDashboard({ title, subtitle, source, data, kpis, charts, filters }) (tool: toolDefinition({ kind: 'dashboard' })). Layout, widths, shared colors and filters are decided for you:

  • title is the question the dashboard answers; a chart title, when you set one, states its finding.
  • At most 5 KPIs, computed from data when possible: { label, field, agg: "sum", compare: { field: "year", current: 2025, previous: 2024 }, trendBy: "month" }.
  • 4–6 charts. The first time series (or the one with primary: true) goes full width; the rest fill balanced rows.
  • filters: ["region", "channel"] become buttons that filter every chart and KPI.
  • No more than one donut; one source for the page.

Outputs

  • plot(spec) → SVG string. Drop it into HTML, Markdown, an .svg file or a PDF.
  • toHTML([spec1, spec2]) → self-contained page with tooltips, sliders and drill-down.
  • describe(spec) → alt text for the chart.
  • schema / toolDefinition() → JSON Schema and tool definition (Anthropic or OpenAI).
  • CLI: npx plotagents spec.json -o chart.svg.

Edit this page on GitHub