Dialogsteuerung in Python über JSON-Konfiguration

# Verwaltung mehrstufiger Dialoge in Python mit JSON-Konfigurationen

Die Erstellung von Umfragen, Onboarding-Abläufen und komplexen Assistenten führt oft zu einer Anhäufung bedingter Logik, die schwer zu warten und zu skalieren ist. Die dialog-engine-Bibliothek bietet eine deklarative Alternative: Dialogstruktur, Sichtbarkeitsregeln für Felder und Navigation werden in JSON oder YAML definiert. Die Engine berechnet automatisch die verfügbaren Schritte basierend auf dem Sitzungskontext und macht verschachtelte Konstrukte für jedes Szenario überflüssig.

Deklarativer Ansatz zum Erstellen von Assistenten

Traditionelle Implementierungen mehrstufiger Formulare erfordern explizite Zustandsverwaltung. Entwickler verfolgen manuell die aktuelle Stufe, prüfen Übergangsbedingungen und setzen die Oberfläche zusammen. Wenn sich die Geschäftslogik ändert oder neue Äste hinzugefügt werden, wird der Code schnell unübersichtlich und verwandelt sich in Spaghetti aus if-Anweisungen und match-Blöcken. dialog-engine kehrt das um: Der Dialog wird zu einer Datenstruktur statt zu einer Abfolge von Anweisungen.

Die Konfigurationsdatei enthält ein Array von Schritten. Jedes Element definiert eine ID, Eingabetyp, Text und optionale Validierungsparameter. Die Engine interpretiert keine Feldtypen – text, choice, photo oder benutzerdefinierte Werte werden über Konventionen zwischen Konfiguration und Rendering-Schicht gehandhabt. Dadurch kann dieselbe Datei für einen Telegram-Bot, eine Weboberfläche oder ein Konsolenprogramm verwendet werden.

{
  "steps": [
    { "id": "name", "type": "text", "text": "What is your name?" },
    { "id": "plan", "type": "choice", "text": "Choose a plan",
      "choices": { "free": "Free", "pro": "Professional" } },
    { "id": "company_inn", "type": "text", "text": "Enter the company tax ID",
      "show_when": { "field": "plan", "equals": "pro" } },
    { "id": "confirm", "type": "text", "text": "Is everything correct? Sending!" }
  ]
}

Die Kerninstallation erfordert keine externen Abhängigkeiten. Zusätzliche Module werden bei Bedarf über Extras installiert, wodurch das Basispaket leichtgewichtig bleibt.

pip install dialog-engine
pip install dialog-engine[validation,yaml,aiogram]

Bedingte Sichtbarkeit und Navigationsmechanismus

Das zentrale Feature der Engine ist kontextabhängiges Routing. Statt Übergänge fest zu kodieren, verwendet sie ein Dictionary mit Benutzerantworten, um Indizes für den nächsten und vorherigen sichtbaren Schritt zu berechnen. Versteckte Stufen werden automatisch aus der Fortschrittsleiste und Navigationslogik ausgeschlossen, was genaue Positionsangaben wie „Schritt 2 von 3“ gewährleistet.

Sichtbarkeitsbedingungen werden über die Felder show_when und skip_when gesetzt. Es unterstützt grundlegende Vergleichsoperatoren und Existenzprüfungen sowie zusammengesetzte Regeln wie any_of und all_of für komplexe Geschäftslogik. Regeln können unbegrenzt verschachtelt werden.

{
  "skip_when": {
    "any_of": [
      { "field": "plan", "equals": "free" },
      { "field": "age", "lt": 18 }
    ]
  }
}

Die Python-API bietet Methoden zur Arbeit mit Indizes und Positionen, die eine präzise Kontrolle des Sitzungszustands ohne manuelle Bedingungsverschachtelung ermöglichen.

ctx = {"plan": "free"}
next_idx = engine.next_index(1, ctx)
prev_idx = engine.previous_index(3, ctx)
pos = engine.effective_position(next_idx, ctx)
total = engine.effective_total(ctx)

if engine.is_last_visible(next_idx, ctx):
    # Complete dialog
    ...

Für die Sitzungspersistenz serialisiert die Klasse DialogSessionState den aktuellen Index und Kontext zu JSON. Das vereinfacht die Speicherung des Zustands in Redis oder relationalen Datenbanken zwischen Benutzeranfragen.

Integration mit aiogram 3 und Callback-Behandlung

Der Bibliotheks-Kern ist framework-agnostisch, aber fertige Helfer für das Telegram-Ökosystem sind verfügbar. Sie generieren Inline-Tastaturen, markieren ausgewählte Werte automatisch und bilden korrekte callback_data. Die Callback-Behandlung ist typisiert und trennt die Logik für Auswahlen, Sprünge und Rückwärts.

from dialog_engine.integrations.aiogram import (
    build_step_keyboard,
    parse_choice_callback,
    is_named_callback,
    KeyboardCallbacks,
)

step = engine.get_step(current_index)
kb = build_step_keyboard(step, translate, show_back=True, current_value=ctx.get(step.id))
await message.answer(step.text, reply_markup=kb)

Das Parsen eingehender Callbacks wird von Parsern gehandhabt, die die Schritt-ID und den ausgewählten Wert zurückgeben. Das macht manuelles String-Parsen von callback.data überflüssig und reduziert Risiken von Präfix-Kollisionen.

@router.callback_query()
async def on_callback(callback: CallbackQuery):
    cb = KeyboardCallbacks()
    pair = parse_choice_callback(callback.data, cb)
    if pair:
        step_id, choice_key = pair
        ctx[step_id] = choice_key
        next_idx = engine.next_index(current_index, ctx)
        ...

CLI-Tools und Konfigurationsvalidierung

Die Unterstützung deklarativer Konfigurationen erfordert statische Analyse-Tools. Die enthaltene CLI überprüft die Dateistruktur auf doppelte IDs, defekte Referenzen und Syntaxfehler vor dem App-Start. Der Strict-Modus verwendet Pydantic für vollständige Typenprüfung.

• dialog-engine validate wizard.json — Grundstrukturprüfung.
• dialog-engine validate --strict wizard.json — Pydantic-Validierung.
• dialog-engine mermaid wizard.json — Generieren eines Übergangsdiagramms für die Dokumentation.
• dialog-engine schema > dialog.schema.json — Ausgabe des JSON Schema für IDE-Autovervollständigung.
• dialog-engine init -o my-dialog.json — Erstellen einer neuen Dialogvorlage.

Die Integration der Validierung in CI/CD-Pipelines stellt sicher, dass ungültige Konfigurationen nicht in die Produktion gelangen. JSON Schema sorgt für Syntaxhervorhebung und Autovervollständigung in Code-Editoren und senkt die Einstiegshürde für Produktmanager und Analysten, die Formulare bearbeiten.

Wichtige Punkte

• Dialoge werden deklarativ in JSON/YAML beschrieben, trennen Geschäftslogik vom App-Code und erlauben Szenario-Änderungen ohne Neudeployment.
• Navigation und Schritt-Sichtbarkeit werden dynamisch aus dem Sitzungskontext berechnet und vermeiden verschachtelte bedingte Strukturen.
• Die Integration mit aiogram 3 bietet fertige Tastatur-Generatoren und typisierte Callback-Parser, die Boilerplate-Code reduzieren.
• CLI-Utility und JSON Schema ermöglichen statische Konfigurationsprüfungen und reibungslose IDE-Entwicklung.
• Die Bibliothek wird unter einer source-available Lizenz vertrieben: Nutzung in Projekten ist erlaubt, aber Modifikation und Weiterverbreitung des Quellcodes sind eingeschränkt.

— Editorial Team