busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
027-dataset-llm-orchestration
ss-tools/027-task.md
busya f8de4b7e8a promts
2026-03-21 16:09:13 +03:00

11 KiB
Raw Permalink Blame History

📋 ТЕХНИЧЕСКОЕ ЗАДАНИЕ: ИНТЕГРАЦИЯ MIXED-INITIATIVE LLM-АГЕНТА

Ветка: 027-dataset-llm-orchestration Контекст: Архитектура автоматического ревью датасетов (US1) и подготовки к запуску (US3) реализована отлично. Требуется переработать процесс "Clarification" (US2) из жесткого модального опросника в полноценный контекстно-зависимый диалог с LLM-агентом (Смешанная инициатива / Mixed-Initiative), а также закрыть архитектурные риски (PII, Concurrency).

Тебе необходимо выполнить задачу в два этапа.

ЭТАП 1: Обновление спецификаций (Директория specs/027-dataset-llm-orchestration/)

Твоя первая задача — актуализировать проектную документацию, чтобы она отражала новую парадигму взаимодействия пользователя и агента, а также закрывала дыры в безопасности.

1. Обновить ux_reference.md:

  • Отказ от модалок: Заменить концепцию ClarificationDialog на интеграцию диалога в выдвижную правую панель AssistantChatPanel.
  • Mixed-Initiative: Описать, что диалог может быть инициирован как системой (очередь Clarification Queue), так и пользователем (свободные вопросы агенту по контексту датасета, например: "Почему этот фильтр помечен как partial?").
  • Inline-взаимодействие (Context Actions): Дописать появление микро-кнопок [✨ Спросить ИИ] / [✨ Улучшить] рядом с неразрешенными фильтрами (unresolved), предупреждениями валидации и полем Бизнес-summary в основном Workspace.
  • Визуальный фокус: Зафиксировать правило: когда агент задает вопрос по конкретному фильтру/полю в чате, карточка этого элемента в центральной колонке UI подсвечивается (highlight/glow).
  • Confirmation Cards: Описать интерактивные виджеты внутри ленты чата для опасных операций (например, подтверждение запуска датасета в SQL Lab), опирающиеся на AssistantConfirmationRecord.

2. Обновить spec.md (Functional Requirements):

  • Добавить FR-045: Система должна позволять пользователю задавать свободные вопросы по контексту загруженного датасета (профиль, фильтры, маппинги, SQL).
  • Добавить FR-046: Агент должен уметь принимать команды на естественном языке для изменения состояния сессии (например: "Одобри все маппинги", "Сгенерируй превью SQL").
  • Изменить FR-013: Уточняющие вопросы должны задаваться не в изолированном окне, а в контексте глобального чата ассистента.

3. Обновить contracts/api.yaml и data-model.md:

  • Связь чата и сессии: В AssistantMessageRequest добавить опциональное поле dataset_review_session_id: string.
  • Оптимистичные блокировки: В сущность DatasetReviewSession (и DTO SessionDetail) добавить поле version: integer для предотвращения состояния гонки (Race Condition) при совместном редактировании сессии коллабораторами (пользователь + агент).
  • PII Masking: В data-model.md для ImportedFilter явно указать требование маскирования чувствительных данных (raw_value) перед отправкой контекста в LLM.

4. Обновить contracts/modules.md:

  • В DatasetReviewOrchestrator добавить связь @RELATION: [EXPOSES_STATE_TO] -> [AssistantApi].
  • В описание ClarificationEngine добавить, что он маршрутизирует свои запросы через AssistantChatPanel.

ЭТАП 2: Реализация доработок в кодовой базе (Frontend & Backend)

На основе обновленных спеков реализуй архитектурные и UI/UX изменения в коде.

🛠️ 2.1 Backend: Архитектура, Безопасность и Инструменты Агента

  1. PII Data Masking:
    • Где: backend/src/core/utils/superset_context_extractor.py или слой подготовки промпта.
    • Что: Реализовать фильтрацию/маскирование значений фильтров (например, email, SSN), извлеченных из Superset, до того, как они попадут в контекст LLM. Агенту нужны только ключи и структура для маппинга, а не сырые PII-данные.
  2. Optimistic Locking (Борьба с Race Conditions):
    • Где: backend/src/services/dataset_review/repositories/session_repository.py.
    • Что: Реализовать проверку поля version при сохранении DatasetReviewSession. В случае конфликта (кто-то другой, включая агента, уже изменил сессию) выбрасывать StaleDataError -> HTTP 409 Conflict.
  3. Интеграция контекста датасета в Ассистента:
    • Где: backend/src/api/routes/assistant.py (_plan_intent_with_llm, _build_tool_catalog).
    • Что: Если в запросе передан dataset_review_session_id, подгружать DatasetProfile, ImportedFilters и ValidationFindings в системный промпт (System Prompt) ассистента, чтобы он мог отвечать на вопросы по датасету.
  4. Новые Tools (Интенты) для Агента:
    • Где: backend/src/api/routes/assistant.py -> _dispatch_intent.
    • Что: Научить агента вызывать методы DatasetReviewOrchestrator. Добавить инструменты: APPROVE_MAPPINGS (одобрить ворнинги), SET_FIELD_SEMANTICS (переписать описание колонки), GENERATE_SQL_PREVIEW (триггер компиляции).
  5. Garbage Collection сессий:
    • Где: backend/src/core/task_manager/cleanup.py (или аналог).
    • Что: Написать scheduled-таску для жесткого удаления (hard delete) брошенных/архивированных сессий обзора (например, старше 30 дней), чтобы БД не переполнялась снепшотами SQL и графами контекста.

🎨 2.2 Frontend: Реактивный Workspace и Чат

  1. Интеграция AssistantChatPanel (Slide-out Drawer):
    • Где: frontend/src/routes/datasets/review/[id]/+page.svelte (DatasetReviewWorkspace).
    • Что: Внедрить вызов боковой панели ассистента AssistantChatPanel. Убедиться, что при её открытии контент Workspace сдвигается или корректно перекрывается, не теряя контекста SQL-превью и фильтров. Удалить старый ClarificationDialog (модалку).
  2. Контекстные кнопки (Inline Triggers ✨):
    • Что: В компоненты ValidationFindingsPanel.svelte, ExecutionMappingReview.svelte и карточки фильтров добавить микро-кнопки [✨ Спросить ИИ].
    • Действие: По клику открывать assistantChat store и отправлять предзаполненный скрытый контекстный промпт (например, "Объясни проблему с фильтром X и предложи решение").
  3. Визуальная синхронизация (State Reactivity):
    • Что: Когда агент через чат задает вопрос по field_id или filter_id (Clarification Queue), соответствующий элемент в Workspace должен получать CSS-класс подсветки (glow/highlight).
    • Как: Связать ClarificationStateResult из стора сессии с рендером строк в SemanticLayerReview.svelte и списках фильтров.
  4. Confirmation Cards в ленте чата:
    • Где: frontend/src/lib/components/assistant/AssistantChatPanel.svelte.
    • Что: Для команд, требующих AssistantConfirmationRecord (например, запуск в SQL Lab), рендерить внутри чата специальный виджет: "Вы уверены, что хотите запустить этот контекст? [Отменить][Запустить]".
  5. Debounce для SQL Preview:
    • Где: frontend/src/lib/components/dataset-review/CompiledSQLPreview.svelte.
    • Что: Предотвратить спам запросами к Superset API. Если пользователь или агент быстро меняют маппинги, статус превью становится stale. Запрос на перегенерацию должен отправляться либо по явной кнопке, либо с debounce-задержкой 2-3 секунды после окончания потока изменений.

⚙️ Правила выполнения для Агента:

  1. Не ломать инварианты: Сохранить принцип WYSIWWR (What You See Is What Will Run). LLM никогда не должна генерировать финальный SQL-код сама. LLM собирает параметры, а SQL компилирует только Superset (SupersetCompilationAdapter).
  2. Семантическое логирование: Любые изменения состояния сессий на бэкенде оборачивать в belief_scope (logger.reason(), logger.reflect()), как указано в системных контрактах.
  3. По завершении этапа 1, дождись утверждения (или переходи к Этапу 2 автономно, если находишься в режиме Auto-Execute), строго следуя обновленным контрактам api.yaml.