RAG_helper/docs/guides/state_machine_and_slots.md

Машина состояний и слоты — на пальцах

Шпаргалка для настройщика мультиагента. Без жаргона: всё через примеры из реальной ветки new_booking (см. ../architecture/GRAPH_ARCHITECTURE_v3.md, раздел 3).

Терминология та же, что в архитектурном документе: при первом упоминании даётся русский термин и английский эквивалент в скобках, дальше — что удобнее по контексту.

---

1. Машина состояний (state machine) — это «карта разговора» внутри одной ветки

Когда роутер (router) определил намерение (intent) пациента и передал диалог в ветку (branch), внутри этой ветки начинается мини-сценарий. Если сценарий — линейный «спросил-ответил», промпт справится сам. Если шагов несколько и порядок важен — нужна машина состояний: явная карта того, на каком шаге (step) сейчас разговор и куда он может пойти дальше.

В нашем проекте каноничный пример — ветка new_booking, у неё шесть шагов:

intro → qualify → present → offer_time → book → close
                    │
                    └─ guard: пациент-ребёнок → собрать законного представителя
                    └─ guard: запрос конкретного врача → рукав «лист ожидания»

Шаг (step) — это одна осмысленная задача в разговоре («квалифицировать пациента», «предложить время»). У шага должна быть одна цель и понятное условие, по которому можно идти дальше.

Защитное условие (guard) — это правило, которое блокирует обычный переход и уводит разговор в сторону до тех пор, пока не выполнено условие. Например, на qualify нельзя уйти в present, пока для ребёнка не собраны ФИО и телефон законного представителя — это юридическое требование.

Что важно при настройке ветки

• У каждого шага должно быть понятное имя в step и одна цель.
• Должно быть условие выхода (exit condition) — когда разговор уходит из этой ветки целиком (например, пациент упомянул операцию → handoff в escalate_human с reason=surgery). См. раздел 4 архитектурного документа.
• Должен быть финальный шаг (у new_booking — close), иначе разговор «зависнет».
• Все нелинейные ветвления оформлять через условные переходы (conditional transitions), а не через под-состояния — так проще тестировать.

---

2. Слоты (slots) — это «поля анкеты», которые заполняются по ходу разговора

Внутри шагов помощник собирает у пациента данные. Каждая такая «графа» — слот. Все слоты текущего треда хранятся в thread_state.slots (JSON-колонка).

Реальный фрагмент состояния треда (thread state) на середине записи:

{
  "intent": "new_booking",
  "step": "offer_time",
  "slots": {
    "patient_name": "Анна",
    "is_child": false,
    "service": "первичный ЛОР",
    "doctor": "Сушков М. Г.",
    "time_candidates": ["2026-04-24 10:00", "2026-04-24 15:00"],
    "time_chosen": null
  }
}

Помощник на каждом ходу видит: «я на шаге offer_time, time_candidates заполнен, time_chosen пуст — значит следующая реплика должна получить выбор времени, а не представляться заново».

Главные свойства слота

Свойство	Что это	Пример
Имя (name)	Идентификатор в slots	time_chosen
Тип (type)	Что туда кладётся	дата, строка, булево, список
Вопрос (prompt)	Что говорит помощник, если слот пуст	«Подскажите, какое время удобнее — утром или вечером?»
Проверка (validation)	Когда значение считается валидным	time_chosen ∈ time_candidates
Обязательность	Можно ли уйти с шага без слота	time_chosen — да, is_child — да, insurance — нет
Источник	Откуда модель может взять значение	реплика пациента, инструмент crm.get_slots, RAG-срез

---

3. Как состояния и слоты работают вместе

Простыми словами:

Шаг говорит, о чём сейчас разговор внутри ветки. Слоты говорят, что именно должно быть собрано к концу шага.

Связка работает через структурированный ответ (structured output) модели:

{
  "reply": "Записала вас на четверг, 10:00...",
  "state_after": "close",
  "slots_updated": { "time_chosen": "2026-04-24 10:00" }
}

Код-валидатор (см. 3.3 архитектурного документа):

1. Проверяет, что переход offer_time → close легален.
2. Применяет slots_updated к thread_state.
3. Если модель вернула несуществующее state_after — состояние не меняется, в лог пишется предупреждение.

Модель рассуждает содержательно, код защищает механически. Поэтому при настройке ветки списка шагов и таблицы легальных переходов между ними достаточно, чтобы прикрутить валидатор — отдельной логики не нужно.

---

4. Что делает настройщик мультиагента

1. Описать карту шагов ветки. Перечислить шаги, разрешённые переходы, финальный шаг и условия выхода (exit conditions). Если ветка простая (reschedule, general_info) — одного-двух шагов достаточно. Если сложная (new_booking) — выписать все шесть и guard'ы к ним.
2. Описать слоты на каждом шаге. Какие обязательные, какие опциональные, какой тип, какой вопрос помощника, какая проверка. Помнить про RAG-срезы по шагам (см. 3.4 архитектурного документа): на разных шагах нужны разные куски базы знаний.
3. Прогнать сценарии вживую на стенде. Минимум:
   • happy path — пациент сразу даёт всё (несколько слотов из одной фразы);
   • по кусочкам — пациент отвечает на каждый вопрос отдельно;
   • боковой вопрос — посреди записи пациент спрашивает про цену/адрес → должна сработать мягкая вставка (soft insertion), step не меняется (см. 4.2);
   • смена темы — пациент посреди записи говорит «нет, я хочу перенести существующую» → должен сработать жёсткий переход (hard handoff) в reschedule;
   • guard — для new_booking: пациент-ребёнок (см. ../examples/03_child_patient_guard.md);
   • отмена/перезапуск — пациент говорит «отмени всё, начнём заново» → корректный сброс состояния.
4. Записать замечания в формате: ветка → шаг → слот → что пошло не так → ожидаемое поведение. Это сильно ускоряет правки на стороне разработки и даёт готовый материал для регрессионных тестов.

---

5. Мини-словарь

• Тред / сессия (thread / session) — один разговор с одним пациентом от приветствия до закрытия.
• Намерение (intent) — категория запроса, которую вернул роутер: new_booking, reschedule, price_question, medical_question, general_info, escalate_human.
• Ветка (branch) — изолированный промпт, обслуживающий одно намерение.
• Шаг (step) — текущая стадия разговора внутри ветки, поле step в thread_state.
• Переход (transition) — правило перехода с шага на шаг; условный переход (conditional transition) — переход, зависящий от значения слота.
• Слот (slot) — поле в thread_state.slots.
• Защитное условие (guard) — правило, которое блокирует переход, пока не выполнено.
• Условие выхода (exit condition) — правило выхода из ветки целиком (триггер handoff'а к роутеру).
• Мягкая вставка (soft insertion) — короткий ответ на боковой вопрос без смены step.
• Жёсткий переход (hard handoff) — выход из ветки с сохранением suspended_intent + resumable_step + resumable_slots.
• Структурированный ответ (structured output) — JSON, который модель возвращает вместо чистого текста: reply, state_after, slots_updated.

---

По любым неясностям — комментарий прямо в этом файле либо тикет с пометкой ветки и шага, дополним.