QuBot: Справочник

---

Структура проекта

Проект с чат-ботом является объектом, свойствами которого являются другие объекты. Базовыми объектами (разделами проекта) являются:

Кроме этого, возможен раздел includes со списком подключаемых файлов: Один из файлов проекта является главным. Через includes он добавляет в себя другие файлы, те, в свою очередь, могут содержать свои includes и т.д. Корневые разделы (bot, slots, states) могут повторяться в файлах, но их содержание должно быть уникальным (например, данное состояние может быть описано в разделе states только одного yml-файла).

---

Структура состояния

Состояния описываются в разделе states. Каждое состояние имеет уникальное имя и содержит список объектов. У каждого объекта есть уникальное свойство (text, slots, ...), которое определят его тип. Часть объектов визуальные (text, button, image), другая часть - логические. Объекты одного и того же типа могут встречаться в списке несколько раз.

Списки визуальных объектов состояния могут быть разбиты на блоки. Начало следующего блока помечается объектом block. Каждый блок является отдельным сообщением. В web-chat это сообщение рисуется на подложке заданного (и при желании изменяемого) цвета. В месенджерах блоки могут оказаться разбитыми на отдельные сообщения.

В состояниях может не быть визуальных объектов. Такие состояния называются логическими. В них выполняются некоторые действия (action), устанавливаться слоты (slots) и т.п. В конце логического состояния ставится оператор перехода (goto) в новое состояние (визуальное или логическое).

Полный перечень объектов, которые могут встретиться в состоянии:

---

Визуальные объекты состояния

✒ text - добавляет текст в сообщение. В web-chat этот текст окружается тегами абзаца <p> ... </p>. Если текст многострочный (внутри есть \n), то символы конца строк в web-chat заменяются на обрыв строки <br>.
Значение свойства text - это строка (единичная или многострочная):

Можно также в text передавать объект с перечнем языков, значение каждого из которых это - однострочный или многострочный текст: Такой же формат имеют свойства других объектов, если их значением является текст (button, caption, и т.д.).

В месенджерах (например telegram) объект text отправляется отдельным сообщением (нарисованным на фоне своей подложки). Если состояние имеет визуальные объекты, то для месенджеров один из них обязательно должен быть текстом или картинкой. Если состояние имеет кнопки, то перед ним обязательно должен идти хотя бы один text или image (для месенджеров).

В строке текста могут помещаться значения слотов (перед их именем ставится знак доллара) и фигурные скобки {...}, содержащие выражение, которое необходимо вычислить (это выражение на Python). В результирующей строке произойдёт замена слотов на их значения и будут проведены соответствующие вычисления внутри {...}:

К категориальным слотам можно в тексте обращаться через точку (выше второй текст). Если в разделе slots есть: Тогда вместо $INFO.COMAPNY будет подставлено название компании в текущем языке.

У объекта text может быть свойство p: false. Оно означает, что в web-chat текст тегами абзаца не нужно. Ещё одно свойство pre: true окружает текст тегами <pre> ... </pre> - моношириннный шрифт с сохранением всех пробелов.

---

✒ image - выводимая в сообщении картинка. Она может содержать необязательное свойство caption. Это подпись под картинкой, которая "прижимается" к ней.

Путь к картинке указывается относительно корневой директории, где находится главный yml-файл проекта.

---

✒ map - вывод карты google. Ссылка соответствует полю src= в ссылке, которая генериться в www.google.com/maps. Для её получения, нажимаем на кнопку с полосочками в левом верхнем углу google map и выбираем "Ссылка/код", а там закладку "Встраивание карт".

---

✒ random - выбрать случайный объект из списка. Ниже будет случайно выбран один из двух текстов:

Если случайно нужно выбрать не один объект, а группу, то используется блок actions:

---

✒ again - выбор и выполнение списка объектов, в зависимости от номера повтора вызова этого блока. Для его использования, необходимо создать слот типа int с нулевым начальным значением (это будет так, если value не указать). Ниже такой слот имеет имя SLOT_WAS_ARE_YOU_BOT. При заходе в again, стоящий в нём слот (без знака доллара!) увеличивается на единицу, а затем выполняется соответствующий его значению раздел (приведенные ниже числа) из ключа cases. Эти числа не обязательно идут подряд и в них могут быть пропуски:

Если значение слота больше любого из чисел в списке, то выполняется болок more. В примере выше, при первом заходе будет выведен текст "Да, я искусственный разум...", при втором заходе ничего не будет выведено, при третьем - текст "Да, да, это я." Все последующие заходы будут порождать последний текст. В списке каждого блока могут быть любые объекты.

В again можно также передавать значение (доллар) слота (again: $SLOT), если в строковом слоте SLOT хранится имя слота, использующегося как счётчик.

В разделе more можно вызвать random, чтобы разнообразить контент при "переполнении" счётчика.

---

✒ video - выводимое в сообщении видео.

---

✒ audio - - выводимое в сообщении аудио.

---

Событийные объекты состояния

✒ buttons - перечисляет список кнопок button (они будут идти в столбик) или строчек row, содержащих список кнопок button (они будут идти в строчку):

Для корректной работы месенджера раздел buttons должен быть последним визуальным объектом состояния и перед ним должен быть хотя бы один text или image.

В списке раздела buttons (и в row), кроме row и button, могут быть объекты if, while, action, run. Если результатом их работы будет объект button, он добавится в соответствующем месте (в строчке или колонке). Это позволяет создавать меню кнопок, зависящее от, например, текущего значения слотов. Других визуальных элементов if, while, action, run в разделе buttons порождать не должны:

Объект buttons не обязателен и служит для повышения структуризации. Кнопки button и строчки кнопок row можно перечислять непосредственно в состоянии.

---

✒ button - одна кнопка. Кроме заголовка (возможно на разных языках) могут также находится следующие объекты, которые активируются при нажатии кнопку:

Если при нажатии кнопки необходимо вызвать несколько объектов в контролируемом порядке, необходимо поставить блок actions и далее привести список этих объектов Фактически в разделе actions могут быть все объекты, допустимые в состоянии.

Если под button есть state, то переход по нажатию на кнопку произойдёт в это состояние. Иначе будет выбрано состояние по умолчанию, указанное в state в корне данного состояния. Если state нет ни в кнопке, но в корне состояния, то будет повторно показано текущее состояние.

Если в кнопке (под actions) есть визуальные элементы ( text, image,...), они будут выведены в начале следующего состояния.

В кнопке может быть свойство url: "http://google.com". Если оно есть, при нажатии кнопки произойдёт переход по ссылке (в другом окне браузера).

По умолчанию текст на кнопке центрируется. Это поведение можно изменить свойством text_align: left (или right). Надпись на кнопке в этом случае будет прижата влево или вправо. Второе свойство text_margin: 10 определяет отступ в пикселях от левого или правого края кнопки соответственно. Эти свойства сработают только в web-чате.

---

✒ input - строка ввода. В настоящее время она одна и её положение в списке объектов состояния роли не играет. Может содержать свойства, срабатывающие при вводе текста пользователем:

INPUT_VALUE - это встроенный строковый слот (его объявлять не нужно), содержащий введенный текст без пробелов в начале и конце. Доллар перед именем слота INPUT_VALUE означает взятие его значения (строку ввода).

Можно анализировать значение ввода в разделе value и выполнять те или иные действия:

Возможны также разделы intents и extract (см. документ Естественный язык).

Если каждое действия данного типа в разделе input присутствует в единственном экземпляре и их порядок не важен, то input может быть объектом (аналогично button):

Однако лучше использовать "списочный синтаксис". В частности action в объектной форрме использовать нельзя (только под блоком actions).

Если в input и в корне состояния нет state, то будет повторно вызвано текущее состояние.

---

✒ message - раздел активируется, если придёт сообщение от другого бота или от этого же бота, но от другого пользователя. Аналогично input может содержать список любых объектов, допустимых в состоянии. Если в нём и в корне состояния нет state, то будет повторно вызвано текущее состояние.

---

Управление сообщениями

Визуальные и событийные объекты состояния по умолчанию формируют одно сообщение. В web-chat оно рисуется на подложке заданного цвета (по умолчнию или из раздела bot), кроме кнопок buttons, которые идут ниже. В месенджерах такое сообщение, возможно будет разбито на несколько (будет несколько подложек).

В состоянии может быть несколько сообщений. Начало нового сообщения определяется объектом block:

Свойства объекта block позволяют управлять цветом подложки, временем задержки вывода этого сообщения, эффектом, сопровождающим его появление:

Желательно раздел buttons (или список button, row) ставить последним визуальным компонентом в последнем блоке (сообщении). Для web-chat это не критично, но для работы бота в месенджерах важно придерживаться этого правила.

Объект block может стоять перед самым первым визуальным элементом для определения свойств первого сообщения. Например, в нём можно изменить цвет первой подложки и удалить предыдущее сообщение:

По умолчанию кнопки предыдущего сообщения удаляются, а после него имитируется ответ пользователя в виде строки, содержащей текст на кнопке или ввод в поле редактирования. При помощи clear из раздела block можно удалять любое число предыдущих сообщений (все визуальные элементы):

Следует помнить, что в месенджере сообщение может быть разбито на несколько (в отличии от web-chat), поэтому свойство clear необходимо использовать с пониманием, что такое сообщение в месенджере.

---

Переходы между состояниями

✒ goto - мгновенный переход на новое состояние. Игнорируются все остальные объекты ниже, поэтому обычно стоит последним в списке объектов состояния или под if. Всегда используется в стартовом состоянии для указания первого запускаемого состояния:

Может также использоваться для переходов между логическими состояниями.

В качестве значения goto выступает имя состояния или имя слота строкового типа (с префиксом $). Это позволяет сохранять в слотах имена состояний: Обратим внимание на знак $, который даёт значение слота SAVE_STATE. Если его не будет (goto: SAVE_STATE), то произойдёт попытка перехода в состояние с именем SAVE_STATE (которого скорее всего нет). Естественно, слотов со значениями запомненных состояний может быть любое количество и они могут использоваться как в goto, так и в state или run.

Переход goto не сбрасывает визуальные элементы состояния (стоящие выше него) и они выводятся в чат.

---

✒ state - состояние для перехода при возникновении события (нажата кнопка, произведен ввод в строке редактирования). В списке объектов состояния state означает переход по умолчанию (значение state, если его не было в событийном объекте):

Объект state в списке объектов должен быть один (используется только последний). Выше при нажатии на "Так себе" и "Ужасно" произойдёт переход в состояние SCR_WHAT_A_PITY.

---

✒ run - аналогично state или goto содержит имя состояния или строковый слот, хранящий это имя (со знаком $). При встречи этого объекта, происходит временное покидание текущего состояния. Выполнятся все действия в новом состоянии и происходит возврат обратно в ту точку откуда был вызван run. Вызываемое состояние может также формировать визуальные элементы, которые добавятся к элементам состояния откуда был вызван run.

---

Логические объекты состояния

---

✒ slots - установка значения слотов:

Выше, вторая запись является сокращением для:

Напомним, что если значением слота является другой слот, то перед его именем необходимо поставить символ доллара, иначе он будет интерпретироваться как обычная строка, содержащая имя слота. В слотах можно использовать вычисляемые выражения:

В последнем случае типы слотов SLOT2 и COUNT должны быть числовыми (int, float). Если COUNT имеет тип float, а SLOT2 тип int, после сложения, произойдёт округление. Фигурные скобки {$COUNT + 1} (как внутри текста) при задании значения слотов ставить не нужно.

Раздел slots может присутствовать в событийных объектах (button, input, message). Тогда он выполняется только при срабатывании этого объекта.

---

✒ if - объект условия. Содержит строку с логическим выражением и раздел then, выполняемый, если выражение истинно и раздел else, если выражение ложно (один из этих разделов может отсутствовать).

В логическом выражении могут быть числа, слоты (начиняющиеся с $) и строки. Строки должны браться в одинарные кавычки 'Маша', '✅' и т.д.

Равенство двух величин это ==. Для сравнения чисел можно использовать >, <, ==, >=, <=, !=. Возможны логические связки and, or, not и скобки. Для чисел - арифметические выражения. Если переменная (слот) не определена у неё значение None. Вот несколько примеров:

Полный пример раздела if:

Фигурные скобки: {$AMOUNT > 5} (как внутри текста) в if ставить не нужно.

Следующим образом можно проверить длину строки и добавить в сообщение текст:

---

✒ while - похож на if, но повторяет then пока условие истинно, но не более 1000 раз.

В теле цикла (под then) что-то должно изменяться (обычно в разделе slots), чтобы изменялось логическое условие в while.

---

✒ action - встроенное или пользовательское действие, написанное на Python. Оно может содержать различные аргументы и возвращать различные значения:

Некоторые действия не возвращают значения, а просто что-то делают (добавляют элемент в список и т.п.) Более подробно встроенные действия описаны в Справочник - Действия.

---

✒ time - время жизни сообщения. После его истечения (если не было событий от button, input или message) происходит переход в следующее состояние (state). Полезно, например, при проведении тестирования клиента, когда на каждый вопрос отведено определенное время:

При помощи time и clear следующим образом можно реализовать таймер, выводящий на протяжении одной минуты в тексте сообщения секунды (перезаписывая предыдущий текст):

Естественно, где-то выше должно быть задано начальное значение слота {COUNTER: 0}. Так как state в состоянии не указано, через каждую секунду будет произведен повторный показ этого состояния, пока не сработает if и в нём goto.

---

✒ intents: - обработка в произвольном месте последнего намерения человека (Работа с естественным языком):

---

✒ print: "строка" выводит на страницу в разделе Info строку. Можно использовать для отладочных целей.

---

Предопределённые состояния

Существуют три предопределённых состояния. Первое START_STATE описывает разработчик бота. Это состояние всегда должно быть в проекте. Оно запускается первым, делает необходимые настройки (например установку языка) и по goto переходит на первый экран.

Ещё два состояния PREV_STATE и PREV_STATE_2 могут использоваться в state и goto для перехода на одно или два состояния назад. Впрочем, для этих целей можно использовать и сохранённые в слотах имена состояний.

---

Слоты

Все данные хранятся в слотах, которые являются парами ключ-значение. Ключ - это имя слота. Его значение может иметь различные типы:

• int - целое число;
• float - вещественное число с плавающей точкой;
• str - строка;
• bool - логическое значение;
• list - список (массив);
• dict - словарь, состоящий из ключей и значений;
• categorical - множество заранее заданных значений;
• email - адрес электронной почты;
• http - web-адрес;
• phone - номер телефона;
• date - дата;
• time - время;

Слоты объявляются в разделе slots (он находится на корневом уровне файла проекта, там же, где и раздел states). У каждого слота обязательно надо указывать его тип (type) и можно, при необходимости, начальное значение (value):

Если value не указан, то для str это будет пустая строка "", для int, float - 0, в для list пустой список [].

В результате работы (например, при попытке вытащить из строки ввода информацию), значение слота может оказаться равным None (не определено). Это можно использовать в условных операторах (if: $NAME == None).

Значением категориального слота (categorical) является один из определённых в разделе values ключей:

Такой слот внутри состояния задаётся обычным образом: slots: { ITEM: Milk }. Для получения значения в текстах можно использовать знак доллара: "Это $ITEM", где на место $ITEM будет подставлено текущее значение value. Можно также обратиться к конкретному значению (не зависимо от текущего value), используя точку между именем слота и именем его возможного значения: "Это $ITEM.Milk". Таким образом можно создавать строковые ресурсы для мультиязычных интерфейсов.

В слотах строкового типа также можно использовать несколько языков.

Предопределённые слоты:

CURRENT_STATE	(type: str)	- имя текущего состояния
LANGUAGE	(type: str)	- имя текущего языка
INPUT_VALUE	(type: str)	- текст из последнего ввода в строке input
BUTTON_ID	(type: int)	- номер последней нажатой кнопки (с единицы)
BUTTON_NAME	(type: str)	- надпись на последней нажатой кнопке
NLU_INTENT	(type: str)	- последнее распознанное намерение
USER_ID	(type: str)	- идентификатор пользователя бота
FRIENDS_ID	(type: list)	- список друзей (от которых можно принимать сообщения)
MESSAGES	(type: list)	- список сообщений

---

Вычисления

✒ Математические функции

• sqrt($X) - квадратный корень
• pow($X, 3) - возведение в степень
• fabs($X) - взятие по модулю вещественного числа
• exp($X) - экспонента;
• log($X) - натуральный логарифм;
• log10($X) - логарифм по основанию 10;
• log2($X) - логарифм по основанию 2;
• pi - число пи;
• e - основание натурального логарифма;
• cos($X) sin($X) tan($X) - тригонометрические функции;
• acos($X) asin($X) atan($X) atan2($X,$Y) - обратные тригонометрические функции.

---

✒ Округление

• floor($X) - округление чисел в меньшую сторону: floor(5.8) = 5, floor(-6.1) # = -7;
• trunc($X) - отбрасывание дробной части: trunc(5.51) = 5, trunc(-6.99) = -6;
• ceil($X) - округление чисел в большую сторону: ceil(5.15) = 6;
• round($X,$N) - округление до $N чисел после запятой: round(pi, 2) = 3.14;

---

✒ Дата и время

• now() - текущая дата и время в неотформатированном виде
• time() - текущее время
• date() - текущая дата

В последних двух функциях можно передавать форматирование времени или даты, а также сдвиг от текщего дня: Список кракозябр для форматирования времени и даты можно найти здесь.

---

✒ Случайные числа

• random() - возвращает случайное число float в диапазоне [0,1];
• randint(min,max) - возвращает целое случайное число int в диапазоне [min,max];
• choice(list) - возвращает случайный элемент списка list;
• shuffle(list) - перемешивает список list.

---

✒ Разное

• len($X) - длина списка list или строки str;
• min($X,$Y,...) - минимальное число;
• max($X,$Y,...) - максимальное число;
• sum($X,$Y,...) - сумма чисел; аргументом может список list из чисел.

---

Логические выражения

Значение ключа if - это строка, содержащая логическое выражение. Логическое выражение принимает два значения True и False. В выражении могут быть числа, переменные (имена слотов с $) и строки. Строки должны браться в одинарные кавычки 'Маша', '✅' и т.д.

Равенство двух величин это ==. Для сравнения чисел можно использовать >, <, ==, >=, <=, !=. Возможны логические связки and, or, not и скобки. Для чисел - арифметические выражения. Если переменная (слот) не определена у неё значение None. Вот несколько примеров:

Если выражение не верное (не является логическим), слева появится ошибка.

---