Ir al contenido
plotagents · protocolo 0.12.0MIT · cero dependencias · SVG

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.

En vivo · un modelo dibuja llamando a plotagents
Persona

Este es nuestro plan de implementación. ¿Dónde estamos y qué se podría atrasar?

Modelo → llamada a la herramienta
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",})
plotagents → modelo
{  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: []}
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 feb), Puesta en marcha (15 jun). Avance total: 35%.La puesta en marcha es el 15 de junio y la integracióncon el ERP es la ruta críticaPlan de implementación por fase, 2026. La parte rellena de cada barra es el avancePor confirmarfeb 2026mayjunEntrevistas a usuariosMapa de procesosInforme de hallazgosModelo de datosPrototipo del agenteIntegración con el ERPTablero de KPIPruebas con usuariosCapacitaciónPuesta en marchaDiagnóstico· 3Diseño· 2Desarrollo· 3Lanzamiento· 2100%100%9 feb80%45%10%0%0%15 junHoy · 12 marFuente: datos ilustrativos
Agent SkillClaude · Cursor · Codex · cualquier IA

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.

Instalar la skillplotagents-skill.zip · para la app de Claude $ npx skills add carlosnavarreteliz/plotagents
  1. Claude Code, Cursor, Codex… Corre el comando de arriba en tu terminal.
  2. App de Claude Descarga el .zip y súbelo en Configuración → Capacidades → Skills.
  3. Cualquier otra IA Pega SKILL.md en sus instrucciones.
01 · El protocolosafePlot(spec) → { ok, svg, description, errors, warnings, suggestions }

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.

01

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.

02

Revisar

safePlot nunca lanza errores. Valida contra el JSON Schema y las reglas de diseño antes de dibujar nada.

03

Corregir

Cada problema trae un fix escrito para que lo lea un modelo. Lo aplica y vuelve a llamar, casi siempre una sola vez.

04

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

Gráfico de barras de stores en 11 categorías. Mayor: Santiago con 430 (51%). Menor: Puerto Montt con 18.Santiago tiene más tiendas que las diez ciudadessiguientes juntas: 430 contra 413Tiendas por ciudad, 2025Santiago430Valparaíso96Concepción88La Serena41Antofagasta39Temuco35Rancagua30Talca26Arica21Iquique19Puerto Montt18Fuente: datos ilustrativos
02 · El vocabulario44 tipos de gráfico · schema.json

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.

04 · MapasGeoJSON · TopoJSON · URL

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. markers por longitud y latitud, layers para ríos, rutas o límites.
  • Tu encuadre. fitTo acerca 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
})
Mapa coroplético de language en 12 territorios: Español (9), Portugués (1), Inglés (1), Neerlandés (1). 12 marcadores (Capital). Capas: Trópico de Capricornio.El español es idioma oficial en 9 de los 12 países deSudaméricaPrincipal idioma oficial por país, con sus capitalesEspañolPortuguésInglésNeerlandésTrópico de CapricornioCapitalBuenos AiresSantiagoLimaBogotáBrasíliaCaracasQuitoLa PazAsunciónMontevideoParamariboVenezuelaEspañolGuyanaInglésSurinamNeerlandésColombiaEspañolEcuadorEspañolPerúEspañolBrasilPortuguésBoliviaEspañolParaguayEspañolUruguayEspañolArgentinaEspañolChileEspañolFuente: Natural Earth (dominio público)
05 · El oficioDe Fundamentals of Data Visualization de Wilke y la práctica de las salas de prensa

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.

01

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.

02

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.

03

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.

04

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.

05

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.

06

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.

06 · IntegrarAnthropic · OpenAI · cualquier entorno

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 su fix.
  • 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.

Pide 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'],
})

Que tu agente muestre, no solo cuente.