Zum Inhalt

Architektur

Der Chart-Generator ist als modulare Python-Anwendung mit klar getrennten Schichten aufgebaut. Im Zentrum steht ein dreistufiger Service-Layer, der eine Nutzeranfrage in aufeinanderfolgenden Schritten in einen ausführbaren Visualisierungs-Code überführt. Datenhaltung erfolgt sitzungsbezogen im Arbeitsspeicher; die Bereitstellung kann lokal, hinter einem Reverse-Proxy oder in einem Container erfolgen.

Auf einen Blick

  • Vier Schichten: Benutzeroberfläche, Service-Layer, fachliche Komponenten (Daten, Charts, LLM, Sitzungen) und Konfiguration.
  • Dreistufige agentische Pipeline: Intent-Erkennung, Plan-Erstellung, Ausführung.
  • Zustand wird ausschließlich sitzungsbezogen im Arbeitsspeicher gehalten (DataFrames serialisiert, Charts als Pickle).
  • Generierter Code wird in einer Sandbox mit eingeschränkten Builtins ausgeführt.
  • Externer LLM-Endpoint (OpenAI-kompatibles Protokoll), pro Anfrage ein bis fünf API-Aufrufe.
  • Konfiguration vollständig über Umgebungsvariablen; Reverse-Proxy-Pfad konfigurierbar.
  • Containerbasierter Betrieb über ein einfaches Python-Image möglich.

Architekturbeschreibung

Schichten und Verantwortlichkeiten

Die Benutzeroberfläche basiert auf Gradio und stellt Datei-Upload, Sheet-Auswahl, Chat-Eingabe, Chart-Anzeige, History-Liste, Theme-Umschaltung sowie Export-Schaltflächen bereit. Sie ruft ausschließlich den Service-Layer auf und enthält keine LLM-Logik.

Der Service-Layer ist das zentrale Architekturelement. Er besteht aus drei spezialisierten Diensten: Der Intent-Service klassifiziert die Anfrage in eine von vier Aktionen (Erstellung einzeln, Erstellung mehrfach, Modifikation, reine Analyse). Der Plan-Service erstellt aus dem Intent und den verfügbaren Metadaten einen Ausführungsplan, der Chart-Typ, Spalten, Aggregation und Modifikationsschritte festlegt. Der Execution-Service setzt den Plan um, validiert den generierten Code und kümmert sich um Retry und Fallback.

Die fachlichen Komponenten kapseln einzelne Verantwortlichkeiten: Der DataFrame-Manager lädt und optimiert CSV/Excel-Dateien und extrahiert Metadaten. Der LLM-Orchestrator stellt die Verbindung zum Sprachmodell-Endpoint her und enthält die Prompts für Code-Generierung und Fehlerkorrektur. Der Chart-Generator führt den Code in einer Sandbox aus, steuert die Retry-Logik und kann auf eine Seaborn-Variante zurückfallen. Der Interactivity-Enhancer reichert die Plotly-Figur mit einheitlichen Layout-, Hover- und Theme-Einstellungen an. Der Session-Manager verwaltet pro Sitzung DataFrames, Metadaten, aktuellen Chart und Chart-Historie.

Die Konfigurationsschicht lädt sämtliche Parameter aus Umgebungsvariablen und validiert sie beim Start; sie ist in fünf Konfigurationsklassen für LLM, Daten, Charts, Benutzeroberfläche und Export gegliedert.

Workflow

flowchart TD
    User([Nutzer]) -->|Datei-Upload| UI[Gradio-UI]
    User -->|Eingabe in natürlicher Sprache| UI

    UI -->|Datei| DM[DataFrame-Manager]
    DM -->|optimierte DataFrames + Metadaten| SM[Session-Manager]

    UI -->|Anfrage + Kontext| IS[Intent-Service]
    IS -->|Intent + Konfidenz| PS[Plan-Service]
    PS -->|Ausführungsplan| ES[Execution-Service]

    IS -.->|Klassifikation| LLM[(LLM-Endpoint)]
    PS -.->|Planung| LLM
    ES -.->|Code-Generierung / Fehlerkorrektur| LLM

    ES -->|Code| CV[Code-Validator]
    CV -->|geprüfter Code| CG[Chart-Generator]
    CG -->|Sandbox-Ausführung| FIG{Erfolg?}

    FIG -->|nein, < max Retries| ES
    FIG -->|nein, max Retries erreicht| SB[Seaborn-Fallback]
    FIG -->|ja| EN[Interactivity-Enhancer]
    SB --> EN

    EN -->|finaler Chart| SM
    SM -->|Anzeige + History| UI
    UI -->|HTML / PNG| Export[(Export-Verzeichnis)]

Der Datenfluss verläuft in zwei Phasen. In der Upload-Phase lädt der DataFrame-Manager die Datei, erkennt Spaltentypen, optimiert den Speicherverbrauch und legt DataFrame und Metadaten in der Sitzung ab. Anschließend werden, sofern aktiviert, Chart-Empfehlungen vom LLM erzeugt und im Chat angezeigt.

In der Anfrage-Phase wird die Eingabe zunächst vom Intent-Service klassifiziert. Der Plan-Service erstellt darauf aufbauend einen Ausführungsplan; bei Mehrfacherstellung enthält der Plan einen Schritt pro Tabellenblatt. Der Execution-Service generiert je Schritt Plotly-Express-Code, lässt ihn vom Code-Validator prüfen und übergibt ihn zur Ausführung. Schlägt die Ausführung fehl, wird der Fehler an den LLM zurückgegeben und der Code in bis zu drei Iterationen überarbeitet. Erst wenn auch das scheitert, greift der Seaborn-basierte Fallback. Die fertige Figur wird vom Interactivity-Enhancer mit einheitlichem Layout, Theme und Modebar versehen und in der Sitzung als aktueller Chart sowie in der History (maximal zehn Einträge) abgelegt.

Modifikationsanfragen folgen demselben Schema, verwenden jedoch den vorhandenen Chart-Code als Basis und ändern nur den vom Nutzer benannten Aspekt. Reine Analyseanfragen erzeugen keine Visualisierung, sondern ausschließlich einen Empfehlungstext.

Rolle des Sprachmodells

Der LLM ist an drei Stellen eingebunden: in der Intent-Klassifikation (niedrige Temperatur, JSON-Ausgabe, Trigger-Wort-Bibliothek im Prompt), in der Plan-Erstellung (mit Mustervorlagen und Anti-Mustern aus der Pattern-Bibliothek) und in der Code-Generierung beziehungsweise Fehlerkorrektur. Die Kommunikation läuft über ein OpenAI-kompatibles Protokoll; Antworten werden in den Klassifikations- und Plan-Schritten als JSON erwartet und beim Parsing tolerant gegenüber Markdown-Codefences behandelt. Das System ist auf einen extern bereitgestellten, intern erreichbaren Endpoint ausgelegt, ein Standard-LLM-Anbieter ist nicht erforderlich.

Robustheit und Sicherheit

Mehrere Mechanismen sichern die Robustheit der Verarbeitung: Validierung der Konfiguration beim Start, Limits für Dateigröße sowie Zeilen- und Spaltenanzahl, Begrenzung der API-Aufrufe pro Anfrage, Timeout für LLM-Aufrufe, Sandbox-Ausführung des generierten Codes (eingeschränkte Builtins, kein Import möglich, kontrollierte Globals), semantische Validierung des Codes vor Ausführung sowie eine mehrstufige Fallback-Kette. Logging dokumentiert jeden Schritt der Pipeline; Fehler in einzelnen Sheets bei Mehrfacherstellung führen nicht zum Abbruch der Gesamtanfrage.

Konfiguration und Bereitstellung

Sämtliche Parameter werden aus Umgebungsvariablen geladen und beim Start validiert. Konfiguriert werden unter anderem LLM-Endpoint und Modellname, maximale Dateigröße, Zeilen- und Spaltengrenzen, Retry- und API-Aufruf-Anzahl, Default-Theme, Chart-Größen, Export-Verzeichnis sowie Server-Adresse, Server-Port und ein optionaler Reverse-Proxy-Pfad. Die Anwendung lässt sich direkt mit Python starten oder in einem schlanken Container betreiben; das Export-Verzeichnis wird beim Start automatisch angelegt.

Technologie-Übersicht

  • Sprache und Laufzeit: Python 3.10+.
  • Benutzeroberfläche: Gradio.
  • Datenverarbeitung: Pandas, NumPy, openpyxl, xlrd.
  • Visualisierung: Plotly Express und Plotly Graph Objects (primär), Matplotlib und Seaborn (Fallback), Kaleido (PNG-Export).
  • LLM-Anbindung: OpenAI Python-Bibliothek gegen einen OpenAI-kompatiblen Endpoint.
  • Konfiguration: python-dotenv, Umgebungsvariablen.
  • Persistenz: Sitzungsbasiert im Arbeitsspeicher (Pickle plus Base64 für DataFrames und Figuren).
  • Bereitstellung: Lokal, containerisiert (schlankes Python-Image) oder hinter einem Reverse-Proxy.