Ir al contenido

Guía para agentes de IA

Una guía breve pensada para pegarla en el prompt de sistema de un agente. El mismo texto, en inglés, está publicado como Markdown en AGENTS.md y llms.txt. Para que tu IA la siga sola, instala la Agent Skill.

Una función, un objeto JSON. Sin decisiones de diseño: la biblioteca las toma por ti.

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

Reglas para un buen gráfico

  1. title, subtitle y source son opcionales. Omítelos si la página que rodea al gráfico ya los dice. Si pones title, que sea el hallazgo, una oración completa con la cifra clave: "Biobío concentra el 30% de las ventas", no "Ventas por región". subtitle dice cómo leerlo (medida, unidad, período); source, de dónde salen los datos.
  2. Elige la forma de data según la tabla. Filas ([{ region: "Biobío", ventas: 1240 }]) sirven para pocas filas. Para muchas, escribe los nombres de campo una vez: encabezado + filas [["region", "ventas"], ["Biobío", 1240], ["Ñuble", 830]], columnas { region: ["Biobío", "Ñuble"], ventas: [1240, 830] } o texto CSV "region,ventas\nBiobío,1240". En un dashboard, pasa data una vez arriba.
  3. padding es 8 px arriba y abajo y 0 a los lados por defecto; pon un número, [vertical, horizontal] o { top, right, bottom, left } para cambiarlo.
  4. data es una lista de filas ([{ region: "Biobío", sales: 1240 }]). Para una tabla ancha, pasa y: ["revenue", "costs"].
  5. Usa safePlot(spec) como tu herramienta: nunca lanza excepciones y devuelve errors, warnings y suggestions, cada uno con un fix. Si ok es false, corrige el spec y vuelve a llamarla.
  6. Define locale: "en" para formatos numéricos en inglés (el valor por defecto es español: 1.234,5); también hay "pt", "fr", "de" o "auto" para reconocerlo a partir del texto. Las tablas lo reconocen por sí solas.

Qué tipo usar

Para mostrartypeCampos clave
Comparar categoríasbarx, y, series?, stack? (true / "percent"), top?
Contar filas por categoríacountplotx
Media por categoría con un ICbarplot o pointx, y, hue?
Cambio en el tiempolinex fecha ("2024-03") o año, y, series?; ci: true con varias observaciones por x
Un plan de proyecto o un cronogramagantttask, start, end (o duration), group?, progress?, dependsOn?, today?, collapsed?
Volumen en el tiempoareacomo line; se apila con series
La forma de una serie en una celda de tablasparkx, y, width/height de cualquier tamaño (p. ej. 108×26), fill?, series?
Una fila de una distribución en una celda de tablarailvalue, min, max, band?: [lo, hi], median?, refs?: [{ field | value, label }], clip? / domain? (pasado un extremo → chevrón); 160×18 por defecto
Quién pasó a quién en el tiempobump (slope para primero vs último)x periodo, y valor (o rank), series, top?, ends?: "first-last"
Medidas en escalas distintasline + index: true, o facetno hay doble eje
Crecimiento exponencialline + yScale: "log"
Relación entre dos medidasregplot (ajuste + IC) / scatter / bubblex, y, hue?, size?, label?
Relación + marginalesjointplotx, y
Qué medidas se mueven juntascorr (correlation)vars? (por defecto: todos los campos numéricos), method? ("spearman"), alpha?: 0.05; cluster: true o type: "clustermap" las agrupa con un dendrograma
Todos los pares de medidas a la vezpairplot (splom)vars (3–6), hue?, corner?, kind?: "reg"
Distribución de una medidahist (kde: true), kde, ecdfx, hue?
Distribución por categoríabox, violin, strip, swarmx categoría, y medida, hue?
Una distribución en que cada cosa sigue siendo unadotplotx, bin?, label?, series?, highlight?, ticks?: [[valor, rótulo]]
Perfil multidimensionalradaraxis, value, series (≤ 4 series)
Parte de un todo jerárquicotreemap o sunburstpath: [level1, level2, …], value
Parte de un todo, ≤ 6 partesdonut / pielabel, value; half: true para un semicírculo
Magnitud en una grillaheatmapx, y, value
Una cuenta como número de cosaswaffleseries, value? (o un cuadro por fila), columns?, unit?
Cómo se agrupan las cosas, y a qué alturadendrogramfilas id, parent, heightField? o linkage + labels; cut?, clusters?
Un valor por región, estado o paíschoropleth (symbolmap para totales)geo: "chile" | "usa" | "world" o cualquier objeto GeoJSON/TopoJSON, key, value (texto → un color por categoría)
Puntos en lugares reales sobre un mapa de callespointmaplon, lat (se detectan solos), size?, hue?, value?, label?; tiles: "osm" (por defecto) / "esri-gray" / "esri-dark", o carto-* / mapbox-* con tilesKey
Quién se conecta con quiénnetworkaristas from, to, value?; nodes? con group; layout?
Intercambios entre pocos gruposchordfrom, to, value
Estructura por edadpyramidage, sex, value
Un proceso con decisionesflowchartnodes (type, lane), edges (label)
Flujos entre etapassankeyfrom, to, value
Una o más cifraskpiitems: [{ label, value, delta, period, trend, target, good }]
Valores exactos para consultartablecolumns?: [field | { field, type, label, format, good, target }], sortBy?, total?, group?; los tipos bar, delta, heat, sparkline, progress, badge y check se infieren cuando se omiten
Lo que más aparece en un textowordcloudtext (campo o texto sin procesar), value?, series?; para comparar con exactitud, prefiere bar + top

Los nombres de seaborn funcionan (histplot, kdeplot, boxplot, violinplot, lmplot, stripplot, swarmplot, pointplot), y hue es un alias de series. Omite type para que se infiera de los datos.

Opciones más útiles

  • highlight: "Ñuble": destaca una categoría o serie y atenúa el resto. exclude: ["Maule"] quita entradas y recalcula el gráfico; los colores no cambian.
  • legend: "top" | "bottom" | "left" | "right" | false: dónde va la leyenda (arriba por defecto).
  • colorScale: "viridis": cualquier mapa de colores de matplotlib para mapas de calor, mapas y treemaps por variación ("RdBu" diverge en torno a 0; _r lo invierte; también sirve una lista de colores). palette: "tab10" para categorías.
  • palette: "nordico": una familia de paletas minimalista (arcilla, nordico, tinta: cinco colores apagados, desde la 6ª serie va gris; cdia es la de fábrica): colores validados y rampas a juego, con variante oscura bajo theme: "noche". palettes: ["cdia", "arcilla", "nordico", "tinta"] (o true) escribe las alternativas en un mismo SVG; data-palette="nordico" en cualquier ancestro cambia la que se ve, y toHTML agrega los botones.
  • dashed para lo que no es una cifra firme (estimaciones, proyecciones, cifras provisionales): un nombre, una lista o un campo de los datos (dashed: "provisional"). Las formas mantienen su color, con relleno achurado y contorno discontinuo. En un eje de tiempo, dashedFrom: 2025 dibuja con trazo discontinuo las líneas, áreas y columnas desde ese año. Define siempre dashedLabel ("Proyección", "Preliminar") para que los lectores sepan qué significa el achurado.
  • facet: "region" (+ columns): un panel por valor, con una escala compartida.
  • time: "year": un período a la vez (el más reciente) con la variación % respecto del anterior. Los controles de tiempo están desactivados por defecto: agrega slider: true solo cuando la persona pida recorrer los períodos (botones para ≤ 8 períodos y un deslizador mínimo en los demás casos; "buttons" / "slider" fuerzan uno de los dos, play: false oculta el botón de reproducir). Los treemaps se pueden colorear por variación con colorBy: "change".
  • refLines: [{ y: 600, label: "Target" }] y annotations: [{ x: "2024-01", label: "New branch" }].
  • format: "percent" | "currency" | "compact" | "integer" o { prefix, suffix, decimals }.
  • xScale / yScale: "log".
  • table: dale un título que enuncie el hallazgo, como a cualquier gráfico. Con más de 15 filas se pagina de a diez (pageSize), en teléfonos cada fila se muestra como una tarjeta y el navegador agrega orden, búsqueda y paginación. Usa good: "down" en los costos para que ▲ se vuelva rojo, progress con target: "budget" para el gasto frente al presupuesto y total: true para una fila de totales. Usa entre 4 y 7 columnas.
  • theme: "noche" o un objeto JSON ({ extends, categorical, type, marks, font }); palette: [...] para tus propios colores.
  • font: "Poppins" y textScale: 1.5 (modo presentación); configure({ font, textScale }) los define para todos los gráficos.
  • network + focus: "node id": centra un nodo y destaca sus vecinos.
  • Tu propio mapa: geo: <GeoJSON or TopoJSON>; la propiedad que coincide se busca sola (featureKey para forzarla). Agrega markers: [{ lon, lat, label }], layers: [{ geo, label }] para ríos o rutas, y fitTo: ["Biobío"] o una caja [lonMin, latMin, lonMax, latMax] para hacer zoom.
  • Mapas para un sitio estático: geo: { paths: { id: "M…Z" } } recibe contornos ya proyectados (no corre proyección); views: [{ id, label, value }, …] mete varias lecturas de una geometría en un SVG (se cambia con data-view, plotagents/views); pathPrecision: 1, simplify: 0.5 achican los trazos; fitTo: "mainland" deja fuera islas lejanas; microstates: true dibuja Singapur o Malta como puntos; los países calzan también por ISO-2.
  • gantt: las fechas end por día son inclusivas; una fila sin end es un hito. Define siempre today en un plan en curso. collapsed: ["Phase 2"] (o true) pliega las fases en una barra resumen; en el navegador, un clic en una fase la abre o la cierra.
  • network + layout: "force" | "circular" | "radial" | "concentric" | "clusters" | "tree" | "grid" elige la disposición; curveness: 0 endereza las aristas.
  • pointmap dibuja sobre teselas de OpenStreetMap por defecto (tiles: "esri-gray", "mapbox-light" + tilesKey, o tus propias { url, attribution }). Las teselas solo se cargan cuando el SVG va incrustado en la página o en toHTML, no dentro de <img>.
  • Tu propio estilo para todos los gráficos: registerTheme("acme", { background, text, grid: { color, dash }, categorical: "tab10", font }) y luego configure({ theme: "acme" }).
  • geo: "usa": los estados coinciden por código postal ("TX"), nombre en inglés o en español, o código FIPS ("48"). Alaska y Hawái aparecen en recuadros; Puerto Rico aparece solo cuando tus datos lo incluyen. En el navegador, los mapas hacen zoom con un clic, con Ctrl/⌘ + rueda o pellizcando.

Errores que la biblioteca ya resuelve

  • Más de 8 series → de la 9.ª en adelante se pintan en gris; lint sugiere highlight o facet.
  • Etiquetas de líneas que chocan → se separan con líneas guía.
  • Dona con más de 6 partes → el resto se agrupa en "Otros".
  • Etiquetas de categoría largas → el gráfico pasa a horizontal.
  • Paleta propia difícil de distinguir → lint nombra el par problemático.
  • Números como texto ("1.234,5", "12%", "$ 3.000") → se interpretan automáticamente.
  • Decenas de miles de puntos → se dibujan como trazados agrupados y sigue siendo rápido.
  • Categorías vacías (null, "") → van juntas en "(sin dato)" / "(no data)", nunca como "null".

Tableros

Cuando alguien pida un dashboard, llama a safeDashboard({ title, subtitle, source, data, kpis, charts, filters }) (herramienta: toolDefinition({ kind: 'dashboard' })). La disposición, los anchos, los colores compartidos y los filtros se deciden por ti:

  • title es la pregunta que responde el tablero; el título de un gráfico, si lo pones, dice su hallazgo.
  • Como máximo 5 KPI, calculados a partir de data cuando sea posible: { label, field, agg: "sum", compare: { field: "year", current: 2025, previous: 2024 }, trendBy: "month" }.
  • De 4 a 6 gráficos. La primera serie de tiempo (o la que tenga primary: true) va a todo el ancho; el resto llena filas equilibradas.
  • filters: ["region", "channel"] se convierten en botones que filtran todos los gráficos y KPI.
  • No más de una dona; una sola source para la página.

Salidas

  • plot(spec) → cadena SVG. Insértala en HTML, Markdown, un archivo .svg o un PDF.
  • toHTML([spec1, spec2]) → página autocontenida con tooltips, deslizadores y drill-down.
  • describe(spec) → texto alternativo del gráfico.
  • schema / toolDefinition() → JSON Schema y definición de herramienta (Anthropic u OpenAI).
  • CLI: npx plotagents spec.json -o chart.svg.

Editar esta página en GitHub