Los gráficos son un lenguaje. Ahora la IA lo habla.
plotagents es un protocolo abierto entre un modelo y la página. El modelo dice lo que un gráfico significa: los datos, el hallazgo, la unidad. La biblioteca responde con un gráfico terminado y accesible, o con la corrección exacta que le falta.
Este es nuestro plan de implementación. ¿Dónde estamos y qué se podría atrasar?
plot({ type: "gantt", title: "La puesta en marcha es el 15 de junio y la integración con el ERP es la ruta crítica", subtitle: "Plan de implementación por fase, 2026. La parte rellena de cada barra es el avance", source: "datos ilustrativos", data: /* 10 tareas: phase, task, start, end, progress, after */, task: "task", start: "start", end: "end", group: "phase", progress: "progress", dependsOn: "after", today: "2026-03-12", dashed: "tentative", dashedLabel: "Por confirmar", locale: "es",}){ ok: true, type: "gantt", svg: "<svg …>…</svg>", // 13.6 kB, con aria-label y <desc> description: "Carta Gantt de 10 tareas en 4 fases, del 5 ene 2026 al 15 jun 2026. Más larga: Integración con el ERP (46 días). Hitos: Informe de hallazgos (9…", errors: [], warnings: [], suggestions: []}Instálala una vez. Tu IA grafica con plotagents desde ahí en adelante.
La skill le dice a tu asistente que use plotagents en cada gráfico, mapa, tabla y dashboard. Trae lo esencial del protocolo y revisa en npm si hay una versión nueva antes de empezar, así nunca queda atrás.
- Claude Code, Cursor, Codex… Corre el comando de arriba en tu terminal.
- App de Claude Descarga el .zip y súbelo en Configuración → Capacidades → Skills.
- Cualquier otra IA Pega SKILL.md en sus instrucciones.
Un mensaje de ida y uno de vuelta. Sin píxeles.
Un modelo es bueno para saber qué dicen los datos y malo para ubicar las etiquetas de un eje. Por eso el protocolo le pide solo el significado y deja el oficio de este lado.
Decir
El modelo describe el gráfico, no el dibujo: filas de datos, el rol de cada campo y un título que dice el hallazgo.
Revisar
safePlot nunca lanza errores. Valida contra el JSON Schema y las reglas de diseño antes de dibujar nada.
Corregir
Cada problema trae un fix escrito para que lo lea un modelo. Lo aplica y vuelve a llamar, casi siempre una sola vez.
Mostrar
Vuelve un SVG con su texto alternativo en description, así el modelo puede leer lo que dibujó antes de responder.
Primera llamada
plot({
type: "donut",
data: /* 11 filas: city, stores */,
label: "city",
value: "store_count",
locale: "es",
})Un campo mal escrito y una dona de 11 partes: dos errores clásicos.
plotagents responde
{
ok: false, svg: null,
errors: [
{ message: "El campo \"store_count\" (value) no existe.",
fix: "Campos disponibles: city, stores" }
],
warnings: [
{ message: "11 segmentos: sobre 6 la dona no se lee; se agrupan en \"Otros\".",
fix: "Usa `type: \"bar\"` o `type: \"treemap\"`." }
],
suggestions: [ ]
}Segunda llamada → gráfico
Una gramática pequeña para todos los gráficos.
Diez palabras bastan para la mayoría de los gráficos. Nombra un tipo, o déjalo fuera y plotagents lo deduce de los datos. Los nombres de seaborn también sirven.
- title
- El hallazgo, como una oración con la cifra.
- subtitle
- Cómo leerlo: medida, unidad, período.
- source
- De dónde vienen los datos. Siempre.
- data
- Filas, tal como llegan:
[{ region, sales }]. - x · y · series
- Qué rol cumple cada campo.
- highlight
- Lo único que el lector debe ver.
- dashed
- Lo que todavía no es una cifra firme.
- facet · time
- Paneles pequeños; un período a la vez.
- geo
- Chile, EE. UU., el mundo o tu propio GeoJSON.
- locale
"es"o"en", para números y fechas.
bar/ line/ area/ scatter/ treemap/ sunburst/ donut/ pie/ heatmap/ sankey/ kpi/ hist/ kde/ ecdf/ regplot/ jointplot/ box/ violin/ strip/ swarm/ point/ radar/ network/ chord/ pyramid/ flowchart/ gantt/ wordcloud/ choropleth/ symbolmap/ pointmap/ table/ corr/ pairplot/ spark/ bump/ waffle/ dendrogram/ dotplot/ rail
Además barplot, histplot, violinplot, lmplot… y palabras simples como timeline, map o roadmap. El contrato completo es un solo archivo: schema.json.
Dibujado por la biblioteca, no adivinado por el modelo.
Cada gráfico salió de un spec de pocas líneas. El orden, las etiquetas, el color, los espacios y la versión móvil se decidieron de este lado.
Trae tu propia geometría.
Chile, Estados Unidos y el mundo vienen incluidos. Todo lo demás está a un campo de distancia: comunas, distritos escolares, zonas de venta, un campus, un plano.
- Cualquier forma en
geo. Un FeatureCollection, un Feature, una lista de features, un TopoJSON o una URL en el navegador. - Sin clave que configurar. La propiedad que calza con tus filas (
NOM_COM,GEOID,ADMIN) se encuentra sola. - Capas encima.
markerspor longitud y latitud,layerspara ríos, rutas o límites. - Tu encuadre.
fitToacerca a unas pocas regiones o a un recuadro; proyecciones desde Mercator hasta UTM en metros. - Los textos también sirven. Un partido o un idioma colorean por categoría, con leyenda.
plot({
type: 'choropleth',
geo: myGeoJSON, // o un TopoJSON, o una URL
data, key: 'country', value: 'language',
markers: { data: capitals, label: 'city' },
layers: [{ geo: tropic, dash: true }],
fitTo: ['Chile', 'Argentina'], // opcional
})Reglas que el modelo no puede romper.
Los agentes tienden al doble eje, a las tortas de doce partes y a los títulos que no dicen nada. Aquí la buena decisión es la única disponible.
El título dice el hallazgo
Una oración completa con la cifra clave. lint marca los títulos que solo nombran el gráfico; describe escribe el texto alternativo.
Un eje, siempre
Nada de doble eje: inventa correlaciones. index: true lleva todo a base 100 y facet dibuja paneles en una escala común.
Etiquetas donde mira el ojo
Las líneas se rotulan en su extremo, los valores van sobre las barras y las etiquetas que chocan se separan con guías. Leyenda solo cuando hace falta.
El color sigue a la entidad
Ocho colores aptos para daltonismo en un orden fijo. “Cobre” conserva su color al filtrar, al entrar en un grupo o al mover el slider.
Honesto con la incertidumbre
Las estimaciones y proyecciones se rayan con dashed, nunca con un color nuevo, y la leyenda dice qué significa el rayado.
SVG rápido y accesible
Cero dependencias, render en el servidor, un aria-label y un <desc> en cada gráfico y los datos densos agrupados en trazos.
Pásaselo a cualquier modelo.
El protocolo viene como un JSON Schema y una definición de herramienta lista, más una guía de una página para el prompt de sistema y una Agent Skill.
- La Agent Skill hace que Claude, Cursor o Codex usen plotagents por su cuenta.
toolDefinition()convierte el schema en una herramienta para Claude u OpenAI.safePlot(spec)devuelve el SVG o los errores, cada uno con sufix.describe(spec)escribe un texto alternativo que el modelo puede revisar.- La guía para agentes, también como AGENTS.md y llms.txt (en inglés).
render()en el navegador agrega tooltips, drill-down, zoom en mapas y controles de tiempo cuando el spec los pide.
import Anthropic from '@anthropic-ai/sdk';
import { safePlot, toolDefinition } from 'plotagents';
const client = new Anthropic();
const res = await client.messages.create({
model: process.env.ANTHROPIC_MODEL,
max_tokens: 4096,
tools: [toolDefinition()], // todo el protocolo, como JSON Schema
messages: [{ role: 'user', content: 'Grafica los tiempos de atención por clínica: …' }],
});
const call = res.content.find((b) => b.type === 'tool_use');
const { ok, svg, description, errors } = safePlot(call.input);
// Nunca lanza errores. Si !ok, devuelve `errors` como resultado:
// cada uno trae un `fix` y el modelo vuelve a llamar.import OpenAI from 'openai';
import { safePlot, toolDefinition } from 'plotagents';
const client = new OpenAI();
const res = await client.chat.completions.create({
model: process.env.OPENAI_MODEL,
tools: [toolDefinition({ flavor: 'openai' })],
messages: [{ role: 'user', content: 'Mapea el desempleo por región: …' }],
});
const call = res.choices[0].message.tool_calls[0];
const result = safePlot(JSON.parse(call.function.arguments));<script src="https://unpkg.com/plotagents/dist/plotagents.js"></script>
<div id="chart"></div>
<script>
// Incluye tooltips, sliders de tiempo, drill-down y zoom en mapas.
plotagents.render('#chart', {
type: 'choropleth',
geo: '/maps/comunas.topojson', // tu propia geometría, por URL
data, key: 'comuna', value: 'poverty',
title: 'La pobreza es más alta en las comunas del carbón',
});
</script># Entra un spec, sale un SVG. Funciona en cualquier pipeline.
npx plotagents spec.json -o chart.svg
# Enséñale a tu asistente de IA a graficar con plotagents:
npx skills add carlosnavarreteliz/plotagents
# La guía que necesita un agente, para su prompt de sistema:
curl https://carlosnavarrete.cl/plotagents/llms.txtPide un dashboard. Recibe uno bueno.
La misma idea, un nivel más arriba: el modelo enumera KPI, gráficos y filtros; dashboard() los ordena como lo haría un analista y los filtros actúan sobre todos los paneles.
- Primero las cifras. Hasta cinco KPI, calculados desde los datos, con la variación anual y una sparkline.
- Lectura en Z. La tendencia va a todo el ancho; el resto llena filas equilibradas de una grilla de 12 columnas.
- Un color por entidad en todos los gráficos, un tema, una línea de fuente.
- Filtros como botones que mueven todos los gráficos y KPI a la vez.
- Un solo archivo HTML. Funciona sin conexión, se imprime y se convierte en PDF.
dashboard({
title: '¿Cómo van las ventas del sur?',
data: sales,
kpis: [{ label: 'Ventas 2025', field: 'sales', agg: 'sum',
compare: { field: 'year', current: 2025, previous: 2024 } }],
charts: [trend, map, byChannel, treemap],
filters: ['region', 'channel'],
})