vegavisuals

vegavisuals ist eine wiederverwendbare Vega-Lite- und Roh-Vega-Visualisierungs-Factory. Es enthält ein zentrales Theme-Registry, einen Projekt-Manifest-/Lock-Vertrag, einen stdio-FastMCP-Adapter und einen Docker-Renderer basierend auf vl-convert-python==1.9.0.post1. Verbraucherprojekte benötigen weder Node, Chromium noch eine Host-Installation von Vega.

Die Host-CLI erfordert Python 3.10 oder neuer und Linux, da die Veröffentlichung descriptor-relative I/O, flock und fail-closed renameat2-Operationen verwendet. Rendering erfordert ebenfalls Docker. Linux x86_64 ist der release-getestete Host; Quellinstallationen auf anderen Linux-Architekturen erfordern kompatible Wheels für jede festgelegte Abhängigkeit.

Das Standard-Kompatibilitätsprofil ist vl-convert-1.9.0: Vega 6.2.0, Vega-Lite 6.4 standardmäßig, SVG/PNG/PDF-Ausgabe, deterministische PDF-Normalisierung mit qpdf und die explizit installierte DejaVu-Schriftfamilie. Das Basis-Image ist per Registry-Digest festgelegt. Die vollständige unterstützte Vega-Lite-Versionsmenge und die Laufzeitrichtlinie werden von vegavisuals compatibility-status bereitgestellt; die Quelldaten befinden sich in src/vegavisuals/assets/compat/vl-convert-1.9.0.json.

Quick Start

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

Der erste Renderer-Build benötigt Zugriff auf Debian- und PyPI-Repositories. Render-Container selbst laufen ohne Netzwerkzugriff und ziehen nie Images. Es wird kein vorgefertigtes Renderer-Image veröffentlicht; jede Installation baut ihr lokales Image aus dem lizenzierten Quellpaket und dem festgelegten Kompatibilitätsprofil.

Die beiden Repository-Beispiele umfassen ein Vega-Lite-Balkendiagramm mit projektlokalem CSV und ein Roh-Vega-Diagramm:

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

Rendering Boundary

Jeder Render verwendet einen festen Worker-Einstiegspunkt im Image. Das Host-Registry:

• Parst JSON selbst und lehnt doppelte Schlüssel und nicht-endliche Zahlen ab.

• Beschränkt Quell-, Daten-, Eingabe-, Manifest-, Cache-, Lock- und Ausgabepfade auf das Verbraucher-Root.

• Veröffentlicht Cache-, Lock- und Ausgabedateien über descriptor-relative, no-follow Linux-Operationen.

• Serialisiert finale Commits mit einer Projektdateisperre, tauscht bedingt exakte Dateischnappschüsse mit renameat2 aus und rollt die Ausgabe zurück, wenn die Lock-Veröffentlichung fehlschlägt.

• Verschiebt atomar jede ausgemusterte Veröffentlichungs-Inode in das Verzeichnis .cache/vegavisuals/replaced/ mit Modus 0700, sodass späte Schreibvorgänge über einen bereits geöffneten Deskriptor bis zur expliziten Cache-Bereinigung wiederherstellbar bleiben.

• Lehnt HTTP/HTTPS-Daten, Bild-, Hyperlink- und dynamische URL-Abhängigkeiten ab.

• Löst lokale Daten relativ zur Quelldatei auf und erstellt Fingerabdrücke für jede Abhängigkeit.

• Mountet das Verbraucherprojekt niemals in den Renderer.

• Mountet nur eine vorbereitete Spezifikation und gestaffelte Ausgabe in einem isolierten Host-Temporärverzeichnis unter /output:rw.

• Führt Docker mit --network none, --read-only, allen Capabilities entfernt, no-new-privileges, einer Nicht-Root-UID/GID, CPU-/Speicher-/PID-/Dateilimits und einem begrenzten tmpfs aus. Root-Aufrufer verwenden 65534:65534.

• Validiert PNG-Chunks und CRCs, normalisierte PDF-Struktur, rekursive SVG-Sicherheit und Ausgabegröße.

• Kopiert das validierte Artefakt in ein temporäres Geschwister und ersetzt atomar das Ziel vom Host aus.

Der Container kann nicht direkt in das Verbraucherprojekt veröffentlichen. Fehlgeschlagene Render lassen ein vorhandenes Ziel unberührt.

Wiederherstellungsarchive sind generierte Cache-Daten und werden nie automatisch entfernt. Untersuchen Sie sie nach einem gemeldeten Veröffentlichungskonflikt; make clean oder manuelle Cache-Entfernung ist der explizite Punkt, an dem sie verworfen werden. Die Projektsperre, verwaltete Ausgaben und .cache/vegavisuals/replaced/ müssen sich auf demselben Dateisystem befinden, damit Veröffentlichung und Wiederherstellung atomar bleiben.

Source And Data Policy

Die automatische Engine-Auswahl verwendet zuerst exakte .vl.json- und .vg.json-Suffixe, dann ein erkanntes $schema und schließlich die Vega-Lite-mark- oder Roh-Vega-marks-Struktur. Explizites --engine vega-lite oder --engine vega funktioniert auch für JSON-Quellen; ein erkanntes Suffix darf der expliziten Engine nicht widersprechen.

Dateiquellen können eine statische projektrelative data.url verwenden. Sie wird aus dem Quellverzeichnis aufgelöst, muss auf eine UTF-8-Regulärdatei innerhalb des Projekts zeigen und wird als rohe Inline-values mit ihrem deklarierten oder abgeleiteten CSV-, TSV- oder JSON-Format bereitgestellt. Dies vermeidet die file:-Loader-Mehrdeutigkeit und bewahrt gleichzeitig den eigenen Formatparser von Vega. Symlink- und ..-Ausbrüche werden abgelehnt. HTTP-, HTTPS-, protokollrelative, file:, data: und dynamische Daten-URLs werden abgelehnt. Bild- und Hyperlink-URL-Kanäle werden ebenfalls abgelehnt, sodass veröffentlichtes SVG offline bleibt.

render-text wendet dieselbe Abhängigkeitsrichtlinie an: Jeder Abhängigkeits-url- oder href-Schlüssel wird abgelehnt, sodass nur Inline-Werte akzeptiert werden. Eingabetext ist auf 1 MiB begrenzt. Sein Cache-Schlüssel umfasst Quelle, Engine, Format, Profil und Theme.

Project Manifest

.vegavisuals.yml ist ein versionierter, expliziter Projektvertrag:

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 und inputs sind optional. Eingaben ergänzen aus der Spezifikation entdeckte Datendateien und nehmen am Fingerprint teil.

.vegavisuals.lock.json verwendet Lock-Version 2. Jeder Eintrag erfasst strikt Quelle, Ausgabe, Engine, ausgewählte Vega-Lite-Version, Format, Profil, Familie, vollständigen Render-Fingerprint, Ausgabe-SHA-256, Eingaben und unveränderliche Renderer-Image-Herkunft. status meldet diese Zustände:

Der portable Fingerprint verwendet den Renderer-Vertrag, nicht die lokale Docker-Image-ID: Saubere Builds können unterschiedliche Image-Metadaten-IDs haben, während sie identische festgelegte Eingaben verwenden. Die beobachtete Image-ID bleibt als Herkunft aufgezeichnet, und das Image muss das passende Renderer-Vertragslabel tragen, bevor es rendern kann.

Frische Ausgaben werden übersprungen, es sei denn, --force wird übergeben. Vorhandene unverwaltete und modifizierte Ausgaben werden nie ersetzt, es sei denn, --replace wird ebenfalls übergeben. Dieselbe Veröffentlichungsregel gilt für direkte Datei-Render und explizite Ausgaben von render-text.

Ein ungültiges Manifest oder Lock bricht status und check ab, anstatt einen pro-Visualisierung invalid-Zustand zu erzeugen.

CLI

JSON-erzeugende Betriebsbefehle geben strukturiertes JSON zurück. Ihre Fehler geben ebenfalls JSON und einen Nicht-Null-Status zurück. Hilfe und --version verwenden normalen CLI-Text, und mcp serve spricht den MCP-stdio-Transport anstelle von JSON-Befehlsausgabe.

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

Vertragsbewusste Befehle akzeptieren auch die dokumentierten --profile-, --family-, Eingabe-, Manifest- und Veröffentlichungsrichtlinien-Optionen. Führen Sie vegavisuals COMMAND --help für die vollständige Synopsis aus.

render, render-text und render-all akzeptieren --include-data, --replace, --force und --dry-run. Inline-Artefaktdaten werden standardmäßig weggelassen. Auf Anfrage wird SVG als artifact.svg zurückgegeben; PNG und PDF werden als artifact.data_base64 zurückgegeben. Das Kompatibilitätsprofil begrenzt Artefakt- und Antwortgrößen.

validate führt strenge JSON-, Tiefen-, Zahlen-, Schema-Versions-, URL-Richtlinien- und grundlegende Vega/Vega-Lite-Strukturprüfungen durch. Es beansprucht keine vollständige JSON-Schema- oder Compiler-Validierung; der festgelegte Worker bleibt maßgeblich für die vollständige Renderer-Semantik.

Python API

Das öffentliche Paket exportiert Registry, __version__ und die typisierte Ausnahmehierarchie. Eine Registry-Instanz legt das Verbraucher-Root fest:

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()

Renderer-Lebenszyklusmethoden sind build_renderer() und ensure_renderer(). Inventarhilfsfunktionen sind profile_inventory(), factory_check() und version_status().

MCP

Das Verbraucher-Root wird einmal vor dem Start des FastMCP-Servers aufgelöst und ist kein MCP-Tool-Argument:

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

Werkzeuge:

validate_visualization
render_visualization
render_visualization_text
visualization_status
visualization_check
render_visualizations
theme_inventory
compatibility_status
factory_manifest

Ressourcen:

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

MCP-Werkzeuge bewahren den dokumentierten Wörterbuch-Ergebnisvertrag. Erwartete Richtlinien-, Validierungs- und Renderfehler sind typisierte Anwendungsergebnisse mit ok: false anstelle von MCP-Transportfehlern; Clients müssen ok prüfen.

Generieren Sie eine Client-Konfigurationsvorlage mit:

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

Der Standard-Platzhalter ist ein Literal für Clients, die ${workspaceFolder} erweitern. Ersetzen Sie ihn durch einen absoluten Verbraucherpfad, wenn der Client diese Erweiterung nicht durchführt. Verwenden Sie --command /absolute/path/to/vegavisuals, wenn die ausführbare Datei nicht im Client-PATH ist, und --format vscode-workspace für die Workspace-Form von VS Code.

Verification

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

make tests hält Docker gemockt. make docker-smoke rendert alle Formate für beide Engines und prüft die verzögerte PDF-Byte-Wiederholbarkeit. make mcp-smoke ruft beide Render-Engines über stdio auf. Die Wheel-Verifikation installiert nicht-editierbar, löst Assets aus site-packages auf und ruft beide echten Render-Engines über die installierte Wheel-MCP-ausführbare Datei auf.

Siehe CONTRIBUTING.md für Beitragsprüfungen und SECURITY.md für unterstützte Versionen und private Schwachstellenmeldung.

License

vegavisuals ist unter der GNU General Public License v3.0 only (GPL-3.0-only) lizenziert. Vega, Vega-Lite, vl-convert und die anderen Laufzeitabhängigkeiten behalten ihre ursprünglichen Lizenzen; siehe THIRD_PARTY_NOTICES.md. Copyright (C) 2026 dosquartsdedocs.

Das Aufrufen der eigenständigen CLI, des Docker-Renderers oder des MCP-Servers ändert für sich genommen nicht die Lizenz eines Verbraucherprojekts oder von generierten SVG-, PNG- und PDF-Artefakten. Anwendungen, die das Python-Paket kopieren, modifizieren, verlinken oder direkt verteilen, müssen die GPLv3-Bedingungen einhalten.