Block Generation PRD

1. Цель и продуктовый контекст

Функция Block Generation нужна для ускорения первичного авторинга библиотеки блоков в TextFoundry.

Проблема бизнеса и продукта:

  • ручное создание блоков замедляет наполнение библиотеки;

  • типовые блоки часто имеют повторяющуюся структуру;

  • старт с пустой формы повышает стоимость каждой новой единицы контента;

  • автор тратит время не на смысловую доработку, а на первичное заполнение полей.

Цель функции:

  • сократить путь от идеи на естественном языке до пригодного черновика блока;

  • оставить пользователю контроль над итоговой версией;

  • не разрушить deterministic и versioned nature системы.

Ожидаемый эффект:

  • быстрее создавать role, system, style, constraint, domain и другие reusable blocks;

  • снизить стоимость первичного draft authoring;

  • улучшить скорость экспериментов при разработке prompt library.

2. Постановка проблемы

Текущее базовое поведение без AI:

  • пользователь вручную вводит id, type, language, description, template, defaults, tags;

  • затем вручную сохраняет новую версию блока.

Это даёт хороший контроль, но имеет недостатки:

  • высокая стоимость "пустого старта";

  • много повторяющегося ручного труда;

  • сложнее быстро исследовать варианты формулировок;

  • авторы начинают откладывать формализацию блока в библиотеке.

Почему текущий подход недостаточен:

  • в early drafting ценнее получить хороший стартовый каркас, чем писать каждое поле с нуля;

  • смысловые инструкции на естественном языке хорошо подходят для генерации черновика, но плохо вписываются в purely deterministic authoring workflow.

Почему здесь нужен ML/LLM:

  • задача предполагает интерпретацию свободной текстовой инструкции;

  • структура блока может быть выведена из семантики запроса;

  • нужен не просто шаблон по форме, а содержательно полезный draft.

3. Пользователи и сценарии использования

Основные пользователи:

  • авторы prompt-библиотеки в GUI;

  • команда, которая сопровождает reusable blocks для композиций;

  • владелец продукта или prompt-инженер, быстро проверяющий новые идеи.

Ключевые сценарии:

  • создать новый блок из короткой инструкции на естественном языке;

  • получить черновик блока с уже заполненными ключевыми полями;

  • доработать существующий блок через AI-ревизию, не меняя его identity;

  • использовать AI как ускоритель authoring, а не как автопубликатор.

Важный UX-принцип:

  • результат генерации воспринимается как suggestion в форме, а не как уже опубликованный артефакт.

4. Область охвата и не-цели

В области охвата

  • генерация одного GeneratedBlockData;

  • использование hints по preferred_id, preferred_type, preferred_language;

  • review-before-save workflow;

  • режим ревизии существующего блока через тот же generator contract;

  • загрузка результата в форму редактора для дальнейшей ручной правки.

Вне области охвата

  • автоматическая публикация результата;

  • скрытый вызов AI из Render() или других deterministic операций;

  • пакетная декомпозиция большого prompt в несколько блоков;

  • автоматический выбор лучшего варианта из нескольких генераций;

  • прямое редактирование storage без review.

5. Критерии успеха

Функция считается успешной, если:

  • пользователь регулярно получает стартовый draft, пригодный для дальнейшей ручной доработки;

  • generated result проходит структурную валидацию engine;

  • в типичных сценариях автор редактирует и уточняет draft, а не переписывает всё полностью;

  • AI authoring не ломает обычный ручной lifecycle блока.

Качественные индикаторы:

  • ускорение времени от идеи до первого сохранённого блока;

  • уменьшение доли completely manual first drafts;

  • понятные failure messages при отсутствии конфигурации или ошибках провайдера.

6. Функциональные требования

Система должна:

  • выполнять генерацию только по явному запросу пользователя;

  • принимать свободную текстовую инструкцию как основной вход;

  • уметь использовать предпочтительный id, type и language, если они заданы пользователем;

  • возвращать структурированный draft-like результат;

  • валидировать block_id, template и коллизии до передачи результата в UI;

  • поддерживать отдельный режим AI-ревизии существующего блока;

  • загружать результат в форму без автоматического сохранения.

Пользователь должен:

  • видеть сгенерированные поля и иметь возможность исправить их вручную;

  • осознанно выполнять отдельное действие Save.

7. Нефункциональные требования

Функция должна:

  • не влиять на deterministic render path;

  • деградировать безопасно при отсутствии AI-конфигурации;

  • возвращать объяснимые ошибки;

  • не привязывать core engine к конкретному вендору;

  • сохранять human-in-the-loop модель публикации.

8. Ограничения и допущения

Ограничения:

  • качество результата зависит от внешнего OpenAI-compatible endpoint;

  • AI может вернуть слабый по смыслу, но формально валидный результат;

  • публикация новой версии остаётся полностью ручной;

  • функция полезна в первую очередь в GUI authoring workflow.

Допущения:

  • пользователь готов формулировать понятную инструкцию;

  • engine располагает списком существующих block ids для валидации;

  • блоки остаются основной reusable единицей в продукте.

9. Зависимости и заинтересованные стороны

Зависимости:

  • IBlockGenerator;

  • tf::Engine;

  • OpenAiCompatibleBlockGenerator;

  • HTTP transport;

  • BlockEditorViewModel;

  • session-level AI configuration.

Заинтересованные стороны:

  • prompt authors;

  • владелец библиотеки блоков;

  • владелец AI adapter layer;

  • владелец core engine.

10. Критерии приёмки

Пилот считается успешным, если:

  • на representative block types пользователь стабильно получает полезные drafts;

  • режим generate/revise понятен и не вызывает ложного ощущения автопубликации.

Функция считается готовой к регулярному использованию, если:

  • review workflow стабилен;

  • error handling понятен;

  • generated drafts достаточно качественны для реальных authoring сценариев;

  • отсутствие AI не ломает обычный ручной редактор блоков.