vegavisuals

vegavisuals es una fábrica reutilizable de visualizaciones Vega-Lite y Vega en bruto. Incluye un registro central de temas, un contrato de manifiesto/bloqueo de proyecto, un adaptador stdio FastMCP y un renderizador Docker basado en vl-convert-python==1.9.0.post1. Los proyectos consumidores no necesitan Node, Chromium ni una instalación de Vega en el host.

La CLI del host requiere Python 3.10 o superior y Linux, porque la publicación utiliza E/S relativa a descriptores, flock y operaciones renameat2 con cierre ante fallos. El renderizado también requiere Docker. Linux x86_64 es el host probado para lanzamientos; las instalaciones desde el código fuente en otras arquitecturas Linux requieren ruedas compatibles para cada dependencia fijada.

El perfil de compatibilidad predeterminado es vl-convert-1.9.0: Vega 6.2.0, Vega-Lite 6.4 por defecto, salida SVG/PNG/PDF, normalización determinista de PDF con qpdf y la familia de fuentes DejaVu instalada explícitamente. La imagen base está fijada por digest del registro. El conjunto completo de versiones de Vega-Lite compatibles y la política de ejecución se exponen mediante vegavisuals compatibility-status; los datos fuente están en src/vegavisuals/assets/compat/vl-convert-1.9.0.json.

Inicio rápido

git clone https://github.com/dosquartsdedocs/vegavisuals.git
cd vegavisuals
python3 -m pip install '.[mcp]'
vegavisuals build-renderer

vegavisuals --project /path/to/consumer validate charts/summary.vl.json
vegavisuals --project /path/to/consumer render \
  charts/summary.vl.json public/summary.svg
vegavisuals --project /path/to/consumer render-all
vegavisuals --project /path/to/consumer check

La primera compilación del renderizador necesita acceso a los repositorios de Debian y PyPI. Los contenedores de renderizado se ejecutan sin acceso a la red y nunca descargan imágenes. No se publica ninguna imagen de renderizador precompilada; cada instalación compila su imagen local a partir del paquete fuente con licencia y del perfil de compatibilidad fijado.

Los dos ejemplos del repositorio cubren un gráfico de barras Vega-Lite con CSV local del proyecto y un gráfico Vega en bruto:

vegavisuals render examples/vega-lite/bar.vl.json dist/examples/bar.svg
vegavisuals render examples/vega/raw.vg.json dist/examples/raw-vega.svg

Related MCP server: nyyon-figures

Límite de renderizado

Cada renderizado utiliza un punto de entrada de trabajador fijo en la imagen. El registro del host:

• Analiza el JSON por sí mismo y rechaza claves duplicadas y números no finitos.

• Confina las rutas de origen, datos, entrada, manifiesto, caché, bloqueo y salida a la raíz del consumidor.

• Publica archivos de caché, bloqueo y salida mediante operaciones Linux relativas a descriptores y sin seguimiento de enlaces.

• Serializa las confirmaciones finales con un bloqueo de archivo del proyecto, intercambia condicionalmente instantáneas de archivos exactas con renameat2 y revierte la salida si falla la publicación del bloqueo.

• Mueve atómicamente cada inodo de publicación retirado al directorio .cache/vegavisuals/replaced/ con modo 0700, de modo que las escrituras tardías a través de un descriptor ya abierto sigan siendo recuperables hasta la limpieza explícita de la caché.

• Rechaza dependencias de datos, imágenes, hipervínculos y URL dinámicas HTTP/HTTPS.

• Resuelve los datos locales en relación con el archivo fuente y calcula la huella de cada dependencia.

• Nunca monta el proyecto del consumidor en el renderizador.

• Monta solo una especificación preparada y una salida en etapas en un directorio temporal aislado del host en /output:rw.

• Ejecuta Docker con --network none, --read-only, todas las capacidades eliminadas, no-new-privileges, un UID/GID no root, límites de CPU/memoria/PID/archivos y un tmpfs acotado. Los llamadores root usan 65534:65534.

• Valida los fragmentos PNG y los CRC, la estructura PDF normalizada, la seguridad recursiva de SVG y el tamaño de la salida.

• Copia el artefacto validado a un archivo hermano temporal y reemplaza atómicamente el destino desde el host.

El contenedor no puede publicar directamente en el proyecto del consumidor. Los renderizados fallidos dejan intacto un destino existente.

Los archivos de recuperación son datos de caché generados y nunca se eliminan automáticamente. Inspecciónalos después de un conflicto de publicación notificado; make clean o la eliminación manual de la caché es el punto explícito en el que se descartan. El bloqueo del proyecto, las salidas gestionadas y .cache/vegavisuals/replaced/ deben residir en el mismo sistema de archivos para que la publicación y la recuperación sigan siendo atómicas.

Política de origen y datos

La selección automática del motor utiliza primero los sufijos exactos .vl.json y .vg.json, luego un $schema reconocido y finalmente la estructura de mark de Vega-Lite o marks de Vega en bruto. Los motores explícitos --engine vega-lite o --engine vega también funcionan para fuentes JSON; un sufijo reconocido no puede contradecir el motor explícito.

Las fuentes de archivo pueden usar un data.url estático relativo al proyecto. Se resuelve desde el directorio de origen, debe resolverse a un archivo regular UTF-8 dentro del proyecto y se prepara como values en línea sin procesar con su formato CSV, TSV o JSON declarado o inferido. Esto evita la ambigüedad del cargador file: mientras se conserva el analizador de formato propio de Vega. Se rechazan los escapes de enlaces simbólicos y ... Se rechazan las URL HTTP, HTTPS, relativas a protocolo, file:, data: y las URL de datos dinámicas. También se rechazan los canales de URL de imágenes e hipervínculos para que el SVG publicado permanezca sin conexión.

render-text aplica la misma política de dependencias: se rechaza cada clave url o href de dependencia, por lo que solo se aceptan valores en línea. El texto de entrada está limitado a 1 MiB. Su clave de caché incluye origen, motor, formato, perfil y tema.

Manifiesto del proyecto

.vegavisuals.yml es un contrato de proyecto explícito y versionado:

version: 1
profile: vl-convert-1.9.0
family: benizar
visualizations:
  - name: quarterly-bars
    source: charts/quarterly.vl.json
    output: public/quarterly.svg
    engine: vega-lite
    format: svg
    inputs:
      - charts/data/quarterly.csv
  - name: raw-overview
    source: charts/overview.vg.json
    output: public/overview.pdf

engine, format e inputs son opcionales. Los inputs complementan los archivos de datos descubiertos a partir de la especificación y participan en la huella.

.vegavisuals.lock.json usa la versión de bloqueo 2. Cada entrada registra estrictamente el origen, la salida, el motor, la versión seleccionada de Vega-Lite, el formato, el perfil, la familia, la huella completa del renderizado, el SHA-256 de la salida, los inputs y la procedencia inmutable de la imagen del renderizador. status informa estos estados:

La huella portátil utiliza el contrato del renderizador, no el ID de la imagen Docker local: las compilaciones limpias pueden tener diferentes IDs de metadatos de imagen mientras usan inputs fijados idénticos. El ID de imagen observado permanece registrado como procedencia, y la imagen debe llevar la etiqueta de contrato del renderizador correspondiente antes de poder renderizar.

Las salidas frescas se omiten a menos que se pase --force. Las salidas existentes no gestionadas y modificadas nunca se reemplazan a menos que también se pase --replace. La misma regla de publicación se aplica a los renderizados directos de archivos y a las salidas explícitas de render-text.

Un manifiesto o bloqueo inválido aborta status y check en lugar de producir un estado invalid por visualización.

CLI

Los comandos operativos que producen JSON devuelven JSON estructurado. Sus errores también devuelven JSON y un estado distinto de cero. La ayuda y --version usan texto CLI normal, y mcp serve habla el transporte stdio de MCP en lugar de la salida JSON de comandos.

vegavisuals [--project ROOT] version
vegavisuals [--project ROOT] profile-inventory
vegavisuals [--project ROOT] theme-inventory [--family FAMILY]
vegavisuals [--project ROOT] compatibility-status [--profile PROFILE]
vegavisuals [--project ROOT] factory-check
vegavisuals [--project ROOT] validate SOURCE [--engine auto|vega-lite|vega] [--input PATH]
vegavisuals [--project ROOT] render SOURCE OUTPUT [--format svg|png|pdf] [--name NAME]
vegavisuals [--project ROOT] render-text [--text JSON] [--output PATH]
vegavisuals [--project ROOT] status [--manifest .vegavisuals.yml]
vegavisuals [--project ROOT] check [--manifest .vegavisuals.yml]
vegavisuals [--project ROOT] render-all [--manifest .vegavisuals.yml]
vegavisuals [--project ROOT] factory-manifest
vegavisuals [--project ROOT] build-renderer [--profile PROFILE]
vegavisuals [--project ROOT] ensure-renderer [--profile PROFILE]
vegavisuals [--project ROOT] mcp serve
vegavisuals [--project ROOT] mcp client-config
vegavisuals [--project ROOT] mcp list-tools

Los comandos conscientes del contrato también aceptan las opciones documentadas --profile, --family, de entrada, manifiesto y política de publicación. Ejecuta vegavisuals COMMAND --help para el resumen completo.

render, render-text y render-all aceptan --include-data, --replace, --force y --dry-run. Los datos de artefactos en línea se omiten por defecto. Cuando se solicitan, el SVG se devuelve como artifact.svg; PNG y PDF se devuelven como artifact.data_base64. El perfil de compatibilidad limita los tamaños de artefactos y respuestas.

validate realiza comprobaciones estrictas de JSON, profundidad, numéricas, de versión de esquema, de política de URL y estructurales básicas de Vega/Vega-Lite. No afirma una validación completa de JSON Schema o del compilador; el trabajador fijado sigue siendo la autoridad para la semántica completa del renderizador.

API de Python

El paquete público exporta Registry, __version__ y la jerarquía de excepciones tipadas. Una instancia de Registry fija la raíz del consumidor:

from vegavisuals import Registry

registry = Registry("/path/to/consumer")
registry.validate_visualization("charts/chart.vl.json")
registry.render_visualization("charts/chart.vl.json", "public/chart.svg")
registry.render_visualization_text(spec_json, output_format="png")
registry.visualization_status()
registry.visualization_check()
registry.render_visualizations()
registry.theme_inventory()
registry.compatibility_status()
registry.factory_manifest()

Los métodos del ciclo de vida del renderizador son build_renderer() y ensure_renderer(). Los ayudantes de inventario son profile_inventory(), factory_check() y version_status().

MCP

La raíz del consumidor se resuelve una vez antes de que el servidor FastMCP se inicie y no es un argumento de herramienta MCP:

vegavisuals --project /path/to/consumer mcp serve

Herramientas:

validate_visualization
render_visualization
render_visualization_text
visualization_status
visualization_check
render_visualizations
theme_inventory
compatibility_status
factory_manifest

Recursos:

vegavisuals://agent-guide
vegavisuals://themes
vegavisuals://compatibility
vegavisuals://project/status
vegavisuals://project/check
vegavisuals://factory-manifest

Las herramientas MCP preservan el contrato de resultado de diccionario documentado. Los fallos esperados de política, validación y renderizado son resultados de aplicación tipados con ok: false en lugar de errores de transporte MCP; los clientes deben inspeccionar ok.

Genera una plantilla de configuración de cliente con:

vegavisuals mcp client-config --workspace-placeholder '${workspaceFolder}'

El marcador de posición predeterminado es un literal para clientes que expanden ${workspaceFolder}. Reemplázalo con una ruta absoluta del consumidor cuando el cliente no realice esa expansión. Usa --command /absolute/path/to/vegavisuals cuando el ejecutable no esté en el PATH del cliente, y --format vscode-workspace para la forma de espacio de trabajo de VS Code.

Verificación

python3 -m pip install -e '.[mcp,dev]'
make check
make tests
make tests-install
make docker-smoke
make mcp-smoke

make tests mantiene Docker simulado. make docker-smoke renderiza todos los formatos para ambos motores y comprueba la repetibilidad retardada de bytes PDF. make mcp-smoke llama a ambos motores de renderizado a través de stdio. La verificación de la rueda instala de forma no editable, resuelve los activos desde site-packages e invoca ambos motores de renderizado reales a través del ejecutable MCP de la rueda instalada.

Consulta CONTRIBUTING.md para las comprobaciones de contribución y SECURITY.md para las versiones compatibles y la notificación privada de vulnerabilidades.

Licencia

vegavisuals está licenciado bajo la Licencia Pública General de GNU v3.0 solamente (GPL-3.0-only). Vega, Vega-Lite, vl-convert y las demás dependencias de ejecución conservan sus licencias originales; consulta THIRD_PARTY_NOTICES.md. Copyright (C) 2026 dosquartsdedocs.

Invocar la CLI independiente, el renderizador Docker o el servidor MCP no cambia por sí mismo la licencia de un proyecto consumidor ni de los artefactos SVG, PNG y PDF generados. Las aplicaciones que copien, modifiquen, enlacen o distribuyan directamente el paquete Python deben cumplir los términos de la GPLv3.