Řízení dialogů v Pythonu prostřednictvím JSON konfigurace

# Řízení vícekrokových dialogů v Pythonu pomocí JSON konfigurací

Vývoj dotazníků, onboardingů a složitých wizardů často vede k nahromadění podmínkové logiky, kterou je obtížné udržovat a škálovat. Knihovna dialog-engine nabízí deklarativní alternativu: struktura dialogu, pravidla viditelnosti polí a navigace se popisují v JSON nebo YAML. Engine sám vypočítává dostupné kroky na základě kontextu relace a eliminuje potřebu psát vnořené konstrukce pro každý scénář.

Deklarativní přístup k tvorbě wizardů

Tradiční implementace krok za krokem formulářů vyžaduje explicitní řízení stavu. Vývojář manuálně sleduje aktuální etapu, kontroluje podmínky přechodu a formuje rozhraní. Při změně business logiky nebo přidání nových větví se kód rychle komplikuje a mění se v těstoviny z if a match. dialog-engine tento proces obrací: dialog se stává sadou dat, nikoli posloupností instrukcí.

Konfigurační soubor obsahuje pole kroků. Každý prvek definuje identifikátor, typ vstupu, text a volitelné parametry validace. Engine neinterpreuje typy polí — text, choice, photo nebo vlastní hodnoty zůstávají na úrovni dohody mezi konfigurací a vrstvou zobrazení. To umožňuje použít stejný soubor pro Telegram bota, webové rozhraní nebo konzolovou utilitu.

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

Instalace jádra nevyžaduje žádné externí závislosti. Další moduly se připojují podle potřeby prostřednictvím extras, což zachovává lehkost základní distribuce.

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

Mechanismus podmínkové viditelnosti a navigace

Klíčovou vlastností enginu je kontextově závislá směrování. Místo hardkódovaných přechodů se používá slovník s odpověďmi uživatele. Na jeho základě se vypočítávají indexy následujícího a předchozího viditelného kroku. Skryté etapy se automaticky vyloučí z progress baru a logiky navigace, což zaručuje správné počítání pozic typu „krok 2 z 3“.

Podmínky viditelnosti se zadávají prostřednictvím polí show_when a skip_when. Podporovány jsou základní operátory porovnání a kontroly existence, stejně jako složené pravidla any_of a all_of pro realizaci složité business logiky. Pravidla lze vnořovat bez omezení hloubky.

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

Python API poskytuje metody pro práci s indexy a pozicemi. To umožňuje přesně kontrolovat stav relace bez manuálního procházení podmínek.

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

Pro perzistenci relací je připravený třída DialogSessionState, která serializuje aktuální index a kontext do JSON. To usnadňuje ukládání stavu v Redis nebo relačních databázích mezi požadavky uživatele.

Integrace s aiogram 3 a zpracování callbacků

Jádro knihovny je framework-agnostické, ale pro ekosystém Telegramu jsou připravené hotové helpery. Ty generují inline klávesnice, automaticky označují vybrané hodnoty a formují správné callback_data. Zpracování stisků je typizované a odděluje logiku výběru, přeskočení a návratu.

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)

Rozbor příchozích callbacků probíhá prostřednictvím parserů, které vracejí identifikátor kroku a vybranou hodnotu. To eliminuje potřebu manuálně parsovat řetězce callback.data a snižuje riziko kolizí prefixů.

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

Nástroje CLI a validace konfigurací

Podpora deklarativních konfigurací vyžaduje nástroje statické analýzy. Dodávaný CLI umožňuje kontrolovat strukturu souboru na duplicity identifikátorů, chybné odkazy a syntaktické chyby ještě před spuštěním aplikace. V přísném režimu se používá Pydantic pro úplnou kontrolu typů.

• dialog-engine validate wizard.json — základní kontrola struktury.
• dialog-engine validate --strict wizard.json — validace přes Pydantic.
• dialog-engine mermaid wizard.json — generování diagramu přechodů pro dokumentaci.
• dialog-engine schema > dialog.schema.json — výstup JSON Schema pro autodoplňování v IDE.
• dialog-engine init -o my-dialog.json — vytvoření šablony nového dialogu.

Vložení validace do CI/CD pipeline zaručuje, že nekorektní konfigurace se nedostanou do produkce. JSON Schema zajišťuje zvýraznění syntaxe a nápovědy v editech kódu, což snižuje vstupní práh pro product managery a analytiky, kteří editují dotazníky.

Co je důležité

• Dialog se popisuje deklarativně v JSON/YAML, což odděluje business logiku od kódu aplikace a umožňuje editovat scénáře bez deploye.
• Navigace a viditelnost kroků se vypočítávají dynamicky na základě kontextu relace, což eliminuje vnořené podmínkové konstrukce.
• Integrace s aiogram 3 poskytuje hotové generátory klávesnic a typizované parsery callbacků, což zkracuje objem boilerplate kódu.
• CLI utilitky a JSON Schema zajišťují statickou kontrolu konfigurací a pohodlný vývoj v IDE.
• Knihovna se šíří pod source-available licencí: použití v projektech je povoleno, modifikace a redistribuce zdrojového kódu jsou omezeny.

— Editorial Team