Gestion des dialogues en Python via configuration JSON

Gestion des dialogues multi-étapes en Python avec des configurations JSON

La création de sondages, de flux d'onboarding et d'assistants complexes entraîne souvent une accumulation de logique conditionnelle difficile à maintenir et à faire évoluer. La bibliothèque dialog-engine propose une alternative déclarative : la structure du dialogue, les règles de visibilité des champs et la navigation sont définies en JSON ou YAML. Le moteur calcule automatiquement les étapes disponibles en fonction du contexte de la session, éliminant le besoin de constructions imbriquées pour chaque scénario.

Approche déclarative pour la création d'assistants

Les implémentations traditionnelles de formulaires multi-étapes nécessitent une gestion explicite de l'état. Les développeurs suivent manuellement l'étape actuelle, vérifient les conditions de transition et assemblent l'interface. Lorsque la logique métier change ou que de nouvelles branches sont ajoutées, le code devient rapidement désordonné, se transformant en un enchevêtrement de déclarations if et de blocs match. dialog-engine renverse la donne : le dialogue devient une structure de données plutôt qu'une séquence d'instructions.

Le fichier de configuration contient un tableau d'étapes. Chaque élément définit un ID, un type d'entrée, un texte et des paramètres de validation optionnels. Le moteur n'interprète pas les types de champs — text, choice, photo ou des valeurs personnalisées sont gérés via des conventions entre la configuration et la couche de rendu. Cela permet d'utiliser le même fichier pour un bot Telegram, une interface web ou une utilitaire en console.

{
  "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!" }
  ]
}

L'installation de base ne nécessite aucune dépendance externe. Les modules supplémentaires sont installés via des extras au besoin, gardant le package de base léger.

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

Mécanisme de visibilité conditionnelle et de navigation

La fonctionnalité clé du moteur est le routage dépendant du contexte. Au lieu de coder en dur les transitions, il utilise un dictionnaire des réponses de l'utilisateur pour calculer les indices des étapes suivante et précédente visibles. Les étapes cachées sont automatiquement exclues de la barre de progression et de la logique de navigation, garantissant des comptes de position précis comme « étape 2 sur 3 ».

Les conditions de visibilité sont définies via les champs show_when et skip_when. Il supporte les opérateurs de comparaison de base et les vérifications d'existence, plus des règles composites comme any_of et all_of pour une logique métier complexe. Les règles peuvent être imbriquées sans limite de profondeur.

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

L'API Python fournit des méthodes pour travailler avec les indices et les positions, permettant un contrôle précis de l'état de session sans parcours manuel des conditions.

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
    ...

Pour la persistance de session, la classe DialogSessionState sérialise l'indice actuel et le contexte en JSON. Cela simplifie le stockage de l'état dans Redis ou des bases de données relationnelles entre les requêtes utilisateur.

Intégration avec aiogram 3 et gestion des callbacks

Le cœur de la bibliothèque est agnostique vis-à-vis des frameworks, mais des aides prêtes à l'emploi sont fournies pour l'écosystème Telegram. Elles génèrent des claviers inline, marquent automatiquement les valeurs sélectionnées et forment des callback_data corrects. La gestion des callbacks est typée et sépare la logique pour les choix, les sauts et les retours.

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)

L'analyse des callbacks entrants est gérée par des parseurs qui retournent l'ID de l'étape et la valeur sélectionnée. Cela élimine l'analyse manuelle des chaînes callback.data et réduit les risques de collision de préfixes.

@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)
        ...

Outils CLI et validation de configuration

Le support des configurations déclaratives nécessite des outils d'analyse statique. Le CLI inclus vérifie la structure des fichiers pour les ID dupliqués, les références cassées et les erreurs de syntaxe avant le lancement de l'app. Le mode strict utilise Pydantic pour une vérification complète des types.

• dialog-engine validate wizard.json — vérification de structure de base.
• dialog-engine validate --strict wizard.json — validation Pydantic.
• dialog-engine mermaid wizard.json — générer un diagramme de transition pour la documentation.
• dialog-engine schema > dialog.schema.json — exporter le JSON Schema pour l'autocomplétion IDE.
• dialog-engine init -o my-dialog.json — créer un nouveau modèle de dialogue.

Intégrer la validation dans les pipelines CI/CD garantit que les configurations invalides n'atteignent pas la production. Le JSON Schema fournit la coloration syntaxique et l'autocomplétion dans les éditeurs de code, abaissant la barrière d'entrée pour les chefs de produit et les analystes qui modifient les formulaires.

Points clés

• Les dialogues sont décrits de manière déclarative en JSON/YAML, séparant la logique métier du code de l'app et permettant les modifications de scénarios sans redéploiement.
• La navigation et la visibilité des étapes sont calculées dynamiquement à partir du contexte de session, évitant les structures conditionnelles imbriquées.
• L'intégration aiogram 3 fournit des générateurs de claviers prêts et des parseurs de callbacks typés, réduisant le code boilerplate.
• Les utilitaires CLI et le JSON Schema permettent des vérifications statiques de configuration et un développement fluide en IDE.
• La bibliothèque est distribuée sous une licence source-available : l'utilisation dans les projets est autorisée, mais la modification et la redistribution du code source sont limitées.

— Editorial Team