vega-for-agents: Vega y Vega-Lite sin nombres inventados

En resumen — vega-for-agents es la referencia de Vega y Vega-Lite para agentes de IA. Cada nombre válido — mark, canal de encoding, transform, tipo de escala, proyección y propiedad — sale del JSON Schema oficial de cada lenguaje, no de lo que el modelo recuerda. Es MIT y está en pre-release: los catálogos y los checks ya funcionan; las skills y el plugin todavía son borradores.

El problema: un spec que parece correcto

Si escribes specs de Vega-Lite con un agente — para Deneb en Power BI o para cualquier otro sitio —, ya viste el fallo típico. El spec se ve bien, el JSON es válido y aun así no dibuja nada, porque el agente usó una propiedad que no existe en esa versión o mezcló la sintaxis de Vega con la de Vega-Lite.

El agente no lo hace por descuido. Cuando le falta un dato, lo rellena con algo plausible. Y Vega tiene mucha superficie donde algo plausible no existe.

Es el mismo hueco que cubre dax-for-agents para DAX, con la misma regla: un agente nunca lee un nombre que no salió de la fuente de verdad. En Vega y Vega-Lite esa fuente es el schema publicado de cada lenguaje.

Cuatro catálogos, elegidos por el $schema

Vega 6 y Vega-Lite 6 son la versión por defecto. Los catálogos v5 se quedan a propósito: Deneb en Power BI y muchos specs publicados siguen declarando $schema v5, y un agente que escribe para ellos tiene que consultar el catálogo v5.

El script check_repo.py elige el catálogo a partir del $schema de cada spec. Un spec sin $schema, o con una versión mayor que no conoce, falla en lugar de adivinarse.

El check que hace cumplir la regla

check_repo.py es el check obligatorio del repositorio (Validate). Falla si algo que va a leer un agente — una ficha o un spec de ejemplo — usa un mark, canal, transform, tipo de escala, proyección o propiedad estructural que no está en el schema que nombra su $schema.

Este spec pasa, porque bar es un mark de Vega-Lite v6:

{
"$schema": "https://vega.github.io/schema/vega-lite/v6.json",
"mark": "bar"
}

Este no, porque barra no está en el schema, y Validate falla:

{
"$schema": "https://vega.github.io/schema/vega-lite/v6.json",
"mark": "barra"
}

Cada schema queda fijado por SHA-256 en el bloque meta de su catálogo, y los v6 registran además la versión exacta: Vega 6.4.0 y Vega-Lite 6.4.3. Cambiar un schema es una extracción nueva, nunca una edición a mano.

Expresiones y event streams, desde el código de Vega

El schema escribe una expresión ("update": "…") y un selector de eventos ("events": "…") como texto libre, así que ninguno de los dos vocabularios puede salir de él. Salen del código fuente de Vega, fijado en la versión 6.4.0 con un SHA-256 por archivo:

• Funciones de expresión: del registro de funciones de vega-functions y vega-expression, con las firmas y categorías de la página de documentación.
• Event streams: del parser de vega-event-selector.

Las fichas se generan desde esos catálogos, no se escriben a mano. Validate falla si un archivo copiado ya no coincide con su SHA, si un spec llama una función de expresión que Vega no tiene o si un selector de eventos no se puede interpretar. Como las expresiones de Vega-Lite se compilan a expresiones de Vega, la misma lista vale para las dos.

Las trampas, con identificador propio

La versión v0.2.0 adoptó 11 trampas de Vega y Vega-Lite en un catálogo aparte, adopted-traps.catalog.json. Cada una tiene un id estable, un síntoma, una causa, un arreglo y el estado de su deduplicación contra los borradores. La misma versión corrigió tres afirmaciones de esas trampas al contrastarlas con Vega 6.4.0 y Vega-Lite 6.4.3: una trampa también se mide.

Cómo se prueba hoy

Para probarlo, el README indica agregar el marketplace del repositorio dentro de Claude Code:

/plugin marketplace add CSalcedoDataBI/vega-for-agents

Y después instalar vega-for-agents desde ese marketplace.

Si lo que quieres son los catálogos como datos, el README recomienda fijar una etiqueta de versión vX.Y.Z en lugar de seguir main, copiar exports/ de esa etiqueta y comprobar cada archivo con el SHA-256 que trae exports/manifest.json.

Lo que no es

• No es la capa de autoría de Deneb. pbiFormat, las plantillas y el cross-filter de Power BI viven aparte, en un repositorio privado. Este plugin cubre el lenguaje — Vega y Vega-Lite —, no el oficio de Deneb.
• No es un tutorial. Es una referencia que un agente consulta, no un curso de gráficos.
• No ejecuta ni renderiza specs. Eso lo hace el motor de Vega.

Si escribes Deneb, esto encaja con la guía completa de Deneb: la guía te dice qué hacer en Power BI y el catálogo evita que el agente escriba un nombre que Vega no conoce.

El código es MIT. Los archivos copiados de Vega son © University of Washington Interactive Data Lab, con su licencia BSD-3-Clause.

→ github.com/CSalcedoDataBI/vega-for-agents · Todos los plugins: Plugins para agentes