Типы портов

У порта две независимые оси. Первая — провод: несёт ли ребро запуск, значение или поток токенов; это жёсткие правила, по ним ребро либо соединяется, либо нет. Вторая — тип данных: чем именно является полезная нагрузка. Тип данных — мягкий сигнал. Он подсказывает редактору, что показать, даёт предупреждение о подозрительной связи и включает приведение, но сам по себе ребро не запрещает.

Тринадцать типов

Тип	Что это	Пример порта
`any`	тип не объявлен или неизвестен	выход функции виджета
`string`	текст	`text` у ноды сообщения
`number`	число с плавающей точкой	—
`integer`	целое число	—
`boolean`	флаг	—
`object`	структура: JSON-объект; может нести схему, чтобы редактор раскрыл поля	выход `ai_agent`
`array`	список значений	`tasks_out` у плана агента
`dataframe`	таблица со строками и колонками	входы и выходы df-нод
`message`	одно сообщение чата: роль, текст, вложения	выход `entry`, вход `ai_agent`
`messages`	список сообщений — история диалога	выход chat_history
`file`	ссылка на файл: картинка, аудио, документ	вход `files` у exit
`bytes`	двоичная нагрузка	—
`binary`	двоичная нагрузка с указанием MIME-типа	—

Прочерк означает, что сегодня ни один порт каталога не объявляет этот тип явно. Скалярные типы всё равно появляются: если порт не объявил тип сам, для основного выхода он выводится из схемы вывода ноды, а во всех остальных случаях остаётся any. На страницах справочника нод тип каждого порта показан в колонке «Данные».

Совместимость

Пара типов считается совместимой — и редактор молчит — в этих случаях:

с любой стороны стоит any: про такой порт ничего не известно;
типы совпадают;
integer и number взаимозаменяемы;
string, message и messages взаимозаменяемы: голая строка становится сообщением с ролью пользователя, а сообщение при чтении превращается в свой текст;
file подключается ко входу message или messages — файл станет вложением;
object подключается ко входу message или messages — вычисленный объект приводится к сообщению так же, как строка;
цель имеет тип string: шаблон приведёт к строке что угодно.

Всё остальное даёт предупреждение port_type.mismatch с указанием, из чего во что. Это именно предупреждение: сохранить и запустить такой граф можно, но если у пары типов есть конвертер, текст подскажет вставить ноду-конвертер.

Приведение значения

Приведение бывает трёх видов, и это разные вещи.

Неявное — для семейства сообщений. Строка, сообщение и список сообщений конвертируются друг в друга на месте, без всяких настроек: сообщение из entry читается как обычный текст в шаблоне, а строка доезжает во вход message ноды ai_agent уже сообщением с ролью пользователя.

Явное — нода convert. Она переводит json, csv и dataframe друг в друга; выберите исходный и целевой формат в её конфигурации. Пара csv ↔ json проходит через dataframe. Это единственный способ, который видно на холсте: конвертация становится шагом графа со своим временем и своей ошибкой.

Автоматическое — по флагу на ребре. Движок умеет привести значение к типу целевого порта сам, но только когда на ребре явно стоит coerce. По умолчанию его нет, и редактор его не выставляет, поэтому в графах, собранных на холсте, работает первый и второй варианты. Если приведение не удалось, значение идёт дальше как есть — запуск от этого не падает.

Что дальше

Провода

Транспорт ребра и его десять типов.

Модель графа

Ноды, порты, вход и выход.

Справочник нод

Тип данных каждого порта в таблицах нод.