Block Generation Service Spec

1. Назначение и граница сервиса

Назначение функции:

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

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

  • вернуть результат в форме, пригодной для review и ручного сохранения.

Потребители:

  • BlockEditorViewModel;

  • потенциальные будущие authoring-клиенты, использующие тот же engine contract.

Не-цели:

  • publish/persist;

  • auto-approve;

  • batch decomposition;

  • скрытая генерация из render path.

2. Потребители и зависимости

Потребители:

  • BlockEditorViewModel

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

  • tf::Engine

  • IBlockGenerator

  • provider API

  • QtHttpTransport

  • session-level AI configuration

3. Методы и точки вызова

Основные методы:

  • Engine.GenerateBlockData(const BlockGenerationRequest&)

  • Engine.GenerateBlockDraft(const BlockGenerationRequest&)

Практически основной GUI workflow использует GenerateBlockData(…​), после чего сам заполняет форму редактора.

4. Входной контракт

Основная структура входа: BlockGenerationRequest

Обязательные поля:

  • prompt

Необязательные поля:

  • preferred_id

  • preferred_type

  • preferred_language

  • existing_block_ids

  • allow_id_collision

Семантика полей:

  • prompt Свободная пользовательская инструкция.

  • preferred_id Подсказка для генератора, какой block_id желательно использовать.

  • preferred_type Подсказка о типе блока.

  • preferred_language Подсказка о language metadata блока.

  • existing_block_ids Список id, который используется engine для post-validation коллизий.

  • allow_id_collision Разрешает контролируемую коллизию только в revision-сценарии того же блока.

5. Выходной контракт

Основные выходные структуры:

  • GeneratedBlockData

  • BlockDraft

Обязательные элементы generated payload:

  • стабильный block_id

  • block_type

  • language

  • description

  • template в поле templ

  • defaults

  • tags

Назначение выходов:

  • GeneratedBlockData Используется, когда GUI хочет отдельно загрузить поля в форму.

  • BlockDraft Представляет draft-форму результата, но всё ещё не является published asset.

6. Правила доменного контракта

Функция обязана соблюдать следующие правила:

  • generator result должен быть конвертируем в доменно корректный draft;

  • отсутствие настроенного generator является explicit error;

  • generated output не считается published version;

  • block_id валидируется в engine до передачи результата вызывающему слою;

  • пустой template недопустим;

  • коллизии с существующими id запрещены, кроме явно разрешённого revision mode.

7. Иерархия источников и prompt policy

Источники данных и логика приоритета:

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

  • optional hints уточняют ожидаемый id, type и language;

  • prompt policy и provider-specific formatting живут в textfoundry_ai;

  • engine не хранит provider-specific prompt assembly как публичный контракт.

8. Ошибки и retry policy

Ошибки, которые должны доходить до вызывающего слоя:

  • transport errors;

  • auth errors;

  • provider errors;

  • parsing errors;

  • invalid generated payload;

  • duplicate id errors;

  • missing configuration errors.

Политика retry:

  • retry определяется transport/provider configuration;

  • сервисный контракт сам не делает implicit persistence retry;

  • при ошибке storage не меняется.

9. Routing и confidence policy

Текущая реализация:

  • использует один configured generator path;

  • не публикует отдельный confidence score;

  • не выполняет multi-provider routing.

Практическим quality gate остаётся:

  • engine validation;

  • human review в редакторе блока.

10. Edge cases и fallback behavior

Ключевые edge cases:

  • generator не настроен Возвращается explicit error, пользователь продолжает ручной authoring.

  • provider вернул malformed response Ошибка доходит до UI, форма не публикуется автоматически.

  • suggestion низкого качества Пользователь вручную редактирует или отбрасывает draft.

  • preferred_id конфликтует с existing ids Engine отклоняет результат, если не включён допустимый revision mode.

11. Связанные документы

Upstream:

Downstream: