Gestión de diálogos en Python mediante configuración JSON

Gestión de diálogos multi-paso en Python con configuraciones JSON

Construir encuestas, flujos de incorporación y asistentes complejos suele resultar en una acumulación de lógica condicional difícil de mantener y escalar. La biblioteca dialog-engine ofrece una alternativa declarativa: la estructura del diálogo, las reglas de visibilidad de campos y la navegación se definen en JSON o YAML. El motor calcula automáticamente los pasos disponibles en función del contexto de la sesión, eliminando la necesidad de construcciones anidadas para cada escenario.

Enfoque declarativo para crear asistentes

Las implementaciones tradicionales de formularios multi-paso requieren una gestión explícita del estado. Los desarrolladores rastrean manualmente la etapa actual, verifican las condiciones de transición y ensamblan la interfaz. Cuando cambia la lógica de negocio o se agregan nuevas ramas, el código se vuelve rápidamente desordenado, convirtiéndose en un espagueti de sentencias if y bloques match. dialog-engine invierte esto: el diálogo pasa a ser una estructura de datos en lugar de una secuencia de instrucciones.

El archivo de configuración contiene un array de pasos. Cada elemento define un ID, tipo de entrada, texto y parámetros de validación opcionales. El motor no interpreta los tipos de campo—text, choice, photo o valores personalizados se manejan mediante convenciones entre la configuración y la capa de renderizado. Esto permite usar el mismo archivo para un bot de Telegram, una interfaz web o una utilidad de consola.

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

La instalación principal no requiere dependencias externas. Los módulos adicionales se instalan mediante extras según sea necesario, manteniendo el paquete base ligero.

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

Mecanismo de visibilidad condicional y navegación

La característica clave del motor es el enrutamiento dependiente del contexto. En lugar de codificar transiciones fijas, utiliza un diccionario de respuestas del usuario para calcular los índices del siguiente y anterior paso visible. Las etapas ocultas se excluyen automáticamente de la barra de progreso y la lógica de navegación, asegurando conteos de posición precisos como «paso 2 de 3».

Las condiciones de visibilidad se establecen mediante los campos show_when y skip_when. Admite operadores de comparación básicos y verificaciones de existencia, además de reglas compuestas como any_of y all_of para lógica de negocio compleja. Las reglas se pueden anidar sin límites de profundidad.

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

La API de Python proporciona métodos para trabajar con índices y posiciones, permitiendo un control preciso del estado de la sesión sin recorrido manual de condiciones.

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

Para la persistencia de la sesión, la clase DialogSessionState serializa el índice actual y el contexto a JSON. Esto simplifica el almacenamiento del estado en Redis o bases de datos relacionales entre solicitudes de usuario.

Integración con aiogram 3 y manejo de callbacks

El núcleo de la biblioteca es agnóstico al framework, pero se proporcionan ayudantes listos para el ecosistema de Telegram. Generan teclados en línea, marcan automáticamente los valores seleccionados y forman callback_data correctos. El manejo de callbacks está tipado y separa la lógica para elecciones, saltos y retrocesos.

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)

El análisis de callbacks entrantes lo manejan analizadores que devuelven el ID del paso y el valor seleccionado. Esto elimina el análisis manual de cadenas callback.data y reduce los riesgos de colisión de prefijos.

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

Herramientas CLI y validación de configuración

El soporte para configuraciones declarativas requiere herramientas de análisis estático. La CLI incluida verifica la estructura del archivo en busca de IDs duplicados, referencias rotas y errores de sintaxis antes del lanzamiento de la app. El modo estricto usa Pydantic para verificación completa de tipos.

• dialog-engine validate wizard.json — comprobación básica de estructura.
• dialog-engine validate --strict wizard.json — validación Pydantic.
• dialog-engine mermaid wizard.json — generar diagrama de transiciones para documentación.
• dialog-engine schema > dialog.schema.json — generar JSON Schema para autocompletado en IDE.
• dialog-engine init -o my-dialog.json — crear nueva plantilla de diálogo.

Integrar la validación en pipelines CI/CD asegura que las configuraciones inválidas no lleguen a producción. JSON Schema proporciona resaltado de sintaxis y autocompletado en editores de código, reduciendo la barrera de entrada para gerentes de producto y analistas que editan formularios.

Puntos clave

• Los diálogos se describen de forma declarativa en JSON/YAML, separando la lógica de negocio del código de la app y permitiendo ediciones de escenarios sin redepliegue.
• La navegación y la visibilidad de pasos se calculan dinámicamente desde el contexto de la sesión, evitando estructuras condicionales anidadas.
• La integración con aiogram 3 proporciona generadores de teclados listos y analizadores de callbacks tipados, reduciendo el código boilerplate.
• Las utilidades CLI y JSON Schema permiten comprobaciones estáticas de configuración y desarrollo fluido en IDE.
• La biblioteca se distribuye bajo una licencia de código fuente disponible: se permite el uso en proyectos, pero la modificación y redistribución del código fuente están limitadas.

— Editorial Team